Assetgen

packages/assetgen is the DOOM-grade asset generation pipeline.

It turns:

prompt + design canon + provider -> post-process/optimize -> manifest + license -> preview

Dry run

Use mock first. It proves the pipeline without model spend.

bun packages/assetgen/src/cli.ts --provider mock --dry-run --id test --prompt "x"

Generate one asset

OPENAI_API_KEY=sk-... bun packages/assetgen/src/cli.ts \
  --id swarm-husk \
  --game scourge-survivors \
  --kind sprite \
  --prompt "a rotting bio-husk of the Scourge, lunging" \
  --repo ../deadrotcom/apps/games/scourge-survivors

Generate a sprite sheet

bun packages/assetgen/src/cli.ts generate --provider mock --dry-run \
  --id swarm-husk-run \
  --game scourge-survivors \
  --kind sprite \
  --prompt "a parasite-taken Scourge host sprint cycle" \
  --views front,side,back \
  --frames 4 \
  --fps 12 \
  --scale 1.5 \
  --license "internal prototype; review before shipping"

Sprite outputs are padded to power-of-two transparent .webp sheets. The manifest entry records sheet dimensions, frame size, view names, animation timing, anchor, scale, license terms, provider/model provenance, and a billboard preview HTML file.

Use Codex as provider

bun packages/assetgen/src/cli.ts \
  --provider codex \
  --id swarm-husk \
  --game scourge-survivors \
  --kind sprite \
  --prompt "a rotting bio-husk of the Scourge, lunging"

The codex provider rides the local authenticated Codex CLI through node-pty. No extra provider key is needed for that path. The CLI streams Codex output, verifies that the requested PNG was written, then runs the normal .webp and assets.json post-process.

If --provider is omitted, assetgen uses the per-kind default: sprites/maps use codex, textures/icons use openai, audio kinds use suno, and model/3D assets use replicate.

Pipeline contract

The shared package owns the full five-step game asset pipeline:

prompt -> generate -> postprocess -> register -> preview

Generator surfaces should call runAssetPipeline so they cannot write generated outputs without also registering them in assets.json. New manifest entries must include a license object with tool, plan, date, and kind.

Fill the matrix

Matrix mode expands every intended (entity x game) render cell and writes it to the Deadrot asset package by default.

# placeholder fills
bun packages/assetgen/src/cli.ts matrix --provider mock
 
# initialize the external assets package first, if needed
bun packages/assetgen/src/cli.ts matrix --init-catalog --provider mock --id scourge-swarm
 
# real generation through Codex
bun packages/assetgen/src/cli.ts matrix --provider codex
 
# one row or column
bun packages/assetgen/src/cli.ts matrix --id scourge-swarm
bun packages/assetgen/src/cli.ts matrix --game pactfall --only-missing

Target a different asset package

bun packages/assetgen/src/cli.ts matrix \
  --provider mock \
  --assets-dir ../deadrotcom/packages/assets

Discover game token targets

games writes games.json into the Deadrot asset package. It discovers each game’s token targets from the game folders, including both supported constants layouts (src/game/constants.ts and src/constants.ts).

bun packages/assetgen/src/cli.ts games \
  --games-root ../deadrotcom/apps/games \
  --assets-dir ../deadrotcom/packages/assets

Generate design tokens

bun packages/assetgen/src/cli.ts tokens
bun packages/assetgen/src/cli.ts tokens --check

The command compiles the reviewed DESIGN.md frontmatter into packages/assetgen/src/style.generated.ts plus packages/assets/tokens/{theme.css,tokens.css,tokens.ts,tokens.json}. Each artifact carries the design version and hash so apps can detect drift without maintaining hand-forked palettes.

Providers

Keychain storage

security add-generic-password -a shipshit -s shipshit-openai -w <OPENAI_KEY>
security add-generic-password -a shipshit -s shipshit-fal -w <FAL_KEY>
security add-generic-password -a shipshit -s shipshit-replicate -w <REPLICATE_API_TOKEN>
security add-generic-password -a shipshit -s shipshit-suno -w <SUNO_API_KEY>

Keep raw .env files out of commits.

Usage log

Provider calls append local JSONL events to:

~/.shipshitgames/assetgen/usage.jsonl

The log stores provider, kind, model, id, output path, duration, and success/failure. It stores prompt hash and length instead of raw prompt text. Use --usage-log <path> to override or --usage-log off to disable.