> For the complete documentation index, see [llms.txt](https://aero-labs.gitbook.io/aero-labs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aero-labs.gitbook.io/aero-labs-docs/scripts/ascenecam.md).

# ASceneCam

A cinematic scene camera: place a free camera around your character to film better roleplay scenes and clips.

![ASceneCam](https://3178353394-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fm2Hc1pmEtJtEBI0blIeE%2Fuploads%2FTytlpbWEjLfewRhNWqnj%2FASceneCam.png?alt=media)

ASceneCam lets players set up a **cinematic camera** around their own character, so they can frame roleplay scenes the way they want them. Move the camera, look around, zoom, and add black cinematic bars for a film look. It's made for recording clips, taking screenshots, and setting up better "scenes" in game.

While the camera is active the normal game HUD and minimap are hidden, so the shot stays clean.

## Requirements

| Dependency                                        | Required | Notes         |
| ------------------------------------------------- | -------- | ------------- |
| [ox\_lib](https://github.com/overextended/ox_lib) | Yes      | Notifications |

ASceneCam runs only on the client and works with **any framework** (Standalone, QBCore, QBox, ESX, TMC).

## Installation

It's a simple drag and drop:

1. Drag the `ASceneCam` folder into your `resources` folder.
2. Add it to your `server.cfg` after ox\_lib:

   ```cfg
   ensure ox_lib
   ensure ASceneCam
   ```
3. Restart your server. That's it. Optionally, adjust `config.lua` and `client/client_open.lua` (see below).

## Usage

### Commands

| Command  | What it does                                                                                                 |
| -------- | ------------------------------------------------------------------------------------------------------------ |
| `/cam`   | Opens the camera. Type it again to close it.                                                                 |
| `/cam 1` | Opens the camera **with cinematic black bars**. While the camera is open, `/cam 1` turns the bars on or off. |

You can change the command name and the bars argument in `config.lua` (`Config.Command` and `Config.BorderArg`).

### Controls

| Key             | Action              |
| --------------- | ------------------- |
| **Mouse**       | Look around         |
| **W / S**       | Move forward / back |
| **A / D**       | Move left / right   |
| **E / Q**       | Move up / down      |
| **Mouse wheel** | Zoom in / out       |

All of these can be rebound. See **Keybinds** below.

### How the camera works

* The camera opens **in front of your character, facing you**, and glides in smoothly.
* It stays close to you: up to **5 m** away, **2 m** above and **0.8 m** below your starting point. You can change these limits in `Config.Boundaries`.
* It stops at walls, so it can't pass through buildings.
* Your character stays still while the camera is open. You can still use **chat (T)**, **push-to-talk (N)** and the **pause menu**.

{% hint style="info" %}
**Tip:** start your emote or pose first, then open the camera. You can also run emote commands from chat while the camera is open.
{% endhint %}

### When the camera closes by itself

The camera switches off automatically if you:

* die,
* get into a vehicle,
* start ragdolling, or
* are moved more than **3 m** from where you opened it (for example, pushed or carried).

If the camera can't be opened, you'll see *"You cannot use the camera right now"*.

## Keybinds

### For players: changing your keys

Every control is a FiveM keybind, so each player can set their own keys:

1. Open the pause menu (**Esc**) and go to **Settings**, then **Key Bindings**, then **FiveM**.
2. Find the entries starting with **Cinematic Cam:**.
3. Click one and press the key you want.

| Keybind                           | Default key      |
| --------------------------------- | ---------------- |
| Cinematic Cam: Toggle             | *not set*        |
| Cinematic Cam: Toggle With Border | *not set*        |
| Cinematic Cam: Move Forward       | W                |
| Cinematic Cam: Move Back          | S                |
| Cinematic Cam: Move Up            | E                |
| Cinematic Cam: Move Down          | Q                |
| Cinematic Cam: Move Left          | A                |
| Cinematic Cam: Move Right         | D                |
| Cinematic Cam: Zoom In            | Mouse wheel up   |
| Cinematic Cam: Zoom Out           | Mouse wheel down |

The two **Toggle** binds have no key by default. Set one if you'd rather open the camera with a key than with `/cam`.

### For server owners: changing the default keys

Set the defaults in `Config.Keybinds`. Each bind has a `label` (the name shown in the settings menu), a `mapper` (the input device) and a `key`:

```lua
Config.Keybinds = {
    toggle       = { label = "Cinematic Cam: Toggle", mapper = "keyboard", key = "" },
    toggleBorder = { label = "Cinematic Cam: Toggle With Border", mapper = "keyboard", key = "" },
    moveForward  = { label = "Cinematic Cam: Move Forward", mapper = "keyboard", key = "W" },
    moveBack     = { label = "Cinematic Cam: Move Back", mapper = "keyboard", key = "S" },
    moveUp       = { label = "Cinematic Cam: Move Up", mapper = "keyboard", key = "E" },
    moveDown     = { label = "Cinematic Cam: Move Down", mapper = "keyboard", key = "Q" },
    moveLeft     = { label = "Cinematic Cam: Move Left", mapper = "keyboard", key = "A" },
    moveRight    = { label = "Cinematic Cam: Move Right", mapper = "keyboard", key = "D" },
    zoomIn       = { label = "Cinematic Cam: Zoom In", mapper = "MOUSE_WHEEL", key = "IOM_WHEEL_UP" },
    zoomOut      = { label = "Cinematic Cam: Zoom Out", mapper = "MOUSE_WHEEL", key = "IOM_WHEEL_DOWN" },
}
```

* For a keyboard key, use `mapper = "keyboard"` and the key name, such as `"F7"`, `"H"` or `"LSHIFT"`.
* Leave `key = ""` to add the bind without a default key.

{% hint style="warning" %}
FiveM saves keybinds **per player**. A new default only applies to players who haven't used the script yet. Players who already joined keep their current key until they change it themselves in **Key Bindings**.
{% endhint %}

## Configuration

All settings are in `config.lua`.

### General

```lua
Config.Debug = true

Config.Command = "cam"
Config.BorderArg = "1"

Config.Text = {
    blocked = "You cannot use the camera right now"
}
```

| Option                | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| `Config.Debug`        | Prints camera start/stop messages in the F8 console. Set to `false` on a live server. |
| `Config.Command`      | The chat command, without the `/`.                                                    |
| `Config.BorderArg`    | The word after the command that adds the cinematic bars (`/cam 1`).                   |
| `Config.Text.blocked` | The message shown when the camera can't be opened.                                    |

### Boundaries: how far the camera can go

```lua
Config.Boundaries = {
    up = 2.0,
    down = 0.8,
    range = 5.0,
    maxPitch = 60.0
}
```

| Option     | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| `up`       | How far the camera can rise above the start point, in metres. |
| `down`     | How far it can drop below the start point, in metres.         |
| `range`    | How far it can move away sideways, in metres.                 |
| `maxPitch` | How far up or down the camera can tilt, in degrees.           |

### Camera: the starting shot

```lua
Config.Camera = {
    startRange = 2.5,
    startHeight = 0.2,
    focusHeight = 0.3,
    fov = 45.0,
    easeTime = 600,
    wallMargin = 0.3
}
```

| Option        | Description                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `startRange`  | How far in front of your character the camera starts, in metres.                                    |
| `startHeight` | How high the camera starts, in metres.                                                              |
| `focusHeight` | Height of the point the camera moves around. Raise it to centre on the head, lower it for the body. |
| `fov`         | Field of view. Lower is more zoomed-in and "filmic", higher is wider.                               |
| `easeTime`    | How long the glide in and out takes, in milliseconds.                                               |
| `wallMargin`  | How far the camera stays from walls, in metres.                                                     |

### Movement: how the camera feels

```lua
Config.Movement = {
    speed = 1.5,
    sensitivity = 6.0,
    zoomStep = 0.3,
    smoothing = 8.0,
    invertX = false,
    invertY = false
}
```

| Option                | Description                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `speed`               | Movement speed in metres per second.                                                                         |
| `sensitivity`         | Mouse look speed.                                                                                            |
| `zoomStep`            | How far one mouse-wheel step moves the camera, in metres.                                                    |
| `smoothing`           | How quickly the camera catches up with your input. Lower is smoother and more cinematic, higher is snappier. |
| `invertX` / `invertY` | Invert mouse left/right or up/down.                                                                          |

### Border: the cinematic bars

```lua
Config.Border = {
    size = 0.1,
    speed = 6.0
}
```

| Option  | Description                                                      |
| ------- | ---------------------------------------------------------------- |
| `size`  | Height of each black bar as a share of the screen (`0.1` = 10%). |
| `speed` | How fast the bars slide in and out.                              |

### Blocked: when the camera can't be used

```lua
Config.Blocked = {
    dead = true,
    vehicle = true,
    ragdoll = true,
    moveDistance = 3.0
}
```

| Option         | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| `dead`         | Block the camera while dead.                                                        |
| `vehicle`      | Block the camera while in a vehicle.                                                |
| `ragdoll`      | Block the camera while ragdolling.                                                  |
| `moveDistance` | Close the camera if the player is moved this many metres from where they opened it. |

### Allowed controls

```lua
Config.AllowedControls = { 199, 200, 245, 249 }
```

While the camera is open, all game controls are switched off except the ones in this list. The defaults are the pause map (**P**, `199`), the pause menu (**Esc**, `200`), chat (**T**, `245`) and push-to-talk (**N**, `249`). Add more [control IDs](https://docs.fivem.net/docs/game-references/controls/) to keep other keys working.

## Hiding your HUD and custom checks (`client_open.lua`)

`client/client_open.lua` is open (not escrowed). It has three functions you can fill in to connect ASceneCam to your own server:

```lua
function hideHud()
end

function showHud()
end

function canUseCam()
    return true
end
```

| Function      | When it runs                               | Use it to                                                                   |
| ------------- | ------------------------------------------ | --------------------------------------------------------------------------- |
| `hideHud()`   | When the camera opens                      | Hide your custom HUD, speedometer, status bars, notifications and so on     |
| `showHud()`   | When the camera closes                     | Show them again                                                             |
| `canUseCam()` | Before opening, and every frame while open | Return `false` to block the camera, for example while handcuffed or in jail |

ASceneCam already hides GTA's own HUD and minimap. `hideHud()` is for **your** HUD resources, which the game can't hide by itself.

### Examples

{% tabs %}
{% tab title="Hide a custom HUD" %}
Call your HUD's own export or event. Check your HUD resource's docs for the right name. The names below are only examples:

```lua
function hideHud()
    exports['my-hud']:toggleHud(false)
    TriggerEvent('my-status:hide')
end

function showHud()
    exports['my-hud']:toggleHud(true)
    TriggerEvent('my-status:show')
end
```

{% endtab %}

{% tab title="Block while handcuffed (QBCore)" %}

```lua
local QBCore = exports['qb-core']:GetCoreObject()

function canUseCam()
    local data = QBCore.Functions.GetPlayerData()
    if data.metadata and data.metadata.ishandcuffed then
        return false
    end
    return true
end
```

{% endtab %}

{% tab title="Block in an area" %}

```lua
local blockedArea = vector3(1690.0, 2600.0, 45.0) -- example: prison
local blockedRadius = 200.0

function canUseCam()
    local coords = GetEntityCoords(PlayerPedId())
    return #(coords - blockedArea) > blockedRadius
end
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`canUseCam()` runs every frame while the camera is open, so keep it light. Read data you already have; don't call the server from it.
{% endhint %}