Syntax Conventions & Design Rules

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.

Namespacing

All new syntax must contain an identifying cine/skcine prefix or uniquely recognized phrase, to minimize collisions with core Skript and addons such as SkBee and skript-gui.

Document notation	Meaning
`%player%`	A single Bukkit/Skript player expression
`%players%`	A player or list of players; concrete registration must resolve plural semantics
`%location%`	A location with valid world
`%timespan%`	Skript timespan expression
`%number%`	Finite number; bounded per property
`%cinescene%`	Custom typed scene definition
`%cineinstance%`	A specific, currently or formerly playing instance
`%cinecamera%`	A validated reusable camera rig
`%cineactor%`	Borrowed or temporary cinematic actor handle
`%cinedisplay%`	Display actor handle
`%cineemitter%`	Particle emitter definition/instance

Placeholders are spec notation, not text users paste into scripts.

Public grammar design rules

Prefer unambiguous verbs (play, pause, seek, attach, restore).
Clearly distinguish definitions from running instances and group audiences.
Changes to definitions apply before play, not implicitly to active snapshots.
Use standard Skript values, not raw Java objects in expressions.
Make all effects safe on missing/expired handles.
Expose distinct event values only in valid event contexts.
Do not register arbitrary syntax aliases that shadow Skript core grammar.
Validate every documented example by actual /sk reload on a test server.

Proposed contracts, not code guarantees

set {_scene} to new cine scene named "example:intro"
set cine duration of {_scene} to 5 seconds
set {_instance} to play cine scene {_scene} for player

This specific syntax might need adjustments during parser implementation. The docs should be updated after tests, not before.

Return types and errors

Creation expressions return typed objects or documented null/error values.
Playback expression returns a cineinstance; when it fails, return an explicit result/null rather than a partially started scene.
Any effect that changes state must define conflict, validation, cancellation and cleanup behavior.
Do not interpret scene id as globally persistent data; definitions are owned by source .sk files.

Canonical ID format

Propose namespace:scene_name; e.g. rpg:boss_intro. Names are case-normalized, validated and collision-checked at script parse time where possible.

Build-time validation

All proposed patterns should be entered into the source manifest with explicit status, since, min_skript, capability, parser_test, runtime_test, and source_example. The included JSON is a seed; extend it as implementation proceeds.