Docs Assets & Sprites

Assets & sprites

Upload the imagery, then reference it by name. Every asset gets a logical name in the Studio — that’s the name you write in your script.

Logical names

Assets are referenced without file extensions.

When you upload an asset, it’s assigned a logical name (defaults to the filename without extension). You use that name in the script — never the file path. Logical names must be unique per game and can be renamed in the Studio asset browser.

Asset type	Where to upload	How to use in script
Background image	Studio → Assets → Backgrounds	`@bg city_night`
CG image	Studio → Assets → CGs	`@cg monster_reveal`
Character sprite	Assets → Sprites, then linked in Characters	`sarah (): "text" or @sprite left sarah`
Character	Studio → Characters	`sarah: "Hey!"`
Variable	Studio → Variables	`$score = 0 or $$flag = true`
Messenger chat	Studio → Apps → Chats	`@chat chat_sarah`

Character sprites

Standard VN only — portrait images that appear over the background while characters speak.

Upload sprite images in Assets → Sprites, then link them to characters in the Characters panel’s sprite map.

Auto-staging. Speaking with sarah (): "text" automatically places the speaker. The first speaker goes center; when a second character speaks, the first moves to the side.

Persistence. Sprites stay on screen until explicitly cleared with @sprite left clear. Scene headers do not clear sprites.

sprites.omi

OmiScript

## The Confrontation
// 'rooftop_night' is a logical name from Studio → Assets → Backgrounds
@bg rooftop_night

// Auto-stage: speaking with () triggers automatic sprite placement.
// The first speaker goes center; the second speaker pushes the first aside.
sarah (): "You followed me up here."
player (): "You left me no choice."

// Named expression — registered in the character's sprite map in Studio.
// Use () for the default expression, (name) for a registered variant.
sarah (angry): "Don't make this harder than it has to be."

// Explicit placement — overrides auto-staging, puts marcus in the left slot.
@sprite left marcus

marcus: "Nobody's going anywhere."

// Clear a slot — removes the sprite visually when a character exits.
@sprite left clear

// sarah and player remain staged in their auto-assigned slots.
sarah: "It's just us now."

// @end — chapter complete. Use @fin to end the entire story.
@end

Sprites only render in the Standard VN template. SimOS games do not render sprites.

Expressions

Multiple images per character, switched mid-dialogue.

Register several images per character (e.g. default, happy, angry) and reference them with a name in parentheses. Unknown expressions fall back to default.

expressions.omi

OmiScript

sarah (): "I'm fine."        // default sprite
sarah (happy): "Guess what!"    // registered variant
sarah (angry): "Don't push it."

CG images

Full-screen illustrations worth collecting.

@cg filename sets a full-screen CG. CGs can be tagged as collectible — players who reach them unlock them in the in-game gallery, so they’re great for key moments and endings.

cg.omi

OmiScript

@bg city_night
stranger: "Look at the window."
@cg monster_reveal

Previous Simulated OS Next Examples

Storyomi Creator Docs

Back to Storyomi