Imagina RPG

What an image for each world slot should be: target size, shape, accepted formats, transparency and the size limits. Read this before making or sourcing art, so a picture is not rejected or reshaped after the fact.

get_image_requirements

Inspect the debug turns of one of your journeys on a world you author: the same world-writer debug view you get in the app. Each turn includes the player action, narrative, the world-state changes it made (trackers, NPCs, plot threads, fired beats, revealed lore), player-safe reasoning, a per-step trace of what the AI did (coarse action kinds, which ones the engine refused, and the text of refused narration drafts, which explains a reply that rewrote itself while streaming), dice rolls, the credits it cost you, and percentage-only token stats, plus the latest world state. Raw prompts and tool-call names, arguments and results are not included. Only works for your own journeys on your own worlds.

get_journey_debug

Performance analytics for one of your worlds: the same numbers as the in-app creator dashboard. Lifetime totals (unique players, journeys, turns, reroll rate, credits earned), the same figures over the selected period (periodTotals, what the dashboard tiles show), a per-day series (journeys, turns, rerolls, new players) over the selected period, and engagement metrics computed over a sample of journeys active within that period (up to the 1000 most recent): average/median turns per journey, a turns-per-journey histogram split into new vs returning players, and model usage share. Earnings over time are lifetime. Also world-page views: lifetime totals plus a period block (views, unique viewers, and the share of viewers who went on to play), with views and uniqueViewers in the per-day series. View counting only began on views.countingSince (YYYY-MM-DD): a period starting before that day is incomplete on the view side. Signed-in viewers dedup exactly; signed-out ones are counted once per day, so unique viewers is a floor for reach, not a headcount. Your own playtesting is excluded by default; pass includeOwn to count it (the own block always reports what is being left out). Your own page views are never counted at all.

get_world_analytics

List your own journeys (playthroughs) that run on worlds you author, newest first. These are the journeys you can debug as the world's writer. Use get_journey_debug to inspect a journey's turns. Optionally filter by worldId.

list_my_journeys

List the worlds (stories) you own, including drafts. Returns each world's id, name, description, published/latest version ids, version count, content flags and tags. Use get_world to read a full definition.

list_my_worlds

List all versions of one of your worlds (newest first), with version number, engine version, changelog, and timestamps.

get_world_versions

Get the world definition ONE of your journeys is actually running on. A journey freezes the world at the moment it started and never picks up later edits, so when a journey misbehaves this frozen snapshot, not the world you are editing, is what the storyteller reads. Use it with get_journey_debug to explain why a beat did not fire or a tracker went missing. Returns the journey's settings and how its pinned version compares to the world today, plus a _restApi URL for the full snapshot: snapshots are large, so curl that URL into a file and grep/jq the file rather than pulling it into the conversation. Pass fields to inline just a few top-level keys instead. Only works for your own journeys on worlds you author.

get_journey_world

Get the definition of one of your worlds. Worlds can be large, so prefer get_world_outline first, then fetch only the fields you need here: pass fields: ["npcs", "generalInstructions"] to return just those top-level keys (id, versionId, name are always included; unknown keys are reported in missingFields). Omit fields to get the whole world. The response also includes a _restApi URL that returns the full world JSON for about 5 minutes (curl to a file / pipe to jq). By default the latest version; pass versionId for a specific one.

get_world

Get Imagina's Markdown reference with examples for authored introductions, public world descriptions, fictional texting bubbles, text effects, images, and story beats. Explains introduction-only versus live-narration formatting and which world settings enable features. During play the storyteller already knows enabled syntax. Returns documentation only, with no inputs, world edits, or real message sending. The same guide ends get_authoring_guide, so skip this if you already read that.

get_markdown_guide

Documentation for this MCP: how the tools work, the editing loop, and a guide to authoring a great Imagina world (what each part of a world is for and how to write it well), followed by the full Markdown guide for player-facing text. Call this before creating or editing a world, and refer back to it while you work.

get_authoring_guide

Update one of your worlds by merging top-level fields into a DRAFT version. Best for scalar fields (name, description, generalInstructions, writingStyle, flags) and whole-field replacement. Call get_world_outline or get_world first to read the current state. IMPORTANT: - To edit ONE list entry (an NPC, a lore entry, a beat), use upsert_world_list_item / delete_world_list_item instead. Here, arrays (npcs, playerCharacters, loreBook, additionalInstructions, settings, tags, ...) are REPLACED entirely, which also clobbers concurrent edits to sibling items. - Edits only an unpublished DRAFT. If the requested version is published, use the latest unpublished draft if one exists. Before calling create_world_version, inspect the world's latest version. If the latest version is already an unpublished draft, edit it instead of creating another. A world can have an older published version and a newer draft at the same time. Only create a draft when the latest version is published, or when the user explicitly asks for a fresh version. Respect the user's versioning wishes and do not accumulate unpublished drafts by default. A new draft first copies its images from the previous version: create_world_version returns status "preparing" while it does (a minute or more for a world with many images), and every edit, publish or delete of that draft is refused until it is ready. Call get_world_version_status every few seconds until status is "ready", then edit it. Edit the draft, then publish from the Imagina app. - additionalInstructions must be an array of objects { name: string, content: string, nsfwOnly?: boolean, partyOnly?: boolean }. nsfwOnly limits a block to NSFW journeys (the same gate as nsfwInstructions), partyOnly to journeys played by a party. - Protected fields (id, versionId, versionNumber, engineVersion) cannot be changed. - Writes may run in parallel: each is applied to the draft as it is when it saves, and returns the new revision. Pass expectedRevision (from a read or an earlier write) to have the write refused instead if the draft changed since. - Endings are one mode at a time. journeyEndingMode: "simple" uses simpleEndings ({ victory?: { enabled, condition, displayText }, defeat?: {...} }); "multiple" uses goodEnds/badEnds ([{ id, title, condition, displayText }], max 10 each); null turns endings off. Switching simple -> multiple converts the pair into named endings (send the mode change alone). Switching multiple -> simple, or turning endings off, deletes the current endings: confirm by sending goodEnds: [] and badEnds: [] (or simpleEndings: {}) in the same update. A list only accepts content in its own mode. Any ending (either mode) may also carry imageId: the id of a world extraImages entry, shown above the ending text on the end screen. An id that matches no extra image simply renders nothing, and an extra image marked nsfw is hidden on a journey that is not adult. - A key that is not a valid world field is rejected, EXCEPT to delete it: if the world still stores such a key from an older write (it shows up in get_world / get_world_outline), send it as null to remove it for good, e.g. fields: { "trackers": null }. - Character spriteLooks are outfits: { id?, name, description?, extraPrompt?, bodyPrompt? }. Omit id for a NEW outfit to have one assigned. Keep existing ids when editing. The response's outfitIds lists the saved { id, name } pairs per character, ready for gallery lookId and outfit beat references. Supplied ids must be non-blank strings and unique within that character. - Character gallery images keep their stored id and key; only labels and flags are editable (exposeToAI is on by default, and a "sprite" label belongs on a transparent cutout; a flat one stands on the stage as a rectangle until its background is removed in the app). See get_authoring_guide, "Character images".

update_world

Put an image you already have onto one of your DRAFT worlds, sending the bytes inline as base64. One image per call. - Call get_image_requirements first: the image is re-encoded to WebP and scaled to FIT the slot box (aspect kept, never enlarged), so it is NOT cropped for you. - Accepted input: JPEG, PNG, WebP. Inline limit: 4194304 base64 characters. For a bigger file use begin_image_upload, or set_world_image_from_url. - Draft-only, like every write here. Publish from the Imagina app. - target "gallery" adds a picture to a character's gallery. A "sprite" / "sprite:<state>" label wants a transparent cutout, whose framing is measured from the image. An opaque sprite is still stored, but the reply's warnings say so: then either cut it out yourself and upload again with replaceLabel, or tell the user to use "Remove background" on it in the editor gallery. - target "codex" sets a Codex entry's picture (entryId names the entry). It is fitted inside 1536px, any shape: square suits items, landscape suits places, and a transparent cut-out keeps its transparency. - target "extra_image" adds a scene picture to the world's extraImages (label, nsfw) and returns its extraImageId, ready for a beat's showSceneImage, an ending's imageId or ::scene[label]. replaceId swaps an existing entry's picture and keeps its id, so whatever uses it stays linked. At most 40 per world (80 for trusted authors). - The reply reports what was stored: final width/height, file bytes, whether it was downscaled, the slot box, and warnings when the result is smaller than the slot (shown upscaled) or the wrong shape for a cropped slot.

upload_world_image

Discard a chunked upload started with begin_image_upload.