castle-web-cli 0.4.203 → 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.
- package/dist/agent-failures.d.ts +3 -1
- package/dist/agent-failures.js +19 -0
- package/dist/agent-prompts.d.ts +1 -0
- package/dist/agent-prompts.js +20 -8
- package/dist/agent.d.ts +5 -2
- package/dist/agent.js +59 -125
- package/dist/castle-host/host.d.ts +17 -0
- package/dist/castle-host/host.js +551 -4
- package/dist/castleJson.d.ts +1 -0
- package/dist/devSessionStorage.js +65 -4
- package/dist/effortSupport.d.ts +7 -0
- package/dist/effortSupport.js +31 -0
- package/dist/init.js +13 -3
- package/dist/platformDoc.js +6 -1
- package/dist/routerFences.d.ts +22 -0
- package/dist/routerFences.js +139 -0
- package/dist/serve.js +35 -2
- package/dist/shell/assets/index-b_bebkRb.css +1 -0
- package/dist/shell/assets/{index-CxrtbzHf.js → index-hWQTC8q6.js} +5 -5
- package/dist/shell/index.html +2 -2
- package/dist/taskAccount.d.ts +13 -0
- package/dist/taskAccount.js +38 -0
- package/dist/vitePlugins.js +19 -1
- package/kits/base/CLAUDE.md +2 -0
- package/kits/base/castle.json +1 -1
- package/kits/base/sdk/README.md +131 -0
- package/kits/base/sdk/agent.d.ts +6 -0
- package/kits/base/sdk/agent.js +70 -0
- package/kits/base/sdk/castle.d.ts +4 -0
- package/kits/base/sdk/castle.js +2 -0
- package/kits/base/sdk/commands.d.ts +106 -0
- package/kits/base/sdk/commands.js +21 -0
- package/kits/base/sdk/decks.d.ts +7 -0
- package/kits/base/sdk/decks.js +31 -0
- package/kits/base/sdk/runtime.d.ts +4 -2
- package/kits/base/sdk/runtime.js +51 -40
- package/kits/base/sdk/server/storage.d.ts +44 -0
- package/kits/base/sdk/server/storage.js +54 -0
- package/kits/base/sdk/transport.d.ts +5 -1
- package/kits/base/sdk/transport.js +106 -23
- package/kits/multiplayer-2d/castle.json +4 -4
- package/kits/multiplayer-2d/code/client/poses.js +7 -0
- package/kits/multiplayer-2d/code/server/limits.js +3 -0
- package/kits/multiplayer-2d/code/server/ownership.js +36 -8
- package/kits/multiplayer-2d/code/systems/multiplayer.js +23 -2
- package/kits/multiplayer-3d/CLAUDE.md +12 -1
- package/kits/multiplayer-3d/castle.json +4 -4
- package/kits/multiplayer-3d/code/client/avatars.js +7 -1
- package/kits/multiplayer-3d/code/client/poses.js +61 -1
- package/kits/multiplayer-3d/code/client/steer.js +383 -0
- package/kits/multiplayer-3d/code/server/limits.js +3 -0
- package/kits/multiplayer-3d/code/server/ownership.js +114 -18
- package/kits/multiplayer-3d/code/server/world.js +12 -4
- package/kits/multiplayer-3d/code/systems/multiplayer.js +315 -34
- package/kits/physics-3d/CLAUDE.md +65 -7
- package/kits/physics-3d/castle.json +3 -3
- package/kits/physics-3d/docs/pxmodel-format.md +916 -15
- package/kits/physics-3d/engine3d/PxModelEditor.jsx +2 -2
- package/kits/physics-3d/engine3d/artobjects.js +218 -0
- package/kits/physics-3d/engine3d/blob.js +1058 -0
- package/kits/physics-3d/engine3d/branches.js +300 -0
- package/kits/physics-3d/engine3d/cage.js +496 -0
- package/kits/physics-3d/engine3d/cageops.js +516 -0
- package/kits/physics-3d/engine3d/frame.js +669 -0
- package/kits/physics-3d/engine3d/look.js +675 -0
- package/kits/physics-3d/engine3d/materialpresets.js +486 -0
- package/kits/physics-3d/engine3d/modelEditorWorld.js +3 -2
- package/kits/physics-3d/engine3d/modelrefs.js +120 -0
- package/kits/physics-3d/engine3d/motion.js +560 -0
- package/kits/physics-3d/engine3d/objtext.js +37 -0
- package/kits/physics-3d/engine3d/optimize.js +1083 -0
- package/kits/physics-3d/engine3d/paint.js +674 -0
- package/kits/physics-3d/engine3d/partgeometry.js +467 -0
- package/kits/physics-3d/engine3d/paths.js +324 -0
- package/kits/physics-3d/engine3d/pxmodel.js +429 -26
- package/kits/physics-3d/engine3d/scatter.js +102 -0
- package/kits/physics-3d/engine3d/sculpt.js +1148 -0
- package/kits/physics-3d/engine3d/surfacedetail.js +267 -0
- package/kits/physics-3d/engine3d/sweep.js +480 -0
- package/kits/physics-3d/engine3d/thumbnails.js +6 -4
- package/kits/physics-3d/engine3d/world3d.js +119 -17
- package/kits/physics-3d/eslint.config.js +13 -0
- package/kits/physics-3d/models/parts/axe.pxmodel +40 -0
- package/kits/physics-3d/models/parts/backpack.pxmodel +47 -0
- package/kits/physics-3d/models/parts/barrel.pxmodel +22 -0
- package/kits/physics-3d/models/parts/bedroll.pxmodel +28 -0
- package/kits/physics-3d/models/parts/belt-pouch.pxmodel +22 -0
- package/kits/physics-3d/models/parts/bolt.pxmodel +10 -0
- package/kits/physics-3d/models/parts/bracer.pxmodel +26 -0
- package/kits/physics-3d/models/parts/chain-span.pxmodel +12 -0
- package/kits/physics-3d/models/parts/chimney.pxmodel +11 -0
- package/kits/physics-3d/models/parts/crate.pxmodel +44 -0
- package/kits/physics-3d/models/parts/crystal.pxmodel +22 -0
- package/kits/physics-3d/models/parts/door-arched.pxmodel +12 -0
- package/kits/physics-3d/models/parts/engine-block.pxmodel +39 -0
- package/kits/physics-3d/models/parts/exhaust-pipe.pxmodel +30 -0
- package/kits/physics-3d/models/parts/fence-span.pxmodel +10 -0
- package/kits/physics-3d/models/parts/fender.pxmodel +19 -0
- package/kits/physics-3d/models/parts/headlight.pxmodel +24 -0
- package/kits/physics-3d/models/parts/hood.pxmodel +17 -0
- package/kits/physics-3d/models/parts/horned-helmet.pxmodel +37 -0
- package/kits/physics-3d/models/parts/jerry-can.pxmodel +26 -0
- package/kits/physics-3d/models/parts/ladder.pxmodel +10 -0
- package/kits/physics-3d/models/parts/lamp.pxmodel +20 -0
- package/kits/physics-3d/models/parts/lantern.pxmodel +30 -0
- package/kits/physics-3d/models/parts/leaf-cluster.pxmodel +21 -0
- package/kits/physics-3d/models/parts/offroad-tire.pxmodel +48 -0
- package/kits/physics-3d/models/parts/pauldron.pxmodel +26 -0
- package/kits/physics-3d/models/parts/rivet.pxmodel +8 -0
- package/kits/physics-3d/models/parts/rock.pxmodel +21 -0
- package/kits/physics-3d/models/parts/roll-bar-light.pxmodel +26 -0
- package/kits/physics-3d/models/parts/round-shield.pxmodel +31 -0
- package/kits/physics-3d/models/parts/saddlebag.pxmodel +30 -0
- package/kits/physics-3d/models/parts/spoked-wheel.pxmodel +39 -0
- package/kits/physics-3d/models/parts/staff.pxmodel +33 -0
- package/kits/physics-3d/models/parts/stepping-stones.pxmodel +8 -0
- package/kits/physics-3d/models/parts/stone-base.pxmodel +10 -0
- package/kits/physics-3d/models/parts/sword.pxmodel +33 -0
- package/kits/physics-3d/models/parts/window-lit.pxmodel +13 -0
- package/kits/physics-3d/models/parts/wizard-hat.pxmodel +28 -0
- package/kits/physics-3d/models/templates/biped-stout.pxmodel +59 -0
- package/kits/physics-3d/models/templates/biped-tall.pxmodel +63 -0
- package/kits/physics-3d/models/templates/quadruped.pxmodel +52 -0
- package/kits/physics-3d/scripts/render/filmstrip.js +217 -0
- package/kits/physics-3d/scripts/render/index.html +20 -0
- package/kits/physics-3d/scripts/render/sheet.js +411 -0
- package/kits/physics-3d/scripts/render.mjs +646 -0
- package/kits/real-time/castle.json +2 -2
- package/kits/real-time/code/client/ownership.js +14 -4
- package/kits/real-time/code/client/smooth.js +2 -2
- package/kits/real-time/code/server/session.js +20 -4
- package/package.json +2 -2
- package/dist/shell/assets/index-CHMcsJrW.css +0 -1
|
@@ -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
|
-
|
|
71
|
+
Choosing a shape:
|
|
66
72
|
|
|
67
|
-
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
74
|
-
shaded
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
88
|
-
|
|
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
|
-
|
|
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
|
|