Land the mill's ladder, and stop the table calling six models static

Two things, both found by pulling on the handcart's thread.

THE LADDER. I said three models had parts floating a few millimetres. One did.
The other two readings were my own measurement error and worth writing down,
because it is the same error as the vertex-sampling ones: I measured each part
against the model's BOUNDING BOX minimum, and a part deliberately bedded into
the ground drags that datum below the floor, so every correctly placed part
beside it appears to float by exactly the bedding depth. The forge's base
stones settle 6.8 mm and the well's drystone kerb 9.3 mm, both on purpose, and
the bellows and the well frame sit exactly on the floor their own source
declares. Nothing wrong with either.

The post mill's tail ladder was real: 14.5 mm clear. It already carried two
analytic corrections for the same corner, both correct about what they
describe, and neither accounting for the chamfer — the corner they compute the
drop of has been cut off, so the residual was very nearly the chamfer itself.
Rather than add a third derivation to a spot that has now been got wrong three
times, the assembled ladder is measured and put on the floor. A bounding box
cannot be wrong about this the way arithmetic can, and it stays right when the
chamfer or the rail section changes.

`restsOn` now covers the mill's trestle and ladder too, and its doc comment
carries the bedding caveat, so the next person to reach for it knows the datum
is the bounding box and knows what that costs.

THE ANIMATED COLUMN. `catalog-table.ts` decided it with `built.action`, which
is the VIEWER's hand-registered button and exists for five models. So the
generated table published the grindstone, the stone well, the post mill, the
cauldron, the forge and the handcart as static — six of the eleven models that
carry actions, including three of the most animated things in the kit.

The obvious replacement is worse. `core/kit.ts` wraps update as
`update: (dt) => options.update?.(dt, runtime)`, so it is a function on every
model whether or not that model does anything with it, and switching to it
marked all thirty-seven animated. One flag too narrow, its replacement too
broad.

So the generator now runs each model — a second of frames, then its action if
it has one — and asks whether anything moved. That catches what moves by
itself. What moves ON DEMAND it cannot catch, because the motion is behind an
interface the catalogue never exposed, so `Entry` now carries `actionNames`
from the model's own actions. Eleven models, and both documents list them.

Worth keeping: this table is generated precisely so it cannot go stale, it says
so in its own prose, and it was wrong for months. Generated is not the same as
correct — it only moves the mistake into the generator, where nobody looks.

Also in the npm README, which is the page npmjs.com renders: `vibe3d init` is
now the first line rather than unmentioned, `@types/three` is called out (three
ships no declarations, so without it the installed source does not typecheck),
the `@/` alias and `allowImportingTsExtensions` have a Project setup block, and
the one relative link is gone — npm resolves those against the repository, and
this one pointed at a directory the package deliberately does not ship.
`homepage` now points at the live site instead of a repository that is private.
This commit is contained in:
CRTkafa 2026-08-27 16:36:24 +07:00
parent bc78f295af
commit 909bfa0f9f
10 changed files with 267 additions and 68 deletions

View file

@ -374,16 +374,16 @@ on the first model you add, and in fact it had gone stale once.
| `wooden-hoe` | Tools | 394 | 3 | 0.23×1.23×0.33 | oak, iron, steel | | | `wooden-hoe` | Tools | 394 | 3 | 0.23×1.23×0.33 | oak, iron, steel | |
| `wooden-shovel` | Tools | 496 | 3 | 0.27×1.20×0.08 | oak, iron | | | `wooden-shovel` | Tools | 496 | 3 | 0.27×1.20×0.08 | oak, iron | |
| `wooden-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | | | `wooden-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | |
| `iron-cauldron` | Lighting | 1134 | 3 | 1.09×1.37×1.10 | stone, iron, char, ember | | | `iron-cauldron` | Lighting | 1134 | 3 | 1.09×1.37×1.10 | stone, iron, char, ember | ✔ |
| `hand-cart` | Structure | 2044 | 4 | 0.88×1.03×2.60 | oak, iron | | | `hand-cart` | Structure | 2044 | 4 | 0.87×0.68×2.49 | oak, iron | ✔ |
| `vegetables` | Props | 1718 | 2 | 0.60×0.12×0.59 | produce | | | `vegetables` | Props | 1718 | 2 | 0.60×0.12×0.59 | produce | |
| `round-shield` | Arms | 729 | 3 | 0.73×0.73×0.17 | oak, leather, iron | | | `round-shield` | Arms | 729 | 3 | 0.73×0.73×0.17 | oak, leather, iron | |
| `forge-hearth` | Smithy | 1426 | 4 | 2.06×1.78×0.87 | stone, char, ember, oak, leather, iron | | | `forge-hearth` | Smithy | 1426 | 4 | 2.06×1.78×0.87 | stone, char, ember, oak, leather, iron | ✔ |
| `stone-well` | Structure | 1376 | 4 | 1.88×2.00×1.28 | stone, oak, iron, cloth | | | `stone-well` | Structure | 1376 | 4 | 1.88×2.00×1.28 | stone, oak, iron, cloth | ✔ |
| `stone-trough` | Structure | 344 | 2 | 1.52×0.45×0.60 | stone, water | | | `stone-trough` | Structure | 344 | 2 | 1.52×0.45×0.60 | stone, water | |
| `grindstone` | Smithy | 568 | 4 | 1.24×0.95×0.70 | stone, oak, iron, water | | | `grindstone` | Smithy | 568 | 4 | 1.24×0.95×0.70 | stone, oak, iron, water | ✔ |
| `market-stall` | Structure | 384 | 4 | 1.83×2.03×0.97 | oak, cloth | | | `market-stall` | Structure | 384 | 4 | 1.83×2.03×0.97 | oak, cloth | |
| `post-mill` | Structure | 1672 | 4 | 6.60×7.23×6.98 | oak, iron | | | `post-mill` | Structure | 1672 | 4 | 6.60×7.23×6.98 | oak, iron | ✔ |
**30,390 triangles** in total. The whole kit in one scene has a budget smaller **30,390 triangles** in total. The whole kit in one scene has a budget smaller
than a single medium-complexity character model. than a single medium-complexity character model.
@ -510,15 +510,27 @@ into place before baking and moves it back afterwards.
### 5.5 Actions and animation ### 5.5 Actions and animation
Five models move and four of them demonstrate a different mechanic: Eleven models carry actions:
| Model | Action | Mechanic | | Model | Action | Mechanic |
| --- | --- | --- | | --- | --- | --- |
| `wooden-chest` | `setOpen` / `toggle` / `openness` / `snap` | exponential approach — independent of frame rate | | `wooden-chest` | `setOpen` / `toggle` / `isOpen` / `openness` / `snap` | exponential approach — independent of frame rate |
| `pitch-torch` | `setLit` / `isLit` | sum of sines at incommensurate frequencies | | `pitch-torch` | `setLit` / `isLit` | sum of sines at incommensurate frequencies |
| `iron-lantern` | `setLit` / `isLit` | the same, but slower: the glass shields the flame from wind | | `iron-lantern` | `setLit` / `isLit` | the same, but slower: the glass shields the flame from wind |
| `bronze-bell` | `ring` / `still` / `strikes` | two independent pendulums | | `iron-cauldron` | `setLit` / `isLit` | the fire under it, on the torch's flicker |
| `forge-hearth` | `setLit` / `isLit` | the same, banked lower: a forge fire is coals, not flame |
| `bronze-bell` | `ring` / `still` / `isRinging` / `strikes` | two independent pendulums |
| `tavern-sign` | `push` / `still` / `lean` | soft pendulum, long swing | | `tavern-sign` | `push` / `still` / `lean` | soft pendulum, long swing |
| `grindstone` | `crank` / `still` / `isTurning` / `turns` | spun up by hand, then exponential decay plus a constant drag, so it stops rather than approaching zero forever |
| `post-mill` | `setTurning` / `isTurning` / `setAngle` | constant rate about the windshaft |
| `stone-well` | `setDepth` / `depth` / `setWinding` | the bucket travels the shaft and the rope pays out with it |
| `hand-cart` | `setRoll` / `roll` | the wheels turn about their own axle origin |
Five of these are wired to a button in the viewer; the rest are driven through
the model's own interface. That distinction cost a documentation bug: the
generated table's Animated column was reading the VIEWER's button registration,
so six of the eleven — including the mill, the well and the grindstone — were
published as static. It now asks the models.
The distinction is written in the architecture document and it matters: The distinction is written in the architecture document and it matters:
`configure()` rebuilds the topology and is **expensive**, it is for user `configure()` rebuilds the topology and is **expensive**, it is for user

Binary file not shown.

Before

Width:  |  Height:  |  Size: 164 KiB

After

Width:  |  Height:  |  Size: 164 KiB

Before After
Before After

View file

@ -67,7 +67,7 @@
"address": "@medieval-kit/wooden-barrel", "address": "@medieval-kit/wooden-barrel",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.751Z", "installedAt": "2026-08-27T09:26:37.713Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-barrel\\model.ts", "path": "src\\models\\medieval-kit\\wooden-barrel\\model.ts",
@ -82,7 +82,7 @@
"address": "@medieval-kit/core", "address": "@medieval-kit/core",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.713Z", "installedAt": "2026-08-27T09:26:37.668Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\core\\geometry.ts", "path": "src\\models\\medieval-kit\\core\\geometry.ts",
@ -129,7 +129,7 @@
"address": "@medieval-kit/wooden-crate", "address": "@medieval-kit/wooden-crate",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.756Z", "installedAt": "2026-08-27T09:26:37.720Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-crate\\model.ts", "path": "src\\models\\medieval-kit\\wooden-crate\\model.ts",
@ -144,7 +144,7 @@
"address": "@medieval-kit/kit", "address": "@medieval-kit/kit",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.764Z", "installedAt": "2026-08-27T09:26:37.729Z",
"files": [], "files": [],
"dependencies": [] "dependencies": []
}, },
@ -152,7 +152,7 @@
"address": "@medieval-kit/iron-anvil", "address": "@medieval-kit/iron-anvil",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.726Z", "installedAt": "2026-08-27T09:26:37.684Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\iron-anvil\\model.ts", "path": "src\\models\\medieval-kit\\iron-anvil\\model.ts",
@ -167,7 +167,7 @@
"address": "@medieval-kit/wooden-bucket", "address": "@medieval-kit/wooden-bucket",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.754Z", "installedAt": "2026-08-27T09:26:37.716Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-bucket\\model.ts", "path": "src\\models\\medieval-kit\\wooden-bucket\\model.ts",
@ -182,7 +182,7 @@
"address": "@medieval-kit/wooden-fence", "address": "@medieval-kit/wooden-fence",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.758Z", "installedAt": "2026-08-27T09:26:37.721Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-fence\\model.ts", "path": "src\\models\\medieval-kit\\wooden-fence\\model.ts",
@ -197,7 +197,7 @@
"address": "@medieval-kit/wooden-hoe", "address": "@medieval-kit/wooden-hoe",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.759Z", "installedAt": "2026-08-27T09:26:37.723Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-hoe\\model.ts", "path": "src\\models\\medieval-kit\\wooden-hoe\\model.ts",
@ -212,7 +212,7 @@
"address": "@medieval-kit/wooden-ladder", "address": "@medieval-kit/wooden-ladder",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.760Z", "installedAt": "2026-08-27T09:26:37.725Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-ladder\\model.ts", "path": "src\\models\\medieval-kit\\wooden-ladder\\model.ts",
@ -227,7 +227,7 @@
"address": "@medieval-kit/wooden-pitchfork", "address": "@medieval-kit/wooden-pitchfork",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.762Z", "installedAt": "2026-08-27T09:26:37.726Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-pitchfork\\model.ts", "path": "src\\models\\medieval-kit\\wooden-pitchfork\\model.ts",
@ -242,7 +242,7 @@
"address": "@medieval-kit/wooden-shovel", "address": "@medieval-kit/wooden-shovel",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.763Z", "installedAt": "2026-08-27T09:26:37.728Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-shovel\\model.ts", "path": "src\\models\\medieval-kit\\wooden-shovel\\model.ts",
@ -257,7 +257,7 @@
"address": "@medieval-kit/wooden-stool", "address": "@medieval-kit/wooden-stool",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.764Z", "installedAt": "2026-08-27T09:26:37.729Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-stool\\model.ts", "path": "src\\models\\medieval-kit\\wooden-stool\\model.ts",
@ -272,7 +272,7 @@
"address": "@medieval-kit/cart-wheel", "address": "@medieval-kit/cart-wheel",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.717Z", "installedAt": "2026-08-27T09:26:37.673Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\cart-wheel\\model.ts", "path": "src\\models\\medieval-kit\\cart-wheel\\model.ts",
@ -287,7 +287,7 @@
"address": "@medieval-kit/log-pile", "address": "@medieval-kit/log-pile",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.733Z", "installedAt": "2026-08-27T09:26:37.692Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\log-pile\\model.ts", "path": "src\\models\\medieval-kit\\log-pile\\model.ts",
@ -302,7 +302,7 @@
"address": "@medieval-kit/trestle-table", "address": "@medieval-kit/trestle-table",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.747Z", "installedAt": "2026-08-27T09:26:37.708Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\trestle-table\\model.ts", "path": "src\\models\\medieval-kit\\trestle-table\\model.ts",
@ -317,7 +317,7 @@
"address": "@medieval-kit/wooden-chest", "address": "@medieval-kit/wooden-chest",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.755Z", "installedAt": "2026-08-27T09:26:37.718Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-chest\\model.ts", "path": "src\\models\\medieval-kit\\wooden-chest\\model.ts",
@ -332,7 +332,7 @@
"address": "@medieval-kit/hay-bale", "address": "@medieval-kit/hay-bale",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.725Z", "installedAt": "2026-08-27T09:26:37.682Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\hay-bale\\model.ts", "path": "src\\models\\medieval-kit\\hay-bale\\model.ts",
@ -347,7 +347,7 @@
"address": "@medieval-kit/pitch-torch", "address": "@medieval-kit/pitch-torch",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.737Z", "installedAt": "2026-08-27T09:26:37.697Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\pitch-torch\\model.ts", "path": "src\\models\\medieval-kit\\pitch-torch\\model.ts",
@ -362,7 +362,7 @@
"address": "@medieval-kit/wooden-bench", "address": "@medieval-kit/wooden-bench",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.752Z", "installedAt": "2026-08-27T09:26:37.715Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wooden-bench\\model.ts", "path": "src\\models\\medieval-kit\\wooden-bench\\model.ts",
@ -377,7 +377,7 @@
"address": "@medieval-kit/linen-sack", "address": "@medieval-kit/linen-sack",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.732Z", "installedAt": "2026-08-27T09:26:37.690Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\linen-sack\\model.ts", "path": "src\\models\\medieval-kit\\linen-sack\\model.ts",
@ -392,7 +392,7 @@
"address": "@medieval-kit/oak-tankard", "address": "@medieval-kit/oak-tankard",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.736Z", "installedAt": "2026-08-27T09:26:37.695Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\oak-tankard\\model.ts", "path": "src\\models\\medieval-kit\\oak-tankard\\model.ts",
@ -407,7 +407,7 @@
"address": "@medieval-kit/straw-broom", "address": "@medieval-kit/straw-broom",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.744Z", "installedAt": "2026-08-27T09:26:37.705Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\straw-broom\\model.ts", "path": "src\\models\\medieval-kit\\straw-broom\\model.ts",
@ -422,7 +422,7 @@
"address": "@medieval-kit/bronze-bell", "address": "@medieval-kit/bronze-bell",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.715Z", "installedAt": "2026-08-27T09:26:37.671Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\bronze-bell\\model.ts", "path": "src\\models\\medieval-kit\\bronze-bell\\model.ts",
@ -437,7 +437,7 @@
"address": "@medieval-kit/iron-lantern", "address": "@medieval-kit/iron-lantern",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.729Z", "installedAt": "2026-08-27T09:26:37.687Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\iron-lantern\\model.ts", "path": "src\\models\\medieval-kit\\iron-lantern\\model.ts",
@ -452,7 +452,7 @@
"address": "@medieval-kit/tavern-sign", "address": "@medieval-kit/tavern-sign",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.746Z", "installedAt": "2026-08-27T09:26:37.707Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\tavern-sign\\model.ts", "path": "src\\models\\medieval-kit\\tavern-sign\\model.ts",
@ -467,7 +467,7 @@
"address": "@medieval-kit/coin-pouch", "address": "@medieval-kit/coin-pouch",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.718Z", "installedAt": "2026-08-27T09:26:37.674Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\coin-pouch\\model.ts", "path": "src\\models\\medieval-kit\\coin-pouch\\model.ts",
@ -482,7 +482,7 @@
"address": "@medieval-kit/glass-phial", "address": "@medieval-kit/glass-phial",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.721Z", "installedAt": "2026-08-27T09:26:37.677Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\glass-phial\\model.ts", "path": "src\\models\\medieval-kit\\glass-phial\\model.ts",
@ -497,7 +497,7 @@
"address": "@medieval-kit/leather-book", "address": "@medieval-kit/leather-book",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.730Z", "installedAt": "2026-08-27T09:26:37.689Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\leather-book\\model.ts", "path": "src\\models\\medieval-kit\\leather-book\\model.ts",
@ -512,7 +512,7 @@
"address": "@medieval-kit/wicker-basket", "address": "@medieval-kit/wicker-basket",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.749Z", "installedAt": "2026-08-27T09:26:37.712Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\wicker-basket\\model.ts", "path": "src\\models\\medieval-kit\\wicker-basket\\model.ts",
@ -527,11 +527,11 @@
"address": "@medieval-kit/post-mill", "address": "@medieval-kit/post-mill",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.739Z", "installedAt": "2026-08-27T09:26:37.698Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\post-mill\\model.ts", "path": "src\\models\\medieval-kit\\post-mill\\model.ts",
"sourceHash": "226b2b20aaf8c98b5570d799d4d739a731cdd771a5d9ad9cc6fe0dff35dfb01f" "sourceHash": "e12c2276d57a4451c2beff28edf7243173bc76a1b837dbe9fc3f0b9355f88b7b"
} }
], ],
"dependencies": [ "dependencies": [
@ -542,7 +542,7 @@
"address": "@medieval-kit/stone-well", "address": "@medieval-kit/stone-well",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.743Z", "installedAt": "2026-08-27T09:26:37.703Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\stone-well\\model.ts", "path": "src\\models\\medieval-kit\\stone-well\\model.ts",
@ -557,7 +557,7 @@
"address": "@medieval-kit/hand-cart", "address": "@medieval-kit/hand-cart",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.724Z", "installedAt": "2026-08-27T09:26:37.681Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\hand-cart\\model.ts", "path": "src\\models\\medieval-kit\\hand-cart\\model.ts",
@ -572,7 +572,7 @@
"address": "@medieval-kit/iron-cauldron", "address": "@medieval-kit/iron-cauldron",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.728Z", "installedAt": "2026-08-27T09:26:37.685Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\iron-cauldron\\model.ts", "path": "src\\models\\medieval-kit\\iron-cauldron\\model.ts",
@ -587,7 +587,7 @@
"address": "@medieval-kit/vegetables", "address": "@medieval-kit/vegetables",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.748Z", "installedAt": "2026-08-27T09:26:37.710Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\vegetables\\model.ts", "path": "src\\models\\medieval-kit\\vegetables\\model.ts",
@ -602,7 +602,7 @@
"address": "@medieval-kit/forge-hearth", "address": "@medieval-kit/forge-hearth",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.719Z", "installedAt": "2026-08-27T09:26:37.676Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\forge-hearth\\model.ts", "path": "src\\models\\medieval-kit\\forge-hearth\\model.ts",
@ -617,7 +617,7 @@
"address": "@medieval-kit/round-shield", "address": "@medieval-kit/round-shield",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.740Z", "installedAt": "2026-08-27T09:26:37.700Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\round-shield\\model.ts", "path": "src\\models\\medieval-kit\\round-shield\\model.ts",
@ -632,7 +632,7 @@
"address": "@medieval-kit/stone-trough", "address": "@medieval-kit/stone-trough",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.741Z", "installedAt": "2026-08-27T09:26:37.701Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\stone-trough\\model.ts", "path": "src\\models\\medieval-kit\\stone-trough\\model.ts",
@ -647,7 +647,7 @@
"address": "@medieval-kit/grindstone", "address": "@medieval-kit/grindstone",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.722Z", "installedAt": "2026-08-27T09:26:37.679Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\grindstone\\model.ts", "path": "src\\models\\medieval-kit\\grindstone\\model.ts",
@ -662,7 +662,7 @@
"address": "@medieval-kit/market-stall", "address": "@medieval-kit/market-stall",
"source": "file:my-registry/dist/registry.json", "source": "file:my-registry/dist/registry.json",
"version": "workspace", "version": "workspace",
"installedAt": "2026-08-27T08:39:24.734Z", "installedAt": "2026-08-27T09:26:37.694Z",
"files": [ "files": [
{ {
"path": "src\\models\\medieval-kit\\market-stall\\model.ts", "path": "src\\models\\medieval-kit\\market-stall\\model.ts",

View file

@ -10,9 +10,19 @@ own tree, not an opaque package boundary.
## Install ## Install
Point `models.json` at the registry. This step is not optional and it is not ```sh
last: `vibe3d add` resolves `@medieval-kit` through this map and stops with bunx vibe3d init
`Registry @medieval-kit is not configured in models.json` if it is missing. bun add three
bun add -d @types/three
```
`init` writes `models.json` and puts the shared Vibe3D runtime under
`src/lib/vibe3d/`, which the installed models import from. `@types/three` is a
dev dependency and not optional: `three` ships no type declarations of its own,
so without it the source you just installed does not typecheck.
`init` seeds `models.json` with `@scifi-kit` only, so add this registry to the
`registries` object it created:
```json ```json
{ {
@ -25,6 +35,9 @@ last: `vibe3d add` resolves `@medieval-kit` through this map and stops with
} }
``` ```
That map is how the namespace resolves — `vibe3d add` stops with
`Registry @medieval-kit is not configured in models.json` without it.
Then take one model, or the lot: Then take one model, or the lot:
```sh ```sh
@ -32,6 +45,30 @@ bunx vibe3d add @medieval-kit/wooden-barrel
bunx vibe3d add @medieval-kit bunx vibe3d add @medieval-kit
``` ```
### Project setup
The installed source imports through the `@/` alias that `models.json` declares,
and it imports `.ts` files by their extension. Both have to be true on your side
as well — in `tsconfig.json`:
```json
{
"compilerOptions": {
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"baseUrl": ".",
"paths": { "@/*": ["./src/*"] }
}
}
```
and in your bundler, because TypeScript's `paths` only teaches the type checker.
For Vite:
```ts
resolve: { alias: [{ find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) }] }
```
## Models ## Models
37 models and one shared lib. Addresses are `@medieval-kit/<id>`. This table is 37 models and one shared lib. Addresses are `@medieval-kit/<id>`. This table is
@ -68,16 +105,16 @@ did once.
| `wooden-hoe` | Tools | 394 | 3 | 0.23×1.23×0.33 | oak, iron, steel | | | `wooden-hoe` | Tools | 394 | 3 | 0.23×1.23×0.33 | oak, iron, steel | |
| `wooden-shovel` | Tools | 496 | 3 | 0.27×1.20×0.08 | oak, iron | | | `wooden-shovel` | Tools | 496 | 3 | 0.27×1.20×0.08 | oak, iron | |
| `wooden-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | | | `wooden-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | |
| `iron-cauldron` | Lighting | 1134 | 3 | 1.09×1.37×1.10 | stone, iron, char, ember | | | `iron-cauldron` | Lighting | 1134 | 3 | 1.09×1.37×1.10 | stone, iron, char, ember | ✔ |
| `hand-cart` | Structure | 2044 | 4 | 0.88×1.03×2.60 | oak, iron | | | `hand-cart` | Structure | 2044 | 4 | 0.87×0.68×2.49 | oak, iron | ✔ |
| `vegetables` | Props | 1718 | 2 | 0.60×0.12×0.59 | produce | | | `vegetables` | Props | 1718 | 2 | 0.60×0.12×0.59 | produce | |
| `round-shield` | Arms | 729 | 3 | 0.73×0.73×0.17 | oak, leather, iron | | | `round-shield` | Arms | 729 | 3 | 0.73×0.73×0.17 | oak, leather, iron | |
| `forge-hearth` | Smithy | 1426 | 4 | 2.06×1.78×0.87 | stone, char, ember, oak, leather, iron | | | `forge-hearth` | Smithy | 1426 | 4 | 2.06×1.78×0.87 | stone, char, ember, oak, leather, iron | ✔ |
| `stone-well` | Structure | 1376 | 4 | 1.88×2.00×1.28 | stone, oak, iron, cloth | | | `stone-well` | Structure | 1376 | 4 | 1.88×2.00×1.28 | stone, oak, iron, cloth | ✔ |
| `stone-trough` | Structure | 344 | 2 | 1.52×0.45×0.60 | stone, water | | | `stone-trough` | Structure | 344 | 2 | 1.52×0.45×0.60 | stone, water | |
| `grindstone` | Smithy | 568 | 4 | 1.24×0.95×0.70 | stone, oak, iron, water | | | `grindstone` | Smithy | 568 | 4 | 1.24×0.95×0.70 | stone, oak, iron, water | ✔ |
| `market-stall` | Structure | 384 | 4 | 1.83×2.03×0.97 | oak, cloth | | | `market-stall` | Structure | 384 | 4 | 1.83×2.03×0.97 | oak, cloth | |
| `post-mill` | Structure | 1672 | 4 | 6.60×7.23×6.98 | oak, iron | | | `post-mill` | Structure | 1672 | 4 | 6.60×7.23×6.98 | oak, iron | ✔ |
**30 390 triangles** in total. The whole kit in one scene costs less than a **30 390 triangles** in total. The whole kit in one scene costs less than a
single mid-complexity character model. single mid-complexity character model.
@ -121,9 +158,12 @@ Each model follows the Vibe3D protocol:
`part.content` is rebuilt. `part.content` is rebuilt.
- **`materials`** resolve per slot and can be overridden. Materials you supply - **`materials`** resolve per slot and can be overridden. Materials you supply
are borrowed: the model never disposes them. are borrowed: the model never disposes them.
- **`actions`** and **`update(delta)`** carry interactive state. Five models use - **`actions`** and **`update(delta)`** carry interactive state. Eleven models
both — `wooden-chest`, `pitch-torch`, `iron-lantern`, `bronze-bell` and have them, and they are the ✔ column in the table above: `wooden-chest`,
`tavern-sign`: `pitch-torch`, `iron-lantern`, `bronze-bell`, `tavern-sign`, `iron-cauldron`,
`hand-cart`, `forge-hearth`, `stone-well`, `grindstone` and `post-mill`. Crank
the grindstone and it turns and slows; set the mill turning and its sails go
round; lower the well's bucket down the shaft:
```ts ```ts
const chest = createModel() const chest = createModel()
@ -185,6 +225,9 @@ are derived from the source — an import from `../core/` makes
list to go stale. list to go stale.
`drafts/` is deliberately outside that walk: the code is kept in the tree but `drafts/` is deliberately outside that walk: the code is kept in the tree but
never reaches the published package. See [`drafts/README.md`](drafts/README.md). never reaches the published package — including its own `drafts/README.md`,
which is why this sentence does not link to it. A relative link on an npm
package page resolves against the repository, and there is nothing at the
other end of it for a reader of this page.
Released under the MIT License. Released under the MIT License.

View file

@ -495,6 +495,26 @@ export function createModel(overrides: Partial<PostMillConfig> = {}) {
steps.push(rung) steps.push(rung)
} }
/**
* Then MEASURE the foot and put it on the ground, rather than reasoning
* about where it ended up.
*
* `liftY` above is two analytic corrections to the same corner, and both
* are right about the thing they describe. What neither accounts for is
* the chamfer: the rail is a chamfered box, so the corner they compute
* the drop of has been cut off, and the ladder came to rest 14.5 mm high
* — very nearly the chamfer itself. That is the third arithmetic mistake
* at this one corner; the comments above are the first two.
*
* A bounding box cannot be wrong about this the way a derivation can, and
* it stays right when the chamfer, the taper or the rail section change.
* The head is buried in the gallery by a 3% overrun that is several times
* this shift, so moving the assembly does not pull it out.
*/
const ladder = mergeColoured(steps)
ladder.computeBoundingBox()
ladder.translate(0, floor - ladder.boundingBox!.min.y, 0)
return { return {
trestle: { slot: 'oak' as const, geometry: mergeColoured(timber) }, trestle: { slot: 'oak' as const, geometry: mergeColoured(timber) },
body: { slot: 'oak' as const, geometry: mergeColoured(shell) }, body: { slot: 'oak' as const, geometry: mergeColoured(shell) },
@ -509,7 +529,7 @@ export function createModel(overrides: Partial<PostMillConfig> = {}) {
extras: [{ slot: 'iron' as const, geometry: shaftBands }], extras: [{ slot: 'iron' as const, geometry: shaftBands }],
origin: [0, hubY, hubZ] as const, origin: [0, hubY, hubZ] as const,
}, },
ladder: { slot: 'oak' as const, geometry: mergeColoured(steps) }, ladder: { slot: 'oak' as const, geometry: ladder },
} }
}, },

View file

@ -5,7 +5,7 @@
"type": "module", "type": "module",
"license": "MIT", "license": "MIT",
"author": "CRTkafa", "author": "CRTkafa",
"homepage": "https://github.com/CRTkafa/medieval-kit#readme", "homepage": "https://medieval.crt.fyi/",
"repository": { "repository": {
"type": "git", "type": "git",
"url": "git+https://github.com/CRTkafa/medieval-kit.git", "url": "git+https://github.com/CRTkafa/medieval-kit.git",

View file

@ -8,10 +8,75 @@
* *
* bun scripts/catalog-table.ts * bun scripts/catalog-table.ts
*/ */
import { Box3, Mesh } from 'three/webgpu' import { Box3, Mesh, type Object3D } from 'three/webgpu'
import { MODEL_META } from '../my-registry/meta.ts' import { MODEL_META } from '../my-registry/meta.ts'
import { CATALOG } from '@/catalog.ts' import { CATALOG, type Entry } from '@/catalog.ts'
/**
* Whether a model moves — decided by RUNNING it, not by asking it.
*
* Both of the obvious flags lie. `built.action` is the viewer's hand-registered
* button descriptor from src/catalog.ts and only five models are given one, so
* the column called the grindstone, the stone well and the post mill static.
* `built.update` is worse: core/kit.ts wraps it as
* `update: (dt) => options.update?.(dt, runtime)`, so it is a function on every
* model whether or not that model does anything with it, and swapping to it
* marked all thirty-seven animated. One flag was too narrow, its replacement
* too broad, and neither is what the column claims to mean.
*
* So: take the model, drive a second of frames through it, and see whether
* anything moved. Where a model's motion is gated behind an action — the chest
* lid only eases once something has opened it — fire the action and drive it
* again. Deterministic seeding makes this reproducible, so the table stays
* stable between runs.
*/
function animates(entry: Entry): boolean {
const snapshot = (root: Object3D): string => {
root.updateMatrixWorld(true)
const out: number[] = []
root.traverse((object) => {
out.push(...object.matrixWorld.elements)
if (object instanceof Mesh) {
// Motion can be in the geometry rather than the transform — a flame is
// rebuilt, not moved — so a sample of the vertices comes along too.
const position = object.geometry.getAttribute('position')
if (position) {
const step = Math.max(1, Math.floor(position.count / 24))
for (let i = 0; i < position.count; i += step) {
out.push(position.getX(i), position.getY(i), position.getZ(i))
}
}
}
})
return out.map((n) => n.toFixed(5)).join(',')
}
const built = entry.build()
// A model with typed actions of its own is a model that does something, and
// no amount of running it will show that from the outside: the grindstone
// only turns once something cranks it, and this generator is not going to
// learn each model's interface to find out. Running it catches what moves by
// itself, `actionNames` catches what moves on demand, and between them the
// column says what a reader takes it to say.
if ((built.actionNames?.length ?? 0) > 0) {
built.dispose()
return true
}
const still = snapshot(built.root)
const run = (frames: number): void => {
for (let i = 0; i < frames; i += 1) built.update?.(1 / 60)
}
run(60)
let moved = snapshot(built.root) !== still
if (!moved && built.action) {
built.action.run()
run(120)
moved = snapshot(built.root) !== still
}
built.dispose()
return moved
}
const rows: string[] = [] const rows: string[] = []
let total = 0 let total = 0
@ -30,7 +95,20 @@ for (const id of Object.keys(CATALOG)) {
}) })
const box = new Box3().setFromObject(built.root) const box = new Box3().setFromObject(built.root)
const size = box.getSize(box.max.clone()) const size = box.getSize(box.max.clone())
const animated = built.action !== undefined // `update`, not `action`.
//
// `built.action` is the VIEWER's hand-registered button descriptor over in
// src/catalog.ts, and only five models are given one. What this column means
// is "this model animates", which is `update`: a model can carry a per-frame
// update without anyone having wired a button for it in the demo app.
//
// The two lists overlap enough that the column looked right, and the table
// quietly called the grindstone, the stone well and the post mill static —
// three of the most animated things in the kit. Worth noting where it was
// read: not here, but in the generated table, by someone checking the
// document against the models. The table is generated so it cannot go stale,
// and it was still wrong, because the generator was asking the wrong object.
const animated = animates(CATALOG[id]!)
built.dispose() built.dispose()
for (const slot of meta.materialSlots) slots.add(slot) for (const slot of meta.materialSlots) slots.add(slot)

View file

@ -333,6 +333,17 @@ interface Case {
* the axis had been run to the floor instead — so its wheels were still * the axis had been run to the floor instead — so its wheels were still
* fractionally clear of the ground after the big fix. A loose tolerance * fractionally clear of the ground after the big fix. A loose tolerance
* would have called that done. * would have called that done.
*
* The floor is the model's own lowest point, and that is worth knowing
* before declaring this on anything: a part that is deliberately BEDDED into
* the ground drags that datum down and makes every correctly placed part
* look as though it floats by exactly the bedding depth. The forge's base
* stones settle 6.8 mm and the well's drystone kerb 9.3 mm, both on purpose,
* and reading their neighbours against the bounding box is what made me
* report two more floating parts than there were. So this belongs on models
* whose ground contacts are meant to be LEVEL with each other, and every one
* of them has to be named — a part left out is a part the tolerance is then
* measured against.
*/ */
readonly restsOn?: readonly string[] readonly restsOn?: readonly string[]
} }
@ -392,6 +403,7 @@ const CASES: readonly Case[] = [
variants: [{ courses: 2 }, { depth: 1 }, { blocks: 6 }], variants: [{ courses: 2 }, { depth: 1 }, { blocks: 6 }],
maxSize: [2.2, 2.2, 1.7] }, maxSize: [2.2, 2.2, 1.7] },
{ id: 'post-mill', make: as(createMill), patch: { sailBars: 12, ladderRungs: 17 }, { id: 'post-mill', make: as(createMill), patch: { sailBars: 12, ladderRungs: 17 },
restsOn: ['trestle', 'ladder'],
parts: 4, ownSlot: 'oak', borrowSlot: 'iron', parts: 4, ownSlot: 'oak', borrowSlot: 'iron',
variants: [{ sailBars: 3 }, { sailWidth: 0.28 }, { height: 3.5 }], variants: [{ sailBars: 3 }, { sailWidth: 0.28 }, { height: 3.5 }],
maxSize: [8.2, 9.0, 7.4] }, maxSize: [8.2, 9.0, 7.4] },

View file

@ -100,6 +100,8 @@ export interface Entry {
build(): { build(): {
root: Group root: Group
update?: (deltaSeconds: number) => void update?: (deltaSeconds: number) => void
/** Names of the model's own typed actions. Empty when it has none. */
actionNames?: readonly string[]
action?: { label(): string; run(): void } action?: { label(): string; run(): void }
params?: ParamGroup params?: ParamGroup
inspect?: Inspection inspect?: Inspection
@ -292,6 +294,18 @@ function entryFor(id: string): Entry {
return { return {
root: model.root, root: model.root,
update: (dt) => { model.update(dt) }, update: (dt) => { model.update(dt) },
/**
* The names of the model's OWN typed actions.
*
* Distinct from `action` below, which is the single button this demo
* registers by hand for five models. A model can carry a whole set of
* actions and have no button: the grindstone is cranked, the mill's
* sails are set turning, the well's bucket is lowered. Nothing outside
* the model could see any of that, so the generated table called those
* three static — a document wrong about the most animated things in
* the kit, and generated, so nobody thought to doubt it.
*/
actionNames: Object.keys((model as { actions?: object }).actions ?? {}),
...(action ? { action } : {}), ...(action ? { action } : {}),
params: { params: {
specs, specs,

View file

@ -495,6 +495,26 @@ export function createModel(overrides: Partial<PostMillConfig> = {}) {
steps.push(rung) steps.push(rung)
} }
/**
* Then MEASURE the foot and put it on the ground, rather than reasoning
* about where it ended up.
*
* `liftY` above is two analytic corrections to the same corner, and both
* are right about the thing they describe. What neither accounts for is
* the chamfer: the rail is a chamfered box, so the corner they compute
* the drop of has been cut off, and the ladder came to rest 14.5 mm high
* — very nearly the chamfer itself. That is the third arithmetic mistake
* at this one corner; the comments above are the first two.
*
* A bounding box cannot be wrong about this the way a derivation can, and
* it stays right when the chamfer, the taper or the rail section change.
* The head is buried in the gallery by a 3% overrun that is several times
* this shift, so moving the assembly does not pull it out.
*/
const ladder = mergeColoured(steps)
ladder.computeBoundingBox()
ladder.translate(0, floor - ladder.boundingBox!.min.y, 0)
return { return {
trestle: { slot: 'oak' as const, geometry: mergeColoured(timber) }, trestle: { slot: 'oak' as const, geometry: mergeColoured(timber) },
body: { slot: 'oak' as const, geometry: mergeColoured(shell) }, body: { slot: 'oak' as const, geometry: mergeColoured(shell) },
@ -509,7 +529,7 @@ export function createModel(overrides: Partial<PostMillConfig> = {}) {
extras: [{ slot: 'iron' as const, geometry: shaftBands }], extras: [{ slot: 'iron' as const, geometry: shaftBands }],
origin: [0, hubY, hubZ] as const, origin: [0, hubY, hubZ] as const,
}, },
ladder: { slot: 'oak' as const, geometry: mergeColoured(steps) }, ladder: { slot: 'oak' as const, geometry: ladder },
} }
}, },