Remove em dashes from README.md, REFERENCE.md and the registry README.

This commit is contained in:
CRTkafa 2026-08-27 18:09:58 +07:00
parent be8c7a485d
commit 5d793c83d0
4 changed files with 113 additions and 114 deletions

View file

@ -7,19 +7,19 @@ Vibe3D is a source-first model registry for Three.js: you install the
TypeScript that *generates* a model into your own project rather than depending TypeScript that *generates* a model into your own project rather than depending
on an opaque package. This repository holds one such registry. on an opaque package. This repository holds one such registry.
- **[`my-registry/`](my-registry/)** — the `@medieval-kit` registry, on npm as - **[`my-registry/`](my-registry/)**: the `@medieval-kit` registry, on npm as
[`@medieval-kit/registry`](https://www.npmjs.com/package/@medieval-kit/registry). [`@medieval-kit/registry`](https://www.npmjs.com/package/@medieval-kit/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.
**[Open the viewer →](https://medieval.crt.fyi/)** — every model in the kit, **[Open the viewer →](https://medieval.crt.fyi/)**. Every model in the kit:
turn it over, pull its sliders, press play. No install, no sign-in. turn it over, pull its sliders, press play. No install, no sign-in.
![The whole kit in one scene](media/kit.png) ![The whole kit in one scene](media/kit.png)
37 models and one shared library, **30,390 triangles** for the whole kit — less 37 models and one shared library, **30,390 triangles** for the whole kit. That
than a single medium-detail character. Every one is procedural source you own is less than a single medium-detail character. Every one of them is procedural
and edit, not an asset you load. source that lands in your project for you to edit.
That picture is a real scene, not a montage: the viewer's `kit` entry builds That picture is a real scene, not a montage: the viewer's `kit` entry builds
every model at once on a common ground plane, which is where inconsistencies in every model at once on a common ground plane, which is where inconsistencies in
@ -30,7 +30,7 @@ scale and tone have nowhere left to hide. Individually:
## Run the viewer ## Run the viewer
Requires [Bun](https://bun.sh). The viewer runs on WebGPU where the browser has Requires [Bun](https://bun.sh). The viewer runs on WebGPU where the browser has
it and falls back to three's own WebGL2 backend where it does not — including it and falls back to three's own WebGL2 backend where it does not, including
for `@scifi-kit`'s TSL node materials, which compile on both paths. Only the for `@scifi-kit`'s TSL node materials, which compile on both paths. Only the
separate demo app at `/` insists on WebGPU. separate demo app at `/` insists on WebGPU.
@ -53,7 +53,7 @@ bun add -d @types/three
``` ```
`init` writes `models.json` and seeds it with `@scifi-kit` only, so add this `init` writes `models.json` and seeds it with `@scifi-kit` only, so add this
registry to the `registries` object it created — `vibe3d add` resolves the registry to the `registries` object it created. `vibe3d add` resolves the
namespace through that map and stops without it: namespace through that map and stops without it:
```json ```json
@ -80,7 +80,7 @@ bun scripts/export-glb.ts --one wooden-chest
The viewer's download button and this command share one implementation The viewer's download button and this command share one implementation
(`src/glb.ts`), so they produce byte-identical files. Colour travels as (`src/glb.ts`), so they produce byte-identical files. Colour travels as
`COLOR_0` vertex data and `baseColorFactor` stays white — the files carry no `COLOR_0` vertex data and `baseColorFactor` stays white. The files carry no
textures at all. textures at all.
## Verify ## Verify
@ -90,7 +90,7 @@ bun run typecheck
bun run verify # geometry, protocol, metadata, actions bun run verify # geometry, protocol, metadata, actions
bun run verify:glb # export every model, read it back, compare bun run verify:glb # export every model, read it back, compare
bun run check:docs # the three READMEs against the kit they describe bun run check:docs # the three READMEs against the kit they describe
bun run render # renders/_sheet.png — actually look at the models bun run render # renders/_sheet.png, to actually look at the models
``` ```
`verify` runs 1,044 browser-free checks against the installed sources: geometry `verify` runs 1,044 browser-free checks against the installed sources: geometry
@ -102,18 +102,18 @@ between each model and its published metadata.
Five 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
shell must point away from the axis, measured in height bands. Closed solids shell must point away from the axis, measured in height bands. Closed solids
use signed volume: `Σ a·(b×c)/6` is positive only when the winding faces use signed volume: `Σ a·(b×c)/6` is positive only when the winding faces
outward. And edge balance catches a *single* flipped face, which signed volume outward. And edge balance catches a *single* flipped face, which signed volume
misses — flipping one face took the volume from 0.058 to 0.039, still misses. Flipping one face took the volume from 0.058 to 0.039, still
positive. positive.
- **Z-fighting** is checked by looking for triangles that share a plane, share a - **Z-fighting** is checked by looking for triangles that share a plane, share a
normal direction, and overlap in area. Edge contact between neighbouring boards normal direction, and overlap in area. Edge contact between neighbouring boards
is fine and is not flagged; genuine coplanar overlap is. is fine and is not flagged; genuine coplanar overlap is.
- **Metadata agreement** verifies that every declared control key is a real - **Metadata agreement** verifies that every declared control key is a real
config field, that declared part names match the model's actual parts, and — config field, that declared part names match the model's actual parts, and,
most importantly — that no mesh uses an *undeclared* material slot. A missing most importantly, that no mesh uses an *undeclared* material slot. A missing
declaration is a material the consumer cannot reach through declaration is a material the consumer cannot reach through
`materials.override()`. This check found real drift in four models the day it `materials.override()`. This check found real drift in four models the day it
was added: a `steel` slot had been used but never declared. was added: a `steel` slot had been used but never declared.
@ -121,7 +121,7 @@ Five of those deserve a note, because each was written after a real bug:
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 - **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 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` lid separated from its chest passed all of them. `scripts/support.ts`
voxelises the model, finds the connected components of occupied space, and 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 requires each one to reach the floor. `scripts/audit.ts` runs that across the
@ -134,13 +134,13 @@ Five of those deserve a note, because each was written after a real bug:
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.
All of it runs in CI on every push — headless, no browser and no GPU, about a All of it runs in CI on every push, headless, no browser and no GPU, in about a
minute — and the contact sheet is uploaded with the run, because the geometry minute. The contact sheet is uploaded with the run, because the geometry
checks cannot say "this does not look like a shovel" and the picture is what checks cannot say "this does not look like a shovel" and the picture is what
makes that reviewable. makes that reviewable.
`render` closed the one gap all of the above left open. Every check was `render` closed the one gap all of the above left open. Every check was
*geometric* — triangle counts, winding, coplanarity, bounds. All of them caught *geometric*: triangle counts, winding, coplanarity, bounds. All of them caught
real bugs, and none of them could say "this shovel does not look like a shovel." real bugs, and none of them could say "this shovel does not look like a shovel."
The renderer is a small software rasteriser: no browser, no GPU. The shovel was 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
@ -158,8 +158,8 @@ viewer.html?showcase=60 # 30, 60 and 90 are offered
**60 s is the default**, and the reason is arithmetic: the tour splits its **60 s is the default**, and the reason is arithmetic: the tour splits its
running time equally between the models, so across 37 of them a 30 s run gives running time equally between the models, so across 37 of them a 30 s run gives
each 0.81 seconds — a flyby, not a demonstration — while 60 s gives 1.6 s and each 0.81 seconds, which is a flyby rather than a demonstration. 60 s gives
90 s gives 2.4 s. 1.6 s and 90 s gives 2.4 s.
That first number moves every time a model is added, which is worth saying out That first number moves every time a model is added, which is worth saying out
loud rather than leaving as a stale sentence in a README: at 27 models, 60 s loud rather than leaving as a stale sentence in a README: at 27 models, 60 s
@ -168,8 +168,8 @@ wants the older pace back.
Two things make the variation visible rather than merely present. Continuous Two things make the variation visible rather than merely present. Continuous
controls travel the whole usable band every beat instead of two random draws 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 — 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, stave count, plank count, spokes, rows and tines, can change at the midpoint,
where the same dip that hides a model swap hides the rebuild. Those are the 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, 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 so before the split they were pinned for the whole beat and the tour looked
@ -183,8 +183,8 @@ bun run site:build # → dist-viewer/, ready for any static host
The output is the viewer at a domain root: an `index.html`, and a bundle and a The output is the viewer at a domain root: an `index.html`, and a bundle and a
stylesheet it loads by absolute path, both content-hashed so they can be cached stylesheet it loads by absolute path, both content-hashed so they can be cached
for a year. Nothing is fetched at run time — the registry address in the for a year. Nothing is fetched at run time, since the registry address in the
sidebar is a label, not a request — so there is no API to stand up and nothing sidebar is a label rather than a request, so there is no API to stand up and nothing
to 404. to 404.
Beside it is `artifact.html`, the same viewer collapsed into one self-contained Beside it is `artifact.html`, the same viewer collapsed into one self-contained
@ -214,10 +214,10 @@ 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 support.ts voxel connectivity: nothing may float
audit.ts runs the support check across every configuration audit.ts runs the support check across every configuration
raster.ts the software renderer: triangles in, PNG out raster.ts the software renderer: triangles in, PNG out
render.ts its command line — sheets, sweeps, turntables render.ts its command line: sheets, sweeps, turntables
text.ts a TrueType reader, so the renderer can set type text.ts a TrueType reader, so the renderer can set type
build-cover.ts the social card, with its numbers counted not typed build-cover.ts the social card, with its numbers counted not typed
check-docs.ts documented counts against the models themselves check-docs.ts documented counts against the models themselves

View file

@ -1,4 +1,4 @@
# vibe3d — working notes # vibe3d working notes
What everything in this folder is for, how vibe3d works, and how to build your What everything in this folder is for, how vibe3d works, and how to build your
own asset pack. own asset pack.
@ -12,7 +12,7 @@ Upstream: <https://github.com/vibe-stack/vibe3d> · Docs:
**Not:** a 3D model library, an AI model generator, an engine. **Not:** a 3D model library, an AI model generator, an engine.
**What it is:** the 3D counterpart of shadcn/ui — a *source distribution **What it is:** the 3D counterpart of shadcn/ui, a *source distribution
protocol*. You don't download models; you copy **the TypeScript code that protocol*. You don't download models; you copy **the TypeScript code that
generates the model** into your own project and own it. No `node_modules` generates the model** into your own project and own it. No `node_modules`
boundary, no patching; the file is yours, open it and change it. boundary, no patching; the file is yours, open it and change it.
@ -26,7 +26,7 @@ The system has four layers:
| Validation | `@vibe3djs/conformance` | schema + path safety + hash check | | Validation | `@vibe3djs/conformance` | schema + path safety + hash check |
| Interface | `vibe3d` (CLI) | `init`, `add`, `view`, `list`, `diff`, `remove`, `doctor` | | Interface | `vibe3d` (CLI) | `init`, `add`, `view`, `list`, `diff`, `remove`, `doctor` |
`@scifi-kit` is none of these — it is **the protocol's first reference `@scifi-kit` is none of these. It is **the protocol's first reference
registry**. Its being sci-fi is an accident; the platform makes no assumption registry**. Its being sci-fi is an accident; the platform makes no assumption
about style. about style.
@ -74,9 +74,9 @@ src/lib/vibe3d/ the universal contracts `init` installs
model.ts ModelInstance, PartHandle, MaterialBindings model.ts ModelInstance, PartHandle, MaterialBindings
ownership.ts ResourceScope (resource ownership) ownership.ts ResourceScope (resource ownership)
materials.ts the MaterialSource interface materials.ts the MaterialSource interface
src/lib/vibe3d/scifi-kit/generator/ @scifi-kit/core — 2,100 lines of procedural tools src/lib/vibe3d/scifi-kit/generator/ @scifi-kit/core, 2,100 lines of procedural tools
src/viewer.ts · src/viewer.css the model viewer (WebGPU, sky, shadow) src/viewer.ts · src/viewer.css the model viewer (WebGPU, sky, shadow)
src/catalog.ts the viewer's catalog — DERIVED from meta.ts src/catalog.ts the viewer's catalog, DERIVED from meta.ts
src/glb.ts GLB export (shared by viewer and CLI) src/glb.ts GLB export (shared by viewer and CLI)
src/models/scifi-kit/pressure-gauge/ the installed sci-fi model src/models/scifi-kit/pressure-gauge/ the installed sci-fi model
src/models/medieval-kit/… your OWN installed models (37 models) src/models/medieval-kit/… your OWN installed models (37 models)
@ -108,7 +108,7 @@ edited (unless you say `--overwrite`).
### Running ### Running
```bash ```bash
bun run dev # playground — two registries, one project bun run dev # playground: two registries, one project
bun run typecheck # does the installed source really compile bun run typecheck # does the installed source really compile
bun my-registry/build.ts # generate registry.json bun my-registry/build.ts # generate registry.json
@ -116,7 +116,7 @@ bunx vibe3d add @medieval-kit --overwrite # install your own kit into yourself
bun scripts/verify-model.ts # geometry, protocol, metadata, actions bun scripts/verify-model.ts # geometry, protocol, metadata, actions
bun scripts/verify-glb.ts # export → read back → compare bun scripts/verify-glb.ts # export → read back → compare
bun scripts/render.ts # renders/_sheet.png — LOOK at the models bun scripts/render.ts # renders/_sheet.png, to LOOK at the models
bun scripts/export-glb.ts # the whole kit under glb/ bun scripts/export-glb.ts # the whole kit under glb/
``` ```
@ -127,7 +127,7 @@ tests the old code.
> **WebGPU required.** The `@scifi-kit` models use TSL node materials > **WebGPU required.** The `@scifi-kit` models use TSL node materials
> (`colorNode`, `attribute(...)`), so `WebGPURenderer` is mandatory. Your own > (`colorNode`, `attribute(...)`), so `WebGPURenderer` is mandatory. Your own
> `@medieval-kit` model uses plain `MeshStandardMaterial` — WebGL is enough. > `@medieval-kit` model uses plain `MeshStandardMaterial`, so WebGL is enough.
> **The `three` vs `three/webgpu` trap.** These are separate bundles and both > **The `three` vs `three/webgpu` trap.** These are separate bundles and both
> contain their own copy of the core classes. Mix them and you get the "Multiple > contain their own copy of the core classes. Mix them and you get the "Multiple
@ -148,24 +148,24 @@ born from code at runtime. GLB is only *output* (export), never *input*.
`@scifi-kit/core` (`src/lib/vibe3d/scifi-kit/generator/`) is a five-stage `@scifi-kit/core` (`src/lib/vibe3d/scifi-kit/generator/`) is a five-stage
pipeline: pipeline:
1. **`primitives.ts`** (867 lines) — `prism`, `extrudeProfile`, `filletRing`, 1. **`primitives.ts`** (867 lines): `prism`, `extrudeProfile`, `filletRing`,
`flatPlate`, `groove`, `cylinder`. These differ from Three.js's box/cylinder: `flatPlate`, `groove`, `cylinder`. These differ from Three.js's box/cylinder:
they produce corner chamfers, tangential fillet rings and shared normals they produce corner chamfers, tangential fillet rings and shared normals
along the chamfer bands. The hard-surface look that "doesn't look along the chamfer bands. The hard-surface look that "doesn't look
AI-generated" comes from here. AI-generated" comes from here.
2. **`profile.ts`** — 2D profile generation: `rect`, `octagon`, `stepEdge`, 2. **`profile.ts`**: 2D profile generation: `rect`, `octagon`, `stepEdge`,
`offsetProfile`, `mirrorProfile`. The cross-section is drawn first, then `offsetProfile`, `mirrorProfile`. The cross-section is drawn first, then
extruded. extruded.
3. **`materials.ts`** — `MaterialLibrary` + `mountMaterialSource`. Materials are 3. **`materials.ts`**: `MaterialLibrary` + `mountMaterialSource`. Materials are
fetched by semantic ids like `MAT-03/GRAPHITE-800` and can be overridden in the project. fetched by semantic ids like `MAT-03/GRAPHITE-800` and can be overridden in the project.
4. **`wear.ts`** (524 lines) — the trick lives here. `bakeOcclusion` and 4. **`wear.ts`** (524 lines): the trick lives here. `bakeOcclusion` and
`bakeSurfaceAttributes` write adjacency and surface identity into **vertex `bakeSurfaceAttributes` write adjacency and surface identity into **vertex
attributes** (`aMask`, `aColor`, `aSurface`, `aWearDir`, `aPlane`) while the attributes** (`aMask`, `aColor`, `aSurface`, `aWearDir`, `aPlane`) while the
parts are still separate. Then `createWearMaterial` produces paint chipping, parts are still separate. Then `createWearMaterial` produces paint chipping,
scratches and grime with a single TSL node graph. The comment in the code scratches and grime with a single TSL node graph. The comment in the code
states the intent plainly: fractal noise is deliberately avoided, because states the intent plainly: fractal noise is deliberately avoided, because
isotropic noise gives a soft cloud and a cloud reads as fog, not damage. isotropic noise gives a soft cloud and a cloud reads as fog, not damage.
5. **`batching.ts` + `glb.ts`** — `mergeStaticByMaterial` reduces the static 5. **`batching.ts` + `glb.ts`**: `mergeStaticByMaterial` reduces the static
parts to one draw call per material; `exportStaticGlb` *bakes* the procedural parts to one draw call per material; `exportStaticGlb` *bakes* the procedural
wear into standard PBR data to produce a portable GLB. wear into standard PBR data to produce a portable GLB.
@ -207,18 +207,18 @@ node (the needle pivot).
`src/lib/vibe3d/model.ts` is small and deliberately so: `src/lib/vibe3d/model.ts` is small and deliberately so:
- **`root` identity is fixed for life.** `configure()` may rebuild the topology - **`root` identity is fixed for life.** `configure()` may rebuild the topology
but cannot swap the root — so that scene parenting, editor selection and but cannot swap the root, so that scene parenting, editor selection and
external references survive. external references survive.
- **Semantic `parts`** — no dependence on anonymous mesh order. `anchor` is - **Semantic `parts`**, with no dependence on anonymous mesh order. `anchor` is
fixed, `content` is rebuildable. A light or label the consumer attached to fixed, `content` is rebuildable. A light or label the consumer attached to
`anchor` survives a rebuild. `anchor` survives a rebuild.
- **`materials.get/override/reset`** — resolution order: instance override → - **`materials.get/override/reset`**, resolution order: instance override →
project override → kit default. project override → kit default.
- **Ownership**: the model disposes its own resources exactly once, **never - **Ownership**: the model disposes its own resources exactly once, **never
touches a material the consumer supplied**, and `dispose()` is idempotent. touches a material the consumer supplied**, and `dispose()` is idempotent.
- **The scene, renderer, camera and render loop are YOURS.** See `src/main.ts`. - **The scene, renderer, camera and render loop are YOURS.** See `src/main.ts`.
`configure()` is expensive — it is for user settings, not for per-frame `configure()` is expensive. It is for user settings, not for per-frame
animation. Continuous motion is done with `actions` + `update(dt)`. animation. Continuous motion is done with `actions` + `update(dt)`.
### 3.4 How the models are *written* (the actual "generate" part) ### 3.4 How the models are *written* (the actual "generate" part)
@ -242,17 +242,17 @@ The rules (`.agents/skills/vibe-model/SKILL.md`): the critiquing agent is given
the code). The agent returns a similarity score and **at most three** prioritized the code). The agent returns a similarity score and **at most three** prioritized
fixes. Silhouette and proportions, main masses and negative space, fixes. Silhouette and proportions, main masses and negative space,
distinguishing marks, and material/value reading are scored in that order. distinguishing marks, and material/value reading are scored in that order.
**Stop at 85**; stop as well if it plateaus twice or exceeds 10 iterations — a **Stop at 85**; stop as well if it plateaus twice or exceeds 10 iterations. A
plateau is proof that the representation or the reference has to change. plateau is proof that the representation or the reference has to change.
`references/modeling-rules.md` contains 17 hard rules. The most expensive ones: `references/modeling-rules.md` contains 17 hard rules. The most expensive ones:
- Budget chamfers by perceptual role — the default is a **single** facet; give a - Budget chamfers by perceptual role. The default is a **single** facet; give a
second one only to masses that carry the silhouette. second one only to masses that carry the silhouette.
- **Assume the winding direction flips** when a ring is inset inward; compare - **Assume the winding direction flips** when a ring is inset inward; compare
the edge cross product of the first triangle against the expected normal. the edge cross product of the first triangle against the expected normal.
- Keep chamfers below ~60% of the affected half-dimension. - Keep chamfers below ~60% of the affected half-dimension.
- Size physical features **in world units** — chamfer, seam, bolt, gap. Do not - Size physical features **in world units**: chamfer, seam, bolt, gap. Do not
scale these as a percentage of the host part. scale these as a percentage of the host part.
- Compute the clearance for every layer you apply; in this meter-scale kit that - Compute the clearance for every layer you apply; in this meter-scale kit that
is at least **0.015 units**, and verify it from a real camera (z-fighting). is at least **0.015 units**, and verify it from a real camera (z-fighting).
@ -268,7 +268,7 @@ A registry is, in the end, **a single JSON file**. No dependencies required.
### Steps ### Steps
**1) Write the source** — `my-registry/models/<model-id>/model.ts` **1) Write the source**, in `my-registry/models/<model-id>/model.ts`
Use the canonical imports; they are rewritten during install: Use the canonical imports; they are rewritten during install:
@ -279,7 +279,7 @@ Use the canonical imports; they are rewritten during install:
This is why the registry never has to assume the consumer's folder layout. This is why the registry never has to assume the consumer's folder layout.
**2) Build the manifest** — `my-registry/build.ts` **2) Build the manifest**, with `my-registry/build.ts`
For every file `{ path, target, content, hash }`. The `{models}` and `{vibe3d}` For every file `{ path, target, content, hash }`. The `{models}` and `{vibe3d}`
placeholders inside `target` are replaced with the `paths` from the consumer's placeholders inside `target` are replaced with the `paths` from the consumer's
@ -289,7 +289,7 @@ placeholders inside `target` are replaced with the `paths` from the consumer's
bun my-registry/build.ts bun my-registry/build.ts
``` ```
**3) Validate** — the official conformance check **3) Validate** with the official conformance check
```bash ```bash
bunx vibe3d registry validate my-registry/dist/registry.json bunx vibe3d registry validate my-registry/dist/registry.json
@ -311,7 +311,7 @@ bunx vibe3d add @medieval-kit/wooden-barrel --dry-run # show it first
bunx vibe3d add @medieval-kit/wooden-barrel bunx vibe3d add @medieval-kit/wooden-barrel
``` ```
**5) Publish** — put the `vibe3d.registry` field in `package.json` and push to **5) Publish**: put the `vibe3d.registry` field in `package.json` and push to
npm: npm:
```json ```json
@ -324,7 +324,7 @@ npm:
``` ```
Users write `"source": "npm:@medieval-kit/registry"` in their `models.json` and Users write `"source": "npm:@medieval-kit/registry"` in their `models.json` and
install with the same CLI. **You do not need anyone's permission** — you can install with the same CLI. **You do not need anyone's permission.** You can
publish your own registry without touching the vibe3d repository. The publish your own registry without touching the vibe3d repository. The
architecture document states this as an explicit goal. architecture document states this as an explicit goal.
@ -333,7 +333,7 @@ This one is live, which is how the claim stopped being theory:
Publishing needed 2FA on the npm account and an org owning the `@medieval-kit` Publishing needed 2FA on the npm account and an org owning the `@medieval-kit`
scope; nothing was needed from vibe3d itself. Worth knowing before you publish scope; nothing was needed from vibe3d itself. Worth knowing before you publish
your own: npm stamps the publishing account's email into the packument per your own: npm stamps the publishing account's email into the packument per
version, and later account changes do not rewrite it — so whatever address is version, and later account changes do not rewrite it, so whatever address is
on the account at that moment is public for good. on the account at that moment is public for good.
### Size warning ### Size warning
@ -341,16 +341,16 @@ on the account at that moment is public for good.
`registry.json` keeps all the source embedded. `@scifi-kit/registry@0.0.1` → `registry.json` keeps all the source embedded. `@scifi-kit/registry@0.0.1` →
**1.8 MB of JSON**, a 404 KB tarball. npm downloads the entire tarball even for **1.8 MB of JSON**, a 404 KB tarball. npm downloads the entire tarball even for
a single item. The architecture document foresees collection-based sharding for a single item. The architecture document foresees collection-based sharding for
the future (`@scifi-kit/industrial`, `@scifi-kit/medical`…) — the address stays the future (`@scifi-kit/industrial`, `@scifi-kit/medical`…). The address stays
the same, the physical package changes. the same, the physical package changes.
--- ---
## 5. Lowpoly medieval — yes, no problem ## 5. Lowpoly medieval: yes, no problem
This is not an assumption: `@medieval-kit` works, is validated and currently This is not an assumption: `@medieval-kit` works, is validated and currently
contains **37 models + 1 lib**. The table is generated from the models contains **37 models + 1 lib**. The table is generated from the models
themselves with `bun scripts/catalog-table.ts` — a hand-written list goes stale themselves with `bun scripts/catalog-table.ts`. A hand-written list goes stale
on the first model you add, and in fact it had gone stale once. on the first model you add, and in fact it had gone stale once.
| Model | Category | Triangles | Parts | Size (m) | Material slots | Animated | | Model | Category | Triangles | Parts | Size (m) | Material slots | Animated |
@ -404,7 +404,7 @@ registry.json) and `src/catalog.ts` (the viewer's sliders and descriptions).
Previously the two were written out by hand separately, and by the seventeenth Previously the two were written out by hand separately, and by the seventeenth
model they had diverged. Divergence is not impossible now, but being SILENT model they had diverged. Divergence is not impossible now, but being SILENT
about it is: `verify-model.ts` compares metadata against reality on every model — about it is: `verify-model.ts` compares metadata against reality on every model,
- are all the `meta.controls` keys really fields of the model's config, - are all the `meta.controls` keys really fields of the model's config,
- is `meta.parts` the same as the model's real part names, - is `meta.parts` the same as the model's real part names,
@ -417,33 +417,33 @@ declaration means a hidden material the consumer cannot reach with
this check was added it caught a real drift in four models (a `steel` slot had this check was added it caught a real drift in four models (a `steel` slot had
been added but not declared). been added but not declared).
### 5.2 The material vocabulary — thirteen slots ### 5.2 The material vocabulary: thirteen slots
| Slot | What | Why separate | | Slot | What | Why separate |
| --- | --- | --- | | --- | --- | --- |
| `oak` | timber | — | | `oak` | timber | the baseline everything else is measured against |
| `iron` | forged iron, oxidized and matte | separate from `steel`: the difference is not in color but in ROUGHNESS, and vertex color cannot carry roughness | | `iron` | forged iron, oxidized and matte | separate from `steel`: the difference is not in color but in ROUGHNESS, and vertex color cannot carry roughness |
| `steel` | steel polished by use | the anvil face, the shovel blade, the pitchfork tip | | `steel` | steel polished by use | the anvil face, the shovel blade, the pitchfork tip |
| `brass` | bronze and copper | the bell, coins | | `brass` | bronze and copper | the bell, coins |
| `straw` | straw, wicker, broom bristle | a bale declaring "oak" would be a lie told to the consumer | | `straw` | straw, wicker, broom bristle | a bale declaring "oak" would be a lie told to the consumer |
| `cloth` | linen, sackcloth, rope | — | | `cloth` | linen, sackcloth, rope | woven, so it takes light softly and never glints |
| `leather` | worked leather | — | | `leather` | worked leather | darker and glossier than cloth at the same colour |
| `glass` | blown glass | transparent, `depthWrite` OFF, `DoubleSide` | | `glass` | blown glass | transparent, `depthWrite` OFF, `DoubleSide` |
| `produce` | fruit and vegetable skin | if I had given it the same roughness as straw an apple would look like dry hay | | `produce` | fruit and vegetable skin | if I had given it the same roughness as straw an apple would look like dry hay |
| `ember` | flame | `MeshBasicMaterial` — it does not receive light, it emits | | `ember` | flame | `MeshBasicMaterial`: it does not receive light, it emits |
| `char` | charcoal, pitch | — | | `char` | charcoal, pitch | the darkest thing in the kit, and it has to stay readable against shadow |
| `stone` | dressed and rubble masonry | its color is close to weathered oak; what tells them apart at a glance is that stone scatters light completely flat, and roughness is not something vertex color can carry | | `stone` | dressed and rubble masonry | its color is close to weathered oak; what tells them apart at a glance is that stone scatters light completely flat, and roughness is not something vertex color can carry |
| `water` | standing water | a thin transparent film over whatever holds it: it works through opacity rather than through a colour of its own | | `water` | standing water | a thin transparent film over whatever holds it: it works through opacity rather than through a colour of its own |
`ember` also works as a rule in two places: bodies in this slot are skipped `ember` also works as a rule in two places: bodies in this slot are skipped
entirely while occlusion and mottle are baked. The reason is simple — on an entirely while occlusion and mottle are baked. The reason is simple: on an
unlit material the vertex color is the final color, and darkening it puts the unlit material the vertex color is the final color, and darkening it puts the
flame out. The rule lives in `kit.ts` bound to the slot itself, not to a flame out. The rule lives in `kit.ts` bound to the slot itself, not to a
per-model flag, so that it cannot be forgotten. per-model flag, so that it cannot be forgotten.
### 5.3 `core`'s vocabulary ### 5.3 `core`'s vocabulary
**Geometry generators** (`geometry.ts`) — all non-indexed, all vertex-colored, **Geometry generators** (`geometry.ts`), all non-indexed, all vertex-colored,
so flat shading comes for free: so flat shading comes for free:
`boxGeometry`, `taperedBoxGeometry`, `chamferedBoxGeometry` (44 triangles, with `boxGeometry`, `taperedBoxGeometry`, `chamferedBoxGeometry` (44 triangles, with
@ -451,11 +451,11 @@ self-correcting edge/corner winding), `prismGeometry`, `latheGeometry`,
`staveGeometry`, `bandGeometry` (with an optional inner face), `headGeometry`, `staveGeometry`, `bandGeometry` (with an optional inner face), `headGeometry`,
`arcBarGeometry`, `dishedSheetGeometry`, `flipGeometry`, `mergeColoured`. `arcBarGeometry`, `dishedSheetGeometry`, `flipGeometry`, `mergeColoured`.
**Deformation** — added later, and it is what stopped the models looking **Deformation**, added later, and it is what stopped the models looking
"generated": "generated":
- `bendGeometry(geometry, curvature)` wraps a straight body into an arc. A real - `bendGeometry(geometry, curvature)` wraps a straight body into an arc. A real
arc mapping, not "rotate every point in proportion to its height" — that arc mapping, not "rotate every point in proportion to its height". That
approach stretched and thinned the body. The pitchfork tines, the tankard approach stretched and thinned the body. The pitchfork tines, the tankard
handle, the hoe blade and the curve of the sign use it. handle, the hoe blade and the curve of the sign use it.
- `roughenGeometry(geometry, amount)` makes the surface irregular. The critical - `roughenGeometry(geometry, amount)` makes the surface irregular. The critical
@ -464,7 +464,7 @@ self-correcting edge/corner winding), `prismGeometry`, `latheGeometry`,
independently tore the surface. A position hash gives every copy at the same independently tore the surface. A position hash gives every copy at the same
point the same displacement. point the same displacement.
**Surface baking** — kit-wide, automatic inside `createKitModel`: **Surface baking**, kit-wide and automatic inside `createKitModel`:
- `bakeOcclusion` (`occlusion.ts`) bakes ambient occlusion into the vertex - `bakeOcclusion` (`occlusion.ts`) bakes ambient occlusion into the vertex
colors. It derives the darkening from the surface's OWN shape: the more colors. It derives the darkening from the surface's OWN shape: the more
@ -475,7 +475,7 @@ self-correcting edge/corner winding), `prismGeometry`, `latheGeometry`,
UV coordinates (our geometry has none), image files the registry would have to UV coordinates (our geometry has none), image files the registry would have to
carry, and a change to the kit's identity. Instead there is a blotch pattern carry, and a change to the kit's identity. Instead there is a blotch pattern
derived from the surface position; the blotch size comes from the model's derived from the surface position; the blotch size comes from the model's
scale, the INTENSITY from the slot — scale, the INTENSITY from the slot:
``` ```
straw 1.35 · cloth 1.15 · oak 1.00 · char 0.85 · leather 0.70 straw 1.35 · cloth 1.15 · oak 1.00 · char 0.85 · leather 0.70
@ -491,7 +491,7 @@ self-correcting edge/corner winding), `prismGeometry`, `latheGeometry`,
triangles, so the mottle is almost invisible there. The remedy is to subdivide triangles, so the mottle is almost invisible there. The remedy is to subdivide
the triangle, and that eats the lowpoly budget. the triangle, and that eats the lowpoly budget.
**Scaffolding** (`kit.ts`) — `createKitModel` makes every model set up the same **Scaffolding** (`kit.ts`): `createKitModel` makes every model set up the same
contract: resource ownership, material resolution and override, a fixed anchor + contract: resource ownership, material resolution and override, a fixed anchor +
replaceable content, a `configure()` that does not break identity, an idempotent replaceable content, a `configure()` that does not break identity, an idempotent
`dispose()`. Writing a model is now just generating geometry. `dispose()`. Writing a model is now just generating geometry.
@ -500,14 +500,14 @@ replaceable content, a `configure()` that does not break identity, an idempotent
`BuiltPart` carries three fields and two of them came later: `BuiltPart` carries three fields and two of them came later:
- `geometry` + `slot` — the part's main body. - `geometry` + `slot`: the part's main body.
- **`extras`** — bodies belonging to the same part that use a DIFFERENT slot. - **`extras`**: bodies belonging to the same part that use a DIFFERENT slot.
Parts are sibling children of the root, so when one of them moves the others Parts are sibling children of the root, so when one of them moves the others
cannot follow it. The chest's lid is oak board and iron strap and lock hasp at cannot follow it. The chest's lid is oak board and iron strap and lock hasp at
once, and the three have to rotate together; as separate parts the straps once, and the three have to rotate together; as separate parts the straps
would hang in mid-air while the lid opened. What is split is not the meaning, would hang in mid-air while the lid opened. What is split is not the meaning,
only the material. only the material.
- **`origin`** — the part's own center of rotation. When given, the anchor is - **`origin`**: the part's own center of rotation. When given, the anchor is
placed there and the geometry is assumed to be written relative to that point. placed there and the geometry is assumed to be written relative to that point.
This is the only thing needed to make the chest lid rotate around its hinge. This is the only thing needed to make the chest lid rotate around its hinge.
@ -522,7 +522,7 @@ Eleven models carry actions:
| Model | Action | Mechanic | | Model | Action | Mechanic |
| --- | --- | --- | | --- | --- | --- |
| `wooden-chest` | `setOpen` / `toggle` / `isOpen` / `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 |
| `iron-cauldron` | `setLit` / `isLit` | the fire under it, on the torch's flicker | | `iron-cauldron` | `setLit` / `isLit` | the fire under it, on the torch's flicker |
@ -537,7 +537,7 @@ Eleven models carry actions:
Five of these are wired to a button in the viewer; the rest are driven through 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 the model's own interface. That distinction cost a documentation bug: the
generated table's Animated column was reading the VIEWER's button registration, 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 so six of the eleven, including the mill, the well and the grindstone, were
published as static. It now asks the models. 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:
@ -561,7 +561,7 @@ Three rules hold for every moving model:
The bell is the most complex piece in the kit and what it teaches is this: The bell is the most complex piece in the kit and what it teaches is this:
**what rings a bell is not the bell swinging, it is the clapper LAGGING **what rings a bell is not the bell swinging, it is the clapper LAGGING
BEHIND.** On the first attempt I made the clapper an `extras` body of the bell — BEHIND.** On the first attempt I made the clapper an `extras` body of the bell,
the bell swung and nothing happened. Now the two are separate parts, swinging on the bell swung and nothing happened. Now the two are separate parts, swinging on
the same axis but with different damping; the difference between them produces the same axis but with different damping; the difference between them produces
the strike and increments the `actions.strikes()` counter. The model PLAYS NO the strike and increments the `actions.strikes()` counter. The model PLAYS NO
@ -575,15 +575,15 @@ overlap, which one is in front is left to the floating-point precision of the
depth buffer. As the camera moves the winner changes and the surface flickers. depth buffer. As the camera moves the winner changes and the surface flickers.
The first version of the crate fell into exactly this trap: the posts, the side The first version of the crate fell into exactly this trap: the posts, the side
boards and the lid boards all put their outer surface on the `±width/2` plane — boards and the lid boards all put their outer surface on the `±width/2` plane,
**96 coincident faces.** The fix was not an "epsilon nudge" but real carpentry: **96 coincident faces.** The fix was not an "epsilon nudge" but real carpentry:
- **The posts stand proud of the boards** — the side boards are pulled behind - **The posts stand proud of the boards.** The side boards are pulled behind
the posts, so their outer faces are on a different plane. the posts, so their outer faces are on a different plane.
- **The lid and the base overhang the frame.** - **The lid and the base overhang the frame.**
- **The posts go INTO the lid and the base**, so their ends stay inside a solid - **The posts go INTO the lid and the base**, so their ends stay inside a solid
part and align with no plane at all. part and align with no plane at all.
- **The boards are butt-joined** — they touch but they do not overlap. Edge - **The boards are butt-joined.** They touch but they do not overlap. Edge
contact does not produce z-fighting. contact does not produce z-fighting.
- **The straps stop before they meet each other at the corner.** - **The straps stop before they meet each other at the corner.**
@ -594,7 +594,7 @@ of them made the model more CORRECT:
**that is where the lock is.** The rule is both historically correct and rules **that is where the lock is.** The rule is both historically correct and rules
out at the root any chance of the strap and the lock bridge landing on the out at the root any chance of the strap and the lock bridge landing on the
same plane at certain dimensions. same plane at certain dimensions.
- The broom's sheaves cannot sit perfectly parallel to each other — in a - The broom's sheaves cannot sit perfectly parallel to each other. In a
hand-tied bundle no bristle is parallel to another anyway. hand-tied bundle no bristle is parallel to another anyway.
- The bell's bearings stand proud of the rail; a real bearing does the same. - The bell's bearings stand proud of the rail; a real bearing does the same.
@ -608,14 +608,14 @@ In hand-written geometry the sneakiest bug is inverted winding: the face becomes
visible from the inside and it is only noticed at one particular camera angle. visible from the inside and it is only noticed at one particular camera angle.
There are three separate criteria, because none of them is sufficient alone: There are three separate criteria, because none of them is sufficient alone:
**Radial alignment** — for bodies of revolution. Every radial face's normal on **Radial alignment**, for bodies of revolution. Every radial face's normal on
the outer shell must point away from the axis. It is measured in height BANDS: the outer shell must point away from the axis. It is measured in height BANDS:
on conical bodies a single radius threshold is meaningless. on conical bodies a single radius threshold is meaningless.
**Signed volume** — for closed solids. Σ a·(b×c)/6 comes out positive if the **Signed volume**, for closed solids. Σ a·(b×c)/6 comes out positive if the
winding faces outward. But this criterion only catches a GLOBAL inversion. winding faces outward. But this criterion only catches a GLOBAL inversion.
**Edge balance** — the only criterion that catches a single flipped face. It was **Edge balance**, the only criterion that catches a single flipped face. It was
added because the signed volume test missed it: when I flipped one face the added because the signed volume test missed it: when I flipped one face the
volume fell from 0.058 to 0.039 but stayed positive. volume fell from 0.058 to 0.039 but stayed positive.
@ -623,12 +623,12 @@ Three more subtleties:
- The side surfaces of staves are TANGENTIAL, so the radial cross product is ~0 - The side surfaces of staves are TANGENTIAL, so the radial cross product is ~0
for them by definition and its sign is only noise. They are filtered out and for them by definition and its sign is only noise. They are filtered out and
**how many were filtered is reported** — they are not silently dropped. **how many were filtered is reported.** They are not silently dropped.
- Hollow bodies (the bell) deliberately carry an inward-facing shell. For those - Hollow bodies (the bell) deliberately carry an inward-facing shell. For those
the threshold is raised so the inner shell is not taken for the "outer shell". the threshold is raised so the inner shell is not taken for the "outer shell".
- `bandGeometry` produces no inner face by default (a hoop always wraps a body, - `bandGeometry` produces no inner face by default (a hoop always wraps a body,
the inner face is invisible). A free-standing ring — the sack's rope, the the inner face is invisible). A free-standing ring such as the sack's rope or
bale's tie — was therefore not a closed solid; `{ inner: true }` exists for the bale's tie was therefore not a closed solid; `{ inner: true }` exists for
that. that.
### 5.8 Validation: three scripts ### 5.8 Validation: three scripts
@ -636,7 +636,7 @@ Three more subtleties:
```bash ```bash
bun scripts/verify-model.ts # ~500 checks · geometry, protocol, metadata, actions bun scripts/verify-model.ts # ~500 checks · geometry, protocol, metadata, actions
bun scripts/verify-glb.ts # exports every model and READS IT BACK bun scripts/verify-glb.ts # exports every model and READS IT BACK
bun scripts/render.ts # PNG contact sheet — for LOOKING at the model bun scripts/render.ts # PNG contact sheet, for LOOKING at the model
``` ```
The method has been the same from the start: **every check was tested by The method has been the same from the start: **every check was tested by
@ -657,7 +657,7 @@ MINE, not the test's:
`render.ts` was added last and it closed the thing that was missing. All the `render.ts` was added last and it closed the thing that was missing. All the
validation was GEOMETRIC: triangle count, winding, coplanarity, bounding box. It validation was GEOMETRIC: triangle count, winding, coplanarity, bounding box. It
all caught real bugs but none of it could say "this shovel does not look like a all caught real bugs but none of it could say "this shovel does not look like a
shovel". To say that sentence you have to look at the model — the script is a shovel". To say that sentence you have to look at the model, and the script is a
software rasterizer with no browser and no GPU: it collects the triangles, software rasterizer with no browser and no GPU: it collects the triangles,
projects them with a camera, fills them with a z-buffer, writes a PNG. The projects them with a camera, fills them with a z-buffer, writes a PNG. The
shovel was rewritten a fourth time, the hoe a third and the hay bale a second shovel was rewritten a fourth time, the hoe a third and the hay bale a second
@ -670,7 +670,7 @@ bun scripts/render.ts --one wooden-hoe --sweep "bladeAngle=62|80|98|116|134"
``` ```
That is how the hoe's blade angle was chosen. Around 98° the blade stays almost That is how the hoe's blade angle was chosen. Around 98° the blade stays almost
horizontal and is seen EDGE-ON by a camera looking from a 3/4 angle — the horizontal and is seen EDGE-ON by a camera looking from a 3/4 angle, so the
model's most characteristic surface disappears from the silhouette. 66° was model's most characteristic surface disappears from the silhouette. 66° was
chosen. chosen.
@ -689,12 +689,12 @@ Batch export is what they do not have and it is the one that actually earns its
keep: it takes the kit to Blender, Godot or Unity with a single command. keep: it takes the kit to Blender, Godot or Unity with a single command.
Because all the color information is in vertex colors it travels to glTF as Because all the color information is in vertex colors it travels to glTF as
`COLOR_0` and `baseColorFactor` stays white — there is no texture in the file at `COLOR_0` and `baseColorFactor` stays white. There is no texture in the file at
all. The kit's entire identity travels in a single attribute. all. The kit's entire identity travels in a single attribute.
The one thing that does NOT travel is the shader: the wear on `@scifi-kit`'s The one thing that does NOT travel is the shader: the wear on `@scifi-kit`'s
gauge is a TSL node graph, i.e. code, and glTF does not carry code. This is not gauge is a TSL node graph, i.e. code, and glTF does not carry code. This is not
a shortcoming — it is the real difference between a vertex-color surface and a a shortcoming. It is the real difference between a vertex-color surface and a
shader-based one. shader-based one.
--- ---
@ -707,7 +707,7 @@ The repository is MIT and a Bun workspace. `apps/*`, `packages/*`,
```bash ```bash
git clone https://github.com/vibe-stack/vibe3d git clone https://github.com/vibe-stack/vibe3d
cd vibe3d && bun install cd vibe3d && bun install
bun run dev # the docs catalog — a live preview of every model bun run dev # the docs catalog, a live preview of every model
``` ```
Versioning is done with **Changesets**: Versioning is done with **Changesets**:
@ -726,7 +726,7 @@ packages in dependency order.
permission, and grows the ecosystem. `@scifi-kit` is only the *reference* permission, and grows the ecosystem. `@scifi-kit` is only the *reference*
registry. registry.
2. **Add a model to `@scifi-kit`.** Add `assets/prototypes/<model-id>/model.ts` 2. **Add a model to `@scifi-kit`.** Add `assets/prototypes/<model-id>/model.ts`
— `registries/scifi-kit/src/build.ts` **auto-discovers** every folder that `registries/scifi-kit/src/build.ts` **auto-discovers** every folder that
contains a `model.ts`, there is no registration list. Follow the `vibe-model` contains a `model.ts`, there is no registration list. Follow the `vibe-model`
loop and fill in the `docs/templates/asset-spec-template.md` contract. loop and fill in the `docs/templates/asset-spec-template.md` contract.
3. **Close the protocol gaps.** Things written in the architecture document but 3. **Close the protocol gaps.** Things written in the architecture document but
@ -748,7 +748,7 @@ contribution opportunity too.
`@scifi-kit/registry@0.0.1` as published on npm: **110 models** (Industrial 76, `@scifi-kit/registry@0.0.1` as published on npm: **110 models** (Industrial 76,
Architecture 12, Streets 9, Military 7, Medical 6) + 2 libs + 1 kit. GitHub Architecture 12, Streets 9, Military 7, Medical 6) + 2 libs + 1 kit. GitHub
`main` is further ahead — there are ~180 folders under `assets/prototypes/` (the `main` is further ahead: there are ~180 folders under `assets/prototypes/` (the
cargo/logistics wave is not published yet). All packages are at `0.0.1`, cargo/logistics wave is not published yet). All packages are at `0.0.1`,
published on 2026-08-11; the project is at a very early stage, so the timing for published on 2026-08-11; the project is at a very early stage, so the timing for
contributing is good. contributing is good.

View file

@ -1,8 +1,8 @@
# Medieval Kit # Medieval Kit
A lowpoly medieval model library for [Vibe3D](https://github.com/vibe-stack/vibe3d) 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 and Three.js. Installing a prop puts its source in your own tree, as readable
own tree, not an opaque package boundary. TypeScript you can edit.
![The whole kit in one scene](https://medieval.crt.fyi/kit.png) ![The whole kit in one scene](https://medieval.crt.fyi/kit.png)
@ -35,8 +35,8 @@ so without it the source you just installed does not typecheck.
} }
``` ```
That map is how the namespace resolves — `vibe3d add` stops with That map is how the namespace resolves. Without it `vibe3d add` stops with
`Registry @medieval-kit is not configured in models.json` without it. `Registry @medieval-kit is not configured in models.json`.
Then take one model, or the lot: Then take one model, or the lot:
@ -49,7 +49,7 @@ bunx vibe3d add @medieval-kit
The installed source imports through the `@/` alias that `models.json` declares, 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 and it imports `.ts` files by their extension. Both have to be true on your side
as well — in `tsconfig.json`: as well. In `tsconfig.json`:
```json ```json
{ {
@ -61,11 +61,11 @@ as well — in `tsconfig.json`:
} }
``` ```
No `baseUrl`: it was removed in TypeScript 7 and `paths` resolves relative to 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. this file on its own. Verified against a clean project on 7.0.2.
and in your bundler, because TypeScript's `paths` only teaches the type checker. The alias has to be set in your bundler too, because TypeScript's `paths` only
For Vite: teaches the type checker. For Vite:
```ts ```ts
resolve: { alias: [{ find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) }] } resolve: { alias: [{ find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) }] }
@ -74,7 +74,7 @@ resolve: { alias: [{ find: '@', replacement: fileURLToPath(new URL('./src', impo
## 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
generated from the models themselves with `bun scripts/catalog-table.ts` — a 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.
@ -156,7 +156,7 @@ Each model follows the Vibe3D protocol:
- **`root`** keeps its object identity for the model's whole lifetime. - **`root`** keeps its object identity for the model's whole lifetime.
- **`parts`** expose stable semantic anchors. Attach your own lights, labels, or - **`parts`** expose stable semantic anchors. Attach your own lights, labels, or
gameplay objects to `part.anchor` — they survive `configure()`, because only gameplay objects to `part.anchor`. They survive `configure()`, because only
`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.
@ -189,24 +189,23 @@ difference.
| Slot | What it covers | Why it is separate | | Slot | What it covers | Why it is separate |
| --- | --- | --- | | --- | --- | --- |
| `oak` | timber | — | | `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 | | `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 | | `steel` | steel polished by use | the anvil face, the shovel blade, the pitchfork tines |
| `brass` | bronze and copper | the bell, the coins | | `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 | | `straw` | straw, wicker, broom bristle | a bale declaring itself "oak" would be a lie told to the consumer |
| `cloth` | linen, sackcloth, rope | — | | `cloth` | linen, sackcloth, rope | woven, so it takes light softly and never glints |
| `leather` | worked leather | — | | `leather` | worked leather | darker and glossier than cloth at the same colour |
| `glass` | blown glass | transparent, `depthWrite` OFF, `DoubleSide` | | `glass` | blown glass | transparent, `depthWrite` OFF, `DoubleSide` |
| `produce` | fruit and vegetable skin | given straw's roughness, an apple would look like dry grass | | `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 | | `ember` | flame | `MeshBasicMaterial`: it does not receive light, it emits |
| `char` | charcoal and pitch | — | | `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 | | `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 | | `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 `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 — entirely while ambient occlusion and mottle are baked. The reason is simple: in an unlit material the vertex colour *is* the final
in an unlit material the vertex colour *is* the final colour, so darkening it colour, so darkening it puts the flame out. The rule is attached to the slot itself rather than to a
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
@ -222,12 +221,12 @@ bunx vibe3d registry validate dist/registry.json
The build walks `models/`. A folder containing `model.ts` becomes a The build walks `models/`. A folder containing `model.ts` becomes a
`vibe3d:model`; any other folder becomes a `vibe3d:lib`. Registry dependencies `vibe3d:model`; any other folder becomes a `vibe3d:lib`. Registry dependencies
are derived from the source — an import from `../core/` makes are derived from the source. An import from `../core/` makes
`@medieval-kit/core` a dependency automatically, so there is no hand-maintained `@medieval-kit/core` a dependency automatically, so there is no hand-maintained
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 — including its own `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 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 package page resolves against the repository, and there is nothing at the
other end of it for a reader of this page. other end of it for a reader of this page.

View file

@ -1,6 +1,6 @@
{ {
"name": "@medieval-kit/registry", "name": "@medieval-kit/registry",
"version": "0.1.1", "version": "0.1.2",
"description": "A lowpoly medieval procedural model library for Vibe3D and Three.js.", "description": "A lowpoly medieval procedural model library for Vibe3D and Three.js.",
"type": "module", "type": "module",
"license": "MIT", "license": "MIT",