# Medieval Kit A lowpoly medieval model library for [Vibe3D](https://github.com/vibe-stack/vibe3d) and Three.js. Installing a prop puts its source in your own tree, as readable TypeScript you can edit. ![The whole kit in one scene](https://medieval.crt.fyi/kit.png) ![Every model](https://medieval.crt.fyi/models.png) ## Install ```sh bunx vibe3d init 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 { "registries": { "@medieval-kit": { "source": "npm:@medieval-kit/registry", "version": "latest" } } } ``` That map is how the namespace resolves. Without it `vibe3d add` stops with `Registry @medieval-kit is not configured in models.json`. Then take one model, or the lot: ```sh bunx vibe3d add @medieval-kit/wooden-barrel 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, "paths": { "@/*": ["./src/*"] } } } ``` No `baseUrl`. It was removed in TypeScript 7, and `paths` resolves relative to this file on its own. Verified against a clean project on 7.0.2. The alias has to be set in your bundler too, because TypeScript's `paths` only teaches the type checker. For Vite: ```ts resolve: { alias: [{ find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) }] } ``` ## Models 37 models and one shared lib. Addresses are `@medieval-kit/`. 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.45×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.99×0.58×0.70 | 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 | 876 | 3 | 0.38×2.29×0.93 | 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.16 | 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 | | | `iron-cauldron` | Lighting | 1134 | 3 | 1.09×1.37×1.10 | stone, iron, char, ember | ✔ | | `hand-cart` | Structure | 2044 | 4 | 0.87×0.68×2.49 | oak, iron | ✔ | | `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 | | | `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-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 | ✔ | | `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 | ✔ | **30 390 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. Eleven models have them, and they are the ✔ column in the table above: `wooden-chest`, `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 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 Thirteen slots, and each one exists because a single material could not carry the difference. | Slot | What it covers | Why it is separate | | --- | --- | --- | | `oak` | timber | the baseline everything else is measured against | | `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 | woven, so it takes light softly and never glints | | `leather` | worked leather | darker and glossier than cloth at the same colour | | `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 | the darkest thing in the kit, and it has to stay readable against shadow | | `water` | standing water | a thin transparent film over whatever holds it: in the reference trough the basin reads hue 39.5, which is the hue of the STONE underneath, so it works through opacity rather than colour | | `stone` | dressed and rubble masonry | its colour is close to weathered oak; what separates them at a glance is that stone scatters light completely flat, and roughness is not something vertex colour can carry | `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, 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.