castle-web-cli 0.4.204 → 0.4.205

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/dist/agent-failures.d.ts +3 -1
  2. package/dist/agent-failures.js +19 -0
  3. package/dist/agent-prompts.js +2 -1
  4. package/dist/agent.d.ts +3 -2
  5. package/dist/agent.js +19 -10
  6. package/dist/castle-host/host.d.ts +17 -0
  7. package/dist/castle-host/host.js +551 -4
  8. package/dist/devSessionStorage.js +65 -4
  9. package/dist/effortSupport.d.ts +7 -0
  10. package/dist/effortSupport.js +31 -0
  11. package/dist/init.js +13 -3
  12. package/dist/platformDoc.js +6 -1
  13. package/dist/serve.js +35 -2
  14. package/dist/shell/assets/{index-DHzA0-Sj.js → index-hWQTC8q6.js} +5 -5
  15. package/dist/shell/index.html +1 -1
  16. package/dist/vitePlugins.js +19 -1
  17. package/kits/base/CLAUDE.md +2 -0
  18. package/kits/base/castle.json +1 -1
  19. package/kits/base/sdk/README.md +131 -0
  20. package/kits/base/sdk/agent.d.ts +6 -0
  21. package/kits/base/sdk/agent.js +70 -0
  22. package/kits/base/sdk/castle.d.ts +4 -0
  23. package/kits/base/sdk/castle.js +2 -0
  24. package/kits/base/sdk/commands.d.ts +106 -0
  25. package/kits/base/sdk/commands.js +21 -0
  26. package/kits/base/sdk/decks.d.ts +7 -0
  27. package/kits/base/sdk/decks.js +31 -0
  28. package/kits/base/sdk/runtime.d.ts +4 -2
  29. package/kits/base/sdk/runtime.js +51 -40
  30. package/kits/base/sdk/server/storage.d.ts +44 -0
  31. package/kits/base/sdk/server/storage.js +54 -0
  32. package/kits/base/sdk/transport.d.ts +5 -1
  33. package/kits/base/sdk/transport.js +106 -23
  34. package/kits/multiplayer-2d/castle.json +4 -4
  35. package/kits/multiplayer-2d/code/client/poses.js +7 -0
  36. package/kits/multiplayer-2d/code/server/limits.js +3 -0
  37. package/kits/multiplayer-2d/code/server/ownership.js +36 -8
  38. package/kits/multiplayer-2d/code/systems/multiplayer.js +23 -2
  39. package/kits/multiplayer-3d/CLAUDE.md +12 -1
  40. package/kits/multiplayer-3d/castle.json +4 -4
  41. package/kits/multiplayer-3d/code/client/avatars.js +7 -1
  42. package/kits/multiplayer-3d/code/client/poses.js +61 -1
  43. package/kits/multiplayer-3d/code/client/steer.js +383 -0
  44. package/kits/multiplayer-3d/code/server/limits.js +3 -0
  45. package/kits/multiplayer-3d/code/server/ownership.js +114 -18
  46. package/kits/multiplayer-3d/code/server/world.js +12 -4
  47. package/kits/multiplayer-3d/code/systems/multiplayer.js +315 -34
  48. package/kits/physics-3d/CLAUDE.md +65 -7
  49. package/kits/physics-3d/castle.json +3 -3
  50. package/kits/physics-3d/docs/pxmodel-format.md +916 -15
  51. package/kits/physics-3d/engine3d/PxModelEditor.jsx +2 -2
  52. package/kits/physics-3d/engine3d/artobjects.js +218 -0
  53. package/kits/physics-3d/engine3d/blob.js +1058 -0
  54. package/kits/physics-3d/engine3d/branches.js +300 -0
  55. package/kits/physics-3d/engine3d/cage.js +496 -0
  56. package/kits/physics-3d/engine3d/cageops.js +516 -0
  57. package/kits/physics-3d/engine3d/frame.js +669 -0
  58. package/kits/physics-3d/engine3d/look.js +675 -0
  59. package/kits/physics-3d/engine3d/materialpresets.js +486 -0
  60. package/kits/physics-3d/engine3d/modelEditorWorld.js +3 -2
  61. package/kits/physics-3d/engine3d/modelrefs.js +120 -0
  62. package/kits/physics-3d/engine3d/motion.js +560 -0
  63. package/kits/physics-3d/engine3d/objtext.js +37 -0
  64. package/kits/physics-3d/engine3d/optimize.js +1083 -0
  65. package/kits/physics-3d/engine3d/paint.js +674 -0
  66. package/kits/physics-3d/engine3d/partgeometry.js +467 -0
  67. package/kits/physics-3d/engine3d/paths.js +324 -0
  68. package/kits/physics-3d/engine3d/pxmodel.js +429 -26
  69. package/kits/physics-3d/engine3d/scatter.js +102 -0
  70. package/kits/physics-3d/engine3d/sculpt.js +1148 -0
  71. package/kits/physics-3d/engine3d/surfacedetail.js +267 -0
  72. package/kits/physics-3d/engine3d/sweep.js +480 -0
  73. package/kits/physics-3d/engine3d/thumbnails.js +6 -4
  74. package/kits/physics-3d/engine3d/world3d.js +119 -17
  75. package/kits/physics-3d/eslint.config.js +13 -0
  76. package/kits/physics-3d/models/parts/axe.pxmodel +40 -0
  77. package/kits/physics-3d/models/parts/backpack.pxmodel +47 -0
  78. package/kits/physics-3d/models/parts/barrel.pxmodel +22 -0
  79. package/kits/physics-3d/models/parts/bedroll.pxmodel +28 -0
  80. package/kits/physics-3d/models/parts/belt-pouch.pxmodel +22 -0
  81. package/kits/physics-3d/models/parts/bolt.pxmodel +10 -0
  82. package/kits/physics-3d/models/parts/bracer.pxmodel +26 -0
  83. package/kits/physics-3d/models/parts/chain-span.pxmodel +12 -0
  84. package/kits/physics-3d/models/parts/chimney.pxmodel +11 -0
  85. package/kits/physics-3d/models/parts/crate.pxmodel +44 -0
  86. package/kits/physics-3d/models/parts/crystal.pxmodel +22 -0
  87. package/kits/physics-3d/models/parts/door-arched.pxmodel +12 -0
  88. package/kits/physics-3d/models/parts/engine-block.pxmodel +39 -0
  89. package/kits/physics-3d/models/parts/exhaust-pipe.pxmodel +30 -0
  90. package/kits/physics-3d/models/parts/fence-span.pxmodel +10 -0
  91. package/kits/physics-3d/models/parts/fender.pxmodel +19 -0
  92. package/kits/physics-3d/models/parts/headlight.pxmodel +24 -0
  93. package/kits/physics-3d/models/parts/hood.pxmodel +17 -0
  94. package/kits/physics-3d/models/parts/horned-helmet.pxmodel +37 -0
  95. package/kits/physics-3d/models/parts/jerry-can.pxmodel +26 -0
  96. package/kits/physics-3d/models/parts/ladder.pxmodel +10 -0
  97. package/kits/physics-3d/models/parts/lamp.pxmodel +20 -0
  98. package/kits/physics-3d/models/parts/lantern.pxmodel +30 -0
  99. package/kits/physics-3d/models/parts/leaf-cluster.pxmodel +21 -0
  100. package/kits/physics-3d/models/parts/offroad-tire.pxmodel +48 -0
  101. package/kits/physics-3d/models/parts/pauldron.pxmodel +26 -0
  102. package/kits/physics-3d/models/parts/rivet.pxmodel +8 -0
  103. package/kits/physics-3d/models/parts/rock.pxmodel +21 -0
  104. package/kits/physics-3d/models/parts/roll-bar-light.pxmodel +26 -0
  105. package/kits/physics-3d/models/parts/round-shield.pxmodel +31 -0
  106. package/kits/physics-3d/models/parts/saddlebag.pxmodel +30 -0
  107. package/kits/physics-3d/models/parts/spoked-wheel.pxmodel +39 -0
  108. package/kits/physics-3d/models/parts/staff.pxmodel +33 -0
  109. package/kits/physics-3d/models/parts/stepping-stones.pxmodel +8 -0
  110. package/kits/physics-3d/models/parts/stone-base.pxmodel +10 -0
  111. package/kits/physics-3d/models/parts/sword.pxmodel +33 -0
  112. package/kits/physics-3d/models/parts/window-lit.pxmodel +13 -0
  113. package/kits/physics-3d/models/parts/wizard-hat.pxmodel +28 -0
  114. package/kits/physics-3d/models/templates/biped-stout.pxmodel +59 -0
  115. package/kits/physics-3d/models/templates/biped-tall.pxmodel +63 -0
  116. package/kits/physics-3d/models/templates/quadruped.pxmodel +52 -0
  117. package/kits/physics-3d/scripts/render/filmstrip.js +217 -0
  118. package/kits/physics-3d/scripts/render/index.html +20 -0
  119. package/kits/physics-3d/scripts/render/sheet.js +411 -0
  120. package/kits/physics-3d/scripts/render.mjs +646 -0
  121. package/kits/real-time/castle.json +2 -2
  122. package/kits/real-time/code/client/ownership.js +14 -4
  123. package/kits/real-time/code/client/smooth.js +2 -2
  124. package/kits/real-time/code/server/session.js +20 -4
  125. package/package.json +2 -2
@@ -38,8 +38,14 @@ JSON).
38
38
 
39
39
  - `format`: always `"pxmodel"`.
40
40
  - `name`: display name.
41
+ - `height`: optional; the finished model is scaled so its visible height is
42
+ this many meters. Game sizes: a prop 0.3-1.2, a creature 0.5-2, a character
43
+ 1.7-2, a vehicle 2-4, a building 3-7 (buildings are smaller than real ones,
44
+ so they fit the camera). Write parts at any scale and set `height`.
41
45
  - `parts`: ordered array of parts. Order is draw/authoring order only;
42
46
  hierarchy comes from `parent`.
47
+ - `look`: outline, rim light and occlusion, on by default (see Look).
48
+ - `triangles`: the model's triangle budget, default 15000 (see Cost).
43
49
 
44
50
  The model's own space is up to the author; the convention is **feet (or base)
45
51
  at y = 0**, 1 unit = 1 meter, facing **+z**. The `Model` behavior places the
@@ -62,37 +68,932 @@ Placement (all optional, defaulting to zero):
62
68
  - `offset: [x, y, z]` -- the mesh's center relative to the pivot. A leg whose
63
69
  pivot is the hip has `offset: [0, -0.22, 0]` so it swings from the top.
64
70
 
65
- Geometry -- same vocabulary as the `Shape` behavior, plus an editable mesh:
71
+ Choosing a shape:
66
72
 
67
- - `kind`: `"box"` (default) | `"sphere"` | `"cylinder"` | `"capsule"` |
68
- `"mesh"`.
69
- - box: `size: [w, h, d]` (default `[1, 1, 1]`).
70
- - sphere: `radius`. cylinder / capsule: `radius` + `height`.
73
+ - The default look is sculpted: a model is a few shaped surfaces, each one a
74
+ single part, the way a mug is one cage with its handle pulled out of it.
75
+ Many small primitives stuck together is a style of its own (a blocky or toy
76
+ look); use it when the request asks for that.
77
+ - An animal, a person or anything organic is a few continuous surfaces, not a
78
+ pile of spheres and capsules. Overlapping spheres read as lumps and show
79
+ seams. Make the body and head one smoothed cage (a `loft` or a mesh with
80
+ `subdivide`, see Cages), legs and tail tubes or small cages, and use spheres
81
+ only for things that are round: eyes, berries, buttons.
82
+ - Tails, necks, horns, trunks and branches are a `tube` with `radii`.
83
+ - Flat things with a curve -- ears, leaves, petals, capes -- are an `extrude`
84
+ with `fold` and `bend`, or a `surface`.
85
+ - When you think in spheres and capsules, list them in a `blob`: they
86
+ become one surface with smooth joins instead of a pile of parts.
87
+ - Primitives are right for built things: boxes for walls and planks,
88
+ cylinders for posts, a lathe for anything turned.
89
+
90
+ Geometry:
91
+
92
+ - `kind`: `"box"` (default) | `"sphere"` | `"cylinder"` | `"cone"` |
93
+ `"capsule"` | `"torus"` | `"lathe"` | `"extrude"` | `"tube"` | `"sweep"` |
94
+ `"loft"` | `"surface"` | `"branches"` | `"blob"` | `"frame"` | `"mesh"` |
95
+ `"model"` (another model file, see Reusing models).
96
+ - box: `size: [w, h, d]` (default `[1, 1, 1]`). `round` rounds its edges and
97
+ corners by that radius, e.g. `0.05`. `roundSegments` is the most steps
98
+ round each edge (default 3; fewer on a small rounding).
99
+ - sphere: `radius`. `noise` (0 to 1) pushes the surface in and out by that
100
+ fraction of the radius, and `seed` picks the pattern: bushes, tree crowns,
101
+ rocks, clouds. `0.2` is gently lumpy, `0.5` is rough. A lumpy sphere's
102
+ `detail` (0 to 4, default 4) is the most it is split: 20 triangles at 0,
103
+ 80 at 1, 500 at 4; a tiny one gets less.
104
+ - cylinder / capsule: `radius` + `height`. A cylinder's `radiusTop` makes it
105
+ taper: trunks, bottles, lampshades, legs. A cone is a cylinder with
106
+ `radiusTop` 0.
107
+ - torus: a ring in the x-y plane around the z axis. `radius` is to the middle
108
+ of the ring, `tube` is the ring's own thickness, `arc` (degrees, default
109
+ 360) makes a partial ring: handles, rims, tires, hoops.
110
+ - lathe: `profile: [[radius, y], ...]` from bottom to top, spun around the y
111
+ axis. A radius of 0 closes that end. Vases, bottles, lanterns, columns,
112
+ goblets, mushroom caps, domes, pawns.
113
+ - extrude: `outline: [[x, y], ...]`, a flat shape in the x-y plane pushed
114
+ `depth` along z and centered on z = 0. `bevel` rounds its edges, `holes` is a
115
+ list of outlines cut through it, and `smooth: true` curves the outline
116
+ through its points. Leaves, gables, arches, signs, blades, wings, ears, fins.
117
+ - tube: a round tube along a smooth curve through `path: [[x, y, z], ...]`,
118
+ from `radius` at the first point to `radiusEnd` at the last, or with
119
+ `radii: [...]`, one radius per path point, so it can swell and taper: a
120
+ bushy tail is thin at the base, fat in the middle and a point at the tip. Branches, roots,
121
+ tails, horns, hair, handles, cables, pipes.
122
+ - sweep: `profile: [[x, y], ...]`, a closed outline carried along a smooth
123
+ curve through `path: [[x, y, z], ...]`. The profile's x points to the side
124
+ of the path and its y along `up` (default `[0, 1, 0]`; `[0, 0, 1]` for a
125
+ frame on a wall). `scaleEnd` is the profile's size at the end of the path
126
+ (1 at the start), `turn` the degrees it turns from start to end. `closed`
127
+ joins the path into a loop; an open path has capped ends. `straight: true`
128
+ makes straight segments with mitered corners. `smooth: true` curves the
129
+ profile through its points; without it every profile corner is a sharp
130
+ edge. Moldings, picture frames, rails, rims, gutters, ribbons, grass
131
+ blades, horns and tusks with flat or oval sections.
132
+ - helix, on a tube or a sweep in place of `path`: `helix: { "radius": 0.05,
133
+ "turns": 8, "height": 0.3, "phase": 0 }` makes the path a coil going up +y
134
+ from the pivot, `radius` out from its middle, starting at +x and turning
135
+ toward -z; `phase` starts it that many degrees further round.
136
+ `around: [[x, y, z], ...]` winds the coil about a smooth curve through those
137
+ points instead of straight up, and `height` is not used. A tube's `radii`
138
+ are spread evenly along the coil, any number of them. A helix with `height`
139
+ 0 and whole `turns` is a closed circle: a band, a rim, a tire (a sweep with
140
+ a tire profile), a ring to repeat along. Uses:
141
+ - coil springs: a thin tube.
142
+ - braids, rope, twisted cables: three tubes with the same `around` and
143
+ `phase` 0, 120 and 240, `radius` about the strand's own radius.
144
+ - threads on a bolt, curly horns (a tube with `radii` tapering to a point),
145
+ vines on a post, springs of flat wire (a sweep).
146
+ - spiral stairs: a helix handrail, with steps repeated along it (below).
147
+
148
+ A coil spring on a shock absorber, and one strand of a three-strand braid
149
+ (the others are the same with `phase` 120 and 240):
150
+
151
+ ```json
152
+ { "id": "spring", "kind": "tube", "position": [0, 0.21, 0], "radius": 0.011,
153
+ "helix": { "radius": 0.058, "turns": 7, "height": 0.34 } }
154
+ { "id": "strandA", "kind": "tube", "radii": [0.02, 0.018, 0.011],
155
+ "helix": { "radius": 0.02, "turns": 5, "phase": 0,
156
+ "around": [[0, 0, 0], [0.01, -0.12, 0.04], [0, -0.26, 0.05], [-0.02, -0.38, 0.03]] } }
157
+ ```
71
158
  - mesh: `vertices: [[x, y, z], ...]` (pivot-relative) + `faces: [[i, j, k,
72
- ...], ...]` -- each face is 3+ vertex indices, CCW seen from outside.
73
- Quads are the working convention (n-gons fan-triangulate at render, flat
74
- shaded). This is the flexible core of the format: a box converts to a mesh
75
- in the editor and from there any form is reachable by moving vertices and
76
- extruding faces. Mesh parts are `color`-only for now (no art UVs yet).
159
+ ...], ...]` -- each face is 3+ vertex indices, CCW seen from outside.
160
+ Quads are the working convention. Without `subdivide` a mesh is drawn as
161
+ written, flat shaded. A box converts to a mesh in the editor. Mesh parts are
162
+ `color`-only for now (no art UVs yet).
163
+ - mesh from OBJ text: `"obj": "v 0 0 0\nv 1 0 0\n...\nf 1 2 3 4\n"` -- the
164
+ plain OBJ format, `v x y z` vertex lines and `f a b c ...` face lines
165
+ counting from 1, written inline as one string. `unit: 0.01` lets the numbers
166
+ be whole centimeters. Everything a mesh part takes still applies: `subdivide`
167
+ smooths it, `symmetric` mirrors it, `ops` and `sculpt` shape it, and faces
168
+ wound either way are turned outward.
169
+ - loft: `sections: [{ "y": 0, "points": [[x, z], ...], "center": [x, z] },
170
+ ...]`, rings of points from bottom to top, every ring with the same number
171
+ of points in the same order. Neighbouring rings are joined and the ends are
172
+ closed. Torsos, necks, snouts, bottles, boat hulls, car bodies, trunks.
173
+ `art` wraps once around the rings and runs up from the bottom ring to the
174
+ top; the end caps take it flat, seen from above. A loft with `ops` or
175
+ `symmetric` is `color`-only.
176
+ - surface: `points: [[[x, y, z], ...], ...]`, a grid of control points, rows
177
+ of the same length (at least 2 x 2; 4 x 4 is typical). The surface is a
178
+ smooth sheet that reaches the four corner points and is pulled toward the
179
+ rest. Several equal points in a row make a pointed end. `thickness` 0 (the
180
+ default) is a single sheet seen from both sides; above 0 it is a closed
181
+ shell that thick. `resolution` is samples per side (default 16). Capes,
182
+ cloth, sails, flags, leaves and petals, shells, ears, car panels.
183
+ The points are in the part's own space, so `rotation` turns the sheet about
184
+ the pivot, not about the sheet's middle. For a card that turns in place
185
+ (a leaf, a petal, a panel), write the points around [0, 0, 0] and put the
186
+ card where it goes with `position`; for a flap that swings from one edge
187
+ (a cape, an ear), put that edge at [0, 0, 0].
188
+ - branches: a trunk from the pivot that splits again and again into tapered
189
+ branches, one piece with no gaps at the forks. `{ "length": 2, "radius":
190
+ 0.15, "depth": 4, "split": 2, "spread": 35, "shrink": 0.72, "thin": 0.65,
191
+ "curve": 15, "lift": 0.2, "seed": 3, "direction": [0, 1, 0] }` -- the
192
+ trunk's `length` and `radius` (write it; the part default of 0.5 is thick),
193
+ `depth` levels of forks (0 to 7), `split` children at each fork, `spread`
194
+ degrees each child turns from its parent, `shrink` and `thin` the length and
195
+ radius of each level as a fraction of the one before, `curve` degrees of
196
+ random bend along each branch, `lift` a pull toward +y (negative pulls down),
197
+ `seed` the pattern, `direction` the trunk's direction. `tips: "<part id>"`
198
+ puts a copy of that part at the end of every last-level branch, its +y along
199
+ the branch and its own `position` and `rotation` relative to the end; the
200
+ tip part itself is not drawn. Uses:
201
+ - trees: a lumpy sphere (`noise` 0.3) as `tips`; `split` 3 and `depth` 3 for
202
+ a round oak crown, `depth` 5 to 6 with no tips for a bare winter tree.
203
+ - roots: `direction: [0, -1, 0]`, `lift` -0.3, `spread` 50.
204
+ - antlers: `split` 2, `depth` 2, a thick `thin` (0.8), and `mirror: "x"`.
205
+ - coral: short `length`, `shrink` and `thin` near 0.85, `lift` 0.4, a small
206
+ sphere as `tips`.
207
+ - bushes: a short `length`, `split` 3 or more, a wide `spread` and leaf tips.
208
+ - blob: `shapes` melted into one smooth surface, in the part's own space.
209
+ Each shape is one of:
210
+ - `{ "sphere": [x, y, z], "radius": r }`; `radius: [x, y, z]` makes an egg,
211
+ and `rotation: [x, y, z]` turns it.
212
+ - `{ "capsule": [[x, y, z], [x, y, z]], "radius": r, "radiusEnd": r2 }`, a
213
+ round-ended rod between two points, `radiusEnd` at the second: limbs,
214
+ necks, snouts, tails, ears.
215
+ - `{ "tube": [[x, y, z], ...], "radii": [r, ...] }`, a round tube along a
216
+ smooth curve through the points, one radius per point (or `radius` to
217
+ `radiusEnd`): a curled bushy tail, a dragon's neck, horns, a trunk,
218
+ curling fingers, a topknot.
219
+ - `{ "box": [x, y, z], "size": [w, h, d], "round": r, "rotation": [x, y, z] }`.
220
+
221
+ `blend` (meters, default 0.08) is how far shapes melt into each other. A
222
+ shape's own `blend` sets how it joins the shapes before it: small (0.005 to
223
+ 0.02) for eyes, a nose, ear tips; larger for a belly or a cloud. A shape
224
+ with `subtract: true` carves itself out of the shapes before it: eye
225
+ sockets, a mouth, the underside of a mushroom cap. A shape's `color` paints
226
+ the surface where that shape is nearest, with a sharp edge like a seam --
227
+ a white chest, dark socks, spots, a hair cap, a shirt; the rest takes the
228
+ part's `color`, and a carving shape's color colors the hole. A colored
229
+ shape only shows where it reaches the surface. `colorBlend: 0.03` fades
230
+ colors into each other over that many meters instead. `symmetric: "x"`
231
+ adds a mirror copy of every shape off x = 0, so only the +x side is
232
+ written; `symmetric: false` on a shape keeps it one-sided (a
233
+ tail curled round). `resolution` is the most grid cells along the longest
234
+ side (default 48, up to 96). A blob built coarser to fit the budget gets
235
+ fewer (see Cost). A blob is one part: a walking character keeps `legL` / `legR` /
236
+ `armL` / `armR` as parts of their own (see Animation). A head:
237
+
238
+ ```json
239
+ {
240
+ "id": "head", "kind": "blob", "color": "#e8b596", "symmetric": "x", "blend": 0.03, "resolution": 64,
241
+ "shapes": [
242
+ { "sphere": [0, 0.16, 0], "radius": [0.105, 0.125, 0.115] },
243
+ { "sphere": [0, 0.085, 0.035], "radius": [0.075, 0.055, 0.075] },
244
+ { "sphere": [0.042, 0.155, 0.115], "radius": 0.028, "subtract": true, "blend": 0.015 },
245
+ { "sphere": [0.042, 0.155, 0.098], "radius": 0.022, "color": "#f7f3ee", "blend": 0.004 },
246
+ { "capsule": [[0, 0.175, 0.112], [0, 0.125, 0.14]], "radius": 0.011, "radiusEnd": 0.02, "blend": 0.02 },
247
+ { "capsule": [[0, 0.09, 0.117], [0.028, 0.093, 0.108]], "radius": 0.007, "subtract": true, "blend": 0.01 },
248
+ { "sphere": [0, 0.2, -0.015], "radius": [0.114, 0.1, 0.122], "color": "#5b3a2a", "blend": 0.01 }
249
+ ]
250
+ }
251
+ ```
252
+
253
+ A sitting fox's tail, curled round its feet on one side, with a white tip:
254
+
255
+ ```json
256
+ { "tube": [[0, 0.12, -0.15], [0.1, 0.08, -0.27], [0.23, 0.075, -0.15], [0.24, 0.07, 0.01], [0.18, 0.065, 0.11]],
257
+ "radii": [0.04, 0.07, 0.078, 0.06, 0.018], "symmetric": false },
258
+ { "sphere": [0.195, 0.067, 0.085], "radius": 0.042, "color": "#f4ede1", "blend": 0.02, "symmetric": false }
259
+ ```
260
+ - frame: round tubes between named points, welded into one piece: roll
261
+ cages, bike frames, scaffolds, ladders, cranes, cages, antenna masts,
262
+ lattice towers, bed and table frames. `nodes: { "a": [x, y, z], ... }` names
263
+ the points, and `edges: [["a", "b"], ["b", "c", 0.03], ...]` joins them,
264
+ each a straight tube of `radius` (write it; the part default of 0.5 is
265
+ thick) or of the edge's own radius, its third entry. An edge may end with
266
+ options: `{ "curve": 0.1 }` bows it by that fraction of its length, away
267
+ from the middle of the frame (negative bows inward), and `{ "via": [[x, y,
268
+ z], ...] }` bends it smoothly through those points.
269
+ - Where two edges meet, the tube bends round a corner of radius `round`
270
+ (default 3 times `radius`; `0` makes a sharp corner with a ball).
271
+ - Where three or more meet, the two closest to a straight line run through
272
+ as one tube and the rest are welded to its side; when none are, the joint
273
+ is a ball.
274
+ - A bar that meets another partway along needs a node there on both: a
275
+ ladder's rails have a node at every rung.
276
+ - `segments` is the sides of each tube (default 10).
277
+ - net, on a frame: `{ "faces": [["a", "b", "c", "d"], ...], "spacing": 0.06,
278
+ "wire": 0.003, "diagonal": false, "color": "#hex" }` fills each face of four
279
+ (or three) nodes, listed in order around it, with a grid of thin wires
280
+ `spacing` apart: mesh guards, netting, fences, grilles, window nets.
281
+ `diagonal: true` runs the wires at 45 degrees, as chain-link does (four-node
282
+ faces only). `color` colors the wires apart from the tubes. A face side that
283
+ is not an edge gets a wire of its own. A buggy's roll cage, with netting
284
+ across the back:
285
+
286
+ ```json
287
+ {
288
+ "id": "cage", "kind": "frame", "color": "#9a8f80", "radius": 0.028, "round": 0.1,
289
+ "nodes": {
290
+ "fl": [0.55, 0.32, 0.95], "fr": [-0.55, 0.32, 0.95], "al": [0.45, 1.22, 0.45], "ar": [-0.45, 1.22, 0.45],
291
+ "ml": [0.6, 0.32, -0.35], "mr": [-0.6, 0.32, -0.35], "hl": [0.5, 1.32, -0.3], "hr": [-0.5, 1.32, -0.3],
292
+ "bl": [0.5, 0.5, -1.15], "br": [-0.5, 0.5, -1.15]
293
+ },
294
+ "edges": [
295
+ ["fl", "al"], ["al", "ar", { "curve": 0.05 }], ["ar", "fr"],
296
+ ["ml", "hl"], ["hl", "hr", { "curve": 0.05 }], ["hr", "mr"],
297
+ ["al", "hl"], ["ar", "hr"], ["hl", "bl"], ["hr", "br"], ["bl", "br"],
298
+ ["fl", "ml"], ["fr", "mr"], ["ml", "bl"], ["mr", "br"], ["ml", "hr", 0.022]
299
+ ],
300
+ "net": { "faces": [["hl", "hr", "br", "bl"]], "spacing": 0.07, "wire": 0.005, "color": "#c9b98a" }
301
+ }
302
+ ```
303
+
304
+ Front hoop `fl`-`al`-`ar`-`fr` and main hoop `ml`-`hl`-`hr`-`mr`, each
305
+ arched on top, joined by roof bars and floor rails, with a diagonal brace
306
+ across the main hoop.
307
+
308
+ Cages -- smooth organic shapes from a few points:
309
+
310
+ - `subdivide: 1` to `3` on a mesh or loft treats it as a cage: a coarse
311
+ low-poly version of the shape that is smoothed that many times (the
312
+ Catmull-Clark rule, as in most 3d modelers). `2` is usually right. A cage
313
+ built coarser to fit the budget skips steps (see Cost). The
314
+ surface ends up inside the cage and rounder, so make the cage fuller than
315
+ the result and put extra points where it should stay sharp.
316
+ - `symmetric: "x"` on a mesh: write only the +x half, with the vertices on
317
+ the middle line at exactly x = 0 and no faces across it. The half is
318
+ mirrored and welded before smoothing, so there is no seam.
319
+ - Quads smooth best. A head is about a 3 x 3 x 3 grid of points, a body 4 to
320
+ 6 rings of 6 to 8 points; add points where there is a nose, a brow, a
321
+ shoulder.
322
+
323
+ Box modeling -- start from a block and pull limbs out of it, with no indices:
324
+
325
+ - `from: { "box": [w, h, d], "segments": [x, y, z] }` on a mesh starts from a
326
+ box centered on the pivot, cut into that many faces along each axis
327
+ (default 1), in place of `vertices` / `faces`. With `symmetric: "x"` only
328
+ the +x half is made and `segments[0]` counts across that half.
329
+ - `ops: [...]` on a mesh or loft, run in order before `symmetric` and
330
+ `subdivide`. Each op has `select`, which picks faces as they are at that
331
+ point:
332
+ - `{ "facing": "+z" }` -- the faces furthest that way (`+x`, `-x`, `+y`,
333
+ `-y`, `+z`, `-z`, or a direction `[x, y, z]`): the whole front of a box.
334
+ - `{ "facing": "-y", "near": [x, y, z] }` -- the face facing that way whose
335
+ middle is nearest the point. `near` may be a list of points, one face
336
+ each: four feet in one op.
337
+ - `{ "facing": "+y", "all": true }` -- every face facing that way.
338
+ - A list of these selects all of them. An op that selects nothing is
339
+ skipped. Points are in the part's own space, as the cage is written.
340
+ - `{ "op": "extrude", "select", "distance": 0.2, "scale": 1, "move": [x, y,
341
+ z], "turn": [x, y, z], "steps": 1 }` -- pushes the faces out along their
342
+ normal and joins them with walls. Faces that touch are pushed as one piece.
343
+ `scale` (a number or `[x, y, z]`) resizes the new end, `move` shifts it,
344
+ `turn` rotates it by degrees. `steps` repeats all of it from the new end:
345
+ steps with `move` make a neck, steps with `turn` curl a tail or a handle.
346
+ A negative distance pushes in: the inside of a mug.
347
+ - `{ "op": "inset", "select", "scale": 0.6 }` -- a smaller face inside each
348
+ face, to extrude next: eyes, a muzzle, windows, a handle's root.
349
+ - `{ "op": "move", "select", "by": [x, y, z] }` and `{ "op": "scale",
350
+ "select", "by": 0.8 }` (or `[x, y, z]`) -- move or resize faces, which
351
+ drags their neighbours along.
352
+ - `crease: { "select": {...}, "sharpness": 2 }` (or a list) keeps the outline
353
+ of the selected faces sharp through `subdivide`: a helmet or mug rim, a
354
+ table top, a blade's flat. Without `sharpness` it stays sharp; with `n` it
355
+ is sharp for n smoothing steps and then rounds.
356
+ - On a symmetric cage points on x = 0 stay on it, and a face that touches
357
+ x = 0 grows from the middle of the whole mirrored shape.
358
+
359
+ A fox, 2 m from nose to tail; the body box runs from z = -0.45 to 0.45:
77
360
 
78
- Material -- same fields as `Shape`, per part:
361
+ ```json
362
+ {
363
+ "id": "body",
364
+ "kind": "mesh",
365
+ "position": [0, 0.6, 0],
366
+ "from": { "box": [0.44, 0.34, 0.9], "segments": [2, 1, 3] },
367
+ "symmetric": "x",
368
+ "subdivide": 2,
369
+ "ops": [
370
+ { "op": "extrude", "select": { "facing": "+z" }, "distance": 0.12, "scale": 0.8, "move": [0, 0.12, 0], "steps": 2 },
371
+ { "op": "extrude", "select": { "facing": "+z" }, "distance": 0.2, "scale": 1.25 },
372
+ { "op": "extrude", "select": { "facing": "+z" }, "distance": 0.2, "scale": 0.45, "move": [0, -0.04, 0] },
373
+ { "op": "extrude", "select": { "facing": "+y", "near": [0.16, 0.5, 0.8] }, "distance": 0.14, "scale": 0.35 },
374
+ { "op": "extrude", "select": { "facing": "-y", "near": [[0.17, -0.17, 0.3], [0.17, -0.17, -0.3]] }, "distance": 0.4, "scale": 0.75 },
375
+ { "op": "inset", "select": { "facing": "-z", "near": [0.05, 0, -0.45] }, "scale": 0.6 },
376
+ { "op": "extrude", "select": { "facing": "-z", "near": [0.03, 0, -0.45] }, "distance": 0.14, "turn": [22, 0, 0], "steps": 4 }
377
+ ]
378
+ }
379
+ ```
380
+
381
+ Neck, head, snout, an ear, two legs (mirrored to four), then a tail curling
382
+ up. The cage is 2 faces wide on the half so ears and legs sit off the middle.
383
+
384
+ Deformers, on any part except a plain unsmoothed mesh -- each works along the
385
+ part's own height, its y axis from lowest to highest point:
386
+
387
+ - `taper: 0.3` (or `[x, z]`) -- width at the top as a fraction of the bottom.
388
+ - `twist: 90` -- degrees turned about y at the top.
389
+ - `fold: 20` -- degrees each side of x = 0 lifts toward +z: a leaf's midrib, a
390
+ wing's crease.
391
+ - `bend: 45` -- degrees the top curves toward +z (negative for -z): drooping
392
+ leaves, curved horns, tails, bent planks, grass blades.
393
+ - A leaf is an `extrude` with a `smooth` outline, a small `depth`, some
394
+ `fold` and some `bend`.
395
+ - `segments` sets how round a sphere, lathe, cylinder, cone, capsule or torus
396
+ is: the most sides it gets (default 24; 32 around a torus). A tiny part,
397
+ or one built coarser to fit the budget, gets fewer (see Cost). A low count
398
+ such as 6 gives a faceted look.
79
399
 
400
+ Any part:
401
+
402
+ - `scale: [x, y, z]` stretches the part's own mesh (not its children): an
403
+ egg is a sphere with `scale: [1, 1.4, 1]`, a flattened sphere makes a cushion
404
+ or a cap.
405
+ - `mirror: "x"` (or `"y"`, `"z"`) adds a copy of the part and everything
406
+ under it, reflected across its parent's x = 0 plane (the model's, for a root
407
+ part). Build one side of a symmetric thing and mirror it: arms, ears, wheels,
408
+ wings, windows.
409
+ - `repeat: { "count": 5, "offset": [x, y, z], "rotate": [x, y, z] }` adds
410
+ copies, the n-th moved by n times `offset` and turned by n times `rotate`
411
+ degrees about the parent's pivot. `offset` alone makes a row (fence posts,
412
+ planks, steps); `rotate` alone makes a ring (petals, spokes, leaves around a
413
+ stem, columns around a tower).
414
+ - `repeat: { "along": [[x, y, z], ...], "count": 20, "align": true }` spaces
415
+ `count` copies (up to 200) evenly along a smooth curve through the points,
416
+ measured from the part's `position` as a tube's path is. The first and last
417
+ copies sit on the ends; a list whose last point is its first is a loop, with
418
+ copies evenly all the way round. `"along": "<part id>"` follows that tube's
419
+ or sweep's path where that part draws it, and the repeated part's `position`
420
+ is not used: a chain along a cable you already wrote, rivets along a band.
421
+ The part itself is not drawn: it is the pattern. `align` turns each copy so
422
+ its +y runs along the curve and its +z points away from the middle of the
423
+ curve (outward on a ring or an arc, +z on a straight line), turning only as
424
+ much as the curve does, so copies never flip. The part's `rotation` and
425
+ `offset` apply inside that frame: `offset: [0, 0, 0.01]` lifts a rivet off
426
+ its band. `alternate: [0, 90, 0]` turns every other copy by that many
427
+ degrees about its own x, y and z: chain links. `jitter` (below) works here
428
+ too. Uses: chains, beads on a braid, rivets around a band, tread blocks
429
+ around a tire, bolts on a rim, vertebrae, teeth on a gear, lights on a
430
+ cable, spiral stairs, fence posts on a slope (without `align`, so they stay
431
+ upright). A chain hanging between two points, a link a little longer than
432
+ the curve's length divided by `count`, so they overlap:
433
+
434
+ ```json
435
+ { "id": "link", "kind": "torus", "radius": 0.028, "tube": 0.008, "scale": [1, 1.7, 1],
436
+ "color": "#8a8580", "metalness": 0.8,
437
+ "repeat": { "along": [[-0.5, 1.1, 0], [0, 0.72, 0], [0.5, 1.1, 0]], "count": 18,
438
+ "align": true, "alternate": [0, 90, 0] } }
439
+ ```
440
+ - `scatter: { "count": 30, "seed": 1, "on": "crown", "scale": [0.7, 1.3],
441
+ "align": true, "spin": true }` places `count` copies (up to 200) at random
442
+ points on the surface of the part `on`, more where it has more area.
443
+ Without `on`, `"within": [w, h, d]` places them inside that box around the
444
+ parent's pivot. The part itself is not drawn: it is the pattern, and its
445
+ `position` and `rotation` apply at each point. `scale` picks a size per
446
+ copy, `align` turns each copy's +y to the surface, `spin` turns it at
447
+ random about that axis, and `seed` picks another arrangement. Leaf clusters
448
+ on a crown, grass on a mound, moss and pebbles, rivets, spots on a
449
+ mushroom cap, flowers in a bed. The whole surface is used, so a mound
450
+ sunk half into the ground loses half its copies below it.
451
+ - `repeat.jitter: { "position": [x, y, z], "rotate": [x, y, z], "scale": 0.1,
452
+ "color": 0.05, "seed": 1 }` gives each copy a small random difference, at
453
+ most those amounts (meters, degrees, fractions of size and of lightness).
454
+ Handmade and natural things -- logs, stones, planks, shingles, fence posts,
455
+ books -- look stamped out without it. Keep it small: a few degrees and a few
456
+ percent. Machined things -- bolts, tiles, windows in a row -- stay exact.
457
+ - Copies made by `mirror`, `repeat`, `scatter` and `tips` have no ids of their own
458
+ and move with their part (see Animation).
459
+ - `displace: 0.03` pushes the surface in and out along its normals by up to
460
+ that distance, with `seed` picking the pattern and `noiseScale` (default
461
+ 5, or `[x, y, z]`) the bumps per unit; a small y value stretches them
462
+ upward, as in bark. The part is refined first so even a box shows it.
463
+ Bark, rock, rough stone walls, lumpy dough, knobbly trunks. (A sphere's
464
+ `noise` is separate: large lumps as a fraction of its radius.)
465
+
466
+ Material -- pick a `material`; fine-tune with paint only when needed:
467
+
468
+ - `material: "<preset>"` gives a part a finished surface: roughness,
469
+ metalness and paint, sized to the part, so a drum and a bolt
470
+ both look right. `materialColor: "#hex"` sets its main color (a written
471
+ `color` does the same); the other colors follow from it. Fields written on
472
+ the part win over the preset, and its own `paint` layers go on top.
473
+ - `rusted-steel` -- gray steel, rust patches and streaks, rusty base.
474
+ - `worn-paint` -- paint (give `materialColor`) worn to bare metal at the edges, dirty low down.
475
+ - `painted-metal` -- clean glossy paint over metal: machines, cars, lockers.
476
+ - `chrome` -- polished silver.
477
+ - `rubber` -- matte black, scuffed edges: tires, grips, hoses.
478
+ - `wood` -- varnished wood with grain along the part's longest side.
479
+ - `weathered-wood` -- gray old wood, strong grain, dark at the base: crates, fences, barrels.
480
+ - `stone` -- gray stone with speckle, fine cracks and dark crevices.
481
+ - `mossy-stone` -- stone with moss on its upper half.
482
+ - `bark` -- dark ridged bark, darker and mossy at the base.
483
+ - `fur` -- soft matte fur, a darker undercoat low down.
484
+ - `skin` -- soft skin with a faint blush.
485
+ - `cloth` -- matte fabric with a sheen, folds shaded.
486
+ - `leather` -- brown leather, darker patches, worn edges.
487
+ - `foliage` -- leaves, darker below and lighter on top.
488
+ - `plastic` -- bright glossy plastic: toys, crates, buttons.
489
+ - `glass` -- clear glass.
490
+ - `gold` -- polished gold, dark in the crevices.
491
+ - `clay` -- matte terracotta: pots, bricks, roof tiles.
492
+ - `ceramic` -- white glazed ceramic: mugs, plates, tiles.
493
+ - `snow` -- white snow, blue in the shadows.
494
+ - `lava` -- dark crust with glowing cracks, glowing at the base; `materialColor` is the glow.
495
+
496
+ ```json
497
+ { "id": "drum", "kind": "cylinder", "radius": 0.3, "height": 0.9,
498
+ "material": "rusted-steel", "materialColor": "#2f5d8a" }
499
+ ```
500
+
501
+ The fields a preset fills in, same as `Shape`, per part:
502
+
503
+ - `flat: true` shades the part in flat facets, for a low-poly look.
80
504
  - `color`, `art` (a `.sprite`/image path, or on boxes a per-face object
81
505
  `{ all, sides, front, back, left, right, top, bottom }`, any ref may pick a
82
506
  frame with `path#<n>`), `artRepeat: [u, v]`, `tint`, `roughness`,
83
507
  `metalness`, `clearcoat`, `emissive`, `emissiveIntensity`.
508
+ - An art object goes anywhere a ref does: `{ "ref": "drawings/plank.sprite",
509
+ "repeat": [u, v], "offset": [u, v], "rotation": deg }`, so each face gets
510
+ its own tiling. `artOffset: [u, v]` and `artRotation` (degrees) set the
511
+ offset and rotation for the whole part, beside `artRepeat`. Per-face names
512
+ also work on a cylinder or cone (`side`, `top`, `bottom`, `caps`, `all`), an
513
+ extrude (`caps`, `sides`, `all`) and a rounded or deformed box; any other
514
+ kind takes `all`. A crate long in x, three planks on its long faces and one
515
+ on its ends: `"art": { "all": { "ref": "drawings/plank.sprite", "repeat":
516
+ [3, 1] }, "left": "drawings/plank.sprite", "right": "drawings/plank.sprite" }`.
517
+ - `brightness` (default 1) multiplies the color, art included; above 1
518
+ lightens, which `tint` cannot. A sunlit face, a lighter trim cut from a
519
+ shared sprite.
520
+ - `alphaTest` (0 to 1) makes art pixels with less alpha than this holes, in
521
+ the shadow and outline too. Leaf and ivy cards on a `surface`.
522
+ - `doubleSided: true` draws both sides of every face.
523
+ - `paint: [layer, ...]` lays patterns over the color, in
524
+ order, each over the last. Sizes are meters in the part's own space, so the
525
+ paint moves with the part; `seed` picks another pattern. One flat color
526
+ reads as a toy; worn and dirty things want a few layers.
527
+ - `{ "pattern": "stripes", "colors": ["#hex", "#hex"], "width": 0.1,
528
+ "angle": 45, "axis": "z" }` -- bands `width` wide, the colors in turn,
529
+ seen along `axis`; angle 0 is level bands. One color alternates with the
530
+ color underneath. Hazard plates, awnings, sweaters, candy, road lines.
531
+ - `{ "pattern": "checker", "colors": [...], "size": 0.1, "axis": "z" }` --
532
+ squares `size` wide; `axis` is the direction it is seen from (without it
533
+ the cells are cubes). Flags, floors, tablecloths, racing trim.
534
+ - `{ "pattern": "spots", "color": "#hex", "size": 0.05, "density": 0.5 }`
535
+ -- round spots up to `size` across the radius, `density` 0 to 1. A
536
+ mushroom cap, a leopard, rust spots, lichen, freckles.
537
+ - `{ "pattern": "grime", "color": "#hex", "amount": 0.5, "scale": 3 }` --
538
+ noisy patches covering about `amount` of the surface, `scale` patches per
539
+ meter. Dirt, soot, rust, moss, faded or peeling paint.
540
+ - `{ "pattern": "cracks", "color": "#hex", "amount": 0.3, "scale": 2 }` --
541
+ a network of thin lines, `scale` cells per meter, `amount` their width.
542
+ Cracked stone, dry mud, crazed glaze, lava.
543
+ - `{ "pattern": "cavity", "color": "#hex", "amount": 0.5, "width": 0.08 }`
544
+ -- darkens creases and hollows (without `color`, a darker shade of what
545
+ is there). Rocks, carvings, bark, folds: it makes detail read.
546
+ - `{ "pattern": "edges", "color": "#hex", "amount": 0.5, "width": 0.03 }`
547
+ -- chips along sharp convex edges (without `color`, lighter). Worn metal,
548
+ chipped paint, scuffed wood.
549
+ - `"above": y` or `"below": y` on any layer limits it to that side of a
550
+ height, measured up the part from its pivot: mud on the lower half, snow
551
+ or moss on top.
552
+ - Stripe and checker borders are exact. The mesh is split for the other
553
+ patterns up to a limit, so very fine grime or spots on a big part come
554
+ out coarse. Cavity and edges see only their own part.
555
+
556
+ A hazard-striped bumper, dirty toward the bottom, with worn edges:
557
+
558
+ ```json
559
+ {
560
+ "id": "bumper",
561
+ "size": [1.4, 0.32, 0.08],
562
+ "round": 0.02,
563
+ "metalness": 0.3,
564
+ "paint": [
565
+ { "pattern": "stripes", "colors": ["#f2b705", "#1c1c1c"], "width": 0.1, "angle": 45 },
566
+ { "pattern": "grime", "color": "#3d3226", "amount": 0.6, "scale": 4, "below": -0.05 },
567
+ { "pattern": "grime", "color": "#6b3a1e", "amount": 0.15, "scale": 9 },
568
+ { "pattern": "edges", "color": "#9a9690", "amount": 0.7 }
569
+ ]
570
+ }
571
+ ```
572
+
573
+ ## Sculpting
574
+
575
+ `sculpt: [stroke, ...]` on any part pushes and pulls its finished surface, as
576
+ a sculpting brush does: block the shape in with a cage or a primitive, look at
577
+ it, then add strokes. Strokes apply in order, after `subdivide` and before the
578
+ deformers, in the part's own space -- the space its cage vertices are written
579
+ in, from the pivot, before `offset` and `scale`.
580
+
581
+ ```json
582
+ { "brush": "grab", "at": [0, -0.04, 0.16], "radius": 0.13, "by": [0, -0.03, 0.16], "strength": 1 }
583
+ ```
584
+
585
+ - `at` -- where the brush works. It moves to the nearest point of the
586
+ surface; a stroke more than `radius` from the surface does nothing.
587
+ - `radius` -- how far the brush reaches. Its effect fades smoothly from `at`
588
+ out to the radius.
589
+ - `strength` -- how much, as each brush says below.
590
+ - `by` -- a move, for `grab` and `crease`.
591
+
592
+ Brushes:
593
+
594
+ - `grab` moves the surface by `by` (times `strength`, default 1): pull out a
595
+ snout, a cheek, a brow, an ear.
596
+ - `inflate` pushes the surface out along its normals by `strength` meters
597
+ (default a quarter of the radius), in when negative: bellies, muscles, eye
598
+ sockets.
599
+ - `smooth` evens the surface out, `strength` 0 to 1 (default 0.5): soften
600
+ lumps, round a hard edge or a seam.
601
+ - `flatten` pulls the surface toward the average plane under the brush,
602
+ `strength` 0 to 1 (default 1): the planes of a face or a rock, a worn step.
603
+ - `pinch` pulls the surface toward `at`, along the surface, `strength` 0 to 1
604
+ (default 0.5): tighten a fold.
605
+ - `crease` cuts a groove along the surface from `at` to `at + by`, `strength`
606
+ meters deep (default a quarter of the radius), a ridge when negative: a
607
+ mouth, an eyelid, a crack in a rock.
608
+
609
+ - On a `symmetric: "x"` part a stroke off the middle line also applies at -x;
610
+ write it at +x. A stroke at x = 0 applies once and does not move the middle
611
+ sideways, except a crease with a sideways `by`, which runs both ways from
612
+ the middle: a whole mouth from one stroke.
613
+ - The surface under a stroke is split finer so it can move, less finely
614
+ when the part is built coarser to fit the budget (see Cost). A part stops
615
+ splitting at 10,000 triangles.
616
+ - Points that meet move together, so seams stay closed. A box keeps its sharp
617
+ edges; start a rounded shape from a cage or a sphere.
618
+ - Where a stroke would turn part of the surface inside out, it is taken back
619
+ there.
620
+
621
+ A head cage (front at z = 0.16) with a snout pulled out and cheeks filled:
622
+
623
+ ```json
624
+ {
625
+ "id": "head",
626
+ "kind": "mesh",
627
+ "position": [0, 0.3, 0],
628
+ "from": { "box": [0.34, 0.3, 0.32], "segments": [1, 2, 2] },
629
+ "symmetric": "x",
630
+ "subdivide": 2,
631
+ "sculpt": [
632
+ { "brush": "grab", "at": [0, -0.04, 0.16], "radius": 0.13, "by": [0, -0.03, 0.16] },
633
+ { "brush": "grab", "at": [0, -0.06, 0.3], "radius": 0.07, "by": [0, -0.01, 0.05] },
634
+ { "brush": "inflate", "at": [0.12, -0.06, 0.1], "radius": 0.08, "strength": 0.02 },
635
+ { "brush": "smooth", "at": [0.08, -0.02, 0.17], "radius": 0.1 }
636
+ ]
637
+ }
638
+ ```
639
+
640
+ The first grab draws the snout forward and down, the second its tip. The
641
+ inflate at +x fills both cheeks, and the smooth softens where the snout meets
642
+ the head.
643
+
644
+ ## Cost
645
+
646
+ A phone game wants about 50,000-150,000 triangles and a few dozen draw calls
647
+ for everything on screen. The contact sheet's header gives a model's cost as
648
+ a game draws it: triangles, draw calls, shadow casters, materials and build
649
+ time.
650
+
651
+ - `triangles` at the model's top level is its budget (default 15000). Parts
652
+ get the detail their fields or their kind's defaults ask for until the
653
+ model goes over. Then the heaviest parts are built coarser, measured in
654
+ pixels of a third-person camera (about 0.85 cm; a 1.7 m character is 200
655
+ pixels tall): a side per 3 pixels of a round outline, a blob cell or cage
656
+ edge of 1.5 pixels, each step doubling the pixel. Paint and `displace`
657
+ split the surface only as finely as the budget leaves room for
658
+ (never under 2 pixels), and a game build shrinks the heaviest meshes when
659
+ the model is still over. A referenced model that sets no budget gets an
660
+ even share of the model's. Budgets that suit: props 300-1500, trees and
661
+ bushes 800-3000, characters 1500-8000, buildings 2500-6000, a hero vehicle
662
+ or a close-up character up to 15000.
663
+ - Parts under 10 cm across (bolts, rivets, eyes) are always built to those
664
+ pixel limits, so they are cheap without asking.
665
+ - Paint stripes and checker cells under 1.5 pixels wide blend into one
666
+ color, and under 3 pixels when the budget leaves paint coarse.
667
+ - A game build merges parts into one draw call each when they hang from the
668
+ same moving part (or none), and match in texture, glow, `flat`, sides, own
669
+ `look`, and whether they are large enough to get an outline (3.5 cm).
670
+ Color, roughness and metalness go in the vertices, so they do not split a
671
+ batch. Parts under 6 cm cast no shadow. Each outline draws its batch again.
672
+ - `keep: true` on a part keeps it out of merging, with its own mesh and
673
+ material, for a deck that reaches for it by id. Parts with a `tint` are
674
+ kept too.
675
+ - The same static model placed many times is built once, and in play every
676
+ copy draws in the same calls.
677
+ - What costs the most: fine paint over large areas (grime with a `scale`
678
+ above about 8 on a big part), `displace` over large areas, and many copies
679
+ of a detailed part (a 500-triangle part repeated 40 times).
680
+
681
+ ## Look
682
+
683
+ Every model is drawn with a stylized look so it reads at game size: a dark
684
+ outline around each part, a rim of light on edges turned away from the
685
+ camera, and darkening where parts meet (ambient occlusion). It is on by
686
+ default with these values:
687
+
688
+ ```json
689
+ "look": { "outline": 0.012, "outlineColor": "#1a1622", "rim": 0.35, "ao": 0.6 }
690
+ ```
691
+
692
+ - `outline`: outline width in meters; `0` turns it off. It is never thinner
693
+ than about one screen pixel, and never wider than the radius of the part
694
+ where it bends most, so wires and thin rods get thin outlines. Parts under
695
+ 3.5 cm across get none.
696
+ - `outlineColor`: the outline's color.
697
+ - `rim`: strength of the rim light, `0` to `1`.
698
+ - `ao`: how dark the occlusion gets, `0` to `1`. It is baked once per model
699
+ in the rest pose, so a leg that swings keeps the shading of where it
700
+ started.
84
701
 
85
- ## Animation hooks
702
+ Set `look` at the model's top level to change it for every part, and on a
703
+ part to change it for that part; a part's fields are merged over the
704
+ model's. `"look": false` turns it off, for the whole model or for one part:
86
705
 
87
- The engine animates any model whose part ids follow the walk convention,
88
- driven by observed motion (anything that moves, walks):
706
+ ```json
707
+ { "id": "glass", "kind": "sphere", "look": { "outline": 0, "ao": 0 } }
708
+ ```
709
+
710
+ ## Reusing models
711
+
712
+ A part with `kind: "model"` draws another `.pxmodel` file in its place. Write a
713
+ tire, a lamp or a crate once and use it on every vehicle and shelf:
714
+
715
+ ```json
716
+ { "id": "wheelFL", "kind": "model", "src": "@imports/castle.physics-3d/models/parts/offroad-tire.pxmodel",
717
+ "position": [0.78, 0.41, 0.8], "mirror": "x" }
718
+ ```
719
+
720
+ - `src` names the file the way art refs do: `models/parts/tire.pxmodel` is a
721
+ file of the deck this model belongs to, and
722
+ `@imports/<alias>/models/...` (or `imports/<alias>/models/...`) is a file
723
+ of an import. A kit's own model saying `models/parts/bolt.pxmodel` keeps
724
+ meaning the kit's bolt after the kit is imported.
725
+ - `position`, `rotation`, `offset` and `scale` place the whole referenced model
726
+ as they place a mesh. `scale` may be one number: `"scale": 0.9`.
727
+ - `tint: "#hex"` multiplies every color in the referenced model: white leaves
728
+ it as it is, dark parts stay dark, and `"#c0c8ff"` cools a barrel without
729
+ losing its hoops. Emissive colors are not tinted.
730
+ - The reference is one part of this model: it can have children, `mirror`,
731
+ `repeat` (including `along`) and `scatter`. Its own parts have no ids here,
732
+ do not animate and cannot be picked one by one in the editor.
733
+ - A referenced model can reference others, up to 4 deep. A file that is
734
+ missing, is not a model, or is already being drawn above it (a loop) draws
735
+ nothing.
736
+ - Art refs inside a referenced model are looked up as written, not against the
737
+ referenced file's deck, so a shared model uses color or `@imports/...` art.
738
+
739
+ The physics-3d kit ships a parts library in `models/parts/`. From a deck that
740
+ imports the kit, write `@imports/castle.physics-3d/models/parts/<name>.pxmodel`.
741
+ Sizes are in meters, width (x) by height (y) by depth (z). "Center" parts have
742
+ their middle at the pivot, so `position` is where the axle or mount point goes.
743
+ Held and worn parts have their pivot where they attach: a weapon's grip, a
744
+ helmet's rim, a pouch's belt loop. The rest stand on y = 0.
745
+
746
+ | Part | Size (m) | Origin and facing |
747
+ | ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
748
+ | `offroad-tire` | 0.29 x 0.82 x 0.82 | center; axle along x, hub and lug bolts on +x. `mirror: "x"` for the far side. |
749
+ | `spoked-wheel` | 0.29 x 0.89 x 0.89 | center; axle along x. Wooden cart wheel, 12 spokes, iron band. |
750
+ | `bolt` | 0.04 x 0.06 x 0.04 | washer on y = 0, hex head up +y, shaft below. `rotation: [0, 0, -90]` points it along +x. |
751
+ | `rivet` | 0.024 x 0.03 x 0.024 | dome on y = 0, up +y, shank below. |
752
+ | `chain-span` | 1.13 x 0.31 x 0.07 | ends at x = +-0.5, y = 0, sagging 0.2 below; end rings on top. |
753
+ | `jerry-can` | 0.36 x 0.52 x 0.18 | on y = 0; X-pressed faces +z and -z, spout at the +x top corner. |
754
+ | `lamp` | 0.21 x 0.27 x 0.13 | lens center at the pivot, shining +z; housing back at z = 0, mount foot below. |
755
+ | `crate` | 0.8 x 0.8 x 0.8 | on y = 0; framed wooden crate with a planked lid. |
756
+ | `barrel` | 0.63 x 0.9 x 0.63 | on y = 0; wooden staves, four iron hoops, bung on top. |
757
+ | `leaf-cluster` | 0.5 x 0.49 x 0.52 | center; a ball of leaves for branch ends, bushes, hedges. |
758
+ | `rock` | 1.02 x 0.58 x 0.86 | on y = 0, sunk 0.1 below; mossy on top, with a pebble at +x. |
759
+ | `lantern` | 0.17 x 0.31 x 0.19 | on y = 0; lit glass, wire guard, bail handle over the top. |
760
+ | `axe` | 0.05 x 0.87 x 0.31 | grip at the pivot, haft up +y, blade edge toward +z. |
761
+ | `sword` | 0.26 x 0.84 x 0.06 | grip at the pivot, blade up +y, flat faces +z and -z, guard along x. |
762
+ | `staff` | 0.11 x 1.68 x 0.12 | grip at the pivot, foot 0.75 below, glowing orb in a claw at the top. |
763
+ | `round-shield` | 0.62 x 0.62 x 0.12 | middle of the back face at the pivot, face and boss toward +z, grip behind. |
764
+ | `horned-helmet` | 0.63 x 0.36 x 0.39 | rim center at the pivot (brow height), dome up, nose guard +z. Fits a head 0.32 wide. |
765
+ | `wizard-hat` | 0.60 x 0.46 x 0.60 | brim center at the pivot, tip bending back to -z, buckle +z. Fits a head 0.31 wide. |
766
+ | `hood` | 0.54 x 0.52 x 0.47 | brow height on the head's middle at the pivot; face opening +z, mantle 0.28 below. |
767
+ | `pauldron` | 0.36 x 0.29 x 0.38 | top of the left (+x) shoulder at the pivot, tilted out to +x. `scale: [-1, 1, 1]` for the right. |
768
+ | `bracer` | 0.15 x 0.17 x 0.17 | center; forearm along y, wide end up toward the elbow, plate on +z. Forearm radius 0.06. |
769
+ | `belt-pouch` | 0.16 x 0.16 x 0.10 | belt loop at the pivot, pouch hanging below, flap toward +z. |
770
+ | `backpack` | 0.46 x 0.40 x 0.35 | middle of the side worn against the back at the pivot, pack toward -z, straps over to +z. |
771
+ | `saddlebag` | 0.51 x 0.23 x 0.30 | top of the cross strap at the pivot, a bag hanging at each side, long along z. |
772
+ | `bedroll` | 0.48 x 0.17 x 0.18 | center; roll along x, strap buckles on +z. |
773
+ | `engine-block` | 0.25 x 0.45 x 0.35 | on y = 0; finned cylinder leaning to +z, air filter at -z, side covers on +x and -x. |
774
+ | `exhaust-pipe` | 0.19 x 0.36 x 0.95 | flange at the pivot (the engine port); loops forward and under, back to a muffler at -z. |
775
+ | `headlight` | 0.27 x 0.20 x 0.15 | lens center at the pivot, shining +z; mounting ears at x = +-0.12 for fork legs. |
776
+ | `roll-bar-light` | 0.52 x 0.18 x 0.09 | pivot on the bar it clamps (along x); light bar 0.1 above, shining +z. |
777
+ | `fender` | 0.35 x 0.76 x 0.90 | pivot on the wheel axle (along x); arc 0.47 out, mud flap at -z. `scale: [0.45, 0.8, 0.8]` for a bike. |
778
+ | `crystal` | 0.34 x 0.43 x 0.40 | on y = 0; glowing crystals on a stone. |
779
+ | `door-arched` | 1.30 x 2.19 x 0.41 | bottom middle of the opening; back at z = 0 on the wall face, facing +z. Stone arch, plank door, step. |
780
+ | `window-lit` | 0.86 x 1.08 x 0.20 | center of the glass; back at z = 0 on the wall face, facing +z. Warm glass, frame, sill, lintel. |
781
+ | `fence-span` | 1.58 x 1.09 x 0.16 | on y = 0; three posts at x = -0.7, 0, 0.7, two rails on +z. `repeat` offset `[1.5, 0, 0]` for a run. |
782
+ | `stepping-stones` | 0.60 x 0.14 x 2.31 | on y = 0; four flat stones along z from -0.95 to 0.95. |
783
+ | `chimney` | 0.68 x 1.58 x 0.68 | on y = 0, stack sunk 0.1 below: set it into the roof. Stone cap, two pots. |
784
+ | `ladder` | 0.51 x 2.00 x 0.06 | on y = 0, upright, rungs along x. Tilt it with `rotation` to lean it on a wall. |
785
+ | `stone-base` | 5.34 x 0.57 x 4.06 | on y = 0, top at y = 0.3: a 4.3 x 3.3 plinth ringed with rubble. `scale` it to the walls. |
786
+
787
+ A building gets a base and two or three ground parts (fence, stones, barrels, lanterns).
788
+
789
+ ## Start from a template
790
+
791
+ The kit ships three characters in `models/templates/`, read from a deck as
792
+ `imports/castle.physics-3d/models/templates/<name>.pxmodel`:
793
+
794
+ | Template | Size (m) | Build |
795
+ | ------------- | ------------------ | ----------------------------------------------------------------------- |
796
+ | `biped-stout` | 0.74 x 1.22 x 0.39 | short and broad, head about 0.3 of the height: dwarves, kids, goblins. |
797
+ | `biped-tall` | 0.55 x 1.69 x 0.27 | slim adventurer, long legs, tall boots. |
798
+ | `quadruped` | 0.24 x 0.56 x 1.02 | four-legged animal: blob body, `head` on the neck, four legs, a `tail`. |
799
+
800
+ - The templates are plain grey bodies with no face, hair or clothes.
801
+ - Copy the template's parts into your model, then reshape them: move and
802
+ resize blob shapes, recolor, add a beard, ears or a snout as shapes. Keep
803
+ the ids and parents, which are the gait hooks (see Gaits): `torso`, `head`,
804
+ `legL`, `legR`, `armL`, `armR` on the bipeds; `torso`, `head`, `tail`,
805
+ `legFL`, `legFR`, `legBL`, `legBR` on the quadruped.
806
+ - Parts named `slot-...` are empty attachment points: `kind: "model"` with no
807
+ `src` draws nothing. Fill a slot by giving it a `src` from the parts
808
+ library, or parent your own parts to it. Delete the slots you do not use.
809
+ - `slot-head` -- brow height on the head's middle: helmets, hats, hoods.
810
+ - `slot-back` -- between the shoulder blades, facing +z like the body. A
811
+ shield there takes `rotation: [0, 180, 0]`.
812
+ - `slot-belt` -- on the belt at the left hip, turned outward: a pouch.
813
+ - `slot-shoulderL`, `slot-shoulderR` -- shoulder tops: pauldrons. The right
814
+ one is mirrored by its `scale`.
815
+ - `slot-forearmL`, `slot-forearmR` -- forearm middles: bracers.
816
+ - `slot-handL`, `slot-handR` -- in the fist, turned so a weapon points
817
+ forward and up.
818
+ - `slot-neck` on the quadruped: a collar.
819
+ - A slot's `scale` fits library parts to that body: `biped-tall` scales its
820
+ head slot 0.68 so the helmets fit its smaller head.
821
+
822
+ The stout template as a dwarf, three of its slots filled:
823
+
824
+ ```json
825
+ { "id": "slot-head", "parent": "head", "kind": "model", "position": [0, 0.2, 0],
826
+ "src": "@imports/castle.physics-3d/models/parts/horned-helmet.pxmodel" },
827
+ { "id": "slot-back", "parent": "torso", "kind": "model", "position": [0, 0.26, -0.18], "rotation": [0, 180, 0],
828
+ "src": "@imports/castle.physics-3d/models/parts/round-shield.pxmodel" },
829
+ { "id": "slot-handR", "parent": "armR", "kind": "model", "position": [-0.04, -0.38, 0.06], "rotation": [60, 0, 0],
830
+ "src": "@imports/castle.physics-3d/models/parts/axe.pxmodel" }
831
+ ```
832
+
833
+ ## Detail on the silhouette
834
+
835
+ Put detail where the outline is; dots in the middle of a face vanish at game
836
+ size. A 1.7 m character is 100 pixels tall, so a stud on a chest is a pixel,
837
+ but a band that sticks out at a hem changes the outline and reads.
838
+
839
+ - Hems, cuffs and belts: a torus round the body, studs repeated along a loop
840
+ just outside it.
841
+ - Helmets, pots and shields: a torus on the rim.
842
+ - Wheels: a library reference, not a cylinder. Spokes and tread break the
843
+ outline.
844
+ - Pouches, straps and buckles: at the side of the body, where they stick out.
845
+
846
+ ```json
847
+ { "id": "hem", "parent": "torso", "kind": "torus", "radius": 0.2, "tube": 0.02, "rotation": [90, 0, 0], "color": "#5b3a2a" },
848
+ { "id": "stud", "parent": "torso", "kind": "sphere", "radius": 0.014, "segments": 6, "color": "#c7a25a",
849
+ "repeat": { "along": [[0.215, 0, 0], [0, 0, 0.215], [-0.215, 0, 0], [0, 0, -0.215], [0.215, 0, 0]], "count": 16 } },
850
+ { "id": "rim", "parent": "helmet", "kind": "torus", "radius": 0.168, "tube": 0.017, "rotation": [90, 0, 0], "color": "#a57c3c" },
851
+ { "id": "wheelF", "kind": "model", "src": "@imports/castle.physics-3d/models/parts/spoked-wheel.pxmodel",
852
+ "position": [0, 0.335, 0.7], "scale": [0.4, 0.75, 0.75] }
853
+ ```
854
+
855
+ The wheel is in place of `{ "kind": "cylinder", "radius": 0.33, "height": 0.1,
856
+ "rotation": [0, 0, 90] }`.
857
+
858
+ ## Animation
859
+
860
+ A model moves in three ways, all written in the model file: gaits, named by
861
+ part id, that follow how the actor moves; `motion` on a part, which runs by
862
+ itself; and named `clips`, which game code plays. Children ride along with
863
+ their parent. The parts of a referenced model (`kind: "model"`) do not move
864
+ on their own, but the reference part can have `motion`. Every moving part is
865
+ drawn apart from the rest (see Cost), so move the few parts that matter.
866
+
867
+ ### Gaits
868
+
869
+ These part ids animate from the actor's observed motion (anything that
870
+ moves, walks):
89
871
 
90
872
  - `legL`, `legR` -- swing from their pivots while moving; tuck in the air.
91
873
  - `armL`, `armR` -- counter-swing; raise in the air.
92
874
  - `torso` -- step bob, and leans into turns. Parent the head/arms to `torso`
93
875
  so they ride along.
876
+ - `legFL`, `legFR`, `legBL`, `legBR` -- four legs, front and back, left and
877
+ right. Diagonal pairs swing together (front left with back right). In the
878
+ air the front legs reach forward and the back legs back.
879
+ - `wingL`, `wingR` -- flap about z, fast while moving or in the air, slowly at
880
+ rest. The pivot is the shoulder; a wing on the -x side flaps the mirrored
881
+ way. `mirror: "x"` on `wingL` alone gives a right wing that flaps with it.
882
+ - `tail` -- sways side to side, faster while moving.
883
+ - `head` -- looks around slowly at rest, and holds still while walking.
884
+
885
+ A leg's pivot is its hip, with `offset` moving the mesh down (see A part).
886
+ Name a part otherwise to keep it still. A part with `motion` uses that in
887
+ place of its gait.
888
+
889
+ The air pose comes from vertical speed. On sloped ground, set
890
+ `scene.three.scene.userData.groundHeight = (x, z) => height` (or on whatever
891
+ node the models sit in) so walking up or down a slope is not read as a fall.
892
+
893
+ ### Motion
894
+
895
+ `motion` on a part is one object or a list of them. Each moves the part
896
+ about its pivot, over and over:
897
+
898
+ ```json
899
+ { "id": "flag", "motion": { "rotate": [0, 20, 0], "speed": 1.5 } }
900
+ ```
901
+
902
+ - `rotate: [x, y, z]` in degrees, `move: [x, y, z]` in meters, `scale: [x, y,
903
+ z]` as a fraction of the size -- a wave from minus to plus that amount
904
+ around the rest pose.
905
+ - `speed` -- cycles per second, default 1. `phase` -- where in the cycle the
906
+ part starts, 0 to 1; two parts at 0 and 0.5 move opposite.
907
+ - `when` -- `"always"` (default), `"idle"` (fades out while walking) or
908
+ `"walk"` (only while walking).
909
+ - `spin: [x, y, z]` -- turns steadily, in degrees per second: sails, wheels,
910
+ fans, a pickup.
911
+ - `flicker: 0.3` -- the glow (`emissive`) jumps up and down by that fraction,
912
+ ten times a second at `speed` 1: fire, torches, a failing bulb. The part
913
+ needs an `emissive` color.
914
+ - `blink: 4` -- squashes the part to a tenth of its height for 0.15 s every 4
915
+ seconds: eyes. Put the eye's pivot at its center.
916
+ - `ripple: true`, beside `repeat` or `scatter`, starts each copy later in the
917
+ cycle so one wave runs along the row: a flag of strips, a caterpillar, a
918
+ tail of segments. A number is the phase step from one copy to the next.
919
+
920
+ Copies from `mirror`, `repeat`, `scatter` and `tips` move with their part.
921
+ Each placed actor starts at its own point in the cycle, so a row of trees
922
+ does not sway in step.
923
+
924
+ A fox: the four leg ids trot, `tail` sways, and one eye mirrored to two
925
+ blinks every 3 s (legs and the body are left out here):
926
+
927
+ ```json
928
+ { "id": "head", "kind": "blob", "position": [0, 0.47, 0.24], "shapes": [...] },
929
+ { "id": "eye", "parent": "head", "kind": "sphere", "radius": 0.02,
930
+ "position": [0.042, 0.06, 0.115], "color": "#1e1a1a", "mirror": "x",
931
+ "motion": { "blink": 3 } },
932
+ { "id": "tail", "kind": "tube", "position": [0, 0.4, -0.3], "color": "#d9772b",
933
+ "path": [[0, 0, 0], [0, -0.1, -0.3], [0, -0.16, -0.42]], "radii": [0.035, 0.075, 0.015] }
934
+ ```
935
+
936
+ A tail with its own wag instead of the gait: `"motion": { "rotate": [0, 30, 0],
937
+ "speed": 2, "when": "idle" }`.
938
+
939
+ A windmill: the sails hang from a hub part that spins about its own z axis.
940
+
941
+ ```json
942
+ { "id": "rotor", "parent": "cap", "size": [0.36, 0.36, 0.34], "position": [0, 0.56, 1.25],
943
+ "motion": { "spin": [0, 0, -40] } },
944
+ { "id": "arm", "parent": "rotor", "position": [0, 0, 0.2], "repeat": { "count": 4, "rotate": [0, 0, 90] } }
945
+ ```
946
+
947
+ A lantern that bobs in the air and glows unsteadily:
948
+
949
+ ```json
950
+ { "id": "lantern", "kind": "model", "src": "@imports/castle.physics-3d/models/parts/lantern.pxmodel",
951
+ "position": [0, 1.2, 0], "motion": { "move": [0, 0.05, 0], "speed": 0.5 } }
952
+ ```
953
+
954
+ Hung from a hook instead, put the pivot at the hook and the lantern below it
955
+ with `offset: [0, -0.31, 0]`, then swing it: `"motion": { "rotate": [0, 0,
956
+ 10], "speed": 0.6 }`.
957
+
958
+ ### Clips
959
+
960
+ `clips` at the model's top level are named actions for game code to play:
961
+
962
+ ```json
963
+ "clips": {
964
+ "wave": { "duration": 1.2, "tracks": {
965
+ "armR": { "rotate": [[0, [0, 0, 0]], [0.3, [0, 0, -150]], [0.5, [0, 0, -125]],
966
+ [0.7, [0, 0, -150]], [1.2, [0, 0, 0]]] }
967
+ } }
968
+ }
969
+ ```
970
+
971
+ - `tracks` maps part ids to `rotate`, `move` and `scale`, each a list of
972
+ `[seconds, [x, y, z]]` keys in the units of `motion`, measured from the rest
973
+ pose. Values ease in and out between keys. `duration` defaults to the last
974
+ key's time.
975
+ - While a clip plays, its channels replace the gait and motion of those
976
+ parts. Start and end a clip at zero so it joins them smoothly.
977
+ - A behavior plays one:
978
+
979
+ ```js
980
+ import { playModelClip } from '@imports/castle.physics-3d/engine3d/motion';
981
+
982
+ playModelClip(actor, 'wave');
983
+ ```
984
+
985
+ It plays once; another call restarts it. A name the model lacks does
986
+ nothing.
987
+
988
+ ### Checking animation
94
989
 
95
- Models without these ids are static (props).
990
+ `npm run render -- --motion models/fox.pxmodel` writes
991
+ `.castle/render/fox-motion.png`: three pages of six frames from the game
992
+ camera -- idle over one cycle of the slowest motion (1 to 4 s), walking in
993
+ place at 4 m/s over one step, and the first clip from start to end. Frames
994
+ are at three, two or one times game size, whichever fits, or smaller for a
995
+ large model; each page's header says which. A blink shows in the first idle
996
+ frame.
96
997
 
97
998
  ## Mesh editing (in the model editor)
98
999