OmiScript

The language behind every Storyomi story. Every construct is introduced by a single character — learn the sigils and you know the whole language.

The sigils#

The complete core vocabulary. Reference pages in this guide walk through each family with examples.

Sigil	What it does	Example
`## Scene Name`	A named label — a jump target; does not clear the stage	`## The Rooftop`
`"text"`	Narration — no speaker, prose overlay	`"The rain fell harder."`
`speaker: "text"`	Character dialogue	`sarah: "I'm scared."`
`speaker (expr): "text"`	Dialogue with a sprite expression	`sarah (worried): "I can't."`
`? "Label"`	Choice gate — the player picks a branch	`? "What will you say?"`
`- "Option"`	A choice option (two-space indent)	`- "Run"`
`-> Name`	Jump to a named label	`-> The Roof`
`@end`	End of chapter — loads the next published chapter	`@end`
`@fin`	End of story — the whole game is over	`@fin`
`@bg filename`	Set a background image	`@bg city_night`
`@cg filename`	Set a full-screen CG image	`@cg monster_reveal`
`@scene [filename]`	Hard cut — clear background, sprites and CG; optionally set a new background	`@scene park_morning`
`@app appId`	Switch to a registered SimOS app	`@app chatter`
`@sprite slot charId`	Stage a character sprite in a slot	`@sprite left sarah`
`@sprite slot clear`	Remove a sprite from a slot	`@sprite left clear`
`$var = expr`	Assign a session variable	`$score = 0`
`$$var = expr`	Assign a persistent variable	`$$saw_ending_b = true`
`? if cond:`	Conditional block	`? if $score >= 10:`
`// comment`	Stripped at compile time	`// fix this later`

Scenes & labels#

A chapter is split into named labels. Labels give you stable places to jump to — they don't move the stage.

Write ## Scene Name to open a label — a named spot the player can be sent to. Labels are the units of structure: each branch lands on a named label, and a new label is the natural place to change location or mood. But a label on its own only marks a position in the script.

scenes.omi

## The Rooftop
@bg rooftop_night

sarah: "You followed me up here."

-> The Kitchen

## The Kitchen
mira: "Make yourself at home."

scene-clear.omi

sarah: "I think we're done here."

@scene park_morning.jpg   // clears bg, all sprites and CG, then shows park_morning.jpg

"A new day."

Narration#

Prose with no speaker — the narrator’s voice, or the world describing itself.

A quoted string on its own line is narration:

narration.omi

@bg city_night

"It was 2 AM when the phone buzzed."

"She put the phone down. Big mistake."

Dialogue#

A speaker name, a colon, and their line. The speaker must be registered in Studio → Characters.

Plain dialogue keeps the speaker’s current sprite staged. Add parentheses for an expression, or empty parentheses to auto-stage the speaker’s default sprite:

dialogue.omi

player: "Who texts at this hour?"
stranger: "Turn around."
stranger (): "I'm not joking."
stranger (serious): "Look at the window."

Choices#

A question to the player. The engine pauses here and waits for a pick.

The gate is ? "prompt" and every option is indented two spaces and starts with -:

choices.omi

? "What do you do?"
  - "Turn around slowly"
    player: "My hands are shaking."
    -> The Reveal
  - "Ignore it"
    "She put the phone down. Big mistake."
    -> Bad End

Options can be hidden behind a condition with [$var >= 1] — see Variables & Conditionals.

Jumps#

Send the player to any named label with an arrow.

-> Scene Name jumps to a label anywhere in the chapter. This is how branches merge — both options land on a shared label.

jumps.omi

## Choices
? "Tea or coffee?"
  - "Tea"
    -> The Kitchen
  - "Coffee"
    -> The Kitchen

## The Kitchen
mira: "Good choice."

Endings#

Two ways to stop. Pick the one that matches the story’s shape.

@end — chapter complete

Ends the current chapter. If a newer chapter is published, the player is carried straight into it. If not, they see the end-of-chapter screen.

@fin — story over

Ends the entire story. Use it for true endings and bad ends. Players can’t continue past it.

endings.omi

## Bad End
"Three hours later, she was gone."
@fin

## Good End
"She was still there. Waiting."
@fin

Everything together#

A complete chapter combining labels, narration, dialogue, choices, variables, conditionals, jumps and both kinds of ending:

chapter_one.omi

## The Message
// Register 'stranger' in Studio → Characters, 'city_night' in Assets → Backgrounds,
// and '$met_stranger' (boolean) in Studio → Variables before running this script.

@bg city_night

// Narration — no speaker, shown as prose overlay
"It was 2 AM when the phone buzzed."

// Dialogue — speaker must be registered in Studio → Characters
player: "Who texts at this hour?"
stranger: "Turn around."

// Choice gate — player picks one branch; the engine waits here
? "What do you do?"
  - "Turn around slowly"
    player: "My hands are shaking."
    stranger: "Smart choice."
    // Session variable assignment — saved with save slots
    $met_stranger = true
    -> The Reveal

  - "Ignore it"
    player: "Probably spam."
    "She put the phone down. Big mistake."
    -> Bad End

## The Reveal
@bg alley_night

"The figure stepped into the light."

// Conditional — branches on a session variable value
? if $met_stranger:
  stranger: "I knew you'd come."
? else:
  stranger: "You shouldn't be here."

stranger: "We need to talk. Not here."

// @end — chapter complete, engine loads the next published chapter
@end

## Bad End
@bg city_night

"Three hours later, she was gone."

// @fin ends the entire story, not just the chapter
@fin