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