# Sprite Maker

Sprite Maker is a standalone authoring tool powered by the ethosBASIC G3D engine. Open `/sprite-maker` on the Studio server (or `web/sprite-maker/index.html` on a server hosting this repository). Studio's toolbar links to it. It needs no editor session, account, external CDN or remote renderer.

A compact 3D subject and an editable recipe generate consistent animation frames. Change an outfit, weapon, colour, camera or light, then record the same sequences again. The built-in library stores procedural geometry, not downloaded atlases. A recipe is the small, reproducible source; baked packs are an explicit export for games that need them.

## Make a pack

1. Choose a genre and model. The 59 original subjects cover fantasy, zombies, space, air, combat, sea, land, science, vegetables, weapons, effects and scenery. The twelve fantasy classes reuse Middle Planet's actual joint rig, clothing and weapon construction. Characters support outfit/weapon swaps and weapon stowing.
2. Select one or more supported sequences. Preview any selected sequence, change facing, play/pause or scrub. Set FPS and duration. Source poses are sampled deterministically. Loops omit the duplicate end pose; one-shot actions include their terminal pose. The exported duration is the rounded frame count divided by FPS, with at least two frames.
3. Choose a camera template, then adjust width, height, direction count, elevation, initial yaw, projection and world span. **Fit whole animation** measures all directions and 16 time samples per action, retaining one common scale/pivot. Extreme custom imported motion may need more span. Anchor X/Y is a fraction of the output frame, not the subject's bounding box.
4. Choose a lighting preset, ground shadow and optional outline. The shadow is a simple contact ellipse, not ray-traced scene occlusion. Preview backgrounds are checkers; exported backgrounds are transparent. Change skin and palette independently on characters.
5. Capture a ZIP, save a recipe, or use a themed collection to generate multiple subjects with the same camera and lighting. Capture can be cancelled. No partial ZIP is downloaded after cancellation.

At 128 × 128, eight directions and eight frames, one sequence produces 64 frames. The tool checks size before allocating: 2,048 frames and 12 megapixels per capture or collection. Lower dimensions, FPS, duration or direction count for larger libraries. Preview caching is limited to 64 images and replaced when settings change. Recipe autosave is best-effort, only below 2 MB; **Save recipe** is the portable copy.

## Capture templates

| Template | Main use |
| --- | --- |
| Isometric 8; Middle Planet 30°; dimetric 16 | Adventure characters, props, creatures and equipment |
| Top-down 8; top-down single; arcade 32 | Ships, tanks, racing, overhead shooters |
| Side-scroller; front/back; RPG 4 | Platformers, characters and traditional RPGs |
| RTS small | Small units with consistent direction sets |
| 3D perspective | Projected vehicles and characters |
| Wide; portrait; large | Wide vehicles, tall characters and larger artwork |
| Inventory; effects | Rotating items, weapons, pickups and effect sequences |

Eight light presets: studio, daylight, sunset, moonlight, dungeon torch, neon cyan, flat palette and silhouette. Nine collections: adventurers, space fleet, zombie outbreak, arsenal, sea/air/land, science laboratory, vegetable patch, effects and world props. Capture settings remain independently editable. A collection records its declared sequences, using only those supported by each model.

## Export contract

Every subject's ZIP directory contains:

- `recipe.json`: schema `ethos-sprite-recipe`, version 1; model, selected actions, camera, light, timing, outfit and colour. Imported geometry and provenance travel with the recipe.
- `sheet-N.png`: paginated, untrimmed RGBA atlases, each at most 1024 × 1024. No alpha keying or per-frame bounding-box shifts. Keep at least 2px texture padding when repacking for filtered GPU rendering; these sheets use exact cells and suit nearest-neighbour sampling.
- `manifest.json`: schema `ethos-sprite-pack`, version 1; frame rectangles, sheet indices, pixel pivots, sequence start/count, FPS, direction angles, looping and authored event-frame hints.
- `sprites.bank`: original EIMG bank encoding, with alpha and stored hotspots.
- `player.eto` and `player.bas`: a self-contained BASIC preview that sweeps the captured frames; arrows move and Space pauses. It is a preview of the whole pack, not a gameplay action controller. Use manifest clip ranges and loop/event semantics in the consuming game.
- `CREDITS.txt`: author, source and licence carried from the imported asset or original procedural library.

Frame order is **action → direction → frame**. Coordinates are Y-up, facing -Z, yaw around Y; angles are degrees. No directions are mirrored. Sequence timings and pivots are stable when changing views. Sprite Maker uses the same native mesh/lighting/depth construction and software triangle rasteriser as the G3D runtime; only its authoring capture target adds true alpha and orthographic projection. Existing BASIC G3D commands retain their original perspective/opaque behaviour.

## Importing and sourcing 3D assets

The searchable source catalogue in the app links to **23 creator pack pages**, checked 9 October 2026. It covers authored animated characters, modular men/women, zombies, animals, monsters, fish, mechs, tanks and space subjects, plus static ships, cars, crops, vegetables, weapons, buildings and scenery. `src/sprites/sources.js` is the machine-readable list. These are external source references, not bundled or automatically downloaded models. Each listed pack page showed CC0 when checked; retain the actual downloaded release's licence and creator details.

The import panel also loads **13 existing Skybreak models** directly from their repository files: the courier, enemies/bosses, rocket and effects. They are fetched on demand and retain their native state geometry and source path.

Supported imports:

- **G3D**: native descriptors with up to 32 model states. States become sampled frames.
- **OBJ**: static geometry, triangulated with positive/negative vertex indices and normalized to a 2.5-unit subject. Materials/MTL/textures are not imported; the neutral material is explicit. Concave OBJ polygons should be triangulated in the modelling tool before import.
- **`.sprite-model.json`**: one or more named clips of evaluated meshes. Each clip has a duration, loop flag and 1–32 source poses, sharing one coordinate system. Playback samples these poses; it does not invent in-between skeletal motion. Every import needs author, source and licence. Per-frame geometry, index, numeric and size limits are validated before rendering.

For FBX, glTF/GLB or Blend models, import into Blender, select the subject meshes, activate the intended action/NLA tracks and use `scripts/sprite-maker/export-blender.py`. It samples evaluated geometry, including skeletal deformation and modifiers, into the JSON import contract. Run it once for each desired scene/action configuration; multiple validated clip objects can share a model file. Keep coordinate transforms and scale identical between clips. The exporter preserves per-material colours, not UV textures/PBR shading. Retargeting animation libraries onto a rig remains a modelling operation.

```sh
blender scene.blend --background --python scripts/sprite-maker/export-blender.py -- \
  --output walk.sprite-model.json --clip walk --start 1 --end 24 --samples 16 \
  --author "Creator" --source "https://creator.example/model" --license CC0-1.0
```

Use `--one-shot` for attack/death/end-state clips, `--scale` for unit conversion, or `--all-meshes` for an intentionally isolated scene. Importing a model does not execute model-provided scripts. The browser importer and fixture clips are tested. The optional Blender adapter is syntax-checked here; running it against a real Blender installation and third-party rigs remains an explicit validation item.

The built-in subjects are stylised low-poly starters. Current rendering uses vertex/material colours, one key light plus ambient, optional outline and contact shadow. UV/PBR texture capture, normal/depth/material-map exports, skeleton retargeting, automatic third-party downloads and arbitrary Blender scene editing are not implemented in this release.

## Examples and verification

`examples/features/sprite-maker-workshop.eto` is registered in Studio. Bank 6 contains eight compact native G3D states; Bank 1 is created at runtime by eight renders and `Image Grab`, then reused. Bank 0 contains editable BASIC. There are no baked image downloads. Arrows move, Space or the on-screen Pause button pauses, Escape exits. The original perspective capture uses colour-key transparency; full alpha/orthographic capture is the standalone tool's export path.

```sh
npm run build:sprite-maker
npm run test:sprite-maker
FEATURE_EXAMPLES=sprite-maker-workshop.eto npm run test:examples
npm run test:sprite-maker:browser
```

Browser tests launch their own local server unless `STUDIO_URL` is set. `CHROMIUM_PATH` selects an installed Chromium. Evidence is written to `SPRITE_EVIDENCE_DIR` (default `/tmp/ethos-sprite-maker-evidence`). The CI job runs the shared renderer regression, both JS engines, real Chromium desktop/touch, archive round trips, source import, recipe persistence, cancellation and collection export. Native Windows parity and physical-device performance are not asserted.

## Standalone hosting and reuse

The dedicated entry page has no dependency on Studio UI state. Serve `web/sprite-maker`, the pinned ethosBASIC SDK and `web/release.json` from the same origin. The shared rig now lives at `src/sprites/presets/characters.cjs`; procedural subjects no longer import a game repository. Middle Planet's original Node entry remains a compatibility shim to that same rig. Serve `.js`, `.mjs` and `.cjs` as JavaScript.

Optional game models are deployment-owned asset packs. Load `/component-config.js` before the application and set `window.ETHOS_COMPONENTS.assetPacks.skybreak` to `{baseUrl:'https://your-assets.example/skybreak/0.56.0/models/',version:'0.56.0'}`. The base must be a complete HTTP(S) directory URL and the version must name the selected release. The SDK supplies model IDs and provenance, but no game-asset URL. Omit the pack (or set it to `null`) to run with only procedural subjects and file import. Allow the asset origin in the site's `connect-src` policy and configure CORS on the asset host. The original combined deployment supplies its local asset path through `component-config.js`.

Programmatic consumers can use `capturePlan`, `SpriteCapture`, `exportPack`, the source/model catalogues and versioned recipes. A compact recipe + procedural model library is the reusable runtime approach, while the explicit atlas/EIMG exports serve conventional sprite games.