flo-bit.dev
[READ-ONLY] Mirror of https://github.com/flo-bit/shapecraft.
flo-bit.dev/shapecraft/
7.3 kB
149 lines
1# Shapecraft — 6-Month Roadmap (v1)
2
3> The original v0 build plan lives in [`plan-v0.md`](./plan-v0.md). This document is the
4> forward-looking strategy: improving the models we have, making many more, and growing the
5> library to support them.
6
7**Team & horizon:** 4 people, full-time, 6 months (~24 person-months).
8
9---
10
11## Where we are
12
13Shapecraft is a procedural 3D model generation library for the browser: an immutable,
14functional `Mesh` API over Three.js, with a stylized low-poly toolbox (noise, palettes,
15face/vertex color, loft/tube/thicken, adaptive subdivision, jitter) and a **schema-driven
16editor** — each generator declares its options and gets a live UI, presets, and
17range-randomization for free.
18
19We ship **three models** today: common tree, pine, palm. All vegetation, all flat-shaded
20vertex-colored.
21
22**The core tension:** every model is ~200 lines of bespoke, copy-pasted code. Trunk warp,
23snow logic, face-shading, and the fragile "call `rand()` to keep the sequence stable" pattern
24are duplicated across all three. This does not scale to 20+ models. The ambition goes into the
25framework that makes each new model cheap.
26
27---
28
29## North star
30
31**All four scopes at once** — best-in-class vegetation, a full stylized environment kit, an
32asset-pipeline product, and a great general-purpose library. **All four consumers** — web/
33Three.js scenes, game engines, no-code designers, and developers using the API.
34
35### The "all four" insight
36
37These don't pull in four directions; they share one spine. The non-negotiable shared platform
38is: generator framework + CSG/bevel + curves + weld/LOD + AO/wind + instancing + glTF export +
39workers + playground + npm publish. Build that once and all four audiences are served.
40
41So "all four" resolves to a strict order: **engine-first, then catalog, then platform polish —
42with the quality bar (LOD, AO, wind, export) baked into the shared pipeline from the start so
43it is free for every model.**
44
45The one risk is shipping four half-products. The mitigation is the sequencing below: the
46foundation serves all four scopes simultaneously, and we don't branch into audience-specific
47polish until the substrate is real.
48
49---
50
51## Thesis: build the multiplier before the models
52
53The highest-leverage work is not more models — it's the substrate that makes every subsequent
54model cheap. Spend the first third of the project there, then flood the catalog.
55
56---
57
58## Two things to fix in week one (regardless of everything else)
59
601. **Determinism model.** Replace the single RNG with **named independent streams**
61 (`rng.stream('canopy')`, `rng.stream('snow')`). The current "consume a `rand()` to keep the
62 sequence stable" hack is a latent bug farm — change one branch and every downstream model
63 shifts. Fix it before it spreads into 20 more files.
642. **Packaging gap.** Today `package.json` `main` points at raw `.ts` — shapecraft is not
65 actually consumable as a package. Decide now that it ships as a real built npm package with
66 **stable seeds as a compatibility guarantee**. This changes how we test (golden snapshots)
67 and how we version from day one.
68
69---
70
71## Workstreams
72
73### A. Generator framework (the model multiplier)
74- Extract repeated patterns into reusable building blocks: a `trunk()` / tapered-limb builder,
75 a `canopyShade()` color helper, a `snow()` modifier.
76- **Anchor / socket points** on meshes (canopy top, ground contact, attachment rings) for
77 composition.
78- **Skeleton / L-system branching engine**: recursive tapered branches with leaf/attachment
79 slots. One engine yields oak, birch, willow, dead tree, bush, fern, coral, and vines from
80 parameters instead of bespoke files.
81- RNG named streams + **golden-snapshot test harness** (vertex counts, bounds, hashes) so
82 "seed 5 looks like X" is locked across versions.
83
84### B. Library capability gaps (unlock new model classes)
85- **CSG booleans** (union / subtract / intersect) — windows in walls, holes, carved props,
86 hard-surface.
87- **Bevel / inset / extrude-faces** — architecture, crates, furniture, crisp edges.
88- First-class **Curve / Path type with parallel-transport frames** — fixes twist artifacts in
89 `tube`/`loft` and cleans up every stalk/branch/vine.
90- **Vertex weld + decimation + automatic LOD generation** — today `faceColor` un-indexes
91 everything (×3 vertices) with no way to weld back or produce LODs. Required for any real use
92 at scale and for game-engine export.
93
94### C. Quality lift across all models (cheap, high-impact, on-brand)
95- **Baked vertex ambient occlusion / cavity shading** — instantly makes everything read as 3D
96 instead of flat.
97- **Per-vertex wind weights** — trees sway in a shader, models ship game-ready.
98- **Real branches** on the trees (currently trunk-plus-blobs).
99- Poly-budget / triangle-count targets per model.
100
101### D. Product surface (make output usable)
102- **Instancing**: `scatter → THREE.InstancedMesh` (the forest demo builds 15 unique meshes
103 today — critical perf win).
104- **glTF / GLB export** (plus OBJ) — the asset pipeline for game engines and designers.
105- **Real Web Worker pool** — the pool is a synchronous stub; `serialize()`/Transferable are
106 already in place to make it real.
107- **Biome / scatter scene generator** — Poisson-disk, noise density maps, slope/altitude rules
108 (the forest demo is the seed).
109- **Hosted playground + gallery** — the schema editor is the unfair advantage; one-click glTF
110 export for the no-code crowd.
111- **npm publish pipeline** — real build, `.d.ts`, dual ESM. Docs, perf benchmarks, visual
112 regression (the `screenshot.cjs` scripts are the seed).
113
114---
115
116## Timeline
117
118### Months 1–2 — Foundation (all 4 people; the whole ballgame, nothing skippable)
119- RNG named streams + golden-snapshot test harness.
120- Shared model primitives + skeleton/L-system branch engine.
121- CSG booleans + bevel/inset/extrude.
122- First-class Curve/Path with parallel-transport frames.
123- Weld + decimate + automatic LOD generation.
124
125### Months 2–4 — Catalog explosion + quality baked in (split: 2 on models, 2 on platform)
126- **Models team:** ride the framework through vegetation (bush, grass, fern, dead tree, cactus,
127 birch, willow, mushroom, bamboo, flower) + rocks/cliffs + the prop/architecture set CSG now
128 enables (crates, fences, walls, simple buildings, furniture — chair/table already in the demo).
129- **Platform team:** bake AO/cavity shading + per-vertex wind weights into the shared pipeline
130 (every model above ships better-looking and game-ready automatically); add instancing and the
131 glTF/GLB exporter.
132
133### Months 4–6 — Platform & product (split: scene/biome + playground)
134- Real Web Worker pool.
135- Biome/scatter scene generator.
136- Hosted playground + gallery with one-click glTF export.
137- npm publish pipeline (build, `.d.ts`, dual ESM).
138- Docs, perf benchmarks, visual regression harness.
139
140---
141
142## Definition of success
143
144- 20+ models spanning vegetation, rocks, props, and basic architecture — each with presets,
145 LODs, baked AO, and wind data.
146- Shapecraft installable from npm with stable, versioned seeds.
147- One-click glTF/GLB export from a hosted playground.
148- Forests/biomes rendered via instancing + workers without blocking the main thread.
149- A general-purpose, documented, benchmarked procedural-mesh library others can build on.