{
  "tab": "world",
  "section": "regions",
  "title": "Regions",
  "summary": "Regions are the geographic map units - the named zones that appear as cells on the player's interactive map. A realm contains all `regions`; `locations` are the specific points of interest inside a region.",
  "uiLocation": "World → Regions",
  "uiSubtitle": "\"The next level of organization in your setting (land, country, etc.). Contains locations\"",
  "editor": "JSON + MAP EDITOR modal + ADD ITEM",
  "sizeLimits": [
    {
      "field": "`regions.*.basicInfo`",
      "limit": "4,000 chars",
      "sections": [
        "world/regions"
      ]
    },
    {
      "field": "`regions.*.hiddenInfo`",
      "limit": "4,000 chars",
      "sections": [
        "world/regions"
      ]
    },
    {
      "field": "`regions` (entire section)",
      "limit": "500,000 chars",
      "sections": [
        "world/regions"
      ]
    }
  ],
  "related": "locations - locations belong to a region via `regionId`; worldLore - nation and political context belongs there, not in region descriptions",
  "wikiUrl": "/world/regions",
  "schema": {
    "_type": "record",
    "domain": "string",
    "codomain": {
      "_type": "intersection",
      "parts": [
        {
          "_type": "required",
          "fields": {
            "name": "string",
            "basicInfo": "string",
            "x": "number",
            "y": "number"
          }
        },
        {
          "_type": "partial",
          "fields": {
            "realm": "string",
            "factions": {
              "_type": "array",
              "of": "string"
            },
            "hiddenInfo": "string",
            "embeddingId": "string",
            "known": "boolean",
            "npcLevelRange": {
              "_type": "required",
              "fields": {
                "min": "number",
                "max": "number"
              }
            },
            "imageUrl": "string"
          }
        }
      ]
    }
  },
  "body": "## Example\r\n\r\n```json\r\n{\r\n  \"The Heartland\": {\r\n    \"name\": \"The Heartland\",\r\n    \"basicInfo\": \"The central heartland of the realm — a patchwork of managed farmland, well-maintained roads, and market towns spaced a day's travel apart. The terrain is flat to gently rolling with no significant natural obstacles; what defences exist are man-made. Climate is temperate with reliable summer harvests and mild winters, making this the most economically productive region in the realm. The ruling administration maintains visible presence here: tax collectors, licensed guild representatives, and city watch detachments at major crossroads. Beneath the administered surface the region is contested: three major trade families have unresolved disputes over road tolls, and the intelligence apparatus has more active operations here than its published mandate suggests.\",\r\n    \"x\": 0,\r\n    \"y\": 4,\r\n    \"realm\": \"The Compact\",\r\n    \"factions\": [\"Ruling Council\", \"Mage Academy\", \"Rangers\", \"Merchant Guild\"],\r\n    \"known\": true,\r\n    \"npcLevelRange\": { \"min\": 1, \"max\": 25 }\r\n  }\r\n}\r\n```\r\n\r\n## Fields\r\n\r\n> **📋 Note:** Validator errors show `regions.Name.0.fieldName`. The `.0`/`.1` are io-ts union/intersection branch indices (required vs optional field groups), not array indices. Value must be a plain object.\r\n\r\n### npcLevelRange\r\n\r\nEach region declares the min and max levels the engine should target when generating ambient NPCs inside that region. The pair shapes the difficulty curve: a starter zone might use `{ min: 1, max: 10 }`, a contested mid-tier zone `{ min: 15, max: 45 }`, an endgame frontier `{ min: 60, max: 100 }`. Both fields are integers. The engine treats missing `npcLevelRange` as a default range (Voyage import does not reject worlds without it), but setting it explicitly is the supported way to keep starter areas and tougher zones on their intended curve. Fixed-level authored NPCs continue to use their authored `level`; this field only constrains AI-generated NPCs in that region.\r\n\r\n> **📋 Note:** `npcLevelRange` is also accepted on **individual locations** (same `{ min, max }` shape). Location-level entries override the parent region's range for NPCs generated inside that specific location. Use this for outlier locations -- a high-tier dungeon inside a low-tier region, or a starter-friendly hub inside a high-tier region. See [Locations](/world/locations) for the location-level field.\r\n\r\n### hiddenInfo\r\n\r\nDo not use on regions. The field exists in the schema and the editor exposes it, but it has no documented function for regions at runtime. Region secrets belong in the `hiddenInfo` of individual locations or NPCs instead. Omit or leave as `\"\"`.\r\n\r\n### realm\r\n\r\nMust match a key in `realms`. Omitting it is valid but the region will not appear in the realm map view. Almost always set.\r\n\r\n### factions\r\n\r\nDisplay-name strings of factions with a broad, region-wide presence (patrols, political control, cultural influence). Names must match faction keys. For site-specific faction presence use `locations.*.factions` instead.\r\n\r\n### imageUrl\r\n\r\nExtra-codec optional string. URL of a banner or map image shown in the region view. Custom image URLs work today but are not an officially supported feature; the engine loads them without moderation enforcement. A native image-generation pipeline with mandatory automatic AI content moderation (the same review applied before a world can be published) is in active development and will replace this slot. Treat custom URLs as a temporary affordance; expect them to be restricted once the native feature ships.\r\n\r\n## Map coordinate system\r\n\r\n\"You can plan out the shape of your realm and arrange the regions in whatever order you want.\" The realm is always rectangular — undefined coordinates between placed regions get filled in.\r\n\r\nRegion and location coordinates use completely different systems.\r\n\r\n### Region x/y (grid cell position)\r\n\r\n- Each integer unit represents one full region cell (regionSize=100 units wide)\r\n- Adjacent regions should differ by exactly 1 in x or y (e.g., (0,1) and (1,1) are side-by-side)\r\n- **Within a realm, all regions must form a connected grid — no isolated regions.** Adjacent means sharing an edge (not diagonal). A region with no edge-neighbor in the same realm is invalid.\r\n- A gap of 2+ between coordinates = empty random-terrain cells between regions\r\n- DO NOT use large values like 95, 220, 555 — these place regions thousands of cells apart, making the map unnavigable\r\n- x increases eastward, y increases southward (regions skill: north is `-y`, south is `+y`, east is `+x`, west is `-x`)\r\n\r\n**Example 11-region grid layout:**\r\n\r\n```text\r\n        x=0           x=1           x=2           x=3           x=4\r\ny=2  [safe NW]    [mid NE]      [random]      [random]      [random]\r\ny=1  [safe W]     [mid W]       [mid C]       [frontier E]  [frontier FE]\r\ny=0  [coastal S]  [random]      [danger C]    [danger E]    [endgame]\r\n```\r\n\r\nEach region's playable area is its ±50 local grid. The map editor shows all regions on a global grid for editing. Players navigate between regions via in-game travel commands; the map shows their current region's local view.\r\n\r\n### Location x/y (local offset)\r\n\r\nLocation coordinates are a **local offset from the parent region's center**, not global.\r\n\r\n- Range: ±50 (since regionSize=100 → each region spans 50 units in each direction from center)\r\n- A location at (0,0) appears at the region center; (-23,25) is 23 units west, 25 units south\r\n- The location editor shows e.g. x=-23, y=25, and the pin appears correctly inside the region box\r\n\r\n### Realm vs region\r\n\r\n**Realm ≠ geographic zone.** A realm is the top-level container — roughly equivalent to a world, country, or plane of existence. Most scenarios should have exactly **one realm** containing all regions. Regions are the actual geographic map units visible on the interactive player map. Do NOT split a single world into multiple realms as if they were continents or zones — use regions for that.\r\n\r\n### Cross-region travel\r\n\r\nWhen players travel past a region boundary, coordinates wrap into the adjacent region. With `locationSettings.regionSize: 100`:\r\n\r\n```text\r\nFrom location (95, 50) in region (2, 2)\r\nTravel +10 in x direction\r\n→ Arrive at (5, 50) in region (3, 2)\r\n```\r\n\r\nThe `regionSize` setting in `locationSettings` determines the float coordinate space within each region (default 100).\r\n\r\n## Authoring tips\r\n\r\n### What belongs in region basicInfo\r\n\r\nA region describes a **geographic area** — the physical terrain, climate, landmarks, and who lives there. It does not describe a nation, political entity, or cultural tradition. Those belong in `worldLore`.\r\n\r\n`basicInfo` **should** describe:\r\n- Terrain type (plains, mountains, coast, forest, desert, urban)\r\n- Climate and weather (temperature, rainfall, seasonal variation)\r\n- Physical landmarks (rivers, peaks, coasts, notable formations)\r\n- Who inhabits it (sparse vs dense, what kind of settlement)\r\n- Local flavour (what makes this patch of land distinct to look at)\r\n\r\n`basicInfo` should **NOT** describe:\r\n- Full national history, dynastic succession, or political lore — that belongs in `worldLore`\r\n- Cultural traditions, religious practices, or economic systems in depth\r\n- School reputations, sports results, or institutional standing\r\n\r\nA brief note on current political or military situation is appropriate — who controls this land and whether that control is contested helps the AI understand the region's mood and NPC loyalties. Keep it to one sentence; the details belong in `worldLore`.\r\n\r\n### basicInfo template (3-aspect pattern)\r\n\r\nOne paragraph covering three aspects:\r\n\r\n1. **Geography** — terrain, landmarks, natural features\r\n2. **Climate / atmosphere** — weather patterns, sensory details, mood\r\n3. **Inhabitant hints** — who or what lives here, without full faction details\r\n\r\nPattern: `\"[Terrain description]. [Climate and atmospheric details]. [Brief mention of inhabitants or dangers].\"`\r\n\r\n### Region scope\r\n\r\nRegions are large geographic areas containing 3-8 locations. Think a forest (not a single grove), a mountain range (not a single peak), a coastal stretch (not a single beach), a district or quarter (not a single building).\r\n\r\n### One region per geographic zone, not per country\r\n\r\nA large nation with 10+ locations should be split into geographic sub-regions (northern highlands, southern plains, capital valley, coastal zone). Put the nation's political and cultural identity in `worldLore` under that nation's entry. The region just describes what the land looks like and who lives on it.\r\n\r\n**Example:** Instead of \"France: Beauxbatons Academy in the Pyrenees. Strong magical tradition.\", write \"A high granite mountain range forming the natural border between France and Spain. Permanent snowfields at elevation, forested mid-slopes, and glacial valleys. Climate is continental at altitude — cold and dry. The Pyrenean passes are the primary overland route between the two nations.\"\r\n\r\n### Geographic layout tip\r\n\r\nThe x/y coordinates are purely visual. Arrange regions spatially to hint at geography — e.g. safe starting regions on the west, dangerous frontier regions on the east, coastal regions in the south. This makes the map feel coherent without requiring any additional config.\r\n\r\n### Coverage targets\r\n\r\n| Region type | Minimum locations | Notes |\r\n|---|---|---|\r\n| Safe starting region | 3–4 | Hub town, wilderness, minor dungeon |\r\n| Mid-game region | 3–4 | Faction base, contested site, ruin |\r\n| Frontier/dangerous region | 3–4 | Outpost, hazard zone, hidden location |\r\n| Endgame region | 3 | Entry point, lore location, final confrontation |\r\n\r\nNever ship an endgame region with only 1 location. Players reaching the endgame expect an arc, not a single room."
}