Supported Ink Syntax
This page documents what the current Ink converter supports when authoring stories for NovyJump.
NovyJump uses standard Ink syntax plus a set of multimedia extensions via Ink’s tag (#) syntax.
Standard Ink Features
Text and Dialogue
Narration and speaker dialogue:
You walk into the room.ALICE: Hello there.Speaker detection: a line starting with ALL_CAPS_NAME: (letters, digits, underscores, spaces) is treated as a character speaking. Anything else is narration.
Glue (<>) suppresses line breaks:
The answer is <>42.Knots and Stitches
=== start ===-> chapter_one
=== chapter_one ===Opening narration.
= scene_twoA new scene begins.=== knot_name ===— a knot (major section)= stitch_name— a stitch (sub-section within a knot)-> target— a divert to a knot or stitch
Choices
* [Be friendly] ALICE: Thanks for being kind! -> next_scene
+ [Ask again] ALICE: Still here.*— non-sticky choice (removed after selection)+— sticky choice (remains available)- Nested choices:
**,***(depth tracking) (label)— optional label on a choice for divert targeting[bracketed text]— choice label shown to the player- Guarded choices:
* {condition} [text] - You can change how choices look with a custom choice layout.
Diverts
-> knot_name-> knot_name.stitch_name-> END-> DONE-> END/-> DONE— terminal (end of story or chapter)- Inline diverts at end of choice body are resolved to direct connections
Tunnels
-> side_quest ->->->-> target ->— tunnel call (enter a section and return)->->— tunnel return (return from current tunnel)
Gathers
* Option A* Option B- You made a choice.-> END- gathers collect flow from all branches and continue.
Gather labels: - (label_name) — creates a named gather point.
Variables
VAR score = 0CONST MAX_SCORE = 100LIST moods = (happy), sad, angry~ score = score + 10~ temp greeting = "Hello"VAR— global variable declarationCONST— immutable constantLIST— enumeration with active/inactive items. Active items are listed in parentheses.~— assignment (supports=,+=,-=,*=,/=,%=)~ temp— temporary variable (scoped to current flow)
Expressions
Full expression support in conditions, assignments, and inline conditionals:
| Operator type | Operators |
|---|---|
| Arithmetic | +, -, *, /, % |
| Comparison | ==, !=, <, >, <=, >= |
| Boolean | and, or, not |
| LIST | has, hasnt |
| Grouping | () |
Conditionals
Multiline:
{ score >= 10: Great score!- else: Keep trying.}With elif:
{ score >= 10: Great score!- score >= 5: Medium score.- else: Low score.}Inline:
You feel {score > 5: confident|nervous}.Tags
# chapter_one# unlocked_endingTags appear in JumpTree metadata. NovyJump multimedia directives use the tag syntax (see below).
Comments
// This is a commentNovyJump Multimedia Directives
NovyJump extends Ink with multimedia directives using tag syntax. These produce NovyScript blocks in the output JumpTree.
Background image
# background: bg_tavern.pngSets the background image asset.
Image (standalone sprite)
# image: overlay_frame.pngDeclares an image asset without placing it on screen. Used to preload or reference assets.
Scene
# scene: tavern_nightSets the current scene by name (must reference a scene defined via # background: or configured in assets).
Clear scene
# clear_sceneRemoves all scene elements from the screen.
Music
# music: ambient.mp3# music: ambient.mp3, channel=bgm, fade=2, loop=true| Param | Default | Description |
|---|---|---|
channel | bgm | Audio channel name |
loop | true | Loop the track |
fade | — | Fade-in duration in seconds |
volume | — | Volume (0.0–1.0) |
Use a supported audio format (
.mp3,.opus,.wav,.flac, …). Avoid.ogg— the converter currently treats it as video. See Media and Resolution Specs.
Sound effects
# sfx: footstep.wav# sfx: footstep.wav, loop=falseDefaults to channel=sfx, loop=false.
Voice
# voice: line_001.mp3Defaults to channel=voice, loop=false.
Stop audio
# stop_audio: bgm# stop_audio: bgm, fade=1Stops playback on the named channel, with optional fade-out.
Character sprite
# sprite: alice, alice_happy.png, happy, x=540, y=960# sprite: alice, alice_sad.png, sad, x=540, y=960, xScale=0.8| Position arg | Description |
|---|---|
| 1 | Character id |
| 2 | Asset filename |
| 3+ | Tags (for sprite selection) |
| Named param | Description |
|---|---|
x | Horizontal position in pixels (default: 540, center) |
y | Vertical position in pixels (default: 960, center) |
xScale | Horizontal scale (default: 1) |
yScale | Vertical scale (default: 1) |
Clear character
# clear_characterRemoves all character sprites from the screen.
Display sprite (standalone)
# display_sprite: frame.png# display_sprite: frame.png, x=100, y=200, xscale=0.5Displays an image on screen without binding it to a character. Useful for overlays, UI frames, etc.
Tween (animation)
# tween: character/alice, opacity, 0, 1, 0.5, easeOutCubic# tween: scene/background, opacity, 1, 0, 1, linear| Position | Property Name | Description |
|---|---|---|
| 1 | targetPath | Target path: character/<id> or scene/<name> |
| 2 | key | Property to animate: opacity, xPos, yPos, xScale, yScale |
| 3 | startValue | Start value |
| 4 | endValue | End value |
| 5 | duration | Duration in seconds |
| 6 | type | Easing type |
Supported easing types: linear, easeInCubic, easeOutCubic, easeInElastic, easeOutElastic, easeInOutElastic, easeInBack, easeOutBack, easeInOutBack.
4-argument form omits start value (uses current value):
# tween: character/alice, opacity, 1, 0.5, linearWith delay:
# tween: character/alice, opacity, 0, 1, 0.5, easeOutCubic, delay=0.2Using parameter assignments is also acceptable. These do not need to be in any specifc order.
# tween: targetPath = character/alice, key = opacity, startValue = 0, endValue = 1, duration = 0.5, type = easeOutCubicStyle
# style: color=#ef7855, fontSize=24Applies a style to the next dialogue node. Multiple # style: directives are merged.
Supported style properties: color, opacity, fontSize, font, textAlign, backgroundColor, backgroundOpacity, wordWrap, borderColor, borderRadius, borderWidth, padding, margin, width, height.
UI
Ink does not have a concept of a UI, so the syntax is a NovyJump-flavored syntax.
UI Block
!# ui: exampleScreen // UI goes here---Creates a screen of name exampleScreen to display on JumpDrive. All UI components belong in a UI Block.
UI blocks must start with !# ui: {insert_name_here}, and end with --- on a new line.
The header can also set kind="choices" or kind="dialogue" to make a
choice or dialogue layout, and default=true to
use it everywhere. Each kind can have one default.
Component
The table shows the UI component types that are supported:
| Name | Description |
|---|---|
button | Creates a clickable button with optional text |
container | Groups multiple UI components into one component |
label | Creates a visible text |
slider | Creates an element with a min and max value |
sprite | Creates an element to display images |
Components can have parameters, marked as parameter = value. Multiple parameters are separated
by commas.
Parameter properties can be one of the following:
| Type | Description | Example |
|---|---|---|
| name | The name of the UI element | name = "player-name" |
| Style | A style property for the UI element | color = "#ef7855" |
value | The UI element’s value. This applies to label, sprite, and slider | value = 100 |
valueRef | The name of the variable for the UI element to track. This applies to label, sprite, and slider | valueRef = "playerHealth" |
Examples:
// A label with a namelabel: name = "label"
// A label with a name and textlabel: name = "label", text = "label text"
// A label with some stylinglabel: name = "label", color = "#ef7855", width = 100, height = 40Button
button: name="a-button", text="Click me!"Creates a clickable button with an optional text.
Container
// Simple containercontainer: name = "container" label: name = "nested label"
// Nested containerscontainer: name = "parent-container" container: name = "child-container" label: text = "Child of child-container" label: text = "Child of parent-container"Creates a UI element to group child elements together. Containers can contain child containers.
Label
// Create a simple textlabel: name = "simple-label", text = "I'm a label!"
// Create a text that references a variablelabel: name = "var-label", text = "Placeholder Text", valueRef = "playerHealth"Creates a displayable text. Labels can reference a variable to display via the valueRef parameter.
Slider
// Create a simple sliderslider: name = "simple-slider", min = 0, max = 100, value = 50
// Create a slider that sets a variableslider: name = "var-slider", min = 0, max = 100, value = 50, valueRef = "difficulty"Creates a slider with a min/max range. Setting the valueRef parameter to a variable allows the
slider to get & set the value of the variable.
Sprite
sprite: name = "portrait", value = "images/protagonist.png"Creates a UI element to display an image on the UI. The path of the image is passed on the value parameter.
UI Examples
// Simple Portrait!# ui: portraitExample image: name = "portrait", value = "images/protagonist.png"---
// Nested!# ui: nestedExampleUI container: name = "player-container" label: name = "health", text = "100", valueRef = "player.health" label: name = "stamina", text = "100", valueRef = "player.stamina" container: name = "relationship-container" label: name = "love", valueRef = "novyChanRelationship"---Custom choice layouts
A UI block with kind="choices" replaces the built-in choice buttons:
!# ui: choice_list, kind="choices", default=true container: layout="vbox", gap=12 repeat: source="choices" button: padding=16, backgroundColor="#182030"---- The layout needs exactly one
repeat: source="choices", alone in its container, holding exactly onebutton. - The button gets its text and action from each choice, so don’t set
textorvalueon it. - Style the container, not the
repeat, which only takessource. - To use another layout for one choice group, put
# choices: ui="compact_choices"on the line directly before it.
Custom dialogue layouts
A UI block with kind="dialogue" replaces the built-in dialogue box:
!# ui: dialogue_box, kind="dialogue", default=true container: layout="vbox", padding=24, backgroundColor="#222222" label: value="props.characterName", fontSize=20 label: value="props.dialogueText", fontSize=28---- Exactly one label must use
props.dialogueText. Theprops.characterNamelabel is optional. Neither can settext. - Only containers, labels, and sprites are allowed.
- To use another layout for one line, put
# dialogue: ui="whisper_box"on the line directly before it. The override covers text joined to that line with glue (<>).
The player shows choice and dialogue layouts automatically. Invalid layouts and annotations are errors that block export.
What’s NOT Supported
The following standard Ink features are not yet converted:
- Sequences, cycles, and shuffles (
{&...},{!...},{~...}) - Named functions (
== function_name ==) - External functions (
EXTERNAL) - Multiple files /
INCLUDE(multi-file projects are concatenated before parsing) - Threads (
<- thread_name) - Advanced label addressing (beyond
knot.stitch) - LIST helper functions —
LIST_COUNT,LIST_MIN,LIST_MAX,LIST_RANDOM,LIST_VALUE,LIST_INVERTare rejected with an error.
Minimal Example
VAR trust = 0
=== start ===# background: bg_city.png# music: city_ambience.mp3, channel=bgm, loop=true# sprite: alex, alex_neutral.png, neutral, x=540, y=960
ALEX: Welcome to the city.
* Be friendly ~ trust = trust + 1 # sprite: alex, alex_happy.png, happy, x=540, y=960 ALEX: Good to meet you! -> ending
* Stay quiet -> ending
=== ending ==={ trust > 0: ALEX: I think we'll get along.- else: ALEX: Maybe next time.}-> END