The scripting language behind every Storyomi story.
A complete OmiScript chapter. It shows backgrounds, character dialogue, choices, variables, conditionals, jumps, and endings all working together.
Register before you reference. The engine validates your script before running it. Characters, backgrounds, variables, and chat IDs must all be set up in Creator Studio first — then you reference them by name in your script. This prevents runtime errors. The example below uses stranger, city_night.jpg, and $met_stranger — you'd create each of those in Studio before this script will pass validation.
=== Scene: The Message ===@bg city_night.jpg "It was 2 AM when the phone buzzed." player: "Who texts at this hour?"stranger: "Turn around." ? "What do you do?" - "Turn around slowly" player: "My hands are shaking." stranger: "Smart choice." !system set_variable met_stranger true -> Jump: The Reveal - "Ignore it" player: "Probably spam." "She put the phone down. Big mistake." -> Jump: Bad End === Scene: The Reveal ===@bg alley_night.jpg "The figure stepped into the light." ? if $met_stranger: stranger: "I knew you'd come."? else: stranger: "You shouldn't be here." stranger: "We need to talk. Not here." -> End === Scene: Bad End ===@bg city_night.jpg "Three hours later, she was gone." -> Game End
Every construct in OmiScript is introduced by a single character. Learn the sigils and you know the whole language.
| Sigil | What it does | Example |
|---|---|---|
=== Scene: Name === | Starts a new scene (jump target) | === Scene: The Roof === |
"text" | Narration — no speaker, prose overlay | "The rain fell harder." |
speaker: "text" | Character dialogue | sarah: "I'm scared." |
speaker (meta): "text" | Dialogue with sprite or meta | sarah (sprite: worried): "I can't." |
? "Label" | Choice gate — player picks a branch | ? "What will you say?" |
- "Option" | Choice option (2-space indent) | - "Run" |
-> Jump: Name | Jump to a named scene | -> Jump: The Roof |
-> End | Chapter ends, next chapter loads | -> End |
-> Game End | Story is completely over | -> Game End |
@app appId | Switch to a registered SimOS app | @app chatter |
@bg filename | Set background image | @bg city_night.jpg |
@cg filename | Set full-screen CG image | @cg monster_reveal.jpg |
!system call arg | Engine side-effect command | !system set_var key value |
// comment | Stripped at compile time | // reminder: fix this |
@app is for Simulated OS games only. For Standard VN games the engine defaults to the VN context automatically — you never need to write @app unless you are switching between registered SimOS apps (like @app chatter).
The most common structures, shown with realistic IDs. Swap in the character names, asset filenames, and variable names you've registered in your project.
? "What do you say?" - "I believe you" [$trust >= 1] player: "I believe you." sarah: "Thank you. Really." !system set_variable route friendship -> Jump: Good Path - "I don't trust you" player: "I don't trust you." sarah: "That's fair. But you're wrong." !system set_variable route tense -> Jump: Tense Path
@app chatter @chat chat_sarah sarah: "hey, you there?" sarah: "hello??" ? reply: - "sorry, was asleep" player: "sorry just woke up lol" sarah: "okay good, we need to talk" !system set_variable replied_sarah true - "leave on read"
? if $route == "friendship": sarah: "I'm glad we talked." player: "Me too."? elif $route == "tense": sarah: "I hope you change your mind." player: "Maybe."? else: "They stood in silence."
When you upload a background, sprite, or other asset in Creator Studio, it gets an Asset ID. Use that ID directly in your script — no paths, no folders.
| Asset type | Where to upload | How to use in script |
|---|---|---|
| Background image | Studio → Assets → Backgrounds | @bg your_filename.jpg |
| CG image | Studio → Assets → CGs | @cg your_filename.jpg |
| Character sprite | Studio → Characters | sarah (sprite: happy): "text" |
| NPC character | Studio → Characters | sarah: "Hey!" |
| Variable | Studio → Variables | !system set_variable key value |
| Messenger chat | Studio → Apps → Chats | @chat chat_sarah |
The filename you see in the asset manager IS the Asset ID. If the file is city_night.jpg, write @bg city_night.jpg — exactly as shown.
OmiScript is under active development. The engine runs correctly for everything on this page. The features below are either partially implemented or reserved for a future release — don't waste time trying to build them in alpha.
Music and sound effect commands are parsed and compiled but the audio engine is not yet wired — they will be silently ignored at runtime.
Persistent variables are defined but cross-session reads are not yet wired.
Defined in the language spec but the Social Feed and Voicemail UI renderers are not yet built.
Premium feed locking syntax is spec'd but not rendered.
Choices inside choice branches may cause unexpected engine behaviour. Keep branching flat for now.
Found something broken that isn't listed here? Report it in Discord or send us an email — we read everything.
Ready to start writing?
Create a free account