Adventure JSON Conversion Guide
Give your AI assistant this page and the adventure you legally have access to.
Use ChatGPT, Claude, Gemini, or a local model to turn a PDF, Markdown
file, or module notes into a validated adventure-json/v1 file that Codex Cryptica checks and stores on your device.
For AI assistants reading this URL: follow only the Canonical Conversion Prompt (prompt.txt). Check that the prompt ends with END OF ADVENTURE JSON V1 CONVERSION PROMPT. If the
link is blocked or the prompt is incomplete, stop.
Ask the user to select “Copy conversion prompt” on the guide and paste the entire prompt into this chat. Wait for it before making an inventory or generating any chunk. A “Continue” request does not replace the missing prompt.
Quick start: from your adventure to Codex Cryptica
- Copy the prompt. Use the button below. If your assistant can open web pages, Copy guide link is a shorter shortcut.
- Paste it and attach your adventure in the AI assistant you prefer (a hosted chatbot or a local model), as a file or pasted text.
- Save the result as a plain
.jsonfile. Keep only the JSON: no Markdown code fences, no commentary before or after. - Import it in your Vault. Open Adventure Mode and choose Import Adventure JSON (step-by-step below).
- Review, approve, then start. Codex Cryptica checks the file on your device. If it is rejected, paste the validation message back to your assistant or see troubleshooting.
Long PDF that an assistant cannot finish in one go? Use the staged method. Passing the import checks does not mean nothing was left out — see valid is not the same as complete.
Copy guide link copies a one-line instruction pointing at the plain-text prompt (prompt.txt). It only works if your assistant can open web pages; local models and chats without browsing need the full prompt instead.
This page is a guide, not a converter. You can't upload or paste your adventure here. Where your adventure goes
Canonical Conversion Prompt
Paste this prompt into ChatGPT, Claude, Gemini, or your local model alongside the adventure text or PDF you want to convert.
Convert the tabletop RPG adventure I provide into a valid Codex Cryptica Adventure JSON v1 document.
Schema: https://codexcryptica.com/schemas/adventure-json/v1.json
Guide: https://codexcryptica.com/adventure-import
Before converting, confirm you have this whole prompt, from the opening conversion instruction through the standalone line “END OF ADVENTURE JSON V1 CONVERSION PROMPT” after the final checklist. If it is missing or cut off, stop. Ask the user to select “Copy conversion prompt” on the guide and paste the entire prompt into this chat. Wait for it before making an inventory or generating any chunk. A “Continue” request does not replace the missing prompt. The complete prompt includes the field contract. If the separate schema URL is unavailable, use that contract without asking the user to paste the schema.
Output contract (read this first):
- Deliver ONE JSON object. If you can create files (a downloadable attachment, canvas or code-tool output), deliver it as a file named after the "id", such as "the-last-grind.json", containing only the JSON, and say only that the file is ready. If you cannot create files, your entire reply is the JSON object: it starts with "{" and ends with "}", with no Markdown code fences and no text before or after it. Never put JSON in a chat reply when you could have attached a file.
- Include all 11 collection arrays, using [] when empty.
- Use only the field names and exact values listed below. Do not add properties.
- Never invent facts. When the source is unclear, record it in "unresolved".
- Never shorten the conversion by dropping or merging entries. If the source is unreadable or inaccessible, name the missing input or page range and ask for readable text or a smaller upload. Never guess.
- If a faithful full conversion will not fit, start staged conversion now. Do not just tell the user to use the staged method.
Automatic staging when the full conversion will not fit:
1. Before generating JSON, inspect the source and make a numbered inventory of all visible sections and their source ranges. For paginated sources, record physical page ranges and flag unreadable or unseen pages separately. For sources without pagination, use headings, anchors or another stable source range; never invent page numbers. Split dense sections into small, non-overlapping chunks. If a page or source range has two sections, say which part each chunk owns. List every expected source-supported entry by collection with its name and planned ID, and mark the section that defines it. Write the exact top-level metadata values in the checkpoint, including the player-safe premise. Reuse them unchanged in every chunk. Assign one ID and defining chunk per shared entity.
2. Convert in source order. Each chunk is a separate JSON object with the same top-level metadata and all 11 arrays. Name files chunk-01.json, chunk-02.json, and so on. Define each entry only in its owning chunk. References to other known chunk IDs may remain pending until assembly. Before marking a chunk complete, compare its actual JSON IDs and per-collection counts with the expected IDs and counts for that section in the inventory; list every missing or unexpected ID and any count mismatch, and do not mark the chunk complete while any discrepancy remains unexplained. Record every completed chunk and any omitted material. Never present an unfinished chunk as complete. If a chunk is too large, split it and retry from the start.
3. If you can create files and keep working within the available limits, save the inventory and proceed with the chunks now. Otherwise return the inventory and checkpoint as plain text, with the next chunk's name and source range and the exact instruction "Continue with chunk 01" (use the actual next number). On continuation, use the existing checkpoint and convert only the requested chunk. Deliver one chunk as raw JSON if you cannot create files. Keep progress notes in separate messages or files, never in the JSON. Ask only for a source range or checkpoint you no longer have.
4. Assemble only after every planned chunk is present, each section's expected IDs and per-collection counts have been compared with its actual chunk JSON, coverage has been checked against the source, and shared metadata and IDs agree. Resolve references against the combined package. If you can run the v1 schema and semantic validator, validate before calling the file ready. Otherwise label the result unvalidated and ask the user to check it in Codex Cryptica. If you cannot assemble reliably, list the saved chunks and point to the assembler at https://codexcryptica.com/adventure-import#long-adventures. Never label an inventory, partial chunk set, or truncated reply as the final adventure.
Conversion procedure (do this silently while writing JSON; return the checkpoint when staging needs another turn):
- Inventory the source by section before writing JSON. Track keyed locations, actors, encounters and their resolutions, clues and alternate sources, rumours, important items, and authored endings. Preserve distinct entries and their source references.
- Classify what the source states, what someone in the story claims, and what the GM decides. Use "unverified" when rumour truth is unspecified. Preserve optional routes and conditional actions without turning them into mandatory scene order. Leave unsupported fields out and record material gaps in "unresolved".
- Audit the result against the inventory. Check each player-visible field and premise field for concealed information, and check that each reference points to the right collection and entity. For labelled PDF excerpts, use the original PDF file positions given in the source.
Shape of a valid answer (trimmed: yours will have more entries and fields). Its ids, codes and wording are only illustrative; use your own, taken from the source:
{
"formatVersion": "adventure-json/v1",
"id": "silent-watchtower",
"title": "The Silent Watchtower",
"version": "1.0.0",
"premise": {
"background": "A hillside watchtower has gone dark.",
"hook": "The Reeve asks the party to relight the beacon."
},
"source": {
"title": "The Silent Watchtower"
},
"locations": [
{
"id": "loc-tower",
"name": "Ridge Watchtower",
"summary": "A stone signal tower above the valley road.",
"visibility": "player-visible",
"epistemicStatus": "explicit"
}
],
"actors": [
{
"id": "actor-tomas",
"name": "Reeve Tomas",
"summary": "The worried village official who hires the party.",
"role": "Village reeve",
"locationId": "loc-tower",
"visibility": "player-visible",
"epistemicStatus": "explicit"
}
],
"factions": [],
"scenes": [
{
"id": "scene-beacon",
"title": "The Cold Beacon",
"summary": "The brazier at the top of the tower is unlit.",
"locationId": "loc-tower",
"visibility": "player-visible",
"epistemicStatus": "explicit"
}
],
"encounters": [
{
"id": "enc-stuck-door",
"title": "The Barred Door",
"description": "The tower door is barred from the inside.",
"alternativeSolutions": [
{
"method": "Talk",
"description": "Convince the watchman inside to lift the bar."
}
],
"locationId": "loc-tower",
"visibility": "player-visible",
"epistemicStatus": "explicit"
}
],
"clues": [
{
"id": "clue-oil-smell",
"text": "The brazier smells of fresh lamp oil.",
"reveals": "Someone tended the beacon recently.",
"placedLocationId": "loc-tower",
"visibility": "player-visible",
"epistemicStatus": "explicit"
}
],
"rumours": [
{
"id": "rumour-ghost-light",
"text": "A ghost puts the beacon out each night.",
"truth": "false",
"sourceActorId": "actor-tomas",
"visibility": "player-visible",
"epistemicStatus": "explicit"
}
],
"items": [],
"secrets": [
{
"id": "secret-tomas-motive",
"text": "Tomas put the beacon out himself to hide a smuggling run.",
"relatedEntityIds": [
"actor-tomas"
],
"visibility": "gm-only",
"epistemicStatus": "explicit"
}
],
"endings": [
{
"id": "ending-lit",
"description": "The beacon burns again and the caravan passes safely.",
"epistemicStatus": "explicit"
}
],
"unresolved": [
{
"id": "unresolved-oil",
"code": "missing-detail",
"message": "The source does not say where the lamp oil is kept.",
"epistemicStatus": "unresolved"
}
]
}
Strict output rules:
1. For a successful conversion, return ONLY valid JSON matching Adventure JSON v1 (no Markdown fences, no prose outside the JSON). Keep staging checkpoints and unreadable-source requests separate from all JSON.
2. Top-level fields:
- Required: "formatVersion": "adventure-json/v1", "id" (/^[a-zA-Z0-9_-]{3,64}$/), "title" (1-200 chars), "version" (strict SemVer, e.g. "1.0.0"), "premise": { "background": string, "hook": string, "theme"?: string[], "tone"?: string }, "source": { "title": string, "authors"?: string[], "publisher"?: string, "publishedDate"?: string, "url"?: string, "license"?: string, "documentHash"?: string (64 lowercase hex chars) }.
- Optional: "description": string, "system": { "name": string, "targetParty"?: { "sizeMin"?: integer >= 1, "sizeMax"?: integer >= 1, "levelMin"?: integer >= 0, "levelMax"?: integer >= 0 } }.
- Required 11 collection arrays ([] when empty): "locations", "actors", "factions", "scenes", "encounters", "clues", "rumours", "items", "secrets", "endings", "unresolved".
3. Source certainty (CRITICAL):
- Every entity requires "epistemicStatus": "explicit" | "inferred" | "ambiguous" | "unresolved".
- Do not invent missing facts merely to fill fields. Omit optional fields when the source is silent.
- Use "explicit" only for what the source states. Use "inferred" for anything you worked out yourself (links, endings, roles, unstated consequences).
- For entries in "unresolved", use "ambiguous" when the source is unclear or contradictory, or "unresolved" when it does not answer the question; never use "explicit" or "inferred".
4. Collection entry contract (? = optional; non-empty strings required for id, name, title, text, description, code, message):
- Every collection entry requires "id" (non-empty string) and "epistemicStatus"; "sourceRef" is optional.
- locations: required name, summary, visibility; optional description: string, parentLocationId: string, connections: LocationConnection[].
- actors: required name, summary, visibility; optional description: string, role: string, motivation: string, disposition: string, factionId: string, locationId: string.
- factions: required name, summary, visibility; optional description: string, goals: string[], dispositionTowardsParty: string.
- scenes: required title, summary, visibility; optional locationId: string, readAloud: string | string[], body: string, conditions: string[], branches: SceneBranch[], optional: boolean.
- encounters: required description, alternativeSolutions (an array, [] if absent), visibility; optional title: string, sceneId: string, locationId: string, conditions: string[], actorIds: string[].
- clues: required text, visibility; optional reveals: string, leadTargetId: string, placedLocationId: string, placedActorId: string, placedSceneId: string, alternativeSourceId: string.
- rumours: required text, truth ("true" | "false" | "partially-true" | "unverified", all strings), visibility; optional sourceActorId: string, sourceLocationId: string, targetEntityId: string.
- items: required name, summary, visibility; optional description: string, locationId: string, actorId: string.
- secrets: required text, visibility ("gm-only" only); optional relatedEntityIds: string[].
- endings: required description; optional title: string, conditions: string[]; visibility is not allowed.
- unresolved: required code, message; optional relatedEntityId: string, context: string; epistemicStatus is "ambiguous" | "unresolved" only; visibility is not allowed.
- SceneBranch: required targetSceneId: string, description: string; optional condition: string, optional: boolean.
- LocationConnection: required targetLocationId: string; optional description: string, travelConditions: string[].
- Each alternativeSolutions entry requires method: non-empty string and description: non-empty string; optional socialBypassOfCombat: boolean.
- Do not emit properties absent from the strict schema. Common slips: encounters use "description" (not "summary"); clues use "placedLocationId" (not "locationId"); rumours use "truth" as a string (not a boolean such as "isTrue").
- Record named objects the source gives importance (clue objects, handouts, treasure) in "items", and give each "unresolved" entry a specific "code" that describes its own problem.
5. Visibility & secrets:
- Keep the title, hook, background, and optional description player-safe and limited to source-supported facts; do not put concealed information in these fields.
- Require "visibility": "player-visible" | "gm-only" on locations, actors, factions, scenes, encounters, clues, rumours, items, and secrets only. Do not add visibility to endings or unresolved. Every entry in "secrets" MUST have "visibility": "gm-only".
- "visibility" applies to the WHOLE record, never to individual fields. Put only what players can know in a "player-visible" record, and move any concealed role, motive or detail into a separate "secrets" entry that lists the record in "relatedEntityIds". When a record cannot be split cleanly, mark it "gm-only" and add an "unresolved" entry.
- Do not over-hide. Keep on the visible record whatever players can learn in play (a stated role, public detail, or harmless goal). Do NOT promote NPC testimony, rumours, or handouts to objective truth unless confirmed by the authored text.
6. Structural integrity:
- Every entity ID across all collections must be unique and non-empty. All cross-references (parentLocationId, locationId, factionId, sceneId, targetSceneId, actorIds, placedLocationId, placedActorId, placedSceneId, leadTargetId, relatedEntityIds, relatedEntityId) must point to existing IDs and never self-reference. Location parentLocationId chains must not form cycles.
- Every non-entry scene with source-supported progression must be reachable via scene branches from scenes[0], with no inescapable mandatory dead-end loops. If progression is unknown, preserve the scene as ambiguous without inventing a branch.
- If the source has no authored order (a sandbox or location-based module), list scenes in source order, add branches only where the source states them, set "epistemicStatus": "ambiguous" on every scene that no earlier scene links to, and add one "unresolved" entry saying the order is left to the GM. Do not invent a flow or an ending.
7. Provenance & copyright:
- Add "sourceRef" ({ page?: integer >= 1, pageEnd?: integer >= 1, chapter?: non-empty string, section?: non-empty string, anchor?: non-empty string, textQuote?: non-empty string }) wherever known. For a PDF, include "page" (and "pageEnd" when it spans pages) on every entry using the page position in the file, not a number printed on the page.
- Write concise structured summaries, key dialogue, and room briefs rather than copying large blocks of prose verbatim. Omit playthrough state or session history.
8. Self-audit before returning (do not output this check):
- Confirm every source section/page, named actor, location, mandatory/optional scene (marked "optional"), missable clue ("alternativeSourceId"), encounter option ("alternativeSolutions"), and intended ending is accounted for, and anything missing, cut or uncertain has an "unresolved" entry naming the source section.
9. Revisions and stable IDs:
- If an earlier Adventure JSON for the same adventure is supplied, keep its "id" exactly, keep every unchanged entity ID exactly, and raise "version" by SemVer.
- Add a top-level "extensions" entry "codex-cryptica.adventure-correspondence" (a list of { "previousId", "currentId", "collection" }) only for renames, splits or merges the source clearly supports. Never infer correspondence from names, titles or order, and never put "extensions" inside an entity. If no earlier package is supplied, use "version" "1.0.0" and omit the correspondence extension.
10. Game mechanics and maps:
- Never add fields outside the v1 schema for stats, DCs, hit points, maps, grids or images, and never put mechanics in "extensions". Keep mechanics only as a short source-grounded paraphrase with "sourceRef" inside "description", "body", "conditions" or "alternativeSolutions[].description", and record any unrepresentable mechanic, stat block or map as an "unresolved" entry naming the source section (never invent values for it).
Sandbox conversion: Put keyed rooms in "locations" and their hazards, opponents and tactical responses in "encounters" or other appropriate collections. Add "scenes" only for authored beats. If any scene outside scenes[0] is unreachable by following branches from scenes[0], give it epistemicStatus "ambiguous" rather than inventing links. A link from another unreachable scene does not make it reachable. Keys, room adjacency and conditional enemy tactics alone do not establish scene progression.
Final visibility audit: Adding a fact to "secrets" is not enough. Check every copy of it across locations, actors, scenes, encounters, clues, summaries, and the premise. Before discovery, a hidden creature, trap, concealed access, or ambush plan must be absent from all player-visible names, text, IDs, and linked details. Preserve discoverable information in a GM-only record until it is revealed. Keep only sensory details or public facts in visible entries. Do not reproduce stat blocks in visible or GM fields; paraphrase the action or consequence and cite an unresolved entry for mechanics the schema cannot represent.
Evidence and citations: Put each source-supported investigative observation in "clues" even when its text also appears in a room description or scene. Preserve where the evidence can be found, and add a revelation only if the source supports it. Do not turn incidental colour into a clue. For paginated sources, cite the page position and heading that describe the entry itself. For unpaginated sources, cite a supported section, anchor or other stable source range; never invent page numbers. For a keyed room, cite its key entry rather than an earlier mention, direction or cross-reference.
Before you reply with a successful conversion, check each of these:
- The result is only the JSON object (as a file, or as your whole reply), with no code fences or commentary.
- All 11 collection arrays are present, every id is unique, and every cross-reference points to an existing id.
- Every "secrets" entry is "gm-only", and no "player-visible" record reveals a hidden role, motive or detail.
- Every entry has "epistemicStatus"; endings and unresolved have no "visibility".
- Nothing outside the schema was added and nothing was invented.
END OF ADVENTURE JSON V1 CONVERSION PROMPTNext: upload your Adventure JSON
There is no paste box on this guide. Save the AI's JSON-only response,
without Markdown fences, as a .json file.
- Open the Vault where you want to save it, then open Adventure Mode. If another adventure is open, choose Leave adventure first; it saves automatically.
- Under Import Adventure JSON, click Choose Adventure JSON or drop the file in the import area.
- Review the validated package and approve it to save it.
Where your adventure goes
- Conversion: your source text or PDF goes to the AI assistant you choose, hosted or local. It does not go to Codex Cryptica, and this page never receives it.
- Import: the Adventure JSON is validated, reviewed and approved in Codex Cryptica, then stored in the Vault on this device. No AI call is made.
- AI play: during Oracle turns, bounded parts of the package, such as its title and premise, are sent to your selected Oracle AI provider along with relevant Vault records. The whole package is not sent.
Imported packages are not included in Codex Cryptica Cloud Backup, even when you opt in to include adventures. Keep your .json file. A Portable Backup (.codex.zip) and Save to Folder do include imported packages. See Cloud Backup help and Export and Back Up help.
Long adventures: convert in stages
A long PDF can be too much for one reply. Instead of letting an assistant cut the result short, work in bounded passes: inventory → convert section by section → check coverage → assemble → import. Conversion runs in the assistant you choose. Hosted assistants may process your source on their servers; local models can process it on your device. This page converts nothing, and Codex Cryptica imports and checks the finished JSON on your device without receiving the original source.
Do not trust an assistant that says it processed the whole upload. Check its work against the inventory and the page numbers in each entry.
What went wrong? Three different problems
| Problem | What you see | What to do |
|---|---|---|
| The assistant cannot read the document | It answers from the title, cannot quote a line you name from page 10, ignores a link you gave it, or pages look scanned or garbled. | Ask it to quote the first line of a page you pick. If it cannot, give it the text instead: paste each section, or use an OCR'd copy. Do not continue with a source it cannot read. |
| The input is too large | Later chapters are missing or thinly covered, or it says it is summarising. | Use smaller sections in Stage 1 (about 10 pages), and start a fresh chat for each pass so earlier text does not crowd out the section. |
| The output is too large | The JSON stops mid-way, has no closing brace, or the assistant replies that it shortened the result. | Convert smaller sections, one file per section. Never ask it to continue a cut-off JSON reply: redo that section in two. |
If a part cannot be read or converted, leave it out and say so. An incomplete conversion that is labelled incomplete is fine; a finished- looking one with invented material is not.
1. Inventory the source
Start a chat, attach the adventure and send this. You get a list of sections with page ranges and one id for each recurring character, faction and place. Check the page count it reports against the real one.
Stage 1 of 3: inventory only. Do not convert anything yet. Read the adventure I attached and list its parts so I can convert it in separate passes. Reply with: 1. If the source is paginated, give the total page count you can actually see and list any pages you cannot read or that look scanned, blank or garbled. If printed page numbers differ from file positions, say so and use the position in the file from now on. If it is not paginated, say that and do not invent page numbers. 2. A numbered list of sections in source order. For each: a short title, the page range for paginated sources or a heading/anchor/source range otherwise, what it holds (scenes, locations or keyed rooms, cast, items, appendix, other), and a short id prefix such as "town-", "caves-" or "cast-". Keep each part small enough to convert in one reply (about 10 pages or a similarly small text section); split big chapters. Sections must not overlap: if a page or source range is shared, say which section owns each part of it. 3. A checklist of every expected source-supported entry, grouped by Adventure JSON collection. Give each a short source name and planned ID, and identify its defining section. Include distinct clues, rumours, encounters, items and endings, not only sections or recurring entities. Do not add entries unsupported by the source. 4. The names of the main recurring characters, factions and places that appear in more than one section, each with the single ID you will use everywhere, and the one section that describes each in detail and so defines it. Other sections only refer to it. Do not summarise the story, do not write any Adventure JSON, and do not claim a part is covered unless you can see its source material. If you cannot read the source at all, say so in one sentence instead of guessing from the title.
2. Convert one section at a time
In a chat that already has the canonical conversion prompt above, send this once per section from the inventory, after filling in the bracketed line. Save the JSON-only result as chunk-01.json, chunk-02.json and so on. Request and keep each completion record separately, never in a chunk file.
Stage 2 of 3: convert one section. Use the Adventure JSON v1 conversion prompt I gave you earlier and follow all of its rules, with these changes for this pass only. Convert only this section of the source: [PASTE THE SECTION TITLE AND PAGE RANGE, HEADING, ANCHOR OR OTHER SOURCE RANGE FROM THE INVENTORY HERE] - Produce a complete Adventure JSON v1 document that contains only entries from this section. Repeat the same "formatVersion", "id", "title", "version", "premise" and "source" in every pass, plus identical "description", "system" and top-level "extensions" when present. If the same adventure has a correspondence mapping, supply the full mapping unchanged in every chunk. Keep all 11 collection arrays (use [] when empty). - Use exactly the ids from the inventory for recurring characters, factions and places. Give new entries ids that start with this section's id prefix. An entry that appears in several sections keeps one id everywhere. - You may refer to an id defined in another section (for example a clue placed with a character from section 1), but define an entry only if the inventory says this section defines it. Never invent an entry that belongs to another section. - Add a "sourceRef" to every entry where the source location is known. For paginated sources, add "sourceRef" with the page number (and pageEnd when needed), using the page position in the file, not any number printed on the page. For unpaginated sources, use the supported section or anchor reference; never invent a page number. - Never invent anything to connect this section to others. Record gaps in "unresolved". - Deliver valid JSON only in a file named after the section, such as "chunk-02.json". If you cannot create files, make the entire reply the JSON document only: no Markdown fences, commentary or completion record. After delivering the file, provide the plain-text completion record as a separate message; if you had to reply with JSON, wait until I ask "completion record" before sending that separate message. The completion record must list the section and source range, IDs actually present in each collection, number of entries per collection, ids you referred to but did not define, and anything unreadable or omitted. If you could not finish this section, say so in the completion record instead of presenting it as complete.
3. Check coverage against the inventory
Paste the inventory and every completion record. This finds missing sections, ids that were referred to but never defined, and duplicate ids for the same character.
Stage 3 of 3: check coverage. Do not convert anything new. Below are my inventory, the JSON files for every chunk, and the completion record for every section I converted. Compare the expected-entry checklist with the actual IDs and counts in the chunk JSON; use completion records only for unreadable or omitted material, not as proof that an entry exists. Reply with: 1. A table with one row per inventory section: "converted", "partly converted" (name missing expected entries) or "not converted". Mark a section converted only when every expected ID assigned to it appears in the corresponding chunk JSON and its reported collection counts match that JSON. 2. Every expected ID missing from the chunk JSON, every unexpected ID, and any collection count mismatch, with its expected section where known. 3. Every id that a section referred to but no section defined, and which section it is expected in. 4. Any recurring character, faction or place that was given more than one id. 5. Any page range or unpaginated source range in the inventory that no chunk covers. Do not assume a section is done because it is listed. If a record is missing or vague, mark that section "not converted". Do not write Adventure JSON. [PASTE THE INVENTORY, THEN EACH CHUNK JSON FILE, THEN EACH COMPLETION RECORD]
4. Assemble the sections into one file
Do not ask an assistant to merge everything in one reply: the result may
be too large and may quietly drop entries. This small script does it
exactly. It keeps every entry and its sourceRef, merges entries that are identical, and stops with an error if two
sections define the same id differently. It never invents a link. If you
do not use Node, ask a code-capable assistant to run it on your files.
Save the script as assemble.js and run node assemble.js chunk-01.json chunk-02.json (adding all your chunk files). It writes adventure.json only when assembly succeeds,
preserving an existing file if a check fails.
// assemble.js: node assemble.js chunk-01.json chunk-02.json
// Writes adventure.json only after every input and consistency check succeeds.
function stableJson(value) {
return JSON.stringify(value, (_key, entry) =>
entry !== null && typeof entry === "object" && !Array.isArray(entry)
? Object.fromEntries(Object.keys(entry).sort().map((key) => [key, entry[key]]))
: entry,
);
}
function assemble(chunks) {
const names = ["locations", "actors", "factions", "scenes", "encounters", "clues", "rumours", "items", "secrets", "endings", "unresolved"];
const metadataKeys = ["formatVersion", "id", "title", "version", "description", "premise", "source", "system", "extensions"];
const first = chunks[0];
const out = {};
for (const key of metadataKeys) {
if (first[key] !== undefined) out[key] = first[key];
}
for (const name of names) out[name] = [];
const errors = [];
const seen = new Map();
chunks.forEach((chunk, index) => {
for (const key of metadataKeys) {
if (stableJson(chunk[key]) !== stableJson(first[key])) {
errors.push("chunk " + (index + 1) + ": " + key + " differs from chunk 1");
}
}
for (const name of names) {
for (const entry of chunk[name] || []) {
const before = seen.get(entry.id);
if (!before) {
seen.set(entry.id, entry);
out[name].push(entry);
} else if (stableJson(before) !== stableJson(entry)) {
errors.push('chunk ' + (index + 1) + ': id "' + entry.id + '" is defined differently elsewhere');
}
}
}
});
return { adventure: out, errors };
}
const fs = require("fs");
const path = require("path");
const files = process.argv.slice(2);
if (files.length === 0) {
console.error("Usage: node assemble.js chunk-01.json [chunk-02.json ...]");
process.exit(1);
}
const chunks = files.map((file) => JSON.parse(fs.readFileSync(file, "utf8")));
const { adventure, errors } = assemble(chunks);
if (errors.length > 0) {
console.error(errors.join("\n"));
process.exit(1);
}
const output = path.resolve("adventure.json");
const temporary = path.join(path.dirname(output), "." + path.basename(output) + "." + process.pid + "." + Date.now() + ".tmp");
try {
fs.writeFileSync(temporary, JSON.stringify(adventure, null, 2) + "\n", { flag: "wx" });
fs.renameSync(temporary, output);
console.log("Wrote " + output);
} catch (error) {
try { fs.unlinkSync(temporary); } catch { /* Nothing to clean up. */ }
throw error;
}5. Import and fix what it reports
Import adventure.json as described above. Codex
Cryptica checks every id and cross-reference and names the exact field that
is wrong. Send that message and the matching section's file back to your assistant
and redo only that section, then assemble again.
Valid is not the same as complete
- (a) Valid JSON. The file parses as JSON.
- (b) Importable package. It passes the Adventure JSON v1 schema and the semantic import checks.
- (c) Faithful, reasonably complete adaptation. Nothing important was left out or changed from your source. Only you and your assistant can judge this.
Codex Cryptica checks only (a) and (b). It never sees your source, so a successful import does not prove that nothing was left out or changed. For a second look, paste this follow-up into the same chat after you receive the JSON:
Copy coverage report promptNow write a short coverage report for the Adventure JSON you just gave me. Reply in plain text, not JSON. Do not change or re-output the JSON. Begin with one line, "Previous package:", naming the earlier "id" and "version" if I supplied one, or otherwise saying exactly "No previous package was provided." Use these four headed lists: Covered sections: each source section or page anchor that the JSON covers. Missing or shortened: source content that is missing, cut down or merged. Risky inferences: anything you inferred rather than read in the source. Left unresolved: contradictions and unknowns, with the source section for each. If you are unsure about something, list it under "Missing or shortened" or "Left unresolved". Do not say the conversion is complete unless "Missing or shortened" and "Left unresolved" are both empty. This report stays outside the JSON file.
What converts well, and what needs manual work
Adventure JSON v1 carries narrative structure (places, people, scenes,
clues and secrets). Keep your source book at hand for stat blocks,
tactical maps, DCs and system rules. The optional system field is descriptive metadata only and
does not make game mechanics executable.
| Content | Converts | How v1 handles it |
|---|---|---|
| Locations | Converts well | locations, with parentLocationId for nesting and connections for links. |
| NPCs | Converts well | actors, with role, motivation, disposition and factionId or locationId. |
| Scenes | Converts well | scenes, with readAloud text and body for the GM. |
| Branches | Converts well | scenes[].branches, with targetSceneId and an optional condition. |
| Clues | Converts well | clues, with leadTargetId, placedLocationId, placedActorId or placedSceneId, and alternativeSourceId. |
| Secrets | Converts well | secrets, always "gm-only", with relatedEntityIds pointing at what they touch. |
| Alternative solutions | Converts well | encounters[].alternativeSolutions, each with a method and a description. |
| System rules | May need manual work | No rules field. Use a short paraphrase in description, body or conditions with sourceRef, and record the rest in unresolved. |
| Stat blocks | May need manual work | No stats or HP fields. Keep the creature as an actor and note the stat block in unresolved. |
| Tactical maps | May need manual work | No map or grid fields. Use location connections for topology and note the map in unresolved. |
| Layout | May need manual work | Boxed read-aloud text goes in readAloud. Page layout and art are not kept. |
Revising an adventure you already imported
- Package
idand entity IDs: keep them stable across revisions of the same adventure, and raiseversion(SemVer) when content changes. - Re-importing: identical content is deduplicated as a
no-op; changed content with the same
idis reviewed and diffed as a new version while existing sessions stay pinned to the version they started with.
Correspondence for renamed content
{
"extensions": {
"codex-cryptica.adventure-correspondence": [
{ "previousId": "scene-stairs", "currentId": "scene-spiral-stair", "collection": "scenes" }
]
}
}
Rules for "codex-cryptica.adventure-correspondence":
- Place "extensions" at the top level of the package (beside "formatVersion" and "id"), never inside an entity.
- "collection" must be one of the 11 collection names, and both IDs must exist in the previous and new packages.
- Splits (one previousId -> several currentIds) and merges (several previousIds -> one currentId) are shown grouped and stay flagged for review.
- Identity is never inferred from titles, name similarity, or ordering.Common Validation Errors & Troubleshooting
SCHEMA_VALIDATION_ERROR
Cause: A required field is missing, a field has the wrong type, an unrecognized key was added, or an "unresolved" item used "explicit" or "inferred".
Fix: Check the field path in the error. Common slips: encounters use "description" (not "summary") and require "alternativeSolutions": []; clues use "placedLocationId" (not "locationId"); rumours use "truth" ("true" | "false" | "partially-true" | "unverified"). For an unresolved item, use "ambiguous" or "unresolved".
DUPLICATE_ID
Cause: Two or more entities share the same id string.
Fix: Give every entity across all 11 collections a globally unique id (e.g. prefix with loc-, actor-, scene-, clue-).
UNRESOLVED_REFERENCE / SELF_REFERENCE
Cause: A reference field (such as locationId, targetSceneId, or relatedEntityIds) points to an ID that does not exist or points to the entity itself.
Fix: Ensure every referenced ID exists in the matching collection and no entity references its own ID.
LOCATION_CYCLE
Cause: Location parentLocationId links form a loop.
Fix: Break the parentLocationId cycle so locations form a tree.
UNREACHABLE_SCENE / DEAD_END_LOOP
Cause: A scene with source-supported progression cannot be reached from scenes[0], or mandatory transitions form a loop with no path to an ending.
Fix: Connect scenes from scenes[0] via branches[].targetSceneId. If the source does not establish progression, preserve the scene as ambiguous and do not invent a branch.
SECRET_VISIBILITY_VIOLATION
Cause: An entry in "secrets" has visibility set to "player-visible".
Fix: Set visibility to "gm-only" on every entry in "secrets".