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:
parent
84a4bca24a
commit
21b0393e1f
3 changed files with 75 additions and 33 deletions
44
README.md
44
README.md
|
|
@ -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.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
## 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
BIN
media/kit.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 344 KiB |
|
|
@ -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.
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
```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
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue