# Creating StoryLocations

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://story-2.gitbook.io/story/basics/interactive-blocks/creating-storylocations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.