Scenes, Tracks, Keyframes & Seeking
API status — PROPOSED, NOT IMPLEMENTED. SkCine is currently a design specification in this conversation; no built SkCine.jar or syntax registry was supplied. All SkCine-specific examples are intended API contracts, not verified runnable
.sk. Do not advertise these as tested until each example passes a real Skript reload and runtime test.
Timeline architecture
A scene definition contains typed tracks evaluated by a centralized Kotlin scheduler. Use Skript to declare cues, not hundreds of wait 1 tick loops.
| Track | Evaluation | Typical work |
|---|---|---|
| Camera | sampled every update | location, rotation, focus |
| Actor | sampled | movement and pose |
| Display | sampled / client interpolation | matrix transforms |
| Particle | bounded emitter update | deterministic spatial sampling |
| Sound | discrete cue | play/stop owned sound |
| Dialogue | discrete + duration | subtitles and choices |
| Title | discrete cue | Adventure titles |
| Marker | one-shot | Skript event callback |
| Branch | one-shot | conditional jump to target marker |
Cue and marker API
add cine marker "door-opens" at 3 seconds to {_scene}
add cine sound "minecraft:block.iron_door.open" at 3 seconds to {_scene}
add cine title "<yellow>The gate opens" at 4 seconds to {_scene}
Runtime control
set {_playback} to play cine scene {_scene} for player
pause cine scene {_playback}
resume cine scene {_playback}
seek cine scene {_playback} to 5 seconds
set cine playback speed of {_playback} to 0.75
These controls operate on an instance, not the shared definition.
Seeking and rewards
Synchronized tracks are divided into:
- Sampled state — jump directly to the value at timestamp (camera position).
- Ephemeral cues — missed sound or burst may be skipped when seeking.
- Gameplay callbacks — must not fire twice or create duplicate rewards.
Define skip policies: cosmetics-only, completion-only, and strict where safe. Once-only callbacks should have a stable (instanceId, cueId, loop) deduplication key.
Looping and nesting
Support bounded loops, child timelines, and predictable nested offsets. Infinite loops require explicit administrative resource budgets and cancellation handling. Reverse is only valid for sampleable reversible tracks; never reverse an economy transaction.
Reloads
On Skript reload, scene definitions owned by that .sk file must be replaced atomically. Existing instances follow configurable policy finish-on-snapshot, cancel-and-restore, or restart, never partial mutation.