Bring both READMEs up to date, and give them a picture

The registry README's model table was generated once and had gone stale in
exactly the way its own note warns about: it claimed 15 425 triangles
against the current 19 007, listed a barrel at 806 triangles that now has
rivets and six hoops at 1 690, and described "the barrel's 13 staves" when
there are 17. Regenerated from the models themselves.

Both READMEs now open with a contact sheet of the whole kit. It lives in a
tracked `media/` directory rather than in `renders/`, which is ignored
because it is rebuilt output -- a README cannot reference a file that is not
in the repository. The registry's copy points at the raw GitHub URL, since
the npm package ships only dist, README and LICENSE and a relative path
would resolve to nothing there.

The root README gains a Showcase section -- the 60 s default, why it is the
default rather than 30 s, and what makes the variation visible -- and the
support check as a fifth note among the checks worth explaining. It is the
most distinctive thing in the suite and the only one that catches a whole
class of fault the others are blind to by construction.

Also: the check count in that section said ~500 and the suite now runs 818.
This commit is contained in:
CRTkafa 2026-08-23 12:25:14 +07:00
parent 84a4bca24a
commit 21b0393e1f
3 changed files with 75 additions and 33 deletions

View file

@ -12,6 +12,8 @@ on an opaque package. This repository holds one such registry.
- **`src/`** — a demo app that installs from both `@medieval-kit` and the - **`src/`** — a demo app that installs from both `@medieval-kit` and the
first-party `@scifi-kit`, so the two can be inspected side by side. first-party `@scifi-kit`, so the two can be inspected side by side.
![The whole kit](media/kit.png)
## Run the viewer ## Run the viewer
Requires [Bun](https://bun.sh) and a browser with WebGPU (the `@scifi-kit` model Requires [Bun](https://bun.sh) and a browser with WebGPU (the `@scifi-kit` model
@ -58,13 +60,13 @@ bun run verify:glb # export every model, read it back, compare
bun run render # renders/_sheet.png — actually look at the models bun run render # renders/_sheet.png — actually look at the models
``` ```
`verify` runs ~500 browser-free checks against the installed sources: geometry `verify` runs ~800 browser-free checks against the installed sources: geometry
validity, winding, coplanar-face (z-fighting) detection, bounding-box limits, validity, winding, coplanar-face (z-fighting) detection, bounding-box limits,
stable root and anchor identity across `configure()`, deterministic seeding, stable root and anchor identity across `configure()`, deterministic seeding,
material ownership, idempotent disposal, action semantics, and agreement material ownership, idempotent disposal, action semantics, and agreement
between each model and its published metadata. between each model and its published metadata.
Four of those deserve a note, because each was written after a real bug: Five of those deserve a note, because each was written after a real bug:
- **Winding** is checked three ways, because no single measure is sufficient. - **Winding** is checked three ways, because no single measure is sufficient.
Bodies of revolution use radial alignment — every radial face on the outer Bodies of revolution use radial alignment — every radial face on the outer
@ -85,6 +87,16 @@ Four of those deserve a note, because each was written after a real bug:
- **Frame-rate independence** for animated models: the same elapsed time is - **Frame-rate independence** for animated models: the same elapsed time is
stepped at two different frame rates and the results must agree. A naive lerp stepped at two different frame rates and the results must agree. A naive lerp
fails this. fails this.
- **Nothing floats.** Every check above asks about surfaces, and none of them
can see a piece of a model hanging in the air with nothing under it — a chest
lid separated from its chest passed all of them. `scripts/support.ts`
voxelises the model, finds the connected components of occupied space, and
requires each one to reach the floor. `scripts/audit.ts` runs that across the
default, both slider extremes, both ends of a sweep, every action and the
midpoint of a morph, because a variation must not break what the default gets
right. It began at 22 failing cases: the bell and the sign had no supporting
structure at all, the lantern was in four pieces, and the ladder's rungs were
sized by a formula that disagreed with where its rails actually were.
Every check was mutation-tested: sabotage the code, confirm the check fails, Every check was mutation-tested: sabotage the code, confirm the check fails,
restore, confirm it passes. A passing test is not evidence that it works. restore, confirm it passes. A passing test is not evidence that it works.
@ -96,6 +108,30 @@ The renderer is a small software rasteriser: no browser, no GPU. The shovel was
rewritten a fourth time, the hoe a third and the hay bale a second because of rewritten a fourth time, the hoe a third and the hay bale a second because of
what those PNGs showed. what those PNGs showed.
## Showcase
The viewer can play itself. A tour orbits the whole catalogue on one continuous
camera move, morphing each model's parameters as it goes, with the interface
hidden so the frame is clean enough to record.
```text
viewer.html?showcase=60
```
**60 s is the default.** The tour splits its running time equally between the
models, so with 27 of them a 30 s run gives each 1.1 seconds — which is a flyby,
not a demonstration. At 60 s each model gets 2.2 s, which is enough for the
sweep to read.
Two things make the variation visible rather than merely present. Continuous
controls travel the whole usable band every beat instead of two random draws
inside it. And every beat is split in half so that the *integer* controls —
stave count, plank count, spokes, rows, tines — can change at the midpoint,
where the same dip that hides a model swap hides the rebuild. Those are the
parameters a viewer actually notices, and morphing cannot interpolate them,
so before the split they were pinned for the whole beat and the tour looked
static.
## Layout ## Layout
```text ```text
@ -115,8 +151,12 @@ scripts/
verify-model.ts browser-free conformance checks verify-model.ts browser-free conformance checks
verify-glb.ts export/re-import round trip verify-glb.ts export/re-import round trip
zfight.ts coplanar overlap detection zfight.ts coplanar overlap detection
support.ts voxel connectivity — nothing may float
audit.ts runs the support check across every configuration
render.ts offline software rasteriser → PNG contact sheet render.ts offline software rasteriser → PNG contact sheet
reference-shots.ts one photographic reference per model, for comparison
export-glb.ts batch GLB export export-glb.ts batch GLB export
media/ images used by this README
models.json which registries this project resolves models.json which registries this project resolves
models.lock.json install receipt; `vibe3d diff` compares against it models.lock.json install receipt; `vibe3d diff` compares against it
``` ```

BIN
media/kit.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 344 KiB

View file

@ -4,6 +4,8 @@ A lowpoly medieval model library for [Vibe3D](https://github.com/vibe-stack/vibe
and Three.js. Install a prop and you own its source: readable TypeScript in your and Three.js. Install a prop and you own its source: readable TypeScript in your
own tree, not an opaque package boundary. own tree, not an opaque package boundary.
![The whole kit](https://raw.githubusercontent.com/CRTkafa/medieval-kit/main/media/kit.png)
```sh ```sh
bunx vibe3d add @medieval-kit/wooden-barrel bunx vibe3d add @medieval-kit/wooden-barrel
bunx vibe3d add @medieval-kit bunx vibe3d add @medieval-kit
@ -29,37 +31,37 @@ generated from the models themselves with `bun scripts/catalog-table.ts` — a
hand-written list goes stale on the first model you add, and this one already hand-written list goes stale on the first model you add, and this one already
did once. did once.
| Model | Category | Triangles | Size (m) | Material slots | Actions | | Model | Category | Triangles | Parts | Size (m) | Material slots | Animated |
| --- | --- | ---: | --- | --- | :-: | | --- | --- | ---: | ---: | --- | --- | :-: |
| `wooden-chest` | Furniture | 552 | 0.86×0.51×0.48 | oak, iron | ✔ | | `wooden-chest` | Furniture | 552 | 4 | 0.86×0.51×0.48 | oak, iron | ✔ |
| `wooden-barrel` | Props | 806 | 0.82×1.05×0.81 | oak, iron | | | `wooden-barrel` | Props | 1690 | 3 | 0.83×1.05×0.83 | oak, iron | |
| `wooden-crate` | Props | 1320 | 0.69×0.52×0.55 | oak, iron | | | `wooden-crate` | Props | 1320 | 3 | 0.69×0.52×0.55 | oak, iron | |
| `wooden-bucket` | Props | 439 | 0.31×0.46×0.30 | oak, iron | | | `wooden-bucket` | Props | 439 | 4 | 0.31×0.46×0.30 | oak, iron | |
| `trestle-table` | Furniture | 660 | 1.91×0.74×0.79 | oak | | | `trestle-table` | Furniture | 660 | 3 | 1.91×0.74×0.78 | oak | |
| `wooden-bench` | Furniture | 168 | 1.62×0.48×0.30 | oak | | | `wooden-bench` | Furniture | 216 | 3 | 1.62×0.49×0.30 | oak | |
| `wooden-stool` | Furniture | 180 | 0.38×0.43×0.36 | oak | | | `wooden-stool` | Furniture | 180 | 2 | 0.38×0.43×0.36 | oak | |
| `pitch-torch` | Lighting | 239 | 0.10×0.77×0.11 | oak, char, ember | ✔ | | `pitch-torch` | Lighting | 239 | 3 | 0.13×0.70×0.13 | oak, char, ember | ✔ |
| `iron-lantern` | Lighting | 440 | 0.15×0.29×0.17 | iron, glass, char, ember | ✔ | | `iron-lantern` | Lighting | 480 | 4 | 0.15×0.30×0.17 | iron, glass, char, ember | ✔ |
| `iron-anvil` | Smithy | 220 | 0.48×0.36×0.21 | iron, steel | | | `iron-anvil` | Smithy | 256 | 6 | 0.54×0.75×0.41 | iron, steel, oak | |
| `cart-wheel` | Structure | 1056 | 0.99×1.04×0.19 | oak, iron | | | `cart-wheel` | Structure | 1136 | 4 | 1.04×1.06×0.19 | oak, iron | |
| `log-pile` | Props | 504 | 1.25×0.43×0.18 | oak | | | `log-pile` | Props | 924 | 2 | 0.98×0.58×0.71 | oak | |
| `hay-bale` | Props | 674 | 1.09×0.46×0.46 | straw, cloth | | | `hay-bale` | Props | 910 | 3 | 1.04×0.42×0.43 | straw, cloth | |
| `linen-sack` | Props | 300 | 0.32×0.53×0.32 | cloth | | | `linen-sack` | Props | 342 | 3 | 0.34×0.53×0.33 | cloth | |
| `oak-tankard` | Props | 366 | 0.09×0.17×0.10 | oak, iron | | | `oak-tankard` | Props | 390 | 4 | 0.11×0.16×0.14 | oak, iron | |
| `straw-broom` | Tools | 880 | 0.20×1.22×0.19 | oak, straw, cloth | | | `straw-broom` | Tools | 1048 | 3 | 0.30×1.22×0.30 | oak, straw, cloth | |
| `bronze-bell` | Props | 696 | 0.48×0.53×0.36 | brass, iron, oak | ✔ | | `bronze-bell` | Props | 1048 | 4 | 0.51×0.68×0.36 | brass, iron, oak | ✔ |
| `tavern-sign` | Props | 516 | 0.54×0.75×0.63 | oak, iron | ✔ | | `tavern-sign` | Props | 888 | 3 | 0.72×2.29×0.86 | oak, iron | ✔ |
| `wicker-basket` | Props | 1906 | 0.35×0.24×0.35 | straw, produce | | | `wicker-basket` | Props | 2326 | 3 | 0.34×0.16×0.35 | oak, produce | |
| `leather-book` | Props | 248 | 0.20×0.07×0.28 | leather, cloth, brass | | | `leather-book` | Props | 440 | 3 | 0.20×0.08×0.27 | leather, cloth, brass | |
| `glass-phial` | Props | 321 | 0.06×0.14×0.06 | glass, ember, oak, char | | | `glass-phial` | Props | 339 | 3 | 0.06×0.14×0.06 | glass, ember, oak, char | |
| `coin-pouch` | Props | 546 | 0.18×0.11×0.19 | leather, cloth, brass | | | `coin-pouch` | Props | 602 | 3 | 0.18×0.11×0.19 | leather, cloth, brass | |
| `wooden-ladder` | Structure | 440 | 0.49×2.20×0.06 | oak | | | `wooden-ladder` | Structure | 440 | 2 | 0.49×2.20×0.06 | oak | |
| `wooden-fence` | Structure | 860 | 5.18×1.31×0.31 | oak | | | `wooden-fence` | Structure | 860 | 2 | 5.18×1.31×0.31 | oak | |
| `wooden-hoe` | Tools | 282 | 0.20×1.23×0.30 | oak, iron, steel | | | `wooden-hoe` | Tools | 394 | 3 | 0.23×1.23×0.33 | oak, iron, steel | |
| `wooden-shovel` | Tools | 468 | 0.27×1.20×0.08 | oak, iron, steel | | | `wooden-shovel` | Tools | 496 | 3 | 0.27×1.20×0.08 | oak, iron | |
| `wooden-pitchfork` | Tools | 338 | 0.25×1.56×0.11 | oak, iron, steel | | | `wooden-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | |
**15 425 triangles** in total. The whole kit in one scene costs less than a **19 007 triangles** in total. The whole kit in one scene costs less than a
single mid-complexity character model. single mid-complexity character model.
Every model depends on `@medieval-kit/core`, a shared support item holding the Every model depends on `@medieval-kit/core`, a shared support item holding the
@ -146,7 +148,7 @@ puts the flame out. The rule is attached to the slot itself rather than to a
per-model flag, so it cannot be forgotten. per-model flag, so it cannot be forgotten.
Colour variation lives in the geometry, not in the materials: each of the Colour variation lives in the geometry, not in the materials: each of the
barrel's 13 staves carries its own tone as vertex colours, and all of them share barrel's 17 staves carries its own tone as vertex colours, and all of them share
one material and therefore one draw call. one material and therefore one draw call.
## Building from source ## Building from source