{
  "version": "1.4.0",
  "generated": "2026-09-02T00:00:00.000Z",
  "description": "Home island seed + scale contract — Driftwood Bay & Ironfang Spire size foundations, organized realistic nature, Railway SSOT, R2 glTF. SI: 1.8 m human yardstick, orc ~2.0 m",
  "authority": {
    "seedContract": "GrudgeBuilder/shared/definitions/homeIslandSeed.ts",
    "specCatalog": "GrudgeBuilder/shared/definitions/homeIslandSpec.ts",
    "foundations": "GrudgeBuilder/shared/definitions/homeIslandFoundations.ts",
    "natureAssets": "GrudgeBuilder/shared/definitions/natureAssetCatalog.ts",
    "liveSpecApi": "GET /api/island/spec",
    "rtsBridge": "GrudgeBuilder/shared/definitions/rtsTerrainBridge.ts",
    "database": "home_islands (Postgres on Railway) — NOT Cloudflare D1",
    "stateApi": "PATCH /api/island/state",
    "exportApi": "POST /api/island/export-from-rts",
    "studioEditor": "https://forge.grudge-studio.com",
    "studioEditorAlias": "https://threeflow.vercel.app",
    "studioEditorLegacy": "https://grudge-studio-editor.vercel.app/editor?mode=home-island",
    "clientBridge": "GrudgeBuilder/client/src/lib/studioEditorBridge.ts",
    "binaryAssets": "assets.grudge-studio.com R2 (grudge-assets)",
    "objectStoreCatalog": "info.grudge-studio.com/api/v1/home-island-contract.json"
  },
  "scale": {
    "warlords3dWorldSizeM": 1024,
    "rtsWorldSizeM": 200,
    "rtsHeightmapResolution": 128,
    "mountainTriadIslandFraction": 0.1,
    "mountainPeakHeightM": 20,
    "dungeonEntranceHeightM": 4,
    "colyseusRoomSizeM": 1024,
    "logicalMapPercent": 100,
    "harvestZoneCount": 19,
    "campPlateauRadiusM": 88,
    "characterReferenceHeightM": 2
  },
  "sizeFoundations": {
    "rule": "Driftwood Bay + Ironfang Spire are the only size foundations for player home islands. Both use worldSizeM=1024 and characterHeightM=2.",
    "driftwood_bay": {
      "id": "driftwood_bay",
      "label": "Driftwood Bay",
      "summary": "Coastal foundation: broad shore, bay indent, moderate elevation",
      "worldSizeM": 1024,
      "rtsCoreSizeM": 200,
      "characterHeightM": 2,
      "landmassFill": 0.58,
      "maxElevationM": 48,
      "minElevationM": -28,
      "beachBandDepthM": 28,
      "mountainFootprintFraction": 0.08,
      "mountainPeakHeightM": 20,
      "preferredBiomes": ["beach", "tropical", "plains", "storm"]
    },
    "ironfang_spire": {
      "id": "ironfang_spire",
      "label": "Ironfang Spire",
      "summary": "Highland foundation: steeper relief, tighter beach, dominant spire",
      "worldSizeM": 1024,
      "rtsCoreSizeM": 200,
      "characterHeightM": 2,
      "landmassFill": 0.72,
      "maxElevationM": 80,
      "minElevationM": -30,
      "beachBandDepthM": 14,
      "mountainFootprintFraction": 0.12,
      "mountainPeakHeightM": 20,
      "preferredBiomes": ["forest", "winter", "frozen", "volcanic", "abyssal", "nexus"]
    }
  },
  "natureAssets": {
    "policy": "No low-poly / polygon megakit (CommonTree, TwistedTree, DeadTree, Rock_Medium, Pine_*, nature-megakit). Organized R2 under /models/nature/realistic/*.",
    "banned": [
      "CommonTree",
      "TwistedTree",
      "DeadTree",
      "Rock_Medium",
      "Pine_1..5 megakit",
      "Bush_Common",
      "nature-megakit",
      "/models/lowpoly/"
    ],
    "storage": {
      "realisticTrees": "/models/nature/realistic/trees/{pine,deciduous,palm,snow}/",
      "realisticRocks": "/models/nature/realistic/rocks/",
      "realisticGroundcover": "/models/nature/realistic/groundcover/",
      "interimHarvestPacks": "/models/environment/island_tree.glb, island_rock.glb, gem_cluster.glb",
      "tropicalPalmPack": "/models/environment/palm-tree.glb",
      "tropicalPalmNodes": "/models/nature/organized/trees/M_Palm_P2_*.glb"
    },
    "interimNote": "Until realistic GLBs are uploaded, harvest + scatter use environment multi-mesh packs only — never Quaternius megakit scatter props. Tropical/home-island palms isolate M_Palm_P2_* from palm-tree.glb — never place the whole pack.",
    "palmTree": {
      "pack": "/models/environment/palm-tree.glb",
      "parentNode": "Palm_2",
      "isolateRule": "clone named M_Palm_P2_* only; each child has Trunk_0 + Leaf_0",
      "deploy": ["tropical", "beach", "home-island", "haven_shore"],
      "nodes": [
        "M_Palm_P2_1", "M_Palm_P2_2", "M_Palm_P2_3", "M_Palm_P2_4", "M_Palm_P2_5",
        "M_Palm_P2_6", "M_Palm_P2_7", "M_Palm_P2_8", "M_Palm_P2_9", "M_Palm_P2_10",
        "M_Palm_P2_11", "M_Palm_P2_12", "M_Palm_P2_13", "M_Palm_P2_14", "M_Palm_P2_15",
        "M_Palm_P2_16", "M_Palm_P2_17", "M_Palm_P2_18", "M_Palm_P2_19", "M_Palm_P2_20",
        "M_Palm_P2_21", "M_Palm_P2_22", "M_Palm_P2_23", "M_Palm_P2_25",
        "M_Palm_P2_30", "M_Palm_P2_31"
      ]
    }
  },
  "zoneTypes": [
    "mountain",
    "forest",
    "field",
    "shore",
    "water",
    "clearing"
  ],
  "regrowAnchors": [
    "forest_grove",
    "quarry",
    "beach_shells"
  ],
  "mountainTriad": {
    "modelUid": "c41cba36d5dd48b1a07241c353689709",
    "cdnModelPath": "/models/evil_rock_mountains_triad.glb",
    "peakModelPaths": [
      "/models/evil_rock_mountain_peak_0.glb",
      "/models/evil_rock_mountain_peak_1.glb",
      "/models/evil_rock_mountain_peak_2.glb"
    ],
    "peakOffsetsM": [
      { "x": -55, "z": 0 },
      { "x": 0, "z": 0 },
      { "x": 55, "z": 0 }
    ]
  },
  "stateFields": [
    "seed",
    "nodes",
    "animals",
    "terrainZones",
    "campPosition",
    "clearings",
    "mountainTriad",
    "rtsHeightmap",
    "rtsNatureScatter",
    "rtsExport",
    "regrowRegions",
    "stats"
  ],
  "notes": {
    "natureScatter": "rtsNatureScatter v2 — organized assets only; isBannedNaturePath gate in client scatter",
    "puterKv": "grudge:island:{id}:state is cache; Railway home_islands.state is SSOT",
    "textures": "PBR ground textures on CDN assets.grudge-studio.com/textures/pbr/ground/",
    "specVersion": "2.2.0 — see GET /api/island/spec on Railway game-data API",
    "d1": "Cloudflare D1 is ObjectStore meta/assets registry — island seeds live in Railway home_islands",
    "studioEditor": "Primary design surface for high-quality biome placement; seed remains deterministic for runtime",
    "ai": "CreatureBrain wildlife, AllyController navmesh, OrcBossAI for PvE bosses",
    "foundations": "Coastal biomes resolve to Driftwood Bay; highland/cold/dark to Ironfang Spire"
  },
  "characterScale": {
    "referenceHeightM": 2,
    "rule": "All props/animals/GLBs fit relative to CHARACTER_REFERENCE_HEIGHT_M",
    "source": "shared/definitions/homeIslandSpec.ts"
  },
  "pipeline": [
    "studio-editor mode=home-island",
    "mapStudioProjectToHomeIslandState",
    "PATCH /api/island/state Railway",
    "Island3DEngine home play + mountain triad portal",
    "CreatureBrain + TerrainNavMesh AI"
  ],
  "factionCities": {
    "policy": "No Elf City / Human City / Undead City prefab. Each city is a parent tree of own meshes (house + camp + alliance kit). Isolate meshName; never fuse the kit into one GLB.",
    "seed": ["home-island", "tropical", "haven_shore"],
    "cities": {
      "human": {
        "id": "faction_city/human",
        "label": "Human city",
        "alliance": "crusade",
        "race": "human",
        "parent": "faction_city/human",
        "house": {
          "id": "entities/human_cabin",
          "nodeName": "Human House",
          "unityPrefab": "Structure Crusade/Human House.prefab",
          "r2Key": "models/warlords/entities/human_cabin.glb",
          "cdnUrl": "https://assets.grudge-studio.com/models/warlords/entities/human_cabin.glb"
        },
        "camp": {
          "id": "entities/human_camp",
          "nodeName": "Human Camp",
          "unityPrefab": "Entities/GRUDGE NPCS/Human Camp.prefab",
          "meshStatus": "prefab_only"
        },
        "kit": [
          "entities/armory",
          "entities/arsenal",
          "entities/blacksmith",
          "entities/flag",
          "entities/castle_gate",
          "entities/laboritory",
          "entities/loom",
          "entities/stable",
          "entities/study",
          "entities/tent_cruisade",
          "entities/castle_wall",
          "entities/workbench",
          "entities/wood_stairs"
        ]
      },
      "elf": {
        "id": "faction_city/elf",
        "label": "Elf city",
        "alliance": "fabled",
        "race": "elf",
        "parent": "faction_city/elf",
        "house": {
          "id": "entities/elf_house",
          "nodeName": "Elf House",
          "unityPrefab": "Structure Fabled/Elf House.prefab",
          "r2Key": "models/warlords/entities/elf_house.glb",
          "cdnUrl": "https://assets.grudge-studio.com/models/warlords/entities/elf_house.glb"
        },
        "camp": {
          "id": "entities/elf_camp",
          "nodeName": "Elf Camp",
          "unityPrefab": "Entities/GRUDGE NPCS/Elf Camp.prefab",
          "meshStatus": "prefab_only"
        },
        "kit": [
          "entities/armory",
          "entities/arsenal",
          "entities/blacksmith",
          "entities/flag",
          "entities/castle_gate",
          "entities/laboritory",
          "entities/loom",
          "entities/stable",
          "entities/study",
          "entities/tent_fabled",
          "entities/castle_wall",
          "entities/workbench",
          "entities/wood_stairs"
        ]
      },
      "undead": {
        "id": "faction_city/undead",
        "label": "Undead city",
        "alliance": "legion",
        "race": "undead",
        "parent": "faction_city/undead",
        "house": {
          "id": "entities/undead_crypt",
          "nodeName": "Undead House",
          "unityPrefab": "Structure Legion/Undead House.prefab",
          "r2Key": "models/warlords/entities/undead_crypt.glb",
          "cdnUrl": "https://assets.grudge-studio.com/models/warlords/entities/undead_crypt.glb"
        },
        "camp": {
          "id": "entities/undead_camp",
          "nodeName": "Undead Camp",
          "unityPrefab": "Entities/GRUDGE NPCS/Undead Camp.prefab",
          "meshStatus": "prefab_only"
        },
        "kit": [
          "entities/legion_armory",
          "entities/legion_arsenal",
          "entities/legion_blacksmith",
          "entities/legion_claim_flag",
          "entities/castle_gate",
          "entities/legion_alch",
          "entities/legion_loom",
          "entities/legion_stable",
          "entities/legion_study",
          "entities/tent_legion",
          "entities/castle_wall",
          "entities/legion_workbench",
          "entities/wood_stairs"
        ]
      }
    }
  }
}