The largest thing in the kit, and the one whose name is its whole design: the entire body -- millstones, gearing, miller and all -- is balanced on one massive vertical post and turns bodily on it, so the sails can be pointed into whatever wind there is. The miller does that by walking the tail ladder round, which is why the ladder is not a way up but a lever, and why it reaches so far behind the mill. Four parts, in the order the thing is built: `trestle` (two cross-trees, the post standing on them, four quarter-bars), `body` (the boarded buck and its pitched roof), `sails` (a windshaft leaving the front gable, with its own origin so `setTurning` spins it alone), and `ladder`. `setTurning`, `setAngle` and `update` drive the sails at about ten revolutions a minute -- a working mill turns slowly, not in the blur people draw. The sails are where the triangles went, and deliberately. A sail is not a blade, it is a LATTICE the miller dresses with canvas according to the wind. Drawn solid the silhouette is wrong in the one place everyone looks, so the bars are modelled and the budget is taken from the buck's boarding, which reads perfectly well as vertex colour. 1 516 triangles. Four faults on the way in, all found by measuring rather than by looking: The roof pitches were built `slope * 2` long and tilted by the complement of the roof angle, which made two panels 2.79 m across a building 1.80 m wide, standing up like the covers of an open book. Each pitch covers half a roof, and the tilt is measured from the horizontal because `chamferedBoxGeometry` takes an X-Z footprint. The rails of the tail ladder were tilted the wrong way round. `run` is positive -- the head sits at a larger z than the foot -- so rotating by `-lean` laid the rails along the opposite diagonal to the one the rungs were placed on. They crossed near the middle and diverged towards the ends, and the bounding box looked correct the whole time because the translation put the ladder where it belonged and only its internals were wrong. The support audit found it as loose rungs, and found it only at the small end of the height slider, where the voxel grid is fine enough not to bridge the gap: the joint was never real at any size. Fixing the ladder's foot, which sat 0.10 m below the cross-trees so the mill hovered above whatever it was placed on, then displaced the rails perpendicular to their own axis by almost exactly a rung's half-depth -- correcting the rails alone was worse than not correcting at all. Rails and rungs now share one lift. And the lowest sail tip came within 0.27 m of the ground, which reads as a mill about to plough its own field. 28 models, 20 523 triangles, all checks pass, 0 floating cases, GLB round-trip clean, Conformant at 30 items, build clean.
171 lines
7.5 KiB
Markdown
171 lines
7.5 KiB
Markdown
# Medieval Kit
|
|
|
|
A lowpoly medieval model library for [Vibe3D](https://github.com/vibe-stack/vibe3d)
|
|
and Three.js. Install a prop and you own its source: readable TypeScript in your
|
|
own tree, not an opaque package boundary.
|
|
|
|

|
|
|
|
```sh
|
|
bunx vibe3d add @medieval-kit/wooden-barrel
|
|
bunx vibe3d add @medieval-kit
|
|
```
|
|
|
|
Configure `models.json` first so the namespace resolves:
|
|
|
|
```json
|
|
{
|
|
"registries": {
|
|
"@medieval-kit": {
|
|
"source": "npm:@medieval-kit/registry",
|
|
"version": "latest"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Models
|
|
|
|
28 models and one shared lib. Addresses are `@medieval-kit/<id>`. This table is
|
|
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
|
|
did once.
|
|
|
|
| Model | Category | Triangles | Parts | Size (m) | Material slots | Animated |
|
|
| --- | --- | ---: | ---: | --- | --- | :-: |
|
|
| `wooden-chest` | Furniture | 552 | 4 | 0.86×0.51×0.48 | oak, iron | ✔ |
|
|
| `wooden-barrel` | Props | 1690 | 3 | 0.83×1.05×0.83 | oak, iron | |
|
|
| `wooden-crate` | Props | 1320 | 3 | 0.69×0.52×0.55 | oak, iron | |
|
|
| `wooden-bucket` | Props | 439 | 4 | 0.31×0.46×0.30 | oak, iron | |
|
|
| `trestle-table` | Furniture | 660 | 3 | 1.91×0.74×0.78 | oak | |
|
|
| `wooden-bench` | Furniture | 216 | 3 | 1.62×0.49×0.30 | oak | |
|
|
| `wooden-stool` | Furniture | 180 | 2 | 0.38×0.43×0.36 | oak | |
|
|
| `pitch-torch` | Lighting | 239 | 3 | 0.13×0.70×0.13 | oak, char, ember | ✔ |
|
|
| `iron-lantern` | Lighting | 480 | 4 | 0.15×0.30×0.17 | iron, glass, char, ember | ✔ |
|
|
| `iron-anvil` | Smithy | 256 | 6 | 0.54×0.75×0.41 | iron, steel, oak | |
|
|
| `cart-wheel` | Structure | 1136 | 4 | 1.04×1.06×0.19 | oak, iron | |
|
|
| `log-pile` | Props | 924 | 2 | 0.98×0.58×0.71 | oak | |
|
|
| `hay-bale` | Props | 910 | 3 | 1.04×0.42×0.43 | straw, cloth | |
|
|
| `linen-sack` | Props | 342 | 3 | 0.34×0.53×0.33 | cloth | |
|
|
| `oak-tankard` | Props | 390 | 4 | 0.11×0.16×0.14 | oak, iron | |
|
|
| `straw-broom` | Tools | 1048 | 3 | 0.30×1.22×0.30 | oak, straw, cloth | |
|
|
| `bronze-bell` | Props | 1048 | 4 | 0.51×0.68×0.36 | brass, iron, oak | ✔ |
|
|
| `tavern-sign` | Props | 888 | 3 | 0.72×2.29×0.86 | oak, iron | ✔ |
|
|
| `wicker-basket` | Props | 2326 | 3 | 0.34×0.16×0.35 | oak, produce | |
|
|
| `leather-book` | Props | 440 | 3 | 0.20×0.08×0.27 | leather, cloth, brass | |
|
|
| `glass-phial` | Props | 339 | 3 | 0.06×0.14×0.06 | glass, ember, oak, char | |
|
|
| `coin-pouch` | Props | 602 | 3 | 0.18×0.11×0.19 | leather, cloth, brass | |
|
|
| `wooden-ladder` | Structure | 440 | 2 | 0.49×2.20×0.06 | oak | |
|
|
| `wooden-fence` | Structure | 860 | 2 | 5.18×1.31×0.31 | oak | |
|
|
| `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-pitchfork` | Tools | 392 | 3 | 0.27×1.58×0.15 | oak, iron | |
|
|
| `post-mill` | Structure | 1516 | 4 | 6.60×7.22×6.98 | oak, iron | |
|
|
|
|
**20 523 triangles** in total. The whole kit in one scene costs less than a
|
|
single mid-complexity character model.
|
|
|
|
Every model depends on `@medieval-kit/core`, a shared support item holding the
|
|
palette, deterministic randomness, and the geometry vocabulary. Pulling a single
|
|
prop brings it along, so an individually installed crate still looks like it
|
|
came from the same catalogue as the barrel beside it.
|
|
|
|
## Plain WebGL
|
|
|
|
This kit does **not** require WebGPU. It declares `capabilities: []` and builds
|
|
on `MeshStandardMaterial` and `MeshBasicMaterial`, so it renders on
|
|
`WebGLRenderer` as well as `WebGPURenderer`.
|
|
|
|
## Configuration
|
|
|
|
Models are procedural, not baked. Every prop exposes typed fields:
|
|
|
|
```ts
|
|
import { createModel } from '@/models/medieval-kit/wooden-barrel/model.ts'
|
|
|
|
const barrel = createModel({ staveCount: 17, taper: 0.22, seed: 42 })
|
|
scene.add(barrel.root)
|
|
|
|
barrel.configure({ hoopCount: 6 }) // rebuilds geometry inside a stable root
|
|
barrel.dispose()
|
|
```
|
|
|
|
`seed` is a real field, not a debug knob. Variation is deterministic: the same
|
|
seed always produces the same prop, so previews, tests, and art direction stay
|
|
reproducible. Change the seed to get a different barrel from the same model.
|
|
|
|
## Runtime anatomy
|
|
|
|
Each model follows the Vibe3D protocol:
|
|
|
|
- **`root`** keeps its object identity for the model's whole lifetime.
|
|
- **`parts`** expose stable semantic anchors. Attach your own lights, labels, or
|
|
gameplay objects to `part.anchor` — they survive `configure()`, because only
|
|
`part.content` is rebuilt.
|
|
- **`materials`** resolve per slot and can be overridden. Materials you supply
|
|
are borrowed: the model never disposes them.
|
|
- **`actions`** and **`update(delta)`** carry interactive state. Five models use
|
|
both — `wooden-chest`, `pitch-torch`, `iron-lantern`, `bronze-bell` and
|
|
`tavern-sign`:
|
|
|
|
```ts
|
|
const chest = createModel()
|
|
chest.actions.setOpen(true)
|
|
chest.update(deltaSeconds) // the lid eases open, frame-rate independent
|
|
|
|
const torch = createModel()
|
|
torch.actions.setLit(false)
|
|
torch.update(deltaSeconds) // flame flicker and light modulation
|
|
```
|
|
|
|
A model that never receives `update()` simply stands still; nothing animates
|
|
behind your back. Reach for `configure()` when a user changes a setting; it
|
|
rebuilds topology and is not cheap. Anything that changes per frame belongs in
|
|
`update()`.
|
|
|
|
## Material slots
|
|
|
|
Eleven slots, and each one exists because a single material could not carry the
|
|
difference.
|
|
|
|
| Slot | What it covers | Why it is separate |
|
|
| --- | --- | --- |
|
|
| `oak` | timber | — |
|
|
| `iron` | forged iron, oxidised and matte | separate from `steel`: the difference is not in colour but in ROUGHNESS, and vertex colour cannot carry roughness |
|
|
| `steel` | steel polished by use | the anvil face, the shovel blade, the pitchfork tines |
|
|
| `brass` | bronze and copper | the bell, the coins |
|
|
| `straw` | straw, wicker, broom bristle | a bale declaring itself "oak" would be a lie told to the consumer |
|
|
| `cloth` | linen, sackcloth, rope | — |
|
|
| `leather` | worked leather | — |
|
|
| `glass` | blown glass | transparent, `depthWrite` OFF, `DoubleSide` |
|
|
| `produce` | fruit and vegetable skin | given straw's roughness, an apple would look like dry grass |
|
|
| `ember` | flame | `MeshBasicMaterial` — it does not receive light, it emits |
|
|
| `char` | charcoal and pitch | — |
|
|
|
|
`ember` also acts as a rule in two places: bodies in that slot are skipped
|
|
entirely while ambient occlusion and mottle are baked. The reason is simple —
|
|
in an unlit material the vertex colour *is* the final colour, so darkening it
|
|
puts the flame out. The rule is attached to the slot itself rather than to a
|
|
per-model flag, so it cannot be forgotten.
|
|
|
|
Colour variation lives in the geometry, not in the materials: each of the
|
|
barrel's 17 staves carries its own tone as vertex colours, and all of them share
|
|
one material and therefore one draw call.
|
|
|
|
## Building from source
|
|
|
|
```sh
|
|
bun build.ts # emit dist/registry.json
|
|
bunx vibe3d registry validate dist/registry.json
|
|
```
|
|
|
|
The build walks `models/`. A folder containing `model.ts` becomes a
|
|
`vibe3d:model`; any other folder becomes a `vibe3d:lib`. Registry dependencies
|
|
are derived from the source — an import from `../core/` makes
|
|
`@medieval-kit/core` a dependency automatically, so there is no hand-maintained
|
|
list to go stale.
|
|
|
|
`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).
|
|
|
|
Released under the MIT License.
|