Operating guide

Make the next decision playable. Let the world keep the receipt.

Ludis can begin a game, forge a fiction artifact, steward campaign state, or package that state for offline use elsewhere. Its job is consequential creative motion—not decorative lore accumulation or live VTT control.

Inputs

Supply what governs the work.

Creative framePremise, tone, scale, current pressure, and the deliverable needed now.

Rules postureGame and edition, house rules, supplied formulas, or an explicitly provisional system-light stance.

Table contractPlayer preferences, lines, veils, accommodations, and other declared boundaries.

AuthorityExisting canon, source provenance, visibility, who may approve change, and publication rights.

Configuration

Campaign choices belong in campaign state, not product doctrine.

Ludis has no environment-variable or network configuration. Behavior is governed, in order, by the current request and supplied campaign material, SKILL.md, the operating/state/canonical-boundary doctrine, one relevant creative instrument when needed, and the campaign ledger for managed continuity.

Current requestThe transformation, horizon, boundaries, visibility, and evidence needed now.

DoctrineStable product behavior for agency, authority, provenance, continuity, and safe degradation.

InstrumentOne focused creative motion loaded only when the immediate artifact needs it.

Campaign ledgerCampaign-specific canon, proposals, rumors, secrets, approvals, and publication state.

Outputs

Four modes; four first proofs.

PLAY NOW

A real choice in the first response.

Immediate situation, visible pressure, only the controls needed, two to four distinct choices, and permission to try another action.

FICTION FORGE

An artifact ready to use.

A character, place, faction, quest, mystery, object, language, or system with leverage, uncertainty, and hooks—new facts marked proposed.

CAMPAIGN OPERATIONS

A governed next horizon.

Compact GM prep, separate player-safe material, state changes, contradictions, checks, approvals, and next prep.

EXPORT & VTT HANDOFF

An inspectable file the next tool can use.

A neutral Ludis Pack, exact-byte player handoff, Alchemy character JSON, or Foundry v14 offline module with a loss report and bounded support claim.

Workflow

Enter at the earliest unresolved stage.

  1. 01SeedIntent, rules, preferences, boundaries, sources, and the next real need.
  2. 02FramePlayable promise, pressure, invitation, scale, and tone—not a required plot.
  3. 03PrepareStakes, approaches, clues, telegraphing, consequences, adaptation, and open mechanics.
  4. 04PlayCompact GM packet, player-safe material, improvisation handles, and agency.
  5. 05RecordObserved events, choices, declared outcomes, resource changes, and unresolved questions.
  6. 06ResolveProposed consequences, reactions, rumors, supersessions, and approval requests.
  7. 07AdvanceAudit continuity, leakage, dead prep, stalled actors, player interest, and the next horizon.

Representative requests

Ask for the transformation, boundary, and evidence you need.

Use $ludis-continuum to prepare one session from this ledger and last-session summary. The party plans to enter the flooded archive. Preserve active canon, keep the archivist's pact GM-only, give the archive at least three viable entry approaches, and do not assign exact DCs unless they follow the supplied rules.
Create a dock registrar who can grant access to the quarantine pier. She wants the missing manifests found, distrusts the harbor guard, and must remain consistent with the attached city notes. Player-facing cues must not reveal who altered the manifests.
Use $ludis-continuum to begin a quiet science-fantasy game. I am a courier at a closed orbital garden. Start in the scene, offer three materially different choices, and let me attempt something else. Use a reversible system-light posture.
Export tonight's session material from this campaign as separate GM and player-safe Ludis Packs. Include declared maps and tokens, preserve every GM-only object, show me the player preview, and do not finalize the player ZIP until I approve those exact bytes.

Campaign ledger

Confidence does not promote canon.

campaign-ledger.json is canonical for a managed workspace. Each object records identity, kind, status, visibility, authority, provenance, confidence, and tenure.

GM_ONLY

Secrets stay segregated.

A player-safe projection cannot traverse a declared link to a GM-only object. Human review must still catch semantic spoilers written directly into ordinary prose.

PLAYER_SAFE

Candidate bytes require approval.

The projection can include structurally valid, export-eligible player_safe objects in canon or non-canon statuses. A human approves the complete candidate, not each object.

Statuses: proposed, active_canon, disputed, superseded, quarantined, and retired. Conflicting claims stay visible until authority resolves them.

Deterministic tools

Guard the state transition; never inflate the verdict.

init_campaign.py

Creates a v2 workspace with an owner-chosen or owner-seeded stable campaign ID and refuses a non-empty destination.

validate_ledger.py

Checks required state, identity, status, visibility, links, assets, authority, and schedule collisions.

promote_object.py

Requires exact selection, eligible status, asserted GM approval, and no active-canon contradiction.

export_campaign.py

Builds and verifies neutral GM packs or reviewable player candidates, then finalizes approved bytes unchanged.

export_target.py

Builds and statically validates Alchemy or Foundry v14 ZIPs with the same player-approval boundary.

snapshot_campaign.py

Creates a hashed ZIP manifest without nesting prior checkpoint ZIPs.

Use the offline export guide for copyable commands, target import steps, completion checks, and recovery. Ledger examples and the broader tool reference live in the complete repository guide.

Limits

Things Ludis will not pretend to have done.