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

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

> Поиск игроков, рассылка и объект игрока

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

<h2 id="get">
  players.get
</h2>

Возвращает игрока по номеру слота.

```lua theme={null}
players.get(id)
```

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

| # | имя  | тип    |                    |
| - | ---- | ------ | ------------------ |
| 1 | `id` | number | номер слота, 1..32 |

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

| тип             |                       |
| --------------- | --------------------- |
| `player \| nil` | `nil`, если слот пуст |

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

Возвращает массив подключённых игроков.

```lua theme={null}
players.list([filter])
```

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

| # | имя      | тип          |                            |
| - | -------- | ------------ | -------------------------- |
| 1 | `filter` | table \| nil | см. [Фильтр](#list-фильтр) |

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

| тип     |                         |
| ------- | ----------------------- |
| `table` | массив объектов игроков |

<h3 id="list-фильтр">
  Фильтр
</h3>

| поле    | тип     |                                                  |
| ------- | ------- | ------------------------------------------------ |
| `alive` | boolean | только живые или только мёртвые                  |
| `team`  | string  | `CT`, `T`, `SPEC`                                |
| `bot`   | boolean | серверные боты (`FL_FAKECLIENT`) или только люди |
| `hltv`  | boolean | HLTV-прокси (`FL_PROXY`) или без них             |
| `name`  | string  | подстрока ника, регистр не важен                 |

### Пример

```lua theme={null}
for _, p in ipairs(players.list{ alive = true, team = "CT" }) do
	p:chat("живой контр")
end

-- люди, не боты, с «kot» в нике
for _, p in ipairs(players.list{ bot = false, name = "kot" }) do
	print(p:name())
end
```

<Warning>
  `alive` и `team` читают живое CS-состояние и требуют ReGameDLL.
  `bot`, `hltv` и `name` работают и на ванильном `mp.dll`.
  Без любого фильтра метод работает везде.
</Warning>

Права и группы (`p:can`, `p:group`) живут в core-слое, не в native.
Их удобнее дописать в Lua:

```lua theme={null}
for _, p in ipairs(players.list{ alive = true }) do
	if p:can("admin.slay") and not p:group("vip") then
		-- ...
	end
end
```

<h2 id="find">
  players.find
</h2>

Ищет игрока по слоту, userid или части ника.

```lua theme={null}
players.find(token)
```

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

| # | имя     | тип    |                              |
| - | ------- | ------ | ---------------------------- |
| 1 | `token` | string | см. [Форматы](#find-форматы) |

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

| тип             |                         |
| --------------- | ----------------------- |
| `player \| nil` | найденный игрок         |
| `string`        | причина, если не найден |

<h3 id="find-форматы">
  Форматы
</h3>

| поле      | тип    |                                                           |
| --------- | ------ | --------------------------------------------------------- |
| `"3"`     | string | номер слота                                               |
| `"#12"`   | string | userid                                                    |
| `"kotya"` | string | часть ника, регистр не важен; совпадение должно быть одно |

### Пример

```lua theme={null}
local target, why = players.find(ctx.args[1])
if not target then
	return ctx.reply(why)
end
```

Тот же поиск делает `opts.target` в [`cmd.add`](../cmd/index.md#add).

<h2 id="broadcast">
  players.broadcast
</h2>

Приёмник «всем сразу»: только отправка сообщений.

```lua theme={null}
players.broadcast:chat(text[, opts])
```

### Пример

```lua theme={null}
players.broadcast:chat("{green}[Server]{default} раунд начался")
players.broadcast:play_sound("items/9mmclip1.wav")
```

Понимает те же методы отправки, что и обычный игрок:
[`chat`](messages.md#chat), [`console`](messages.md#console), [`center`](messages.md#center),
[`hud`](messages.md#hud), [`dhud`](messages.md#dhud), [`play_sound`](messages.md#play_sound).

`play_sound` тут — один `EMIT_SOUND` от первого подключённого игрока, а не
цикл по всем: `EMIT_SOUND` и так слышен всем, у кого PAS накрывает точку
излучения, повторять его на каждого — значит дать части слушателей услышать
один и тот же клип по два-три раза подряд.

<Warning>
  Состояния у него нет: `players.broadcast:alive()` бросает ошибку
  с объяснением. Для чтения и записи состояния перебирай
  `players.list()`.
</Warning>

<h2 id="method">
  players.method
</h2>

Добавляет свой метод всем объектам игроков.

```lua theme={null}
players.method(name, fn)
```

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

| # | имя    | тип      |                        |
| - | ------ | -------- | ---------------------- |
| 1 | `name` | string   | имя метода             |
| 2 | `fn`   | function | получает `(self, ...)` |

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

Ничего.

### Пример

```lua theme={null}
players.method("playtime", function(self)
	return sessions[self.id] and sessions[self.id]:seconds() or 0
end)
```

<Warning>
  Занятое имя переопределить нельзя — это то, что не даёт одному
  плагину подменить `p:health()` для всех остальных.
</Warning>