> For the complete documentation index, see [llms.txt](https://acestudios.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://acestudios.gitbook.io/docs/roleplay/advanced-knockout/dream-sequences.md).

# Dream Sequences

Configure, switch and add fullscreen dream videos.

When a player is knocked out, they may enter a **dream**: the screen fades to black, and after about two seconds a random video from your list fades in and plays fullscreen. When the video ends, or the player skips it, the dream closes.

## Options

```lua
Config.Dreaming = {
    Enabled = true,
    BaseChance = 0.5,
    DreamMessages = "You feel a strange sensation as you drift into a dream...",
    Folder = "dreams",
    Extensions = {"mp4"},
    Videos = { 'underwaterDream.mp4', ... },
    ShowOverlayAfterDream = false,
    AllowSkip = true,
    SkipAfterSeconds = 5,
    SkipControl = 38, -- INPUT_CONTEXT (E)
    FadeIn = true,
    FadeOut = true,
    Debug = false
}
```

| Option                  | Default    | Description                                                                                       |
| ----------------------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `Enabled`               | `true`     | Turns dreams on or off.                                                                           |
| `BaseChance`            | `0.5`      | Chance (0.0–1.0) of dreaming when knocked out.                                                    |
| `DreamMessages`         | text       | Message shown when a dream starts.                                                                |
| `Folder`                | `"dreams"` | Folder that contains the videos.                                                                  |
| `Extensions`            | `{"mp4"}`  | Video file extension(s) in use.                                                                   |
| `Videos`                | 9 files    | Exact file names to choose from at random.                                                        |
| `ShowOverlayAfterDream` | `false`    | If `true`, the unconscious overlay (text and timer) stays after the dream until the player wakes. |
| `AllowSkip`             | `true`     | Lets players skip the dream.                                                                      |
| `SkipAfterSeconds`      | `5`        | Seconds before the *"Press \[E] to Wake From Dream (Skip)"* prompt appears.                       |
| `SkipControl`           | `38`       | Control ID used to skip (38 = <kbd>E</kbd>).                                                      |
| `FadeIn` / `FadeOut`    | `true`     | Fades the dream in and out.                                                                       |
| `Debug`                 | `false`    | Dream-specific debug output.                                                                      |

## Included videos

| Video                       | MP4 file                          | WEBM file (in `dreams/WEBM/`)      |
| --------------------------- | --------------------------------- | ---------------------------------- |
| Underwater                  | `underwaterDream.mp4`             | `underwaterDream.webm`             |
| Car crash                   | `carcrashDream.mp4`               | `carcrashDream.webm`               |
| Jump from building          | `jumpfrombuildingDream.mp4`       | `jumpfrombuildingDream.webm`       |
| Pier walk in the rain       | `pierwalkingrainyDream.mp4`       | `pierwalkingrainyDream.webm`       |
| Police chase on foot (long) | `policechaseonfootLongDream.mp4`  | `policechaseonfootLongDream.webm`  |
| City stroll (short)         | `strollthroughcityShortDream.mp4` | `strollthroughcityShortDream.webm` |
| Hitman job                  | `hitmanjobDream.mp4`              | `hitmanjobDream.webm`              |
| Plane crash (short)         | `planecrashShortDream.mp4`        | `planecrashShortDream.webm`        |
| Police car chase            | `Policecarchasedream.mp4`         | `policecarchaseDream.webm`         |

{% hint style="info" %}
MP4 files total about **200 MB** and WEBM files about **50 MB**. WEBM loads much faster, but the video quality is lower.
{% endhint %}

## Switching to WEBM

{% stepper %}
{% step %}

### Move the WEBM files

Move the `.webm` files from `dreams/WEBM/` into `dreams/`, the same folder as `Config.Dreaming.Folder`. You can delete the `.mp4` files to save space.
{% endstep %}

{% step %}

### Update `fxmanifest.lua`

Comment out the MP4 line and uncomment the WEBM line in `files`:

{% code title="fxmanifest.lua" %}

```lua
files {
    'ui/index.html',
    'ui/style.css',
    'ui/app.js',
    'ui/heartbeat.mp3',
    --'dreams/*.mp4',
    'dreams/*.webm'
}
```

{% endcode %}
{% endstep %}

{% step %}

### Update `config.lua`

Use the **exact** file names:

{% code title="config.lua" %}

```lua
Extensions = {"webm"},
Videos = {
    'underwaterDream.webm',
    'carcrashDream.webm',
    'jumpfrombuildingDream.webm',
    'pierwalkingrainyDream.webm',
    'policechaseonfootLongDream.webm',
    'strollthroughcityShortDream.webm',
    'hitmanjobDream.webm',
    'planecrashShortDream.webm',
    'policecarchaseDream.webm',
},
```

{% endcode %}

{% hint style="warning" %}
The example in `dreams/WEBM/WEBM = LOWER QUALITY & LOWER STORAGE USE.txt` lists `pierwalkingDream.webm` and `Policecarchasedream.mp4`. The real WEBM file names are **`pierwalkingrainyDream.webm`** and **`policecarchaseDream.webm`**. Use the list above.
{% endhint %}
{% endstep %}

{% step %}

### Restart the server

{% endstep %}
{% endstepper %}

## Adding your own dreams

1. Convert your video to **`.webm`**. The ReadMe recommends this to avoid buffering problems in FiveM's browser.
2. Put the file in `ace_knockout/dreams/`.
3. Make sure `fxmanifest.lua` includes that extension in `files` (for example `'dreams/*.webm'`).
4. Add the exact file name to `Config.Dreaming.Videos`, and its extension to `Extensions`.
5. Restart the server.

{% hint style="warning" %}
Every video is downloaded by players when they join. Keep videos short and compressed.
{% endhint %}