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#
- Give ChatGPT the complete screenplay scene and the reusable prompt below.
- Copy the returned JSON or save it as a
.jsonfile. The document must use theabraxas.scene-importformat, version1. - In the Writer Workspace, choose Import Scene. Paste the JSON or choose the file, then select Validate and preview.
- Review the scene title, node counts, and any validation errors. Correct the JSON and validate it again if needed.
- 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.
- 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.
formatandversionidentify the format. Useabraxas.scene-importand1exactly.scene.titlebecomes the new scene title.scene.startnames the first node.nodesare in screenplay order. Connections, rather than array order, control the playable flow.descriptionandactionnodes containtextand a requirednextdestination. They are not spoken to the player.dialoguenodes containspeaker, spokentext, andnext.choicenodes contain optional introductoryspeakerandtext, and one or more explicitoptions. Each option has its own ID, response text, and destination. Use the same target ID for options that reconverge.endhas only an ID and type; it stops that path.formattingis an optional array of{ "start", "end", "style" }spans. Offsets are zero-based Unicode code-point positions into the text after formatting markers are removed;endis exclusive. Styles areboldoritalic.- 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
\nin 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.jsonand useformat: "abraxas.scene-import"andversion: 1.Preserve every screenplay word, punctuation mark, capitalization, and paragraph break. Put the original scene heading and setting or atmosphere in
descriptionnodes. Put explicit physical events and movement inactionnodes. Put spoken words indialoguenodes and use the correct screenplay speaker label inspeaker; do not include that label intext.Create a
choiceonly 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, usenull. Add anendnode only when the scene explicitly concludes.Give each node and choice response a unique short local ID, such as
opening,adam-line, orask-question. These are temporary labels, not database IDs. Usescene.startfor the first node. Set eachnextor responsenextto a declared node ID ornull.If the screenplay marks text as bold or italic, omit the markup delimiters from the text and represent the styling with
formattingspans. Span offsets are zero-based Unicode code-point positions in the resulting text, with an exclusiveend. Do not add unsupported fields. If required structure is genuinely ambiguous, do not guess: return a JSONnodesarray 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.