> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/en/feature-configuration/effect.md).

# Effect cutscenes

Effect is ArcMenu's cutscene and choreography module. It provides a timeline workspace similar to post-production video tools, letting you combine frontend visual elements, images, animated GIFs, 3D item models, sound effects, NBS note-block songs, and server commands into a complete audiovisual sequence. You can use it to build new-player introductions, dungeon teleport transitions, seasonal event openings, or crate reward reveals.

Administrators choreograph sequences visually in game using ArcMenu Editor, while regular players watch them directly through the server without installing any client mods. Both live playback and editor previews use vanilla display entities and a fixed camera viewpoint, preserving natural world lighting, shadows, and block occlusion so scenes blend seamlessly into the environment even with shader packs enabled. When a sequence uses custom images, fonts, or local music files, clients simply load them through the server resource pack.

## Creation and playback commands

Stand on solid ground with the `arcmenu.admin` permission and run the following command to create or open an Effect project:

```
/arcmenu editeffect intro
```

If you run `/arcmenu editeffect` with no arguments when the server has no Effect projects yet, ArcMenu automatically generates and opens a built-in example. To build a cutscene starting from the visual layout of an existing menu, append the source menu ID after the project ID:

```
/arcmenu editeffect intro main
```

This copies the frontend elements from the `main` menu into `effects/intro/scene.yml`. Any changes you make in the Effect project are completely independent and leave the original menu untouched.

Once you save your project, use these commands to control playback and manage loaded Effects:

| Command                                 | Description                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `/arcmenu effect <project-id>`          | Play the specified cutscene for yourself. Your camera is locked during playback and restored automatically when it finishes. |
| `/arcmenu effect <project-id> <player>` | Play the cutscene for a target online player (available to administrators and the console).                                  |
| `/arcmenu effect pause [player]`        | Pause the currently playing animation and audio.                                                                             |
| `/arcmenu effect resume [player]`       | Resume playback from the paused frame.                                                                                       |
| `/arcmenu effect stop [player]`         | Stop playback immediately and restore the player's camera view.                                                              |
| `/arcmenu effect list`                  | List all currently loaded Effect projects.                                                                                   |
| `/arcmenu effect reload`                | Validate and reload all Effect configuration files. Running `/arcmenu reload` also refreshes active Effect directories.      |

Players triggering playback for themselves need the default `arcmenu.effect` permission plus any project-specific `permission` configured in `timeline.yml` (leave it empty to require no extra permission). Editing projects, reloading files, and controlling playback for other players require `arcmenu.admin`.

## Timeline workspace

The Effect editor is divided into four coordinated panels: a searchable **Project and Asset Browser** on the left, a live **Scene Composition Viewport** in the center, a **Property Inspector** on the right, and a multi-track **Timeline Panel** across the bottom. Drag the dividers between panels to resize them at any time.

### Viewport modes and tools

By default, the viewport uses **Playback** scale, matching the project's canvas dimensions, `pixels-per-block`, and design distance so you see the exact size players will experience. When you need to align fine details, switch to **Fit** mode to scale the canvas to fill the preview area, then use `Ctrl + Mouse Wheel` to zoom or hold the middle mouse button to pan.

Switch tools quickly with keyboard shortcuts: `V` (Select), `H` (Hand pan), `Z` (Zoom), `W` (Rotate), and `Q` (Draw shape). In the right property inspector, drag left or right directly on numeric labels to scrub values (`Shift` for fine adjustments, `Ctrl` for larger steps), or click any color swatch to open the RGBA and hex color picker.

### Layers, keyframes, and curves

Select an element layer in the browser or timeline and expand its properties to insert keyframes at the current playhead position. If you enable **Auto-key**, moving the playhead and editing a value in the property inspector automatically records a keyframe at that frame.

You can keyframe a wide range of properties:

* **Spatial transforms and visibility**: Position offsets (`offset.x` / `offset.y` / `offset.z`), 3D rotation (`rotation.x` / `y` / `z`), 3D scale (`scale.x` / `y` / `z`), width and height dimensions, visibility (`visible`), and opacity (`opacity`, for text and shape nodes that support alpha).
* **Appearance and content**: RGB colors, text strings, fonts, font sizes, alignment, line width, image paths, item materials and display contexts, and block states. Numeric values and color channels interpolate smoothly between keyframes, whereas text strings, booleans, and asset paths switch cleanly when the playhead reaches the keyframe.

Each keyframe lets you choose the `interpolation` mode leading to the next keyframe:

* `linear`: Constant rate of change between keyframes.
* `hold`: Freezes the current value until the next keyframe, then switches instantly.
* `ease-in` / `ease-out` / `ease-in-out`: Preset smooth acceleration and deceleration curves.
* `bezier`: Cubic Bezier interpolation using `curve: [x1, y1, x2, y2]` to control timing and velocity.
* `auto-bezier`: Automatically calculates smooth, continuous tangents based on neighboring keyframes.

Click the timeline graph toggle to open the **Graph Editor**, where you can drag Bezier handles visually in either the **Value Graph** or **Speed Graph** view. Double-clicking any keyframe opens a dialog to type exact frame numbers, values, and curve coordinates.

Along the timeline, drag a layer bar's left or right edge to trim its active range `[start, end)`, hold `Alt` while dragging a bar to shift it in time, hide individual layers, or toggle **Solo** to isolate the current branch.

## Common shortcuts

| Action                                                                       | Shortcut                             |
| ---------------------------------------------------------------------------- | ------------------------------------ |
| Save project (saves both scene and timeline)                                 | `Ctrl + S`                           |
| Undo / Redo (unified across scene and timeline)                              | `Ctrl + Z` / `Ctrl + Shift + Z`      |
| Copy / Cut / Paste layers or keyframes                                       | `Ctrl + C` / `Ctrl + X` / `Ctrl + V` |
| Duplicate selected layer in place (including animation tracks)               | `Ctrl + D`                           |
| Split layer into two segments at the playhead (preserving continuous curves) | `Ctrl + Shift + D`                   |
| Play / Pause preview                                                         | `Space`                              |
| Step forward / backward one frame                                            | Left / Right Arrow                   |
| Apply Easy Ease to selected keyframes                                        | `F9`                                 |
| Filter Position / Scale / Rotation / Opacity / Animated properties           | `P` / `S` / `R` / `T` / `U`          |
| Open command palette to search actions and shortcuts                         | `Ctrl + Shift + P`                   |

Drag keyframes horizontally on the timeline to retime them, hold `Alt` while dragging to duplicate keyframes, and hold `Ctrl` while clicking to select multiple keyframes. Context menus are available by right-clicking in the project tree, viewport, property inspector, keyframes, layers, cues, and marker bar.

## Audio previews and timeline cues

Alongside visual tracks, the timeline can drive audio playback and trigger server events.

### Audio tracks and waveform scrubbing

Effect supports four audio sources:

* **Vanilla sound effects**: Enter a Bukkit Sound enum name (such as `ENTITY_PLAYER_LEVELUP`) or a vanilla namespaced ID (such as `minecraft:block.note_block.chime`).
* **CraftEngine custom sounds**: Enter a registered namespaced sound ID (such as `custom:cinematic.whoosh`).
* **Local OGG audio**: Place lowercase `.ogg` files inside `plugins/ArcMenu/effects/assets/` (for example `music/intro.ogg`) and reference the relative path `music/intro.ogg` in the cue. After adding new OGG files, rebuild and distribute your resource pack following [Images and resource packs](/en/feature-configuration/resource-packs.md).
* **NBS note-block songs**: Place `.nbs` files (supporting NBS versions 0–5, vanilla and custom instruments, volume, stereo panning, and fine pitch) inside `effects/assets/` (for example `songs/intro.nbs`). The server parses and plays NBS tracks directly.

Inside the editor, **Audio Preview** reads OGG audio from the client's loaded resource packs (including vanilla sounds, CraftEngine sounds, and local OGG tracks), decodes it asynchronously, and draws the real **audio waveform** and clip duration directly on the timeline. You can jump the playhead to any frame to audition the track from that point, or scrub back and forth across frames to hear short audio samples and sync keyframes to the beat. Audio previews support overlapping clips, mute toggles, pitch playback speed (`pitch`), and work-area looping.

### Triggering commands and actions

You can attach command or action cues to specific frames on the timeline. While previewing or scrubbing in the editor, command and action cues remain silent so they never fire accidentally. They execute on the server at their exact frame numbers only during live `/arcmenu effect` playback.

For example, to open the main menu automatically at frame 90 right before the cutscene ends:

```yaml
cues:
  - id: open-main
    frame: 90
    kind: action
    source: 'open: main'
```

## File structure and configuration reference

Each Effect project lives in `plugins/ArcMenu/effects/<project-id>/` and consists of two YAML files, while shared audio files are kept in `effects/assets/`:

```
plugins/ArcMenu/effects/
  intro/
    scene.yml       # Visual scene definition (uses the same canvas and frontend structure as standard menus)
    timeline.yml    # Timeline settings, layer ranges, animation tracks, cues, and markers
  assets/
    music/intro.ogg
    songs/intro.nbs
```

Here is a complete `timeline.yml` example:

```yaml
schema-version: 1
id: intro
fps: 20
duration: 100
loop: false
work-start: 0
work-end: 100
permission: ''
layers:
  - {target: title, start: 0, end: 100, enabled: true, solo: false}
tracks:
  - target: title
    property: offset.x
    enabled: true
    keys:
      - {frame: 0, value: '-100', interpolation: bezier, curve: [0.25, 0.1, 0.25, 1]}
      - {frame: 30, value: '0', interpolation: hold}
      - {frame: 75, value: '0', interpolation: ease-in}
      - {frame: 100, value: '100'}
cues:
  - {id: chime, frame: 10, kind: sound, source: 'minecraft:block.note_block.chime', volume: 0.8, pitch: 1.0}
  - {id: bgm, frame: 0, end: 100, kind: sound, source: 'music/intro.ogg', volume: 1.0, pitch: 1.0}
  - {id: song, frame: 0, end: 80, kind: nbs, source: 'songs/intro.nbs'}
  - {id: player-cmd, frame: 40, kind: command, source: 'me is watching the opening cutscene'}
  - {id: console-cmd, frame: 50, kind: console, source: 'say Welcome to the server'}
  - {id: next-menu, frame: 95, kind: action, source: 'open: main'}
markers:
  - {frame: 30, label: Title hold}
```

Valid values for each field:

* `schema-version`: Always set to the integer `1`.
* `id`: Unique project identifier. Must match the project folder name and the `id` in `scene.yml`.
* `fps`: Timeline frames per second. Accepts any finite number from `1` to `120` (integers or decimals; `20` is common).
* `duration`: Ending frame number of the timeline. Accepts an integer from `1` to `432000`, with a maximum total duration (`duration / fps`) of `3600` seconds (1 hour). For example, `fps: 20` and `duration: 100` produce a 5-second animation. Live playback finishes frame `100` completely before cleaning up the scene.
* `loop`: Boolean (`true` or `false`). When set to `true`, both live playback and editor previews loop continuously, firing timeline cues on each pass.
* `work-start` and `work-end`: Integer frame numbers defining the preview and loop range inside the editor. Must satisfy `0 <= work-start < work-end <= duration`. Does not affect the full duration of live playback.
* `permission`: String specifying an extra permission node required for players to watch the cutscene. Leave empty `''` to require only the default `arcmenu.effect` permission.
* `layers`: Defines the active lifespan and visibility state of each element layer. `target` is the frontend element ID from `scene.yml`, `start` and `end` define the half-open frame interval `[start, end)`, `enabled` controls whether the layer is visible, and `solo` isolates the layer and its children.
* `tracks`: List of property animation tracks. `target` is the element ID, `property` is the animated property path, `enabled` toggles the track on or off, and `keys` is a list of keyframes sorted in ascending order by `frame`.
* `cues`: List of timeline events. Each entry includes a unique `id`, trigger `frame` (plus an optional `end` frame for sound and NBS cues), `kind`, and `source`:
  * `kind: sound`: Plays a vanilla sound, CraftEngine sound, or relative `.ogg` path under `effects/assets/`. Supports optional `volume` (`0` to `4`, default `1`) and `pitch` (`0.01` to `4`, default `1`).
  * `kind: nbs`: Plays a relative `.nbs` song path under `effects/assets/`.
  * `kind: command`: Runs a command without a leading slash as the viewing player, with placeholder parsing.
  * `kind: console`: Runs a command from the server console, with placeholder parsing.
  * `kind: action`: Executes a standard ArcMenu action expression (see [Actions and navigation](/en/menu-configuration/menus/actions.md)).
* `markers`: List of timeline markers containing a `frame` number and a descriptive `label` to help mark beats and transitions while editing.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/en/feature-configuration/effect.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.