@alpaca-software/40kdc-data 0.3.0 → 0.3.1

package/schemas/core/terrain-layout.schema.json

@@ -2,84 +2,68 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://40kdc.dev/schemas/core/terrain-layout.schema.json",
   "title": "Terrain Layout",
-  "description": "A recommended arrangement of terrain pieces on the board, independent of the deployment map (a deployment-pattern references the layouts it recommends via recommended_terrain_layout_ids). Geometry is the source of truth; the GW standard piece templates are expressed as explicit footprints, with an optional descriptive `template` label. Footprints are deliberately open (not enum-locked) — the launch catalog and its size are unconfirmed, so this models any shape rather than a fixed set. No layout data is authored yet.",
+  "description": "A recommended arrangement of terrain pieces on the board, independent of the deployment map (a deployment-pattern references the layouts it recommends via recommended_terrain_layout_ids). Each piece draws its geometry from a catalog `template` (a terrain-template entity) or an inline `footprint`; geometry is the source of truth. Placement is template-centroid-anchored: `position` is the piece's centroid, which is invariant under rotation and mirror, so orientation and location are decoupled. Resolved board-space vertices are derived by the shared terrain resolver (pinned by the conformance corpus), never stored here. No layout data is authored yet beyond migrated examples.",
   "type": "object",
   "$defs": {
-    "footprint": {
-      "description": "A terrain piece's 2D footprint, relative to the piece's `position`. Axis-aligned rectangle, right triangle (right angle at the local origin, legs along +x/+y), or an explicit polygon. GW's standard templates (e.g. 7\"×11.5\" rectangles, 8\"×11.5\" right triangles, 6\"×4\" rectangles, 10\"×2.5\" and 6\"×2\" lines) are all expressible here; lines are thin rectangles.",
-      "oneOf": [
-        {
-          "type": "object",
-          "properties": {
-            "type": { "const": "rectangle" },
-            "width": { "type": "number", "exclusiveMinimum": 0 },
-            "height": { "type": "number", "exclusiveMinimum": 0 }
-          },
-          "required": ["type", "width", "height"],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "type": { "const": "right-triangle" },
-            "width": { "type": "number", "exclusiveMinimum": 0 },
-            "height": { "type": "number", "exclusiveMinimum": 0 }
-          },
-          "required": ["type", "width", "height"],
-          "additionalProperties": false
-        },
-        {
-          "type": "object",
-          "properties": {
-            "type": { "const": "polygon" },
-            "points": {
-              "type": "array",
-              "items": { "$ref": "../defs/common.schema.json#/$defs/vec2" },
-              "minItems": 3
-            }
-          },
-          "required": ["type", "points"],
-          "additionalProperties": false
-        }
-      ]
-    },
-    "terrain-area-keyword": {
-      "type": "string",
-      "enum": ["obscuring", "hidden", "plunging-fire"],
-      "description": "An 11e terrain-area keyword. Confirmed launch set; extend as further keywords publish on dataslate."
-    },
     "piece": {
       "type": "object",
-      "description": "One terrain feature placed on the board.",
+      "description": "One terrain piece placed on the board. Geometry comes from a catalog `template` or an inline `footprint` (if both are present, `footprint` is authoritative and `template` is provenance).",
       "properties": {
+        "id": {
+          "$ref": "../defs/common.schema.json#/$defs/entity-id",
+          "description": "Layout-local id. Required for any piece referenced by another piece's `parent_area_id`."
+        },
         "name": { "type": "string", "minLength": 1, "maxLength": 128 },
-        "footprint": { "$ref": "#/$defs/footprint" },
+        "piece_type": {
+          "type": "string",
+          "enum": ["area", "feature"],
+          "default": "area",
+          "description": "An `area` is a gameplay terrain zone (the 11e 'terrain area'); a `feature` is physical scenery (walls, containers, pipes) placed on an area."
+        },
+        "template": {
+          "$ref": "../defs/common.schema.json#/$defs/entity-id",
+          "description": "Id of the terrain-template this piece instances. Footprint and defaults (height, blocking, keywords) are taken from that template unless overridden here."
+        },
+        "footprint": {
+          "$ref": "../defs/common.schema.json#/$defs/footprint",
+          "description": "Inline geometry, standing in for or overriding a template footprint. Authoritative when present."
+        },
         "position": {
           "$ref": "../defs/common.schema.json#/$defs/vec2",
-          "description": "Board-inch placement of the footprint's local origin."
+          "description": "Placement of the piece's CENTROID (the polygon area centroid of its footprint). Rotation- and mirror-invariant: changing `rotation_degrees` or `mirror` never moves this point. In board inches, unless the piece is a feature with `parent_area_id`, in which case it is in the parent area's centroid-local frame."
         },
         "rotation_degrees": {
           "type": "number",
           "minimum": 0,
           "exclusiveMaximum": 360,
-          "description": "Clockwise rotation of the footprint about `position`. Absent or 0 means axis-aligned."
+          "description": "Clockwise rotation about the centroid in the y-down board frame. Absent or 0 means the template's natural orientation."
         },
-        "template": {
+        "mirror": {
           "type": "string",
-          "minLength": 1,
-          "maxLength": 64,
-          "description": "Optional descriptive label for the GW standard template this piece uses (e.g. 'large-ruin', 'long-wall'). Free-form, not enum-locked — the geometry in `footprint` is authoritative."
+          "enum": ["none", "horizontal", "vertical"],
+          "default": "none",
+          "description": "Reflection applied in the centroid-local frame before rotation: `horizontal` negates local x (left-right flip), `vertical` negates local y."
+        },
+        "parent_area_id": {
+          "$ref": "../defs/common.schema.json#/$defs/entity-id",
+          "description": "For a feature: the layout-local id of the area it sits on. The feature's `position`/`rotation_degrees`/`mirror` are composed with the parent area's placement, so moving, rotating, or mirroring the area carries the feature with it."
+        },
+        "floor": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Ruin floor this piece occupies (0 = ground level)."
         },
         "height_inches": {
           "type": "number",
           "minimum": 0,
-          "description": "Height of the piece in inches. Gates Plunging Fire (a piece 3\" or taller confers +1 BS on ground-level targets)."
+          "description": "Height of the piece in inches; overrides the template default. Gates Plunging Fire (a piece 3\" or taller confers +1 BS on ground-level targets)."
         },
         "terrain_area_keywords": {
           "type": "array",
           "uniqueItems": true,
-          "description": "Terrain-area keywords this piece's area carries.",
-          "items": { "$ref": "#/$defs/terrain-area-keyword" }
+          "description": "Terrain-area keywords this piece's area carries; overrides the template default.",
+          "items": { "$ref": "../defs/common.schema.json#/$defs/terrain-area-keyword" }
         },
         "link_group": {
           "type": "string",
@@ -109,7 +93,9 @@
           "additionalProperties": false
         }
       },
-      "required": ["footprint", "position"],
+      "required": ["position"],
+      "if": { "not": { "required": ["template"] } },
+      "then": { "required": ["footprint"] },
       "additionalProperties": false
     }
   },

package/schemas/core/terrain-template.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://40kdc.dev/schemas/core/terrain-template.schema.json",
+  "title": "Terrain Template",
+  "description": "A reusable terrain piece in the standard catalog: a gameplay area (the 11e terrain-area templates) or a scenery feature (walls, containers, pipes, floor segments). Footprints are authored in natural local inches; the terrain resolver derives each footprint's polygon area centroid and re-centers on it, so a layout piece that instances a template places its centroid via the layout's `position`. An `area` template may carry an embedded `features` list — scenery placed in the area's centroid-local frame — making the template a reusable composition (e.g. a ruin with its walls). Placing such a template places all of its features, transformed by the area's own placement.",
+  "type": "object",
+  "$defs": {
+    "composed-feature": {
+      "type": "object",
+      "description": "A feature placed on an area template, positioned in the area's centroid-local frame (y-down inches). When the area is placed, rotated, or mirrored, its composed features are carried along.",
+      "properties": {
+        "id": {
+          "$ref": "../defs/common.schema.json#/$defs/entity-id",
+          "description": "Composition-local id for this feature instance."
+        },
+        "template": {
+          "$ref": "../defs/common.schema.json#/$defs/entity-id",
+          "description": "Id of the feature-kind terrain-template to place."
+        },
+        "position": {
+          "$ref": "../defs/common.schema.json#/$defs/vec2",
+          "description": "The feature's centroid in the area's centroid-local frame (origin at the area centroid, y-down inches)."
+        },
+        "rotation_degrees": {
+          "type": "number",
+          "minimum": 0,
+          "exclusiveMaximum": 360,
+          "description": "Clockwise rotation of the feature about its own centroid, within the area-local frame."
+        },
+        "mirror": {
+          "type": "string",
+          "enum": ["none", "horizontal", "vertical"],
+          "default": "none"
+        },
+        "floor": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 0,
+          "description": "Ruin floor this feature occupies (0 = ground level)."
+        }
+      },
+      "required": ["template", "position"],
+      "additionalProperties": false
+    }
+  },
+  "properties": {
+    "id": { "$ref": "../defs/common.schema.json#/$defs/entity-id" },
+    "name": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "kind": {
+      "type": "string",
+      "enum": ["area", "feature"],
+      "description": "`area` = a gameplay terrain zone; `feature` = physical scenery placed on an area."
+    },
+    "source": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Catalog or mission pack the template originates from."
+    },
+    "footprint": { "$ref": "../defs/common.schema.json#/$defs/footprint" },
+    "default_height_inches": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Default height in inches for pieces instancing this template. Gates Plunging Fire (>= 3\")."
+    },
+    "default_blocking": {
+      "type": "boolean",
+      "description": "Whether the template blocks line of sight / movement by default."
+    },
+    "ground_accessible": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether models may be placed on the ground footprint. `false` marks an elevated-only piece (a platform reachable only on its `upper_floor`, e.g. a gantry/catwalk) or a solid obstacle with no valid placement (e.g. a generator). Meaningful for `kind: \"feature\"`."
+    },
+    "upper_floor": {
+      "type": "object",
+      "description": "An elevated platform carried by this feature (e.g. a ruin's second storey). Its footprint is authored in the SAME local frame as `footprint` and re-centered on the GROUND footprint's polygon area centroid, so the two floors stay registered when the piece is placed, rotated, or mirrored. Non-resolved metadata: the terrain resolver does not emit it; authoring/visualization tools render it as an overlay. Meaningful for `kind: \"feature\"`.",
+      "properties": {
+        "footprint": { "$ref": "../defs/common.schema.json#/$defs/footprint" },
+        "floor": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 1,
+          "description": "Ruin floor this platform occupies (1 = first floor above ground)."
+        }
+      },
+      "required": ["footprint"],
+      "additionalProperties": false
+    },
+    "default_terrain_area_keywords": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "Terrain-area keywords areas of this template carry by default. Meaningful for `kind: \"area\"`.",
+      "items": { "$ref": "../defs/common.schema.json#/$defs/terrain-area-keyword" }
+    },
+    "features": {
+      "type": "array",
+      "description": "Composed scenery features, in the area's centroid-local frame. Only meaningful for `kind: \"area\"`.",
+      "items": { "$ref": "#/$defs/composed-feature" }
+    },
+    "game_version": { "$ref": "../defs/game-version-ref.schema.json" }
+  },
+  "required": ["id", "name", "kind", "footprint", "game_version"],
+  "additionalProperties": false
+}