> ## Documentation Index
> Fetch the complete documentation index at: https://cs-lua.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# hook — Пространство имён

> Одна система на движковые события и на свои

# Пространство имён

<h2 id="add">
  hook.add
</h2>

Подписывает функцию на событие.

```lua theme={null}
hook.add(event, id, fn)
```

### Аргументы

| # | имя     | тип      |                                           |
| - | ------- | -------- | ----------------------------------------- |
| 1 | `event` | string   | имя события; своё обязано содержать точку |
| 2 | `id`    | string   | уникален внутри этого плагина             |
| 3 | `fn`    | function | получает объект события                   |

### Возвращает

Ничего.

### Пример

```lua theme={null}
hook.add("player:spawn", "myplugin.armor", function(e)
	e.player:armor(100)
end)
```

Повторная регистрация той же пары `(event, id)` **заменяет** обработчик. Это то,
что не даёт `lua_reload <plugin>` удвоить подписки.

Id уникален внутри плагина — два разных плагина спокойно называют свои `"init"`.

### Приём сетевых сообщений — `msg:Name`

Особый вид имени, без точки: `hook.add("msg:TextMsg", id, fn)` подписывается
на сетевые сообщения, которые движок отправляет клиентам — приёмная сторона
к [`msg.send`](../msg/send.md#send). Свои подробности — у [`msg`](../msg/index.md).

### Порядок вызова

Обработчики идут в порядке загрузки плагинов. Обычно это неважно, но на
отменяемом событии решает, кто выиграет: `e:cancel()` обрывает цепочку.

Числа приоритета в `hook.add` тут не помогли бы: как только их начнут ставить
все, они снова перестанут что-либо значить. Порядком распоряжается владелец
сервера — через `addons/lua/load_order.txt`:

```
# грузятся первыми и в этом порядке
godmode
damager
stats
```

Всё, чего в файле нет, идёт после по алфавиту, поэтому список не обязан быть
полным. Текущий порядок видно в [`lua_list`](../console.md) и
[`lua_hooks`](../console.md).

<Warning>
  Неизвестное имя без точки и без `msg:` — ошибка со списком
  движковых событий. Так ловится опечатка, которая иначе дала бы
  молча неработающую подписку.
</Warning>

### Смотри также

* [hook.remove](namespace.md#remove)
* [msg.send](../msg/send.md#send)
* [lua\_hooks](../console.md)

<h2 id="remove">
  hook.remove
</h2>

Снимает подписку по имени события и id.

```lua theme={null}
hook.remove(event, id)
```

### Аргументы

| # | имя     | тип    |                               |
| - | ------- | ------ | ----------------------------- |
| 1 | `event` | string | имя события                   |
| 2 | `id`    | string | id, под которым подписывались |

### Возвращает

| тип       |                             |
| --------- | --------------------------- |
| `boolean` | `true`, если обработчик был |

Снимает только собственный обработчик плагина: один плагин не может тихо отписать чужой.

<h2 id="run">
  hook.run
</h2>

Запускает своё событие плагина.

```lua theme={null}
hook.run(event[, data])
```

### Аргументы

| # | имя     | тип          |                             |
| - | ------- | ------------ | --------------------------- |
| 1 | `event` | string       | имя, обязательно с точкой   |
| 2 | `data`  | table \| nil | становится объектом события |

### Возвращает

| тип     |                                           |
| ------- | ----------------------------------------- |
| `table` | та же таблица — из неё читается результат |

### Пример

```lua theme={null}
local e = hook.run("shop.buying", { player = p, item = item })
if e.cancelled then return end
```

Точка в имени обязательна: она отличает своё событие от опечатки в движковом.

Движковое событие через `hook.run` запустить нельзя — это делает модуль.

### Смотри также

* [export / import](../exports/index.md)

<h2 id="list">
  hook.list
</h2>

Возвращает список подписок в порядке вызова.

```lua theme={null}
hook.list([event])
```

### Аргументы

| # | имя     | тип           |                          |
| - | ------- | ------------- | ------------------------ |
| 1 | `event` | string \| nil | только по одному событию |

### Возвращает

| тип     |                                        |
| ------- | -------------------------------------- |
| `table` | массив `{ event = , id = , plugin = }` |

Консольная обёртка — [`lua_hooks`](../console.md).