Remove em dashes from README.md, REFERENCE.md and the registry README.
This commit is contained in:
parent
be8c7a485d
commit
5d793c83d0
4 changed files with 113 additions and 114 deletions
52
README.md
52
README.md
|
|
@ -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.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
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
|
||||||
|
|
|
||||||
134
REFERENCE.md
134
REFERENCE.md
|
|
@ -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.
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
||||||

|

|
||||||
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
|
|
@ -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",
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue