castle-web-cli 0.4.128 → 0.4.130

package/kits/physics-3d/docs/pxmodel-format.md

@@ -0,0 +1,111 @@
+# `.pxmodel` 3D Model Format (physics-3d kit)
+
+A `.pxmodel` is the 3d analog of `.pxart`: a small, hand- and agent-editable
+JSON file describing a model as a list of named PARTS. A part is usually a
+primitive (legible, diffable, easy for an agent to patch); when a form needs
+more than primitives, a part can be an editable polygon MESH (`kind:
+"mesh"`) -- explicit vertices and quad-dominant faces, still plain JSON.
+Files live under `models/` and are edited in the kit's model editor (or as
+JSON).
+
+```json
+{
+  "format": "pxmodel",
+  "name": "Barrel",
+  "parts": [
+    {
+      "id": "body",
+      "kind": "cylinder",
+      "radius": 0.4,
+      "height": 0.9,
+      "position": [0, 0.45, 0],
+      "art": "drawings/platform.pxart"
+    },
+    {
+      "id": "rim",
+      "parent": "body",
+      "kind": "cylinder",
+      "radius": 0.42,
+      "height": 0.06,
+      "position": [0, 0.42, 0],
+      "color": "#391f21"
+    }
+  ]
+}
+```
+
+## The model
+
+- `format`: always `"pxmodel"`.
+- `name`: display name.
+- `parts`: ordered array of parts. Order is draw/authoring order only;
+  hierarchy comes from `parent`.
+
+The model's own space is up to the author; the convention is **feet (or base)
+at y = 0**, 1 unit = 1 meter, facing **+z**. The `Model` behavior places the
+model at the actor's Transform (offset by `Model.yOffset`, e.g. `-0.7` to put
+feet under a capsule whose center is the Transform).
+
+## A part
+
+Identity and hierarchy:
+
+- `id` -- unique string. Part ids are also animation hooks (below).
+- `parent` -- another part's id. A child's `position`/`rotation` are relative
+  to its parent's pivot. Omit for a root part.
+
+Placement (all optional, defaulting to zero):
+
+- `position: [x, y, z]` -- the part's PIVOT, in parent (or model) space.
+  Rotations happen about this point.
+- `rotation: [x, y, z]` -- degrees.
+- `offset: [x, y, z]` -- the mesh's center relative to the pivot. A leg whose
+  pivot is the hip has `offset: [0, -0.22, 0]` so it swings from the top.
+
+Geometry -- same vocabulary as the `Shape` behavior, plus an editable mesh:
+
+- `kind`: `"box"` (default) | `"sphere"` | `"cylinder"` | `"capsule"` |
+  `"mesh"`.
+- box: `size: [w, h, d]` (default `[1, 1, 1]`).
+- sphere: `radius`. cylinder / capsule: `radius` + `height`.
+- mesh: `vertices: [[x, y, z], ...]` (pivot-relative) + `faces: [[i, j, k,
+...], ...]` -- each face is 3+ vertex indices, CCW seen from outside.
+  Quads are the working convention (n-gons fan-triangulate at render, flat
+  shaded). This is the flexible core of the format: a box converts to a mesh
+  in the editor and from there any form is reachable by moving vertices and
+  extruding faces. Mesh parts are `color`-only for now (no art UVs yet).
+
+Material -- same fields as `Shape`, per part:
+
+- `color`, `art` (a `.pxart`/image path, or on boxes a per-face object
+  `{ all, sides, front, back, left, right, top, bottom }`, any ref may pick a
+  frame with `path#<n>`), `artRepeat: [u, v]`, `tint`, `roughness`,
+  `metalness`, `clearcoat`, `emissive`, `emissiveIntensity`.
+
+## Animation hooks
+
+The engine animates any model whose part ids follow the walk convention,
+driven by observed motion (anything that moves, walks):
+
+- `legL`, `legR` -- swing from their pivots while moving; tuck in the air.
+- `armL`, `armR` -- counter-swing; raise in the air.
+- `torso` -- step bob, and leans into turns. Parent the head/arms to `torso`
+  so they ride along.
+
+Models without these ids are static (props).
+
+## Mesh editing (in the model editor)
+
+Select a mesh part and hit **Edit mesh**: pick faces or vertices on the
+stage (shift extends), move the selection with the gizmo, **Extrude** pushes
+selected faces out along their normals. **To mesh** converts a box part into
+an equivalent editable mesh. Planned ops, in the spirit of real polygon
+modelers: inset, bevel, loop cut, edge slide, knife, region (shared-edge)
+extrusion, and mirror-across-axis.
+
+## Using a model
+
+Give an actor a `Model` behavior: `{ "file": "models/barrel.pxmodel",
+"scale": 1, "yOffset": 0 }`. The model replaces the Shape's mesh; the `Shape`
+still provides the physics collider (and its dimensions should roughly wrap
+the model). Everything else -- Solid, Body, Pickup, etc. -- is unchanged.

package/kits/physics-3d/drawings/crate.pxart

@@ -0,0 +1,26 @@
+{
+  "format": "compact",
+  "palette": {
+    "d": "#8a4836",
+    "o": "#bf6f4a",
+    "l": "#e69c69"
+  },
+  "grid": [
+    "dddddddddddddddd",
+    "dlllllllllllllld",
+    "dldoooooooooodld",
+    "dlodoooooooodold",
+    "dloodoooooodoold",
+    "dlooodoooodooold",
+    "dloooodoodoooold",
+    "dloooooddooooold",
+    "dloooooddooooold",
+    "dloooodoodoooold",
+    "dlooodoooodooold",
+    "dloodoooooodoold",
+    "dlodoooooooodold",
+    "dldoooooooooodld",
+    "dlllllllllllllld",
+    "dddddddddddddddd"
+  ]
+}

package/kits/physics-3d/drawings/door-edge.pxart

@@ -0,0 +1,26 @@
+{
+  "format": "compact",
+  "palette": {
+    "d": "#391f21",
+    "o": "#8a4836",
+    "l": "#bf6f4a"
+  },
+  "grid": [
+    "dddddddddddddddd",
+    "llllllllllllllll",
+    "oooooooooooooooo",
+    "oooooooooooooooo",
+    "dddddddddddddddd",
+    "llllllllllllllll",
+    "oooooooooooooooo",
+    "oooooooooooooooo",
+    "dddddddddddddddd",
+    "llllllllllllllll",
+    "oooooooooooooooo",
+    "oooooooooooooooo",
+    "dddddddddddddddd",
+    "llllllllllllllll",
+    "oooooooooooooooo",
+    "oooooooooooooooo"
+  ]
+}

package/kits/physics-3d/drawings/door.pxart

@@ -0,0 +1,27 @@
+{
+  "format": "compact",
+  "palette": {
+    "d": "#391f21",
+    "o": "#8a4836",
+    "l": "#bf6f4a",
+    "s": "#657392"
+  },
+  "grid": [
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "sdsdsdsdsdsdsdsd",
+    "sdsdsdsdsdsdsdsd",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo",
+    "dloodloodloodloo"
+  ]
+}

package/kits/physics-3d/drawings/face.pxart

@@ -0,0 +1,26 @@
+{
+  "format": "compact",
+  "palette": {
+    "f": "#e5ceb4",
+    "k": "#391f21",
+    "r": "#e69c69"
+  },
+  "grid": [
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffkkffffkkffff",
+    "ffffkkffffkkffff",
+    "ffffffffffffffff",
+    "ffrffffffffffrff",
+    "ffffffffffffffff",
+    "ffffffkkkkffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff",
+    "ffffffffffffffff"
+  ]
+}

package/kits/physics-3d/drawings/floor.pxart

@@ -0,0 +1,27 @@
+{
+  "format": "compact",
+  "palette": {
+    "k": "#1b1b23",
+    "a": "#24242e",
+    "b": "#282833",
+    "f": "#2e313f"
+  },
+  "grid": [
+    "kkkkkkkkkkkkkkkk",
+    "kaaaaaaakbbbbbbb",
+    "kaaaaaaakbbbbbbb",
+    "kaaaaaaakbbbbbbb",
+    "kaaaaaaakbbbbbbb",
+    "kaaaaaaakbbbbbbb",
+    "kaaaaaaakbbbbbbb",
+    "kaaaaaaakbbbbbbb",
+    "kkkkkkkkkkkkkkkk",
+    "kbbbbbbbkaaaaaaa",
+    "kbbbbbbbkaaaaaaa",
+    "kbbbbbbbkaaaaaaa",
+    "kbbbbbbbkaaaaaaa",
+    "kbbbbbbbkaaaaaaa",
+    "kbbbbbbbkaaaaaaa",
+    "kbbbbbbbkaaaaaaa"
+  ]
+}

package/kits/physics-3d/drawings/platform.pxart

@@ -0,0 +1,27 @@
+{
+  "format": "compact",
+  "palette": {
+    "e": "#3a3f52",
+    "p": "#657392",
+    "d": "#525e78",
+    "v": "#c7cfdd"
+  },
+  "grid": [
+    "eeeeeeeeeeeeeeee",
+    "eppppppdpppppppe",
+    "epvpppdppppppvde",
+    "eppppdpppppppdpe",
+    "epppdpppppppdppe",
+    "eppdpppppppdpppe",
+    "epdpppppppdppppe",
+    "edpppppppdpppppe",
+    "epppppppdppppppe",
+    "eppppppdpppppppe",
+    "epppppdpppppppde",
+    "eppppdpppppppdpe",
+    "epppdpppppppdppe",
+    "epvdpppppppdpvpe",
+    "epdpppppppdppppe",
+    "eeeeeeeeeeeeeeee"
+  ]
+}

package/kits/physics-3d/drawings/statue.pxart

@@ -0,0 +1,27 @@
+{
+  "format": "compact",
+  "palette": {
+    "s": "#b8b5b9",
+    "d": "#918e95",
+    "l": "#d4d1d5",
+    "g": "#567b79"
+  },
+  "grid": [
+    "lslsssssllllllss",
+    "sssssssssslssssl",
+    "sssssslsssssssss",
+    "lssssslsssslslsl",
+    "sslssssllssslsss",
+    "ssssssssssssssss",
+    "lslsslslslssslss",
+    "ssssslssslssssss",
+    "ssllslssssslssll",
+    "ssssssssslssssss",
+    "ssssssssssslsssl",
+    "slssssssslsslsss",
+    "sslsslllslsslsss",
+    "ssslsslslsssssss",
+    "ssssssssllssssls",
+    "llslsssslsssssls"
+  ]
+}

package/kits/physics-3d/drawings/wall.pxart

@@ -0,0 +1,27 @@
+{
+  "format": "compact",
+  "palette": {
+    "m": "#37363f",
+    "a": "#646365",
+    "b": "#75717a",
+    "c": "#8f8a93"
+  },
+  "grid": [
+    "mmmmmmmmmmmmmmmm",
+    "bbbbbmbbbbbbbmbb",
+    "bbbbbmbbbbbbbmbb",
+    "bbbbbmbbbbbbbmbb",
+    "bbbbbmbbbbbbbmbb",
+    "mmmmmmmmmmmmmmmm",
+    "bmbbbbbbbmbbbbbb",
+    "bmbbbbbbbmbbbbbb",
+    "bmbbbbbbbmbbbbbb",
+    "bmbbbbbbbmbbbbbb",
+    "mmmmmmmmmmmmmmmm",
+    "bbbbbmbbbbbbbmbb",
+    "bbbbbmbbbbbbbmbb",
+    "bbbbbmbbbbbbbmbb",
+    "bbbbbmbbbbbbbmbb",
+    "mmmmmmmmmmmmmmmm"
+  ]
+}

package/kits/physics-3d/engine3d/PlayOnly3D.jsx

@@ -0,0 +1,32 @@
+// Play-mode entry point, the 3d counterpart of the imported kit's PlayOnly.
+// Files, assets, live reload, and the behavior registry all come from the
+// physics-2d import (they're renderer-agnostic); only the player is 3d.
+import React from 'react';
+import { Lifecycle } from 'castle-web-sdk';
+import { parseJsonFile } from '@imports/castle.physics-2d/engine/files';
+import { useLiveDeckFiles3D } from './modelFiles';
+import { collectAssets } from '@imports/castle.physics-2d/engine/assets';
+import { behaviorClasses } from '@imports/castle.physics-2d/editors/behaviorRegistry';
+import { Scene3DPlayer } from './Scene3DPlayer';
+
+const DEFAULT_SCENE = 'scenes/main.scene';
+
+export function PlayOnly3D({ initialScene } = {}) {
+  const { files, dataVersion } = useLiveDeckFiles3D();
+  const scenePath =
+    initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
+  const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
+  if (!sceneData) return null;
+  const { sprites } = collectAssets(files);
+  return (
+    <Scene3DPlayer
+      key={`${scenePath}:${dataVersion}`}
+      sceneData={sceneData}
+      sprites={sprites}
+      files={files}
+      behaviorClasses={behaviorClasses}
+      scenePath={scenePath}
+      onFirstFrame={Lifecycle.ready}
+    />
+  );
+}