Import a Screenplay Scene

Turn a structured screenplay scene into an editable ABRAXAS narrative graph.

On this page

Use Import Scene in the Writer Workspace to turn a screenplay scene into the existing ABRAXAS dialogue graph. ChatGPT can prepare the JSON; the website does not send your screenplay to an AI service.

Import a scene#

  1. Give ChatGPT the complete screenplay scene and the reusable prompt below.
  2. Copy the returned JSON or save it as a .json file. The document must use the abraxas.scene-import format, version 1.
  3. In the Writer Workspace, choose Import Scene. Paste the JSON or choose the file, then select Validate and preview.
  4. Review the scene title, node counts, and any validation errors. Correct the JSON and validate it again if needed.
  5. Leave New scene (default) selected to create a separate scene. Choose Append to current scene only when you want every open path in the current graph to lead into the imported scene; the website asks you to confirm before it changes those connections.
  6. Confirm the import. New-scene imports are created as one saved scene. For an append, use Undo to restore the prior graph.

The importer creates graph and response UUIDs in ABRAXAS, checks every connection, and lays out the nodes. It never deletes or replaces existing scene content. Append leaves explicit ending nodes intact and attaches to open node or choice-response paths. If a current scene has no open paths, create a new scene or add an open connection before appending.

The application accepts up to 750 KB of JSON and 3,000 combined node and response identifiers. Descriptions and actions are stored as narrative graph nodes and export as Yarn comments. Dialogue and choice text stays player-facing. An import requires a starting node and valid local IDs and connections. IDs in the source file are labels only; do not put Supabase or Unity IDs in the JSON.

Format specification#

The complete JSON Schema is available at /schemas/abraxas-scene-import-v1.schema.json. The website also verifies that IDs are unique across nodes and response options, that the start and every connection reference a declared node, and that total ID counts stay within graph limits. A null destination means that path ends there; use an end node when the screenplay explicitly concludes.

  • format and version identify the format. Use abraxas.scene-import and 1 exactly.
  • scene.title becomes the new scene title. scene.start names the first node.
  • nodes are in screenplay order. Connections, rather than array order, control the playable flow.
  • description and action nodes contain text and a required next destination. They are not spoken to the player.
  • dialogue nodes contain speaker, spoken text, and next.
  • choice nodes contain optional introductory speaker and text, and one or more explicit options. Each option has its own ID, response text, and destination. Use the same target ID for options that reconverge.
  • end has only an ID and type; it stops that path.
  • formatting is an optional array of { "start", "end", "style" } spans. Offsets are zero-based Unicode code-point positions into the text after formatting markers are removed; end is exclusive. Styles are bold or italic.
  • IDs must begin with a letter and contain only letters, digits, underscores, or hyphens. They are local labels, unique across both nodes and response options.
  • Preserve line breaks in text fields as \n in JSON. Description and action line breaks remain visible in writer-only Yarn comments. Yarn dialogue statements are line-based; each non-empty line in a multiline dialogue node exports as a consecutive Yarn line with the same speaker. Empty dialogue paragraphs are reported as export errors rather than silently removed.

Do not add fields outside the schema. Do not create a choice unless the screenplay explicitly presents a player response or alternate path. When a screenplay does not specify where a path continues, use null; never invent a next scene or response.

Example#

This short example includes a multiline description, an action, multiple speakers, a formatted line, two explicit player responses, a reconverging path, and an ending.

{
  "format": "abraxas.scene-import",
  "version": 1,
  "scene": { "title": "The Interview", "start": "room" },
  "nodes": [
    {
      "id": "room",
      "type": "description",
      "text": "INT. ADAM'S APARTMENT — LATE AFTERNOON\nThe apartment is quiet. Rain taps against the window.\nA stack of old magazines leans beside the refrigerator.",
      "next": "adam-waits"
    },
    { "id": "adam-waits", "type": "action", "text": "Adam closes the notebook and waits.", "next": "maya-enters" },
    { "id": "maya-enters", "type": "dialogue", "speaker": "MAYA", "text": "You said you wanted to talk.", "next": "adam-replies" },
    { "id": "adam-replies", "type": "dialogue", "speaker": "ADAM", "text": "I do. I need the truth.", "formatting": [{ "start": 17, "end": 22, "style": "bold" }], "next": "question" },
    {
      "id": "question",
      "type": "choice",
      "speaker": "MAYA",
      "text": "What do you want to know?",
      "options": [
        { "id": "ask-about-file", "text": "Ask about the file.", "next": "file-answer" },
        { "id": "ask-about-call", "text": "Ask about the call.", "next": "call-answer" }
      ]
    },
    { "id": "file-answer", "type": "dialogue", "speaker": "MAYA", "text": "I never opened it.", "formatting": [{ "start": 2, "end": 7, "style": "italic" }], "next": "shared-answer" },
    { "id": "call-answer", "type": "action", "text": "Maya looks toward the dark phone.", "next": "shared-answer" },
    { "id": "shared-answer", "type": "dialogue", "speaker": "ADAM", "text": "Then tell me who called.", "next": "end" },
    { "id": "end", "type": "end" }
  ]
}

Reusable ChatGPT prompt#

Paste this prompt with the complete screenplay scene:

Convert the screenplay scene I provide into one valid JSON document using the ABRAXAS Scene Import v1 format. Return only JSON, with no Markdown fence or explanation. Follow the published schema at /schemas/abraxas-scene-import-v1.schema.json and use format: "abraxas.scene-import" and version: 1.

Preserve every screenplay word, punctuation mark, capitalization, and paragraph break. Put the original scene heading and setting or atmosphere in description nodes. Put explicit physical events and movement in action nodes. Put spoken words in dialogue nodes and use the correct screenplay speaker label in speaker; do not include that label in text.

Create a choice only when the screenplay explicitly gives the player responses or alternate paths. Ordinary character dialogue is never a player choice. Preserve explicit path connections, reconvergence, loops, and endings. Do not invent dialogue, action, characters, branches, gameplay logic, or destinations. If a continuation is not stated, use null. Add an end node only when the scene explicitly concludes.

Give each node and choice response a unique short local ID, such as opening, adam-line, or ask-question. These are temporary labels, not database IDs. Use scene.start for the first node. Set each next or response next to a declared node ID or null.

If the screenplay marks text as bold or italic, omit the markup delimiters from the text and represent the styling with formatting spans. Span offsets are zero-based Unicode code-point positions in the resulting text, with an exclusive end. Do not add unsupported fields. If required structure is genuinely ambiguous, do not guess: return a JSON nodes array only when the scene can be represented without invention; otherwise ask me a concise clarification before producing the import.

After import, select Export Yarn to generate the Yarn Spinner 3.3.2 file for the scene. Description and action nodes stay as comments, while dialogue and explicit choice responses remain playable. Review export warnings for disconnected nodes or open paths before bringing the file into Unity.