Location NPC Population Command

The `/locinitnpcs` command is a powerful multi-agent system that automatically generates a population of NPCs for any location in your world.

Command Syntax

/locinitnpcs <location> <context> [npc_count] [debug]

Parameters

  • location (required): The name of an existing StoryLocation

  • context (required): Description of the NPCs you want to generate

  • npc_count (optional): Number of NPCs to generate (1-20, default: 5)

  • debug (optional): Enable debug mode for detailed logging (default: false)

Example

/locinitnpcs "Lannisport" "Generate 5 Lannisport commonfolk NPCs. Game of Thrones. House Lannister. Westerosi people." 5

How It Works

The command follows a 4-step process:

Step 1: Location Analysis

  • Validates that the location exists

  • Analyzes the location's context and relationships

  • Displays location information for confirmation

Step 2: NPC Planning

  • AI analyzes the location and your context

  • Generates a plan for diverse NPCs with different roles

  • Creates unique personalities, backgrounds, and relationships

  • Shows a preview of planned NPCs

Step 3: NPC Generation

  • Generates detailed context and appearance for each NPC

  • Creates NPC data files with full character information

  • Spawns Citizens NPCs at the target location

  • Processes NPCs concurrently for faster generation

Step 4: Memory Generation

  • Creates core background memories for each NPC

  • Establishes relationships between generated NPCs

  • Generates recent event memories based on relationships

Context Writing Tips

Effective Context Examples

Generic Population:

"Generate 5 commonfolk NPCs for this trading town. Mix of merchants, guards, and villagers."

Themed Population:

"Generate 8 NPCs for this elven city. Include nobles, scholars, and craftsmen. Focus on elven culture and magic."

Specific Setting:

"Generate 6 NPCs for this pirate cove. Include smugglers, tavern keepers, and dock workers. Dark and dangerous atmosphere."

Cross-Reference Existing World:

"Generate 4 NPCs for this Brotherhood sanctuary. Include initiates and maesters. Reference the Brotherhood lore and Lysathara connections."

Context Best Practices

  1. Be Specific About Roles: Mention the types of NPCs you want (merchants, guards, nobles, etc.)

  2. Include Cultural Context: Reference the setting, culture, or theme

  3. Reference Existing Lore: Mention factions, locations, or events from your world

  4. Set the Tone: Describe the atmosphere or mood you want

  5. Keep It Concise: 1-2 sentences work best for clear AI understanding

Command Output

Success Messages

🏗️ Starting multi-agent NPC population for location: Lannisport
📝 Context: Generate 5 Lannisport commonfolk NPCs. Game of Thrones. House Lannister. Westerosi people.
👥 Target NPC count: 5
🔍 Step 1: Analyzing location 'Lannisport'...
🧠 Step 2: Planning NPC population...
✅ Generated plans for 5 NPCs
⚡ Step 3: Generating 5 NPCs...
✅ Generated NPC 1/5: Ser Willem
✅ Generated NPC 2/5: Maester Pycelle
...
🎉 Generated 5/5 NPCs successfully!
🧠 Step 4: Generating memories and relationships...
💭 Generated core memory 1/5: Ser Willem
...
🎉 Location NPC population complete!

Error Messages

❌ Location 'Nonexistent' not found. Please create the location first.
❌ NPC count must be between 1 and 20.
❌ Failed to generate NPC plan
❌ No valid NPC plans generated

Generated NPCs

What Gets Created

Each generated NPC includes:

  • Unique Name: Contextually appropriate for the setting

  • Role: Profession or social position

  • Background: Detailed history and experiences

  • Personality: Character traits and motivations

  • Relationships: Connections to other NPCs

  • Current Situation: What they're doing now

  • Appearance: Physical description

  • Memories: Core background and recent events

NPC Data Structure

Generated NPCs are saved as YAML files in the npcs/ directory with:

  • Basic information (name, role, location)

  • Detailed context and background

  • Appearance description

  • Memory system integration

  • Relationship tracking

Integration with Citizens

The command automatically:

  • Creates Citizens NPCs for each generated character

  • Spawns them at the target location

  • Links them to the Story system for AI conversations

  • Enables voice generation and interaction

Debug Mode

Enable debug mode to see detailed information:

/locinitnpcs "Lannisport" "Generate 5 NPCs" 5 true

Debug mode shows:

  • AI request details

  • JSON parsing information

  • Generation progress

  • Error details and stack traces

Best Practices

Before Running the Command

  1. Create the Location First: Use /story location create to establish the location

  2. Plan Your Context: Think about what types of NPCs fit the location

  3. Consider NPC Count: Start with 3-5 NPCs for testing, then expand

  4. Check Permissions: Ensure you have storymaker.npc.init permission

After Generation

  1. Test Conversations: Talk to the generated NPCs to verify they work

  2. Review NPC Data: Check the generated YAML files for accuracy

  3. Adjust as Needed: Manually edit NPC files if needed

  4. Create Relationships: Use other commands to establish connections

Troubleshooting

Location Not Found:

  • Verify the location exists with /story location list

  • Check spelling and capitalization

  • Create the location first if it doesn't exist

No NPCs Generated:

  • Check your context - make it more specific

  • Try a smaller NPC count first

  • Enable debug mode to see error details

NPCs Don't Spawn:

  • Verify Citizens plugin is installed and working

  • Check if NPCs already exist with the same names

  • Ensure you have permission to create Citizens NPCs

Advanced Usage

Large Population Generation

For locations that need many NPCs:

/locinitnpcs "Lysathara" "Generate 15 elven city NPCs including nobles, merchants, guards, and craftsmen" 15

Themed Populations

Create specific types of NPCs:

/locinitnpcs "Pirate Cove" "Generate 8 pirate NPCs including captains, crew, and tavern staff" 8

Cultural Integration

Reference existing world elements:

/locinitnpcs "Brotherhood Sanctuary" "Generate 6 Brotherhood initiates and maesters, referencing the Brotherhood lore" 6

Permissions

Required permission: storymaker.npc.init

Related Commands

  • /story location create - Create locations before populating them

  • /story npc create - Create individual NPCs manually

  • /story npc list - View existing NPCs

  • /story location list - View available locations

PreviousCreating StoryLocationsNextLores

Last updated