# Cutscene
> A scripted sequence of timed actions including camera paths, HUD elements, effects, and callbacks.
`gg.lode.lecternapi.api.cutscene.Cutscene`
---
## Signature
```java
public final class Cutscene
```
---
## Overview
Cutscene provides a fluent builder for creating timed sequences of actions. Actions can include showing/hiding HUD elements, camera movement, screen effects, audio, and server-side callbacks.
Use `Cutscene.builder(id)` to create a new cutscene, chain actions using `then(ticks)` or `at(tick)`, and finalize with `build()`.
---
## Creating a Cutscene
```java
Cutscene cutscene = Cutscene.builder("my_cutscene")
.at(0)
.letterbox(true)
.hideHud(true)
.showText("title", "<gold>Chapter 1</gold>", MenuTransform.at(0, 0).centered(), 3.0f)
.then(60)
.hideText("title")
.playSound("minecraft:entity.experience_orb.pickup", 1.0f, 1.0f)
.then(20)
.letterbox(false)
.hideHud(false)
.onComplete(() -> player.sendMessage("Cutscene complete!"))
.build();
```
---
## Static Methods
### builder
```java
public static Builder builder(String id)
```
Creates a new cutscene builder with the specified ID.
| Parameter | Type | Description |
|---|---|---|
| `id` | `String` | A unique identifier for this cutscene. |
**Returns:** A new `Builder` instance.
---
## Instance Methods
### getId
```java
public String getId()
```
**Returns:** The cutscene identifier.
---
### getActions
```java
public List<CutsceneAction> getActions()
```
**Returns:** The list of actions in this cutscene.
---
### getCameraPath
```java
@Nullable public CameraPath getCameraPath()
```
**Returns:** The camera path, or `null` if none was configured.
---
### getTotalDurationTicks
```java
public int getTotalDurationTicks()
```
**Returns:** The total duration in ticks (based on the last action's tick).
---
### isLoop
```java
public boolean isLoop()
```
**Returns:** `true` if the cutscene loops.
---
### getCallbacks
```java
public Map<Integer, Runnable> getCallbacks()
```
**Returns:** Map of callback IDs to their Runnable actions.
---
### getOnComplete
```java
@Nullable public Runnable getOnComplete()
```
**Returns:** The completion callback, or `null` if none was set.
---
## Builder Methods
### Timeline Control
#### then
```java
public Builder then(int ticks)
```
Advances the cursor by the specified number of ticks. Subsequent actions will be scheduled at the new cursor position.
| Parameter | Type | Description |
|---|---|---|
| `ticks` | `int` | Number of ticks to advance. |
---
#### at
```java
public Builder at(int tick)
```
Sets the cursor to an absolute tick position.
| Parameter | Type | Description |
|---|---|---|
| `tick` | `int` | The tick to set the cursor to. |
---
### HUD Elements
#### showTexture
```java
public Builder showTexture(String ref, String textureId, MenuTransform transform, int width, int height)
```
Shows a texture on the HUD at the current tick.
| Parameter | Type | Description |
|---|---|---|
| `ref` | `String` | Unique reference ID for this element. |
| `textureId` | `String` | The texture identifier (e.g. `"namespace:textures/gui/image.png"`). |
| `transform` | `MenuTransform` | Positioning data. |
| `width` | `int` | Texture width in pixels. |
| `height` | `int` | Texture height in pixels. |
---
#### hideTexture
```java
public Builder hideTexture(String ref)
```
Hides a previously shown texture.
---
#### showText
```java
public Builder showText(String ref, String text, MenuTransform transform, float scale)
```
Shows text on the HUD. Supports MiniMessage formatting.
| Parameter | Type | Description |
|---|---|---|
| `ref` | `String` | Unique reference ID. |
| `text` | `String` | The text content (MiniMessage format). |
| `transform` | `MenuTransform` | Positioning data. |
| `scale` | `float` | Text scale multiplier. |
---
#### hideText
```java
public Builder hideText(String ref)
```
Hides previously shown text.
---
#### showHead
```java
public Builder showHead(String ref, UUID headUuid, MenuTransform transform, int width, int height)
```
Shows a player head on the HUD.
---
#### hideHead
```java
public Builder hideHead(String ref)
```
Hides a previously shown head.
---
#### showPlayer
```java
public Builder showPlayer(String ref, String identifier, MenuTransform transform, int width, int height)
```
Shows a player bust render on the HUD.
| Parameter | Type | Description |
|---|---|---|
| `identifier` | `String` | Player username or UUID. |
---
#### hidePlayer
```java
public Builder hidePlayer(String ref)
```
Hides a previously shown player bust.
---
### Screen Effects
#### letterbox
```java
public Builder letterbox(boolean enabled)
```
Enables or disables letterbox (cinematic black bars).
---
#### hideHud
```java
public Builder hideHud(boolean hidden)
```
Hides or shows the vanilla HUD.
---
#### flash
```java
public Builder flash(int r, int g, int b, int a, int layer, float durIn, float durStay, float durOut)
```
Triggers a screen flash effect.
| Parameter | Type | Description |
|---|---|---|
| `r`, `g`, `b`, `a` | `int` | RGBA color components (0-255). |
| `layer` | `int` | Render layer. |
| `durIn` | `float` | Fade-in duration in seconds. |
| `durStay` | `float` | Stay duration in seconds. |
| `durOut` | `float` | Fade-out duration in seconds. |
---
#### motionBlur
```java
public Builder motionBlur(boolean enabled)
```
Enables or disables motion blur.
---
### Audio
#### playSound
```java
public Builder playSound(String soundId, float volume, float pitch)
```
Plays a sound effect.
| Parameter | Type | Description |
|---|---|---|
| `soundId` | `String` | The sound identifier (e.g. `"minecraft:entity.experience_orb.pickup"`). |
| `volume` | `float` | Volume (0.0 to 1.0). |
| `pitch` | `float` | Pitch multiplier. |
---
### Input Control
#### disableInput
```java
public Builder disableInput(boolean disabled)
```
Disables or enables player input. When disabled, the player cannot move or interact.
---
### Camera Control
#### setCamera
```java
public Builder setCamera(double x, double y, double z, float yaw, float pitch, float roll)
```
Moves the camera to a fixed position.
| Parameter | Type | Description |
|---|---|---|
| `x`, `y`, `z` | `double` | World coordinates. |
| `yaw`, `pitch`, `roll` | `float` | Rotation angles. |
---
#### releaseCamera
```java
public Builder releaseCamera()
```
Releases camera control back to the player.
---
#### setFov
```java
public Builder setFov(float fov)
```
Sets the field of view.
---
#### resetFov
```java
public Builder resetFov()
```
Resets FOV to the player's default.
---
#### cameraPath
```java
public Builder cameraPath(Consumer<CameraPathBuilder> configurator)
```
Configures a camera path for smooth movement between waypoints.
```java
.cameraPath(path -> path
.waypoint(Vec.of(100, 70, 200), 0, -10, 0, 0)
.waypoint(Vec.of(120, 75, 220), 15, -5, 0, 60)
.interpolation(CameraInterpolation.CATMULL_ROM))
```
---
### Component Animation
#### animateComponent
```java
public Builder animateComponent(String ref, int durationTicks, int easingType,
float bz0, float bz1, float bz2, float bz3,
float targetX, float targetY, int targetLayer, float targetAlpha,
int targetWidth, int targetHeight, float targetScale)
```
Animates a HUD component (texture, text, etc.) from its current state to the target values over the specified duration using a cubic Bezier easing curve.
| Parameter | Type | Description |
|---|---|---|
| `ref` | `String` | The reference ID of the element to animate. |
| `durationTicks` | `int` | The animation duration in ticks. |
| `easingType` | `int` | The easing type identifier. |
| `bz0`, `bz1`, `bz2`, `bz3` | `float` | Cubic Bezier control points for the easing curve. |
| `targetX` | `float` | Target horizontal position. |
| `targetY` | `float` | Target vertical position. |
| `targetLayer` | `int` | Target render layer. |
| `targetAlpha` | `float` | Target opacity. |
| `targetWidth` | `int` | Target width. |
| `targetHeight` | `int` | Target height. |
| `targetScale` | `float` | Target scale. |
---
### Callbacks
#### callback
```java
public Builder callback(Runnable callback)
```
Registers a server-side callback at the current tick. When the cutscene reaches this tick, a `CutsceneCallbackEvent` is fired and the callback is executed.
---
### Completion
#### loop
```java
public Builder loop(boolean loop)
```
Sets whether the cutscene loops. Default is `false`.
---
#### onComplete
```java
public Builder onComplete(Runnable onComplete)
```
Sets a callback to run when the cutscene finishes (does not run if looping).
---
#### build
```java
public Cutscene build()
```
Builds and returns the final `Cutscene` instance.
---
## Related Pages
- [[ICutsceneManager]] — Playback control
- [[CameraPath]] — Camera path definition
- [[CameraInterpolation]] — Interpolation modes
- [[Vec]] — Position helper
- [[CutsceneAction]] — Action types
- [[MenuTransform]] — Positioning