Offline exports and VTT handoffs

Barf out the files. Keep canon where it belongs.

Ludis turns a validated campaign ledger into an inspectable ZIP: a neutral Tonight Pack, a separately approved player handoff, Alchemy character JSON, or a Foundry VTT generation 14 module. The ledger stays canonical. No MCP server, account credential, network call, or live VTT control enters the arrangement.

Choose a deliverable

Use the smallest handoff that completes the job.

Each export is created from a frozen local capture. Supplied assets are copied, mapped, and checked before the final ZIP appears.

Neutral Ludis PackGM prep, handouts, objects, tables, scenes, tokens, audio cues, assets, manifests, and a loss report in one deterministic ZIP.

Player handoffA candidate ZIP plus rendered preview and audit. A human reviews the exact bytes before Ludis creates the unchanged final ZIP.

Alchemy character JSONOne JSON file per supported character plus _all.json. An explicit Alchemy systemKey is required.

Foundry v14 moduleAn offline module for core JournalEntry, RollTable, Scene, and embedded Level documents. Actor and Item data are intentionally excluded.

Every format includes reports/loss-report.json. Read it before sharing or importing. A warning records a lossy or omitted mapping; a blocked mapping prevents the target artifact from being built.

Before you export

Start from valid v2 campaign state.

  1. Open PowerShell or a terminal in the Ludis Continuum repository or installed skill directory.
  2. Use Python 3.10 or newer. The exporters use only the Python standard library.
  3. Confirm the campaign contains a cd-ludis-campaign-ledger/v2 ledger.
  4. Declare each asset with a campaign-relative path, visibility, SHA-256 digest, rights status, provenance, and useful alternative text.
  5. Validate the ledger before building:

Windows PowerShell:

python -B scripts/validate_ledger.py C:\Games\MyCampaign\campaign-ledger.json

macOS/Linux:

python3 -B scripts/validate_ledger.py "$HOME/Games/MyCampaign/campaign-ledger.json"

Use a new output filename for every build. Ludis refuses to overwrite an export, preview, audit, receipt, or final artifact because those files are evidence of a specific run.

Generic GM pack

Build tonight's material without choosing a VTT.

The neutral cd-ludis-pack/v1 format is the portable default for unknown or unsupported targets.

Windows PowerShell:

python -B scripts/export_campaign.py build C:\Games\MyCampaign C:\Games\Exports\tonight-gm.zip --audience gm
python -B scripts/export_campaign.py verify C:\Games\Exports\tonight-gm.zip

macOS/Linux:

python3 -B scripts/export_campaign.py build "$HOME/Games/MyCampaign" "$HOME/Games/Exports/tonight-gm.zip" --audience gm
python3 -B scripts/export_campaign.py verify "$HOME/Games/Exports/tonight-gm.zip"

A successful build creates:

Inside the ZIP, start with README.md and ludis-pack.json. Structured data lives under data/, table-ready prose under handouts/, copied files under assets/, and mapping disclosures under reports/.

Supplied Universal VTT JSON is validated and passed through. Ludis does not invent walls, doors, lights, or movement geometry that the campaign did not provide.

Do not send a GM ZIP to players. A GM export may contain secrets by design. Build a separate player candidate even when the two packets seem similar.

Player-safe handoff

Review first. Approve exact bytes. Share the unchanged final.

Structural checks catch declared visibility and link leaks. They cannot recognize a secret casually written into ordinary prose, so the preview is a mandatory human judgment surface.

  1. Build a candidate whose filename ends in .candidate.zip:

Windows PowerShell:

python -B scripts/export_campaign.py build C:\Games\MyCampaign C:\Games\Exports\tonight-players.candidate.zip --audience player

macOS/Linux:

python3 -B scripts/export_campaign.py build "$HOME/Games/MyCampaign" "$HOME/Games/Exports/tonight-players.candidate.zip" --audience player
  1. Open tonight-players.candidate.zip.preview.html in a browser. Review every rendered object, filename, and image for secrets, rights, credits, and table suitability.
  2. Extract a review copy of the candidate into a new directory. Compare its full inventory with the preview and audit; for a neutral pack, also cross-check ludis-pack.json. Listen to audio and inspect every asset or member the HTML preview cannot render. Treat code as text and do not execute it.
  3. Verify the unchanged candidate:

Windows PowerShell:

python -B scripts/export_campaign.py verify C:\Games\Exports\tonight-players.candidate.zip

macOS/Linux:

python3 -B scripts/export_campaign.py verify "$HOME/Games/Exports/tonight-players.candidate.zip"
  1. If the candidate is safe, record the local operator assertion and finalize it:

Windows PowerShell:

python -B scripts/export_campaign.py approve C:\Games\Exports\tonight-players.candidate.zip --asserted-by "local GM"

macOS/Linux:

python3 -B scripts/export_campaign.py approve "$HOME/Games/Exports/tonight-players.candidate.zip" --asserted-by "local GM"

Completion produces tonight-players.zip and tonight-players.zip.approval.json. The final ZIP is byte-for-byte identical to the reviewed candidate. The operator label records an unauthenticated local assertion; it is not identity verification.

If the candidate or preview changes, approval fails. Repair the campaign source, choose a fresh output name, rebuild, and review again. Do not edit ZIPs or sidecars in place.

Target adapters

Speak the target's file dialect without pretending to operate it.

Target exports use the same frozen capture, separate audience projection, immutable output, preview, audit, and exact-byte player approval as a neutral pack.

Windows PowerShell:

python -B scripts/export_target.py build C:\Games\MyCampaign C:\Games\Exports\alchemy-gm.zip --target alchemy --audience gm
python -B scripts/export_target.py verify C:\Games\Exports\alchemy-gm.zip

python -B scripts/export_target.py build C:\Games\MyCampaign C:\Games\Exports\foundry-gm.zip --target foundry-v14 --audience gm
python -B scripts/export_target.py verify C:\Games\Exports\foundry-gm.zip

macOS/Linux:

python3 -B scripts/export_target.py build "$HOME/Games/MyCampaign" "$HOME/Games/Exports/alchemy-gm.zip" --target alchemy --audience gm
python3 -B scripts/export_target.py verify "$HOME/Games/Exports/alchemy-gm.zip"

python3 -B scripts/export_target.py build "$HOME/Games/MyCampaign" "$HOME/Games/Exports/foundry-gm.zip" --target foundry-v14 --audience gm
python3 -B scripts/export_target.py verify "$HOME/Games/Exports/foundry-gm.zip"

Add --object LEDGER-ID to a build command, repeating it when needed, to limit an export. Include every selected object's declared link dependencies or the build stops. Omit the option to project the complete eligible audience set and let the adapter emit the records it supports.

For a player target, use a .candidate.zip filename and --audience player. Follow the complete rendered and non-rendered member review in Player-safe handoff, then approve with the matching tool:

Windows PowerShell:

python -B scripts/export_target.py approve C:\Games\Exports\alchemy-players.candidate.zip --asserted-by "local GM"

macOS/Linux:

python3 -B scripts/export_target.py approve "$HOME/Games/Exports/alchemy-players.candidate.zip" --asserted-by "local GM"

Alchemy RPG

Import explicit character JSON.

The adapter emits one file per supported character and a combined _all.json. It never infers the Alchemy system from a campaign title and never invents missing mechanics.

STATIC: VALIDATED

Constructed and validated.

Ludis checks the emitted JSON shape, required fields, explicit systemKey, safe paths, and loss report against its documented adapter contract.

LIVE: UNVERIFIED

Import remains unverified.

No current Alchemy account import has been observed in this local candidate evidence. Treat the bundle as a reviewable candidate until your own import succeeds.

Prerequisite: use a signed-in Alchemy account and a Universe or active module you can edit. Alchemy's current help article describes JSON import without naming a plan, while its developer documentation says Alchemy Unlimited provides NPC import. Treat plan eligibility as unresolved and confirm it in the current UI; local build and verification establish no account, plan, or edit access.

  1. Extract the target ZIP to a new folder.
  2. Read reports/loss-report.json. Stop if the intended character was omitted or materially reduced.
  3. Open an Alchemy Universe and select NPCs.
  4. Open the menu beside CREATE NPC, then select Import JSON.
  5. Select _all.json for the whole set or an individual character file.
  6. Compare the imported record with the preview and source ledger before using it in play.

Alchemy documents a similar route for character-library and Universe-premade imports. See Alchemy's character import guide and developer format documentation for the current target behavior.

Foundry VTT generation 14

Install a local module, then import into a disposable world first.

The adapter targets Foundry 14.365 core documents. It maps prose and unsupported game-specific records to JournalEntry, valid tables to RollTable, and maps to Scene with embedded Level backgrounds. Player bundles assign those documents OBSERVER; GM bundles assign NONE.

STATIC: VALIDATED

Module and importer are checked.

Ludis validates the exact generated importer, a strict manifest and member allowlist, campaign-scoped identity and revisions, module-relative declared assets, table ranges, scene dimensions, and Level backgrounds.

LIVE: UNVERIFIED

Runtime behavior remains unverified.

Recognition, database acceptance, rendering, visual grid alignment, and repeat-run behavior have not been observed in a running Foundry 14.365 instance.

  1. Back up the Foundry world you intend to use. Prefer a disposable copy for the first import.
  2. Extract the ZIP. Open module.json and note its exact id.
  3. Create <Foundry User Data>/Data/modules/<module-id>/. Extract the ZIP contents there so module.json is directly inside that folder and the folder name exactly matches the manifest id.
  4. Restart Foundry VTT and enable the module in the test world through Manage Modules.
  5. Enter the world as a GM. In Import Ludis campaign bundle, select Import or resume.
  6. Read the completion notification. If it reports errors, preserve the browser console report and do not call the bundle compatible yet.
  7. Inspect every created Journal Entry, Roll Table, Scene, Level background, grid, and asset before importing into the real world. For a player bundle, sign in as a non-GM user and confirm the intended documents are visible before relying on the handoff.

The importer preserves each original source ID but scopes it to the campaign. An exact rerun skips matching revisions and can resume a partial import. Changed content or audience for the same campaign object is reported as a conflict and left untouched; inspect the console report rather than expecting reconciliation.

Foundry defines a module as a named folder under {userData}/Data/modules with module.json at its root. See Foundry's module development guide and 14.365 release page.

Actor and Item are deliberately absent. Foundry core does not define game-system data for them. Add those document types only through a separately qualified adapter for a named game system and version.

Loss reports and recovery

Fix the source, not the evidence.

Build is blocked

Preserve the error. Repair the missing or invalid ledger field, link, asset, digest, scene dimension, table entry, or target field. Build to a fresh path.

Warning is unacceptable

Read the source ID and message in reports/loss-report.json. Add explicit source data or choose the neutral format rather than accepting a lossy target mapping.

Live import fails

Keep the ZIP, loss report, target version, import result, and exact errors. Disabling or removing the module does not remove imported World documents. Restore the recorded pre-import World backup for complete rollback; if no backup exists, preserve the damaged state and follow the flag-guided, explicitly incomplete manual cleanup in the repository guide.

For the complete backup restoration and module quarantine sequence, read Roll back a Foundry test import. Removing the module alone is not rollback.

After a live target attempt, bind the result to the exact ZIP without promoting a product-wide compatibility claim. The output receipt must be a new path. Use --result imported, partial, or failed to match what you observed, and replace the target, version, notes, and paths accordingly. The following commands record a failed Foundry 14.365 attempt.

Windows PowerShell:

python -B scripts/record_import_observation.py C:\Games\Exports\foundry-gm.zip C:\Games\Exports\foundry-gm.import.json --target foundry-v14 --target-version 14.365 --result failed --asserted-by "local GM" --notes "Importer reported three errors"

macOS/Linux:

python3 -B scripts/record_import_observation.py "$HOME/Games/Exports/foundry-gm.zip" "$HOME/Games/Exports/foundry-gm.import.json" --target foundry-v14 --target-version 14.365 --result failed --asserted-by "local GM" --notes "Importer reported three errors"

You are done only when the ZIP verifies, the loss report is acceptable, the correct audience preview has been reviewed, any player candidate has an approval receipt, and the imported or manually used result has been inspected in its actual destination.