> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlasscripts.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Entities

> Spawn networked vehicles, peds, and objects server-side, track them in a registry, and let the bridge auto-clean them when their owner disconnects.

`Bridge.Entities` is the sanctioned way to spawn networked entities from a resource. It spawns **server-side**, tracks every entity in a registry, and automatically deletes a player's entities when they disconnect. You get back a data-only view keyed by `netId`, which is what you use to reach the entity on clients.

This is a **server-only** surface.

## Why server-side spawning

A client-spawned networked entity is owned by the spawning client. That client controls its network state — it can teleport it, modify it, give it god mode, or delete it at will. It is one of the most exploited attack surfaces on FiveM.

Spawning server-side makes the **server** authoritative over the entity's creation and lifecycle. A client may *request* a spawn over [`Bridge.Net`](/atlas-bridge/developer/networking) (validate the request first), but the server performs the spawn through `Bridge.Entities.Spawn`.

<Warning>
  Never `CreateVehicle` / `CreatePed` / `CreateObject` from a client for anything other players interact with. Route the request to the server, validate it, and spawn with `Bridge.Entities.Spawn`.
</Warning>

## Spawn

```lua theme={null}
local view, err = Bridge.Entities.Spawn({
    kind   = 'vehicle',          -- 'vehicle' | 'ped' | 'object'
    model  = 'adder',            -- model name or hash
    coords = vec4(215.7, -810.1, 30.7, 90.0),
    owner  = src,                -- optional: ties cleanup to this player's disconnect
    purpose = 'garage',          -- optional: free-form tag stored on the record
    meta   = { plate = 'ATLAS01' }, -- optional: arbitrary data stored on the record
})

if not view then
    -- err: 'bad_kind' | 'create_failed' | 'no_exist' | 'bad_spec'
    return
end

print(view.netId)   -- use this on clients
```

### Spec fields

<ParamField path="kind" type="'vehicle' | 'ped' | 'object'" required>
  What to spawn. Invalid kinds return `nil, 'bad_kind'`.
</ParamField>

<ParamField path="model" type="string | number" required>
  Model name (hashed for you) or a precomputed hash.
</ParamField>

<ParamField path="coords" type="vector4 | vector3 | table" required>
  Spawn position; the `w` component is the heading (defaults to 0 if omitted).
</ParamField>

<ParamField path="owner" type="integer (player src)">
  If set, the entity is filed under this player and **auto-deleted when they disconnect**.
</ParamField>

<ParamField path="purpose" type="string">
  Free-form tag stored on the record and returned in the view.
</ParamField>

<ParamField path="meta" type="table">
  Arbitrary data stored on the record and returned in the view.
</ParamField>

<ParamField path="vehicleType" type="string">
  Vehicle class for the server setter (default `'automobile'`). Use e.g. `'bike'`, `'heli'`, `'boat'` for other classes.
</ParamField>

<ParamField path="pedType" type="integer">
  Ped type for `CreatePed` (default `4`).
</ParamField>

### Return — a data-only view

`Spawn` returns a **view**, not the raw entity handle. The raw handle stays server-side; consumers reach the entity through `netId`.

```lua theme={null}
{
    id      = 'entity:...',   -- bridge registry id (use with Despawn / Get)
    netId   = 42,             -- network id (use on clients)
    kind    = 'vehicle',
    model   = -1234567,       -- resolved hash
    owner   = 3,
    purpose = 'garage',
    meta    = { plate = 'ATLAS01' },
}
```

## Track & retrieve

```lua theme={null}
local byId  = Bridge.Entities.Get(id)            -- view by registry id
local byNet = Bridge.Entities.GetByNet(netId)    -- view by network id
```

| Method                            | Returns                               |
| --------------------------------- | ------------------------------------- |
| `Bridge.Entities.Get(id)`         | The view for a registry id, or `nil`. |
| `Bridge.Entities.GetByNet(netId)` | The view for a network id, or `nil`.  |

## Despawn & cleanup

```lua theme={null}
Bridge.Entities.Despawn(id)            -- delete one tracked entity
Bridge.Entities.ReleaseOwner(src)      -- delete all of a player's entities
```

Cleanup is **automatic** for owned entities: when a player disconnects, every entity spawned with `owner = src` is despawned for you. You only call `ReleaseOwner` if you want to drop a player's entities early (e.g. on a job change).

| Method                              | Effect                                             |
| ----------------------------------- | -------------------------------------------------- |
| `Bridge.Entities.Despawn(id)`       | Delete the entity and remove it from the registry. |
| `Bridge.Entities.ReleaseOwner(src)` | Despawn every entity owned by `src`.               |

<Note>
  Auto-cleanup on disconnect runs regardless — `ReleaseOwner` is only for releasing early. An entity spawned without an `owner` is tracked but is never auto-deleted; despawn it yourself.
</Note>

## Protected statebags

Attach tamper-revert state to any networked entity. If a client edits the statebag, the bridge reverts it to your value — use it for server-authoritative entity data (fuel, lock state, ownership).

```lua theme={null}
Bridge.Entities.ProtectState(netId, 'fuel', 100.0)
Bridge.Entities.ClearState(netId, 'fuel')
```

| Method                                            | Effect                                            |
| ------------------------------------------------- | ------------------------------------------------- |
| `Bridge.Entities.ProtectState(netId, key, value)` | Set a tamper-revert statebag value on the entity. |
| `Bridge.Entities.ClearState(netId, key)`          | Remove a protected statebag value.                |

## Attach props to a player

Attach (and later clear) decorative props on a player ped — handled server-side so every client sees them.

```lua theme={null}
Bridge.Entities.AttachProps(src, {
    { model = 'p_amb_clipboard_01', bone = 18905,
      pos = { x = 0.0, y = 0.0, z = 0.0 }, rot = { x = 0.0, y = 0.0, z = 0.0 } },
})
Bridge.Entities.ClearProps(src)
```

## Request-then-spawn pattern

The full secure flow: client requests, server validates, server spawns, client gets the `netId` to use.

```lua theme={null}
-- client
RegisterCommand('mycar', function()
    Bridge.Net.Emit('vehicles:request', { model = 'adder' })
end, false)

Bridge.Net.On('vehicles:spawned', function(netId)
    local timeout = GetGameTimer() + 5000
    while not NetworkDoesNetworkIdExist(netId) and GetGameTimer() < timeout do Wait(0) end
    if NetworkDoesNetworkIdExist(netId) then
        SetPedIntoVehicle(PlayerPedId(), NetworkGetEntityFromNetworkId(netId), -1)
    end
end)
```

```lua theme={null}
-- server
local ALLOWED = { adder = true, sultanrs = true }

Bridge.Net.On('vehicles:request', {
    payload   = Bridge.Validate.obj({ model = Bridge.Validate.str() }),
    rateLimit = { windowMs = 5000, maxHits = 1 },
    handle = function(src, data)
        if not ALLOWED[data.model:lower()] then return end   -- whitelist server-side

        local ped = GetPlayerPed(src)
        local c = GetEntityCoords(ped)
        local view = Bridge.Entities.Spawn({
            kind = 'vehicle', model = data.model, owner = src,
            coords = vec4(c.x + 2.0, c.y, c.z, GetEntityHeading(ped)),
        })
        if view then
            Bridge.Net.Emit('vehicles:spawned', src, view.netId)
        end
    end,
})
```

<CardGroup cols={2}>
  <Card title="Networking" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/plug-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=523bca8bdf53a69adf80f6699df734b4" href="/atlas-bridge/developer/networking" width="24" height="24" data-path="icons/plug-filled.svg">
    Validate and rate-limit the spawn request before you act on it.
  </Card>

  <Card title="World" icon="https://mintcdn.com/atlasscripts/BwePy2Q7bMLnl0yQ/icons/box-filled.svg?fit=max&auto=format&n=BwePy2Q7bMLnl0yQ&q=85&s=c228a3b89453b292c0cedb29c252b3ab" href="/atlas-bridge/developer/world" width="24" height="24" data-path="icons/box-filled.svg">
    Interaction prompts, zones, and blips for the entities you spawn.
  </Card>
</CardGroup>