Core Concepts & Ownership

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.

Concept map

Skript source (.sk)
   └── cine scene definition [immutable after validation]
        ├── camera track + keyframes
        ├── actors and display tracks
        ├── dialogue / sound / particles
        ├── event markers and branching
        └── configuration and audience defaults
                ↓ play
           scene instance [mutable state]
             ├── timeline clock and variables
             ├── viewers and per-viewer camera states
             ├── owned temporary actors/effects
             └── cleanup + restoration ledger

Definition vs. instance

cine scene is a reusable authored blueprint. cine scene instance represents exactly one run. Do not mutate a definition for one viewer once playback begins; clone or bind instance parameters. Every play operation should return an instance handle so a script can stop that playback.

Thread ownership

Core timeline math may operate on immutable data, but Bukkit world/player/entity operations must respect Paper's thread rules. Skript callbacks must run in a compatible Skript event context on the server thread unless a genuinely verified asynchronous event contract exists.

Timing

The scene clock is measured in logical ticks, usually exposed as Skript timespans. Camera paths are sampled mathematically, but the server cannot force unlimited client-side frames. An effect's at 3 seconds occurs at timeline position, not necessarily three seconds of perfect wall-clock time during lag.

Keyframes vs cues

• Keyframes interpolate between values (camera position, display scale).
• Cues perform one-shot actions at timestamps (sound, title, marker).
• Callbacks notify Skript; they must be deduplicated when seeking/looping.

Ownership rules

Scene-owned temporary entities, sounds, UI and camera targets must be released on completion, skip, failure, disconnect and plugin disable. A scene should restore only state SkCine changed, accounting for modifications made meanwhile by other plugins.

Choosing authoring style

Imperative style is the baseline stable contract, built from effects/expressions. Declarative structures (cine scene "name":) are experimental design, dependent on actual Skript parser registration and reload testing; see Structures.