Игроки

Всё про игроков вашего сервера — список, кто сейчас в игре, полный профиль (статы, навыки, базы, транспорт, выживание), инвентарь и статус модерации. Отдельный скоуп открывает историю нарушений и IP-данные.

Как указать игрока

Каждый пер-игроковый эндпоинт принимает сегмент {ref}, который понимает любой из двух идентификаторов:

• Steam64 — 76561198000000000
• Discord-id с префиксом — discord:123456789012345678

GET /v1/players/76561198000000000
GET /v1/players/discord:123456789012345678

Steam64 — канонический неизменяемый ключ. Сам Discord-id стабилен, а изменяться может его привязка к игроку, поэтому discord:-ссылка резолвится в текущего привязанного игрока в момент запроса (404 not_found, если действующей привязки нет). Искать игрока можно и на эндпоинте списка через ?steam_id= или ?discord_id=.

Авторизация

steam_id и discord_id возвращаются в ответах списка и профиля под базовым players:read; живой снимок (/players/online) несёт только steam_id. Ключ без нужного скоупа получает 403 insufficient_scope.

GET /v1/players

Список игроков с пагинацией. Опциональные фильтры:

Возвращает конверт-коллекцию:

{
  "data": [
    {
      "steam_id": "76561198000000000",
      "discord_id": "123456789012345678",
      "user_profile_id": 7,
      "steam_name": "Bob",
      "char_name": "Bobby",
      "online": true,
      "squad": { "id": 4, "name": "Alpha", "rank": 1 },
      "money": 500, "gold": 3, "coins": 9, "fame_points": 12.5,
      "attributes": { "strength": 2.35, "constitution": 3.1, "dexterity": 4, "intelligence": 5.25 },
      "play_time": 3600, "is_admin": false,
      "last_seen": "2024-01-01 12:00:00", "created_at": "2023-01-01 10:00:00"
    }
  ],
  "total": 1,
  "has_more": false,
  "next_cursor": null
}

total — число игроков, подходящих под запрос (по всем страницам).

GET /v1/players/online

Живой снимок всех, кто сейчас онлайн — позиции, пинг, стойка, актуальная валюта. Отфильтровать до одного игрока: ?steam_id= или ?discord_id=. Без пагинации (онлайн-набор ограничен); отдаётся с коротким max-age, чтобы поллер не долбил игровой сервер.

{
  "online": 1,
  "data": [
    {
      "steam_id": "76561198000000000", "name": "Bob", "ping": 30,
      "position": { "x": 1, "y": 2, "z": 3 },
      "alive": true, "conscious": true, "immortal": false, "super_jump": false,
      "is_admin": false, "money": 0, "gold": 0, "fame_points": 0,
      "stance": "stand", "item_in_hands": null
    }
  ]
}

GET /v1/players/{ref}

Полный профиль: всё из строки списка плюс warden_stats (убийства, смерти, серии, тоталы, серия входов, таймстемпы), skills, bases, vehicles и типизированный блок survival. money — это баланс банка игрока.

GET /v1/players/{ref}/inventory

Полный вложенный инвентарь игрока — каждый предмет может нести contents (рекурсивно) для контейнеров. Поддерево, которое мод перестал раскрывать на пределе глубины, помечается contents_truncated: true.

{ "items": [ { "id": 1, "class": "Weapon", "name": "Rifle", "icon": "…", "health": 100, "max_health": 100, "weight": 3.5, "is_container": false, "is_weapon": true, "contents_truncated": false, "contents": [] } ] }

GET /v1/players/{ref}/moderation

Текущий статус бана и мьюта. player (субъект) и banned_by (модератор) — identity-объекты с steam_id и discord_id; discord_id равен null, если человек не привязан к Discord. banned_by равен null, когда игрок не забанен; у устаревшей/системной записи без Steam-id модератора его метка выходит как name (при steam_id: null).

{
  "player": { "steam_id": "76561198000000000", "discord_id": "123456789012345678" },
  "ban": { "banned": true, "reason": "cheating", "permanent": false, "expires_at": "2023-11-14T22:13:20.000Z", "banned_at": "2023-11-03T…", "banned_by": { "steam_id": "76561198000000001", "discord_id": "223…", "name": null } },
  "mute": { "muted": false, "permanent": false, "muted_at": null, "duration_minutes": null, "channels": [] }
}

Чтобы изменить статус бана/мьюта, см. Модерация (players:ban / players:mute).

GET /v1/players/{ref}/violations

Требует players:read_sensitive. Пагинированная история нарушений (баны, мьюты и события ловушек), сначала новые, с указанием модератора. Пагинация через limit (1–100) и cursor. Никогда не кешируется (Cache-Control: private, no-store). issued_by — identity-объект с steam_id модератора, discord_id (null, если не привязан) и name.

{
  "data": [ { "id": 11, "type": "ban", "action": "applied", "source": "mod", "reason": "…", "issued_by": { "steam_id": "76561198000000001", "discord_id": "223…", "name": "Admin" }, "applied_at": "2023-11-03T…", "expires_at": "2023-11-14T…", "duration_sec": 3600, "metadata": { "channel": "Global" } } ],
  "has_more": false,
  "next_cursor": null
}

GET /v1/players/{ref}/ips

Требует players:read_sensitive. История IP игрока, сначала новые; current_ip — самый свежий. Никогда не кешируется.

{ "current_ip": "…", "history": [ { "ip": "…", "first_seen": "2023-11-03T…", "last_seen": "2023-11-14T…" } ] }

Кеширование

Список, живой снимок, профиль, инвентарь и модерация отдают ETag и короткий Cache-Control: private, max-age; пришлите ETag обратно как If-None-Match, чтобы получить 304 Not Modified (ETag живого снимка совпадает, если в его окне ничего не сдвинулось). Чувствительные чтения (/violations, /ips) — no-store.

Ошибки

Стандартный конверт ошибки. Самые вероятные: