> For the complete documentation index, see [llms.txt](https://story-2.gitbook.io/story/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://story-2.gitbook.io/story/basics/interactive-blocks/creating-storylocations.md).

# Creating StoryLocations

StoryLocations are interactive places in your Minecraft world that the AI system can understand and reference. They contain rich context about the location's history, current events, and relationships

### Creating a Location

#### Primary Method: In-Game Command

Use the `/story location create` command while standing at the location you want to create:

```
/story location create <location_name> [context]
```

**What happens:**

* The plugin automatically captures your current coordinates (x, y, z, yaw, pitch)
* If you provide context, it cross-references keywords with your existing NPCs, lore, and other locations
* An AI-generated location context is created based on your input and world knowledge
* A YAML file is created in the `locations/` directory

#### Examples

**Basic location creation:**

```
/story location create <location_name>
```

Creates a location with just coordinates and basic info.

**Location with context:**

{% code overflow="wrap" %}

```
/story location create Lannisport "A bustling trade city ruled by House Mervail, known for its three-tiered structure and strategic position on the Azure Sea"
```

{% endcode %}

The system will:

* Recognize "House Mervail" if it exists in your lore/NPCs
* Generate context about trade, city structure, and geography
* Cross-reference with other coastal locations or trade hubs

**Location referencing existing world elements:**

{% code overflow="wrap" %}

```
/story location create "Brotherhood_Base" "A secret Brotherhood hideout hidden beneath the ruins of the old Lysathara library"
```

{% endcode %}

The system will:

* Connect to existing "Brotherhood" lore
* Reference "Lysathara" location context
* Generate appropriate secret/hidden location details

### Sublocations

Create sublocations using the "Parent/Child" naming convention:

```
/story location create "York/Tavern"
/story location create "York/Tavern/Upstairs"
/story location create "York/Tavern/Upstairs/Private_Room"
```

This creates a hierarchical structure:

* `York.yml` (main location)
* `York/Tavern.yml` (sublocation)
* `York/Tavern/Upstairs.yml` (nested sublocation)
* `York/Tavern/Upstairs/Private_Room.yml` (deeply nested)

**Unlimited nesting depth** is supported (untested).

### Writing Effective Context

#### Tips for Better AI Generation

**Include specific names and references:**

* Mention existing NPCs, factions, or locations
* Reference established lore and events
* Use proper names from your world

**Be descriptive but concise:**

* Describe the location's purpose and atmosphere
* Mention key features or landmarks
* Include any current events or rumors

**Examples of good context prompts:**

{% code overflow="wrap" %}

```
"A fortified outpost of the Eldoran Kingdom, recently captured from Rutis forces"
"A hidden Brotherhood sanctuary where initiates study cross-racial magic"
"The main marketplace of Lysathara, bustling with elven merchants and foreign traders"
```

{% endcode %}

### Manual Creation and Editing

#### YAML File Structure

You can manually create or edit location YAML files:

{% code overflow="wrap" %}

```yaml
# Name of the location
name: LocationName

# List of contexts
context:
  - |-
    First paragraph of context describing the location...
  - |-
    Second paragraph with additional details...
    
# "sit" or "sleep". This is optional. If this is set, it will pose the NPC if they random path to the location.
randomPathingAction: "sit" 

# Auto-generated location details if location create command is used. This is used to determine a NPC's current location (which we feed current location context during conversations). Also enables to be used in random pathing and schedule pathing. Still, optional.
world: world
x: -1267.36
y: 111.0
z: 970.68
yaw: -0.42
pitch: 0.0
```

{% endcode %}

#### Key Fields

* **`name`**: Location identifier
* **`context`**: List of descriptive paragraphs (use `|-` for multi-line text)
* **`world`**: Minecraft world name (usually "world")
* **`x, y, z`**: Exact coordinates
* **`yaw, pitch`**: Player facing direction

#### Manual Editing Tips

* Use the `|-` syntax for multi-line context paragraphs
* Each context entry should be a complete thought or description
* Keep coordinates accurate to the actual in-game location
* Test your location by having NPCs reference it in conversations

### Best Practices

1. **Stand at the exact spot** where you want the location center
2. **Use descriptive context** that references your existing world
3. **Test locations** by having NPCs mention them in conversations
4. **Organize sublocations** logically (e.g., "City/District/Building/Room")
5. **Keep context updated** as your world evolves

### File Organization

Locations are stored in the `locations/` directory:

* Main locations: `LocationName.yml`
* Sublocations: `LocationName/Sublocation.yml`
* Nested sublocations: `LocationName/Sublocation/Subsublocation.yml`

The plugin automatically creates the necessary directory structure when using the `/story location create` command.