Cinematic Actors & Entity Control
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.
An actor is a reference and control policy for an entity within a scene. It may wrap a world entity or a temporary owned cinematic entity.
Actor families
| Family | Typical source | Isolation |
|---|---|---|
| Existing Bukkit entity | Skript entity |
Modify only explicitly owned aspects |
| Temporary entity | Spawn via SkCine | Despawn automatically |
| Display actor | Item/block/text display | Interpolated visual actor |
| Player actor | Actual player | Respect permissions and state owner |
| Packet-only visual actor | Optional PacketEvents | Viewer/session scoped and client-limited |
| Third-party model actor | Optional verified adapter | Integration-specific capabilities |
Proposed Skript usage
set {_actor} to new cine actor from {_entity}
set cine actor name of {_actor} to "Guardian"
add cine actor keyframe at {_start} to {_actor} at 0 seconds
add cine actor keyframe at {_end} to {_actor} at 4 seconds
add cine actor {_actor} to {_scene}
Crucial: A world mob is not a fully skinnable model. Vanilla entities do not expose generic bone animations. For external-model animation, require a tested optional integration.
Actor lifecycle
- Actors are created with
world,scene, orviewerownership. - Existing entities are borrowed, not deleted by cleanup.
- Temporary world entities are removed when the owning instance ends.
- Packet actor IDs are allocated/released per viewer.
- World unload, entity death, despawn, viewer disconnect and chunk boundaries have explicit policies.
- Ownership conflicts should be rejected or arbitrated, not silently overwritten.
Audience control
show cine actor {_actor} to {_audience}
hide cine actor {_actor} from {_spectator}
Packet-only actors can be audience-scoped. Real Bukkit entities require a supported visibility implementation and may remain physically relevant in the world.
Best practices
Prefer display or client-only actors for cosmetic reveals; do not give temporary cinematic actors AI when unnecessary. Budget all temporary entities, update only when viewed, and ensure deterministic cleanup.