# Location NPC Population Command

### 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
