Sakura Script Commands - Supported in Ourin

This document lists all Sakura Script commands that are currently supported by Ourin's SakuraScriptEngine.

2026-03 ukadoc gap audit (priority order)

Compared against ukadoc (/manual/list_sakura_script.html) and current runtime handlers in GhostManager, the main remaining gaps are:

1. Event integration gaps (high)
   - \![embed,event,...] inline event embedding
   - \![timerraise,ms,repeat,event,...] delayed/repeating event raise
   - Status: Implemented in this update

2. Runtime switching gaps (high)

   • \![change,ghost,name] full ghost switch semantics
   • \![change,shell,name] shell switch and redraw
   • \![change,balloon,name] balloon config switch
   • Status: Expanded in this update (--option=raise-event, OnGhostChanging/Changed, OnShellChanging/Changed, OnBalloonChange)
   • Related: \![call,ghost,name] runtime path added with OnGhostCalling/OnGhostCalled

3. Dialog family gaps (high)
   - \![open,inputbox|dateinput|sliderinput|dialog|teachbox,...]
   - Status: Expanded in this update (added passwordinput|timeinput|ipinput, with option-style args like --timeout, --text, and dialog subtypes open/save/folder/color)

4. Open non-input family (high)
   - \![open,browser|mailer|editor|explorer|file|readme|terms|help,...] and \![open,communicatebox]
   - \![close,inputbox|communicatebox|dialog|teachbox,...]
   - Status: Implemented in this update (runtime routing added and existing dialog event paths reused) - Extended: \![open,ghostexplorer|shellexplorer|balloonexplorer|headlinesensorexplorer|pluginexplorer|rateofusegraph|calendar|messenger|surfacetest|aigraph]

5. Plugin event family (high)
   - \![raiseplugin|notifyplugin,plugin,event,...]
   - \![timerraiseplugin|timernotifyplugin,ms,repeat,plugin,event,...]
   - Status: Implemented in this update (plugin target resolution by id/name/filename plus random/lastinstalled, timer overwrite/cancel semantics)

6. Sound extended family (medium)
   - \![sound,play|load|loop|wait|pause|resume|stop|option,...]
   - Status: Expanded in this update (load/wait/pause/resume/option runtime path added)

7. Semantic mismatch commands (medium)
   - \6, \7, \- behavior differs from some ukadoc expectations
   - Status: Addressed in this update (\7 begins SNTP flow, \6 applies SNTP adjustment action, \- exits ghost)

8. Cross-ghost event routing (high)
   - \![raiseother,...], \![notifyother,...]
   - \![timerraiseother,...], \![timernotifyother,...]
   - Status: Implemented in this update (target parsing including byte-1 separators and __SYSTEM_ALL_GHOST__, timer scheduling/cancel by key)

9. Notify timer semantics (high)
   - \![notify,...], \![timernotify,...] return handling and timer behavior
   - Status: Implemented in this update (notify now discards response script; timerraise/timernotify now follow 0=repeat, >=1=one-shot and support per-event cancel/overwrite with ms=0)

Scope Commands

Character/Scope Selection

Surface Commands

Surface Display

Animation Commands

Basic Animation

Animation Control (via \! command)

Animation Layer Control

Balloon Commands

Balloon ID Switching

Notes: - Only even IDs (0, 2, 4, 6, 8) are usable for main character balloons - Odd IDs are reserved for partner/right-side balloons - SSP 2.6.34+ supports fallback syntax: \b[ID1,--fallback=ID2,--fallback=ID3]

Balloon Images

Options (for \_b[file,x,y,options...] or \_b[file,inline,options...]): - --option=opaque - No transparency - --option=use_self_alpha - Use PNG alpha channel - --clipping=left top right bottom - Crop image region - --option=fixed - Don't scroll with text - --option=background - Display behind text (default) - --option=foreground - Display in front of text

Example:

\_b[test.png,10,20,--option=use_self_alpha,--clipping=100 30 150 90,--option=foreground]

Balloon Control

Text Control Commands

Basic Text Control

Text Positioning

Coordinate formats: - Numeric: Pixels from top-left (e.g., 30) - em: Character heights (e.g., 5em) - lh: Line heights (e.g., 2lh) - %: Percentage of character height (e.g., 100%) - @: Relative to current position (e.g., @-100) - Omit parameter to keep current value (e.g., \_l[,@-100] only moves Y)

Examples:

\_l[30,5em]       Text at X=30px, Y=5 characters
\_l[@-1650%,100]  X=left 16.5 characters, Y=100px
\_l[,@-100]       Same X, 100px up

Text Clearing

Notes: - Character/line counting follows script order, not display position - \_b[file,inline] images count as 1 character - Lines separated by \n, \n[...], \_l[x,y] count as separate lines - Empty lines (e.g., \n\n) don't count

Text Wrapping

Wait Commands

Tag Passthrough

Notes: - Text between opening and closing tags is not parsed as SakuraScript - Useful for displaying example scripts or debugging

Voice Synthesis Control

Ourin does not automatically synthesize speech for ordinary displayed text. Speech synthesis must be explicitly enabled in the script. Voice asset playback (\_v) is independent of speech synthesis.

Font & Text Styling Commands

Text Alignment

Notes: - \f[align,...] affects text until next intentional newline (\n, \_l) - \_l tag resets alignment to left - \f[valign,...] does NOT reset on newline (unlike align) - Text added after alignment command will retroactively align previous text on same line

Font Properties

Font name notes: - default - Reset to balloon default font - disable - Use disabled text font - Can specify font files in ghost/master/ or balloon folder - Multiple comma-separated names = priority order (SSP only)

Text Colors

Color format notes: - Named colors: red, blue, green, black, white, etc. - RGB: Three numbers 0-255, or percentages like 50%,90%,20% - Hex: Standard web format #RRGGBB

Text Styles

Notes: - All style commands support: 1/true (enable), 0/false (disable), default, disable - Font must support the style (some fonts don't have bold/italic variants)

Text Position

Reset Commands

Example combinations:

\f[shadowcolor,#6699cc]\f[bold,1]\f[underline,1]\f[height,20]Styled text\f[default]Normal
\f[align,center]\f[color,red]\f[height,24]Centered Red Title\n
H\f[sub,1]2\f[sub,0]O + O\f[sub,1]2\f[sub,0] → H\f[sub,1]2\f[sub,0]O\f[sub,1]2\f[sub,0]

Character Movement Commands

Move Command Parameters

Format: \![move,--X=x,--Y=y,--time=ms,--base=ref,--base-offset=pos,--move-offset=pos,--option=opt]

Parameters: - --X=value: X coordinate (can be negative) - --Y=value: Y coordinate (can be negative) - --time=ms: Movement time in milliseconds - --base=ref: Reference point (screen, primaryscreen, ID, ghost/ID, me, global) - --base-offset=pos: Reference anchor (left.top, right.bottom, center.center, etc.) - --move-offset=pos: Character anchor to align - --option=opt: Options (ignore-sticky-window)

The legacy positional form (x,y,time,method,scope) is also accepted. Set either axis to fix to retain its current coordinate. moveasync can be canceled both before dispatch and while the animation is running with \![moveasync,cancel]. --wait queues a wait for a timed move to finish.

Example:

\![move,--X=80,--Y=-400,--time=2500,--base=screen,--base-offset=left.bottom,--move-offset=left.top]

Dressup/Bind Commands

Rendering Control

Position & Alignment

Desktop Alignment

Alignment Directions: - top - Snap to top - bottom - Snap to bottom - left - Snap to left - right - Snap to right - free - No snapping - default - Reset to default

Position Locking

Visual Effects

Scaling

Notes: - 100 = user's configured scale (100%) - Negative values flip the axis (-100 = flipped) - Persists until ghost terminates - time or --time interpolates the actual value frame by frame - --wait=true queues a wait until interpolation completes

Transparency

Notes: - 0 = fully transparent (invisible) - 100 = fully opaque - Persists until ghost terminates - time or --time interpolates the alpha value - --wait=true queues a wait until interpolation completes - Negative values leave alpha unchanged and request a redraw only

Effects & Filters

Window Management

Z-Order

Notes: - IDs listed left to right = front to back - Example: \![set,zorder,1,0] makes character 1 always in front of character 0

Sticky Windows

Notes: - Linked windows move together when dragged - Works with \![move] commands (unless --option=ignore-sticky-window)

Window Reset

Special Commands

Marker

Escape Sequences

Argument Quoting

Arguments in [...] brackets are comma-separated and support quoting:

Implementation Status

✅ Fully Implemented

Parser Level (SakuraScriptEngine.swift)

All commands listed above are parsed correctly. The parser converts Sakura Script text into tokens that can be processed by the rendering engine.

Rendering Level (GhostManager.swift + CharacterViewModel/CharacterView)

Voice - IMPLEMENTED: - ✅ \__v[enable|disable|alternate,...]...\__v - Voice synthesis control (automatic speech for ordinary text is disabled by default) - ✅ \_v[filename] - Voice asset playback from ghost/sound - ✅ \_V - Wait for voice, sound, and video playback completion

Visual Effects - IMPLEMENTED: - ✅ \![set,scaling,ratio] - Uniform scaling - ✅ \![set,scaling,x,y] - Non-uniform scaling - ✅ \![set,alpha,value] - Transparency (0-100) - ✅ \![lock,repaint] / \![unlock,repaint] - Rendering control - ✅ \![set,alignmenttodesktop,DIR] - Desktop alignment state - ✅ \![set,position,x,y,scopeID] / \![reset,position] - Position locking state - ✅ \![set,zorder,...] / \![reset,zorder] - Z-order grouping state - ✅ \![set,sticky-window,...] / \![reset,sticky-window] - Sticky window grouping state - ✅ \![execute,resetwindowpos] - Reset all window positions/alignments

Command Handling: - Character visual state is stored in CharacterViewModel with @Published properties - Visual effects are applied in CharacterView using SwiftUI modifiers (.scaleEffect(), .opacity(), .allowsHitTesting()) - All settings persist until ghost terminates (per UKADOC specification) - \![lock,repaint] auto-unlocks at script end unless manual option is used

⚠️ Remaining gaps requiring real-device verification

The old “parsed only / placeholder” list in this section no longer matches the runtime and must not be used as the completion source. The current evidence is:

• ✅ Balloon rendering, variable newlines, cursor movement, clearing, inline images, text styles, anchors, SERIKO, dress-up, updates, and input dialogs have runtime paths.
• ✅ Online markers, wallpaper, task-tray icons, dumpsurface, ping/nslookup, and vanish perform real work and emit failure events.
• ✅ \f[cursor*] is applied to the actual choice-dialog buttons.
• ✅ A local mouse monitor tracks the actual modal choice button, emitting OnChoiceEnter on enter/exit and OnChoiceHover after 500 ms of stillness.
• ✅ updateother resolves installed balloon/shell/plugin/headline/language targets by descriptor name/id and applies updates to each target's own root. testonly downloads and verifies MD5 without changing existing files. Real-network and installed-ghost UI/update verification remains pending.
• ⚠️ Timed move/scaling/alpha interpolation, moveasync rendering in a real window, and platform-specific window behavior require real UI verification beyond the unit suite.

Testing

All commands have comprehensive test coverage in OurinTests/SakuraScriptEngineTests.swift. Run tests with:

xcodebuild -project Ourin.xcodeproj -scheme Ourin -only-testing:OurinTests/SakuraScriptEngineTests test

References

• Full specification: docs/SAKURASCRIPT_FULL_1.0M_PATCHED.md
• Parser implementation: Ourin/SakuraScript/SakuraScriptEngine.swift
• Test suite: OurinTests/SakuraScriptEngineTests.swift