Errors, Contracts & Cancellation

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.

Error taxonomy

Code	Example	Expected behavior
`SCENE_NOT_FOUND`	Unknown scene ID	Return null/error; never change player
`INVALID_DURATION`	Negative timespan	Validate before scheduling
`INVALID_LOCATION`	Null world / NaN coordinate	Reject with source context
`CAMERA_UNSUPPORTED`	Packet mode missing	Capability error or verified fallback
`CAMERA_IN_USE`	Other active owner	Reject/queue/replace policy
`ENTITY_GONE`	Actor despawned	Cancel/skip/freeze by policy
`SCENE_TOO_COMPLEX`	Budget exceeded	Reject before playback
`CHOICE_TIMEOUT`	No reply	Emit timeout, clear UI
`SOURCE_RELOADED`	`.sk` unloaded	Finish snapshot or cancel safely
`BACKEND_FAILURE`	Packet send error	Restore camera, isolate instance

Status model

CREATED → PREPARING → READY → PLAYING → COMPLETED → CLEANING_UP, with pause, waiting, cancel and failure branches. Every terminal outcome leads to cleanup, and cleanup must be idempotent.

Event guarantees

Start event fires only after state acquisition.
Finish and cancel are mutually exclusive terminal outcomes.
Explicit skip fires a skip event and then a documented terminal result (not two rewards).
One-shot marker can fire once per (instance, marker, loop).
Choice result is validated on the server.

Diagnostics

Proposed maintenance commands /skcine info, /skcine capabilities, /skcine profiler, /skcine debug are not scene authoring commands. Avoid enabling verbose logs in production.