Seedling

Deterministic generation with verifiable provenance: generators turn a seed string into the same output forever (names, loot, dungeons, noise maps), series mint supply-capped serial-numbered artifacts, and every artifact carries an append-only hash-chained custody history whose genesis can cite the exact (generator, version, seed) that grew it. Verifiable scarcity and lineage, no blockchain. Every example on this page was executed against a live server.

When to reach for it: daily-challenge dungeons identical for every player, shareable world seeds as URLs, "1 of 500" founder badges with verifiable mint caps, custody chains for tradable items, reproducible test fixtures, AI-content audit trails.

When not to: random draws that should not be reproducible belong to Lottery; inventory slots, stacking, and crafting belong to Item (which delegates custody back to Seedling); proving ownership of external social accounts belongs to Attestation.

Concepts

• Generators are versioned definitions of a deterministic algorithm (types: name, loot, sequence, noise, grid_map, bsp_rooms, wfc, perlin_noise, simplex_noise, grammar). They start as drafts; publishing freezes an immutable version snapshot you can generate against forever.
• The determinism triple - (generator, version, seed) plus params always yields the same output and the same content_hash. Omitting version resolves to the latest published one and echoes it back.
• Seeds are plain strings - share them as URLs, register them by name, or let the server derive a canonical daily seed per generator.
• Results are cached keyed by (generator, version, params, seed); responses carry cached: true on a hit. Same triple, different params is a different cache entry and a different output.
• Artifacts and series live on the provenance side: a series mints serial-numbered artifacts, each with a hash-chained record history. See Minting and provenance.
• Permissions - anyone authenticated can create generators and publish seeds; publishing a generator is creator-or-admin; creating series and featuring seeds require a platform admin token.

Define and publish a generator

snug seedling generators create --name "Norse Names" --type name \
  --determinism-contract "Same seed, same names, forever"
snug seedling generators publish --generator-id gen_AyXCjwbTZspw
snug seedling generators list -t grid-map
snug seedling generators version --generator-id gen_AyXCjwbTZspw --version 1

A draft cannot generate - the call fails with 400 not_published until you publish. Publishing twice fails with 409 already_published, and publishing someone else's generator fails with 403 insufficient_permissions unless you are a platform admin. grammar generators additionally require an inline --grammar JSON definition with start and rules.

Generate

snug seedling generate --generator-id gen_AyXCjwbTZspw \
  --seed glacier-fox-9421 --param style=norse --param count=3

Over HTTP the same call is POST /api/v1/seedling/generate; the enveloped response, captured live:

{
  "status": 200,
  "msg": "OK",
  "data": {
    "generator_id": "gen_AyXCjwbTZspw",
    "version": 1,
    "seed": "glacier-fox-9421",
    "content_hash": "sha256:717d66faf511df2880556aaf21e6839f...",
    "output": { "names": ["Eirrik", "Thorar", "Eirstein"], "style": "norse" },
    "png_url": null,
    "permalink": "/api/v1/seedling/generators/gen_AyXCjwbTZspw/v1/glacier-fox-9421",
    "cached": true
  }
}

Name generators accept a style pack (norse, elvish, corporate_startup, cyberpunk_handle, tavern); an unknown pack fails with 400 invalid_params. Spatial types (grid_map, bsp_rooms, noise, perlin_noise, simplex_noise, wfc) also render a PNG to Blob storage and return a signed png_url.

Any generation is addressable as a permalink - GET /api/v1/seedling/generators/{id}/v{version}/{seed} - so a seed can be shared as a URL:

snug seedling permalink --generator-id gen_AyXCjwbTZspw --version 1 --seed glacier-fox-9421

Golden-check reproducibility any time - the server regenerates the triple and compares hashes:

snug seedling verify-determinism --generator-id gen_AyXCjwbTZspw --version 1 --seed glacier-fox-9421
# { "deterministic": true, ... }

Batch generation

Pass explicit seeds, or a base seed plus a count - sub-seeds are derived deterministically as base#0, base#1, ...:

snug seedling generate-batch --generator-id gen_AyXCjwbTZspw --base-seed world --count 100

Batch size is capped (256 by default; see the configuration reference).

Daily seeds

Every generator has a canonical seed per UTC date, derived from its id, version, and a per-generator daily salt - the same for every caller all day, with no way to peek ahead:

snug seedling daily --generator-id gen_AyXCjwbTZspw
# { "date": "2026-08-28", "seed": "6955d2fbaf26b0cb", "version": 1, ... }

Named seed registry

Publish memorable seeds for a generator version, browse them, and feature the best (featuring requires a platform admin token):

snug seedling seeds publish --generator-id gen_AyXCjwbTZspw --version 1 \
  --seed glacier-fox-9421 --name "Glacier Fox" --tags norse,easy
snug seedling seeds list --featured-only
snug seedling seeds feature --seed-id seed_mKqCXPYqcADf   # admin only

Minting and provenance

Series, supply-capped minting with idempotency keys, hash-chained custody records, chain and genesis verification, ownership and derivation queries, and external-object tracking have their own page: Minting and provenance.

Limits and configuration

Names up to 200 characters, seeds up to 256, batches up to 256 items, supply caps up to 1,000,000, and a one-hour result cache by default - all tunable via the SEEDLING_* variables in the Seedling CONFIG reference.

Reference

• Seedling API - every endpoint, callable
• Related: Lottery for non-reproducible weighted draws, Item for inventory and crafting, Blob where generated PNGs are stored