@three-flatland/bake

Shared bake pipeline infrastructure for three-flatland and Three.js WebGPU. Provides the flatland-bake CLI dispatcher, browser-safe loader utilities for assets with offline-baked siblings, and the baker discovery mechanism.

Alpha Release — this package is in active development. The API will evolve and breaking changes are expected between releases. Pin your version and check the changelog before upgrading.

Install

npm install @three-flatland/bake

Install alongside any package that contributes a baker — e.g. @three-flatland/normals for sprite normal maps.

Quick Start

Run a registered baker

npx flatland-bake normal public/sprites/knight.png
npx flatland-bake --list

The CLI walks node_modules and picks up any package that declares a flatland.bake manifest in its package.json. Install a baker package and its subcommand appears in --list automatically — no registration step.

Use the browser-safe utilities

Loaders that follow the "try baked sibling → fall back to in-memory" pattern share a small utility surface from the default entry. Importable from any environment (browser, node, workers):

import {
  bakedSiblingURL,
  probeBakedSibling,
  hashDescriptor,
  devtimeWarn,
  type BakedAssetLoaderOptions,
} from '@three-flatland/bake'

Node-only code (CLI, discovery, sidecar file writers) lives under the /node subpath:

import { discoverBakers, writeSidecarPng, writeSidecarJson } from '@three-flatland/bake/node'

Authoring a Baker

Packages contribute bakers via a flatland.bake manifest plus a default-exported Baker:

// package.json
{
  "flatland": {
    "bake": [
      {
        "name": "normal",
        "description": "Bake a tangent-space normal map from a sprite PNG",
        "entry": "./dist/cli.js"
      }
    ]
  }
}

// src/cli.ts
import type { Baker } from '@three-flatland/bake'

const baker: Baker = {
  name: 'normal',
  description: 'Bake a tangent-space normal map from a sprite PNG',
  run: async (args) => {
    // your CLI logic here — return 0 for success
    return 0
  },
}
export default baker

@three-flatland/normals is a reference implementation.

Options

CLI

flatland-bake <name> [args...]    Run a registered baker
flatland-bake --list              List registered bakers
flatland-bake --help              Show usage

Shared loader option

Every loader that speaks the baked-sibling pattern extends BakedAssetLoaderOptions, which adds a single flag:

interface BakedAssetLoaderOptions {
  /** Generate this asset's derived data in the browser on every load
   *  instead of loading a pre-baked sidecar. */
  forceRuntime?: boolean
}

forceRuntime: true declares the browser is where this asset's derived data is produced — not the CI bake step. You always get the data either way (if you ask for it, you get it); this flag just chooses where the generation runs. Use it for assets that are procedurally varied, throwaway prototypes, or asset bundles where shipping the sidecar isn't worth the bytes. Suppresses the "no baked sibling" warn because the missing sidecar is the architecture, not a mistake.

Not a dev-iteration knob — the default path (probe → generate on miss + warn pointing at flatland-bake) already handles iteration. Mirrors SlugFontLoader.forceRuntime; one name across every baked-asset loader in the ecosystem.

Using with plain Three.js

@three-flatland/bake is renderer-agnostic. Run the CLI from any project's npm scripts to bake assets, or import the browser-safe helpers to write your own sidecar-aware loaders — no three-flatland dependency required.

Related

• three-flatland — the 2D engine. High-level loaders consume this package's helpers internally.
• @three-flatland/normals — reference baker: sprite / tileset normal map generation.

Documentation

Full docs, interactive examples, and API reference at thejustinwalsh.com/three-flatland

License

MIT

This README was created with AI assistance. AI can make mistakes — please verify claims and test code examples. Submit corrections here.