Docs Guides
Best practices
How to structure, pace and branch a story people finish — and the alpha limitations to design around.
Structure a story
Chapters and scenes are your scaffolding — use them deliberately.
One chapter, one arc. A chapter should feel like an episode: a setup, a turn, and an ending that leaves a question open.
@end carries the player into the next chapter automatically. Scenes are branches. Every jump target is a scene. Design scenes so the story can re-merge at them — two branches landing on
## The Kitchen keeps your graph readable. Set up, then deliver. Introduce the world in a quiet scene before the phone starts buzzing. Players need a beat to care before the drama starts.
Pace the reading
The engine is the director — feed it short lines and let the drip do the work.
- Keep lines short. One idea per line reads faster and hits harder.
- In chats, let messages drip — a long wall of text loses the rhythm of a real conversation.
- Alternate texture: a chat scene after a narration scene, a call after a quiet moment.
- Use
@notifyand locks to tease what’s coming, not to spam the player.
Branching hygiene
Big branching amplifies scope. Keep it flat, named and mergable.
Branch out, then merge. Write branches that rejoin a shared scene. Deep, parallel trees are the fastest way to multiply your writing workload.
Track intent in variables. Instead of threading every choice everywhere, set a flag (
$route = "friendship") and branch on it later — you only write the divergence once. Keep choices flat. Nested choices (a choice inside a choice branch) can produce unexpected engine behaviour in alpha — design around it for now.
SimOS vs Standard VN
The two templates have different strengths — pick the one that serves the scene.
| Aspect | Simulated OS | Standard VN |
|---|---|---|
| Mood | Phone-native: chats, feeds, calls | Cinematic: sprites, full-bleed art |
| Interactions | Reply, comment, subscribe, answer | Choose from dialogue options |
| Sprites | Not rendered | Auto-staging + expressions |
| @app | Required to switch apps | Not used |
| Best for | Modern, chat-driven stories | Classic visual novel pacing |
Do
- Register characters, assets and variables before you reference them — validation then catches typos early.
- Start each story with a short, atmospheric scene that establishes who, where and why.
- End every chapter on a hook or a decision so players hit “next chapter” wanting more.
- Use session variables ($var) for anything that should reset on a fresh playthrough.
- Keep branching flat — merge branches back into shared scenes instead of nesting forever.
- Vary the texture: chats for intimacy, calls for tension, narration for atmosphere.
- Name scenes clearly — they double as jump targets and show up in the flowchart.
Don’t
- Don't reference an unregistered name and hope — the engine will refuse to run it.
- Don't bury a choice in a choice in a choice; players lose the thread.
- Don't write one unbroken block of narration — split it with dialogue or a choice.
- Don't rely on sprites in SimOS games — they only render in Standard VN.
- Don't make every line a decision; choices lose weight when everything is one.
- Don't forget @end — a chapter that never ends can't load the next one.
- Don't put player-facing numbers in UI copy; let the engine own the state.
Alpha limitations
OmiScript is under active development. These features are partial or reserved — don’t build your story around them yet.
Audio commands are parsed, not played.
!system play_music and friends compile cleanly but the audio engine isn’t wired yet — they’re silently ignored at runtime. Persistent variable reads across chapters.
$$var assignment is stored, but reading persistent values across separate play sessions isn’t wired end-to-end yet. Nested choices. Choices inside choice branches may behave unexpectedly — keep branching flat for now.
Storyomi Creator Docs
Back to Storyomi