> For the complete documentation index, see [llms.txt](https://wiki.holyworld.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.holyworld.me/lite/api/protocol.md).

# In-Game API

Документация для разработчиков клиентских модов.

Пример реализации на Fabric: [liteapi-fabric-example](https://github.com/HolyWorldMC/liteapi-fabric-example)

***

## Модули

| Модуль          | Канал                     | Документация                            |
| --------------- | ------------------------- | --------------------------------------- |
| Feature Control | `liteapi:feature-control` | [feature-control](/lite/api/feature.md) |

***

## Транспорт

Весь обмен данными происходит через [**Minecraft Plugin Messaging Channels**](https://minecraft.wiki/w/Plugin_channels):

* Клиент отправляет [Serverbound Plugin Message (play)](https://minecraft.wiki/w/Java_Edition_protocol/Packets#Serverbound_Plugin_Message_\(configuration\)) пакет на именованный канал.
* Сервер отвечает [Clientbound Plugin Message (play)](https://minecraft.wiki/w/Java_Edition_protocol/Packets#Clientbound_Plugin_Message_\(play\)) пакетом на тот же канал.
* Содержимое пакета — строка **UTF-8 JSON**.

Каждый модуль LiteAPI имеет свой канал, например `liteapi:feature-control`. Канал указан в документации конкретного модуля.

***

## Формат пакетов

### Запрос (клиент → сервер)

```json
{
  "id":      "<UUID запроса>",
  "method":  "<название метода>",
  "payload": { ... }
}
```

| Поле      | Тип      | Обязательно | Описание                                                                                                           |
| --------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`      | `string` | да          | UUID запроса. Сервер вернёт его в ответе — по нему вы поймёте, на какой именно запрос пришёл ответ.                |
| `method`  | `string` | да          | Название метода, который нужно вызвать.                                                                            |
| `payload` | `object` | нет         | Параметры запроса. Если отсутствует или `null` — считается пустым объектом. Не может быть массивом или примитивом. |

### Ответ — успех (сервер → клиент)

```json
{
  "id":      "<UUID запроса>",
  "ok":      true,
  "payload": { ... }
}
```

### Ответ — ошибка (сервер → клиент)

```json
{
  "id":      "<UUID запроса>",
  "ok":      false,
  "error":   "<код ошибки>",
  "message": "<описание, может отсутствовать>"
}
```

### Push-событие (сервер → клиент, без запроса)

```json
{
  "event":   "<название события>",
  "payload": { ... }
}
```

Push-события не имеют `id` и `ok` — они не являются ответами на запросы.

***

## Коды ошибок

| `error`          | Когда возникает                                                           |
| ---------------- | ------------------------------------------------------------------------- |
| `BAD_REQUEST`    | Пакет невалидный: не JSON, нет поля `id` или `method`, неверный `payload` |
| `NOT_FOUND`      | Метод с таким именем не существует                                        |
| `RATE_LIMITED`   | Превышен лимит запросов                                                   |
| `INTERNAL_ERROR` | Непредвиденная ошибка на сервере (детали не раскрываются)                 |

Поле `message` присутствует не всегда: при `INTERNAL_ERROR` его нет намеренно.

***

## Rate limiting

Лимиты настраиваются отдельно для каждого метода и указаны в документации модуля. При превышении сервер отвечает `RATE_LIMITED` и игнорирует запрос. Лимит считается **per player**.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.holyworld.me/lite/api/protocol.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.