> ## 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.

# Networking

> Protected client↔server events and callbacks with Bridge.Net, plus payload validation with Bridge.Validate.

`Bridge.Net` replaces raw `RegisterNetEvent` / `TriggerServerEvent`. Logical event names are scrambled on the wire and regenerated every restart, and every client→server call carries a single-use, event-bound proof — so executors cannot guess or replay your events. You just use the readable names.

On top of that, every handler can declare a payload **validator**, a **rate limit**, and a **permission** node. Validation and rate limiting run before your handler executes.

## Server handlers

### Bridge.Net.On

Register a fire-and-forget handler for client→server events.

```lua theme={null}
Bridge.Net.On('shop:buy', {
    handle = function(src, data)
        grantItem(src, data.item)
    end,
    payload = Bridge.Validate.obj({ item = Bridge.Validate.str() }),  -- optional, runs first
    rateLimit = { windowMs = 1000, maxHits = 5 },                     -- optional
    permission = 'shop.use',                                          -- optional
})
```

| Field        | Type                    | Notes                                                     |
| ------------ | ----------------------- | --------------------------------------------------------- |
| `handle`     | `fun(src, data)`        | Required. `src` is verified; `data` is validated.         |
| `payload`    | validator               | Optional. Rejects the call if the payload does not match. |
| `rateLimit`  | `{ windowMs, maxHits }` | Optional per-event guard.                                 |
| `permission` | `string`                | Optional permission node the caller must hold.            |

### Bridge.Net.OnCallback

Register a request/response handler. Return a single value (or `value` plus an error handled by your own convention).

```lua theme={null}
Bridge.Net.OnCallback('bank:balance', {
    handle = function(src, data)
        return getBalance(src)
    end,
})
```

### Emitting to clients

```lua theme={null}
Bridge.Net.Emit('shop:opened', src, { stock = stock })   -- to one player
Bridge.Net.EmitAll('event:started', {})                  -- to everyone
```

## Client handlers

```lua theme={null}
-- subscribe to a server emit; the return value unsubscribes
local off = Bridge.Net.On('shop:opened', function(data)
    openUI(data.stock)
end)
off()

-- fire-and-forget to the server
Bridge.Net.Emit('shop:buy', { item = 'water' })
```

### Callbacks (blocking)

`Bridge.Net.Callback` blocks until the server responds, so it must run inside a thread.

```lua theme={null}
CreateThread(function()
    local balance, err = Bridge.Net.Callback('bank:balance', {}, 10000)  -- payload, timeout ms
    if err then return end
    updateUI(balance)
end)
```

<Warning>
  `Bridge.Net.Callback` yields. Always call it inside a `CreateThread` or a command/event callback — never at file top level.
</Warning>

## Validation

`Bridge.Validate` builds composable validators. Use them as the `payload` of a net handler, or call them directly to guard any untrusted input.

```lua theme={null}
local schema = Bridge.Validate.obj({
    spot   = Bridge.Validate.int({ min = 0, max = 20 }),
    note   = Bridge.Validate.optional(Bridge.Validate.str()),
    tags   = Bridge.Validate.array(Bridge.Validate.str()),
})
```

| Builder                         | Validates                            |
| ------------------------------- | ------------------------------------ |
| `Bridge.Validate.number(opts?)` | A number (optional `min` / `max`).   |
| `Bridge.Validate.int(opts?)`    | An integer (optional `min` / `max`). |
| `Bridge.Validate.str(opts?)`    | A string.                            |
| `Bridge.Validate.bool()`        | A boolean.                           |
| `Bridge.Validate.enum(values)`  | One of a fixed set.                  |
| `Bridge.Validate.optional(v)`   | `nil` or a value matching `v`.       |
| `Bridge.Validate.array(v)`      | A list whose entries match `v`.      |
| `Bridge.Validate.obj(shape)`    | A table matching the field shape.    |

<Tip>
  Validate every client→server payload. The net layer enforces the proof and rate limit, but only your validator guarantees the **shape** of the data your handler trusts.
</Tip>