StagingEvent

Tells the client to PLAY A STAGING: a scripted sequence of map effects that Ankama's map editor (AleCore) stores with each map. It is presentation only: nothing in the game state changes.

WHAT A STAGING IS

Each map can carry staging sequences, numbered (the map's StagingManager keeps them in a table keyed by the sequence id). A sequence is a timeline of shots, and each shot applies effects to targets on the map: - objects: move, rotate, scale, show map animated elements; - materials: colour animation, emissive glow, dissolve, distortion, alpha; - particles: start, stop, burst, change emission; - sound: play or stop FMOD events, set FMOD parameters and snapshots, switch the music playlist. The only non-visual effect is a 'FightStopWaiting' event, used by fight stagings to release a fight action that waits for its staging; a roleplay staging cannot change anything else.

WHY IT EXISTS

The server decides WHEN a map's scripted moment happens; the client owns the sequence itself (it is map data). This event is the cue: which sequence, from where, how strongly.

WHEN IT ARRIVES

Whenever the server triggers a staging on the map you are on (inferred: a map event, a quest or interactive step, an ambience change). It can arrive before the map has finished rendering, for example right after a map change: the official client keeps it and plays it once the map is rendered.

WHAT TO DO WHEN YOU RECEIVE IT

1. StagingEvent.sequence_id: the sequence to play, in the CURRENT map's staging table. An id the map does not have is ignored, and so is a sequence with no shot. 2. StagingEvent.progression: where to start, in PERCENT of the sequence's duration: 0 = from the beginning, 50 = halfway, 100 = at the end. Values outside 0-100 are clamped. Start time = progression / 100 x duration. 3. StagingEvent.intensity_multiplier: how strongly to play it, in PERCENT: 100 = as authored. The sequencer scales its effects by intensity_multiplier / 100. 4. If the map is not rendered yet, keep the three values and play the sequence once it is. 5. SEND NOTHING BACK. A bot that does not render the map can ignore this event safely.

EXAMPLE. sequence_id 904, progression absent (0), intensity_multiplier 100: play map sequence 904 from its start, at its authored strength.

WHAT THE OFFICIAL CLIENT DOES

Its map staging service calls StagingManager.PlaySequenceFromProgression(sequenceId, progression, intensityMultiplier). The manager looks the id up in the map's sequences, builds a sequencer with intensityMultiplier / 100, keeps only the shots allowed by the 'map effects' graphics option, computes the duration, converts progression to a start time and starts it. Each sequence has an exclusivity rule (fast- forward, stop, wait or cancel) that decides what happens to a sequence already playing.

RELATED

- PersistentStagingEvent (same file): long-running map stagings. It carries a list of sequence ids and the date they started; the client resumes each one at the elapsed time (PlaySequenceFromStartTime), so a player arriving on the map sees them already running. - GameActionFightEvent.staging: the same kind of sequence played as a step of a fight action, possibly blocking the fight until the sequence signals FightStopWaiting.