sprite-machine 0.1.0 → 0.2.0

package/README.md

@@ -1,58 +1,83 @@
 # sprite-machine
 
-Turn a **3×2 sheet of pixel-art face sprites** (left / front / top over
-right / back / bottom) into a real, low-poly, textured **three.js mesh** —
-or a **glTF 2.0 binary** any engine's importer reads. The chunky look is
-carved into the geometry, not faked by a shader: 1 pixel = 1 voxel, with
-45° wedges smoothing every same-colour staircase and the colour riding a
+Turns a 3×2 sheet of pixel-art face sprites (left / front / top over right /
+back / bottom) into a low-poly, textured model: indexed triangle buffers and
+a skin bitmap, or a glTF 2.0 binary. One pixel is one voxel. 45° wedges
+smooth every same-colour staircase, and the colour comes from a
 nearest-sampled skin texture.
 
 This is the engine behind [Sprite Machine](https://aportilla.github.io/sprite-machine/),
-the System 7 desktop app that draws these sheets. Keep the sheet as the
-source of truth and derive the model wherever you need it — at a build
-step, at a server's startup, or in the browser, straight into a scene.
+the desktop app that draws these sheets. It runs at a build step, at a
+server's startup, or in the browser.
 
 ```bash
-npm install sprite-machine three
+npm install sprite-machine
 ```
 
-`three` is a peer dependency: the mesh is a `THREE.Mesh` and the mesher
-uses three's geometry utilities. Node 20.19+ / 22.12+.
+The root entry depends on `earcut` alone. Requires Node 20.19+ or 22.12+.
 
 ## The API
 
 ```js
 import { buildModel, modelToGlb } from 'sprite-machine';
 
-// pixels in: {width, height, data} — an ImageData, or the same shape
-const model = buildModel(sheet, { transforms });
-//   → { mesh, dims, triangles, warnings, unitsPerVoxel: 1 }
-//     a THREE.Mesh at ONE UNIT PER VOXEL, its skin the material's map;
-//     `transforms` is the document's per-view reorientation (optional)
+// sheet: {width, height, data}, an ImageData or the same shape
+const model = buildModel(sheet, { transforms, layers });
+//   → { geometry, skin, color, triangles, dims, warnings, unitsPerVoxel: 1 }
+//     geometry is { position, normal, uv, index, bounds }: Float32 xyz per
+//     vertex at one unit per voxel, centered on X and Z, unit normals, uv
+//     pairs in [0, 1], a Uint32 CCW triangle index and the bounds. skin is
+//     the texture, { width, height, data }, sRGB RGBA with row 0 at v = 0.
+//     transforms is the per-view reorientation (optional). layers is the
+//     sheet's block count (optional, 1 by default; see Layers).
 
 const glb = modelToGlb(model, { name: 'car', voxelsPerMeter: 10 });
 //   → Uint8Array: one node, one mesh, one primitive, the skin embedded as
-//     a PNG behind a NEAREST sampler; `unlit: true` for KHR_materials_unlit
+//     a PNG behind a NEAREST sampler. unlit: true adds KHR_materials_unlit.
 ```
 
-Both are synchronous and pure. A three.js page uses `model.mesh` directly
-and never writes a file; a Node process writes the glb. To run the build
-off a main thread, wrap it in a worker or a child process.
+Both functions are synchronous and pure. `buildModel` throws on an invalid
+sheet or a sheet with no painted view in any layer. To build off the main
+thread, call them from a worker or a child process.
+
+### In three.js
+
+Two routes. `sprite-machine/three` turns the model into a `THREE.Mesh`, with
+`three` installed beside the engine:
+
+```js
+import { toMesh, toGeometry, skinTexture } from 'sprite-machine/three';
+
+const mesh = toMesh(model); // a flat-shaded MeshStandardMaterial over the skin
+const geo = toGeometry(model.geometry); // a BufferGeometry with its bounds
+const map = skinTexture(model.skin); // a DataTexture, nearest, sRGB, flipY false
+```
+
+Or write the glb and load it with `GLTFLoader`, which reads the sampler, the
+sRGB texture, the unlit extension and the node name. Every other engine loads
+the glb. `three` is an optional peer (0.152 or later), and the root entry
+never imports it.
 
 ### In Node: a document PNG in
 
 ```js
 import { readSheet, sheetToGlb } from 'sprite-machine/node';
 
-const { image, name, transforms } = readSheet(bytes); // pngjs decodes; the
-// Title and sprite-machine:transforms chunks are read as the app reads them
-const glb = sheetToGlb(bytes, { voxelsPerMeter: 10 }); // the three calls in one
+// pngjs decodes the pixels. The Title, sprite-machine:transforms and
+// sprite-machine:layers chunks are read as the app reads them.
+const { image, name, transforms, layers } = readSheet(bytes);
+const glb = sheetToGlb(bytes, { voxelsPerMeter: 10 }); // readSheet, buildModel, modelToGlb
 ```
 
-`sprite-machine/node` is the one entry with a decoder; the root entry takes
-pixels and depends on nothing but three, so a browser bundle never sees
-`pngjs`. In a browser, decode with `createImageBitmap` and a canvas and
-hand `buildModel` the `ImageData`.
+`readSheet` also returns `chunks`, every text chunk verbatim. `layers` is the
+layer names, or null. `sheetToGlb` builds as many layers as the chunk names
+when that count divides the sheet's height into whole blocks, and one layer
+otherwise. It takes an optional `name`, which overrides the Title chunk. With
+neither, the name is `'sprite'`.
+
+`sprite-machine/node` is the only entry with a PNG decoder. The root entry
+takes pixels, so a browser bundle never includes `pngjs`. In a browser, decode with `createImageBitmap` and a canvas, and pass
+the `ImageData` to `buildModel`.
 
 ### The CLI
 
@@ -60,59 +85,83 @@ hand `buildModel` the `ImageData`.
 npx sprite-machine build sprites/*.png --out models/ [--voxels-per-meter 10] [--unlit]
 ```
 
-One `<name>.glb` per sheet — the Title chunk's name, else the file's — and a
-line per file. The first failure exits non-zero.
+Writes one `<name>.glb` per sheet, named from the Title chunk or else the
+file name, and prints a line per file. The first failure exits non-zero.
 
 ## The sheet
 
-One PNG, six tiles in a fixed layout, empty tiles allowed (a face with no
-view of its own is mirror-filled from its opposite):
+One PNG with six tiles in a fixed layout. Empty tiles are allowed: a face
+with no view of its own is mirror-filled from its opposite.
 
 ```
 LEFT   FRONT  TOP
 RIGHT  BACK   BOTTOM
 ```
 
-The tile size derives from the image (a 120×80 sheet is 40×40 tiles). Use
-**square tiles**: a tile is a literal slice of the voxel lattice, so a
-pixel's position inside its tile is its position in the object, and the
-faces must be **registered** — a FRONT pixel is solid only where the SIDE
-covers its row and the TOP covers its column. Sprites are hard pixel art:
-every texel fully opaque or fully transparent.
-
-World: `+x` right, `+y` up, `+z` toward the front. Draw FRONT and BACK
-head-on and upright; RIGHT and LEFT as the sides with the front pointing
-right and left; TOP and BOTTOM as plan views with the front at the top edge.
-Per-tile `rot` / `flipX` / `flipY` transforms exist for sheets that don't
+The tile size derives from the image (a 120×80 sheet has 40×40 tiles). Use
+square tiles. A tile is a slice of the voxel lattice, so a pixel's position
+in its tile is its position in the object. The faces must be **registered**:
+a FRONT pixel is solid only where the SIDE covers its row and the TOP covers
+its column. Every texel must be fully opaque or fully transparent.
+
+World axes: `+x` right, `+y` up, `+z` toward the front. Draw FRONT and BACK
+head-on and upright, RIGHT and LEFT as side views with the front pointing
+right and left, and TOP and BOTTOM as plan views with the front at the top
+edge. Per-tile `rot` / `flipX` / `flipY` transforms handle sheets that don't
 follow the convention.
 
-The model's origin is the **lattice floor's centre**, Y up, winding CCW.
-`voxelsPerMeter` is the reader's scale: at 10, a 40-voxel car is 4 m long.
+The model's origin is the centre of the lattice floor, Y up, with CCW
+winding. `voxelsPerMeter` sets the glb's scale: at 10, a 40-voxel car is
+4 m long.
+
+### Layers
+
+A sheet can stack several blocks of the six tiles, one under another at one
+tile size: `3t × 2tN` for `N` layers, the first on top. Each layer carves its
+own hull and the model is their union, so it can hold concave shapes a single
+hull fills in, such as a body on separate wheels. Where two layers hold the
+same voxel, the later layer colours its faces. A layer with views on one plane
+only is one voxel deep, on the face of the lattice those views look at: a
+front-only layer lies on the front plane.
+
+```js
+const model = buildModel(sheet, { layers: 2 });
+```
+
+Without `layers`, a sheet is one block. A document PNG names its blocks in a
+`sprite-machine:layers` text chunk, `{"layers":[{"name":"Body"},{"name":"Wheels"}]}`,
+whose length is the layer count. The parts are exported too: `sliceLayers`,
+`buildLayeredVoxels`, `unionVoxels`, `LAYERS_CHUNK`, `layersChunk`,
+`parseLayersChunk`, `layerCount` and `LAYER_MAX` (8, the app's cap, which the
+chunk parser also holds to).
 
 ## The technique: multi-view visual-hull voxelization
 
-1. **Ingest** — each tile at native size into occupancy and packed-RGB
-   arrays. No auto-crop: registration is the whole point.
-2. **Reconcile dims** — one integer resolution per axis from the tile size
+1. **Ingest**: each tile at native size into occupancy and packed-RGB
+   arrays. No auto-crop, so the views stay registered.
+2. **Reconcile dims**: one integer resolution per axis from the tile size
    (`front → W×H`, `side → D×H`, `top → W×D`), views placed at identity.
-3. **Carve** — a voxel is solid iff it is inside every provided view's
-   silhouette: a boolean AND of extruded masks.
-4. **Surface** — keep the voxels with an exposed face, six-bit masks.
-5. **Colour** — each exposed face takes the colour of the view that sees it
+3. **Carve**: a voxel is solid iff it is inside every provided view's
+   silhouette (a boolean AND of extruded masks).
+4. **Surface**: keep the voxels with an exposed face, as six-bit masks.
+5. **Colour**: each exposed face takes the colour of the view that sees it
    first along its axis (depth-aware first hit), snapped to the sprite's
-   palette; faces no view sees fall through mirrored opposite → neighbour
-   average → dominant body colour.
-6. **Mesh** — exposed faces merge on occupancy alone into coplanar regions
-   (holes included), triangulated by earcut; 45° **wedges** fill every
-   concave unit-step notch whose two faces share a material, one quad per
-   slope block, the gable caps folded into the walls; a lattice-exact
-   T-junction repair keeps it watertight. The colour is the **skin**: a
-   chart per multi-colour region, a swatch per colour, packed
-   deterministically onto a power-of-two sheet and sampled nearest.
-
-The wedge gate is strict and local: paint a riser and its tread the same
-colour and the corner ramps; paint them differently and it stays a crisp
-step. That is the author's control over every slope.
+   palette. Faces no view sees fall back to the mirrored opposite, then the
+   neighbour average, then the dominant body colour.
+6. **Mesh**: exposed faces merge on occupancy alone into coplanar regions (holes
+   included), triangulated by earcut. 45° wedges fill every concave
+   unit-step notch whose two faces share a material, one quad per slope
+   block, with the gable caps folded into the walls. A lattice-exact
+   T-junction repair keeps the mesh watertight. The colour is a skin: a
+   chart per multi-colour region and a swatch per colour, packed
+   deterministically onto a power-of-two texture and sampled nearest.
+
+With layers, steps 1 to 5 run once per layer. The union ORs the solids in the
+largest lattice, extracts its surface again, and gives each exposed face the
+colour the last layer holding its voxel gave it. Step 6 meshes the union.
+
+The wedge gate is local. A riser and its tread painted the same colour get a
+ramp at the corner. Painted differently, they keep the step.
 
 ## License
 

package/bin/sprite-machine.mjs

@@ -1,14 +1,6 @@
 #!/usr/bin/env node
-// ---------------------------------------------------------------------------
-// The CLI: sprite sheets in, glb files out.
-//
-//   sprite-machine build <sheet.png>... --out <dir> [--voxels-per-meter N] [--unlit]
-//
-// One <name>.glb per sheet under --out — the Title chunk's name, else the
-// file's — and a line per file naming it, its triangles and its bytes. The
-// first failure exits non-zero. A thin shell over `sprite-machine/node`:
-// nothing here builds anything.
-// ---------------------------------------------------------------------------
+// CLI over sprite-machine/node: writes one glb per sprite sheet (see USAGE)
+// and prints each file's path, name and size. Exits 1 on the first failure.
 
 import { parseArgs } from 'node:util';
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sprite-machine",
-  "version": "0.1.0",
-  "description": "Turn a 3×2 sheet of pixel-art face sprites into a low-poly, textured three.js mesh or a glTF binary — the engine behind Sprite Machine.",
+  "version": "0.2.0",
+  "description": "Turn a sheet of pixel-art face sprites into a low-poly, textured glTF binary — the engine behind Sprite Machine.",
   "license": "MIT",
   "author": "Adam Portilla",
   "type": "module",
@@ -28,7 +28,8 @@
   "sideEffects": false,
   "exports": {
     ".": "./src/index.js",
-    "./node": "./src/node.js"
+    "./node": "./src/node.js",
+    "./three": "./src/three.js"
   },
   "bin": {
     "sprite-machine": "./bin/sprite-machine.mjs"
@@ -44,9 +45,15 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "peerDependencies": {
-    "three": "^0.185.0"
+    "three": ">=0.152.0"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    }
   },
   "dependencies": {
+    "earcut": "3.0.2",
     "pngjs": "^7.0.0"
   }
 }