docs: present Shacraft Core and its documentation in English

docs/PACKAGES.md

@@ -1,17 +1,17 @@
-# Единые пакеты расширений
+# Unified extension packages
 
-`packages/<directory>/manifest.json` объявляет точные версии, лицензии, зависимости, возможности и ресурсы. При запуске сервер проверяет весь граф зависимостей, размеры, SHA-256, пути и отсутствие symlink. Отсутствующая версия, цикл, неизвестная возможность или изменённый ресурс останавливают запуск. Публикуются только `client` и `common`; файлы `server` не имеют публичного маршрута. Ресурс повторно проверяется при HTTP-чтении.
+`packages/<directory>/manifest.json` declares exact versions, licenses, dependencies, capabilities, and resources. At startup, the server verifies the entire dependency graph, sizes, SHA-256 hashes, paths, and absence of symlinks. A missing version, cycle, unknown capability, or modified resource prevents startup. Only `client` and `common` resources are published; `server` files have no public route. Resources are verified again when read over HTTP.
 
-Примеры — `packages/base` и `packages/trampoline`. Все изображения, звук и модели авторские. Данные каталога происходят из официальных отчётов и измерения публичного API Java 26.2; ванильные текстуры и модели в пакеты не входят.
+Examples are provided in `packages/base` and `packages/trampoline`. All images, audio, and models are original. Catalog data comes from official reports and measurements through the public Java 26.2 API; packages contain no vanilla textures or models.
 
-Манифест schema 1 содержит:
+A schema 1 manifest contains:
 
-- `id`, `version` из трёх числовых частей, `license`;
-- `dependencies:[{id,version}]` с точными версиями;
-- `capabilities`, например `blocks.define`, `client.texture`, `server.on_jump`;
+- `id`, a `version` with three numeric components, and `license`;
+- `dependencies:[{id,version}]` with exact versions;
+- `capabilities`, such as `blocks.define`, `client.texture`, and `server.on_jump`;
 - `resources:[{path,scope,role,sha256,size}]`.
 
-Один ресурс не больше 16 МиБ; пакет не больше 64 МиБ, до 128 ресурсов, до 128 записей в каталоге пакетов. Это ограничения сервера; браузер дополнительно ограничивает суммарно проверяемые публичные ресурсы 128 МиБ на подключение. Определения блоков имеют роль `definitions`, ресурс с этой ролью требует schema 1. Сервер допускает до 4096 дополнительных определений. Блок задаёт `state` как новый идентификатор `namespace:path` без свойств (строчные ASCII-буквы, цифры, `_`, `.`, `-`, дополнительно `/` в path), `color:[r,g,b]`, `collision:[{min,max}]` и необязательный `render` аналогичной формы. Необязательный `opacity` — число 0…1. Если render не указан, используется существующая авторская форма того же состояния или коллизия нового блока. Максимум 64 бокса на каждый набор; допустимый локальный диапазон координат −2…3. Дубликаты определений и переопределение `minecraft:*` отвергаются. Runtime ID назначает сохраняемый реестр; `Game::open` расширяет каталог проверенными определениями до регистрации в WorldStore. Обычный пакетный блок без `behavior` хранится и участвует в физике; `behavior.server_hook: on_jump` связывает его с активным WASM-провайдером.
+Each resource is limited to 16 MiB; a package to 64 MiB and 128 resources; the package directory to 128 entries. These are server limits; the browser additionally limits the total verified public resources to 128 MiB per connection. Block definitions use the `definitions` role, and a resource with this role requires schema 1. The server allows up to 4096 additional definitions. A block specifies `state` as a new `namespace:path` identifier without properties (lowercase ASCII letters, digits, `_`, `.`, and `-`, plus `/` in the path), `color:[r,g,b]`, `collision:[{min,max}]`, and an optional `render` of the same form. Optional `opacity` is a number from 0…1. If render is omitted, the existing original shape for that state is used, or the collision shape for a new block. Each set may contain at most 64 boxes; the allowed local coordinate range is −2…3. Duplicate definitions and overrides of `minecraft:*` are rejected. The persistent registry assigns runtime IDs; `Game::open` extends the catalog with verified definitions before registering them in WorldStore. An ordinary package block without `behavior` is stored and participates in physics; `behavior.server_hook: on_jump` binds it to the active WASM provider.
 
 ```json
 {
@@ -26,18 +26,18 @@
 }
 ```
 
-## Исполнение модуля
+## Module execution
 
-В MVP нужен ровно один активный провайдер серверного hook `on_jump`; отсутствие провайдера или два модуля с этой ролью останавливают запуск. Серверный `.wasm` объявляется ресурсом `role: "wasm-on-jump"`, `scope: "server"`; необходима capability `server.on_jump`. Экспорт `on_jump: () -> f32` возвращает импульс прыжка в блоках/с. Сервер вызывает его только при прыжке игрока с блока, который связан с hook через проверенное определение пакета.
+The MVP requires exactly one active provider for the `on_jump` server hook; no provider or two modules with this role prevents startup. A server `.wasm` file is declared as a resource with `role: "wasm-on-jump"` and `scope: "server"`; the `server.on_jump` capability is required. The export `on_jump: () -> f32` returns a jump impulse in blocks/s. The server calls it only when a player jumps from a block bound to the hook through a verified package definition.
 
-Исполнение идёт в Wasmi: без импортов, файлов, сети и системных вызовов; до 10 000 единиц fuel на вызов, одна память до 64 КиБ, одна таблица до 128 элементов, один экземпляр. Бинарный модуль не больше 64 КиБ. Результат должен быть конечным числом 0…20; trap или недопустимое значение фиксируется метрикой и даёт обычный прыжок. Выполняемый пример возвращает 10. Тесты проверяют реальный вызов, бесконечный цикл, превышение памяти, попытку импорта и NaN. Отдельный тест создаёт пакет `example:spring`, проверяет его SHA-256, добавляет новый блок в каталог, регистрирует и сохраняет runtime ID, связывает блок с модулем и получает импульс 12 от собственного бинарного WASM. Дубликаты, Minecraft override, недопустимая геометрия, opacity/идентификатор и изменение ресурса после загрузки отвергаются.
+Execution uses Wasmi with no imports, files, network access, or system calls; at most 10,000 fuel units per call, one memory up to 64 KiB, one table up to 128 elements, and one instance. The binary module is limited to 64 KiB. The result must be a finite number from 0…20; a trap or invalid value is recorded in a metric and falls back to a normal jump. The working example returns 10. Tests cover an actual invocation, an infinite loop, excessive memory, an attempted import, and NaN. A separate test creates an `example:spring` package, verifies its SHA-256, adds a new block to the catalog, registers and persists its runtime ID, binds the block to the module, and receives an impulse of 12 from its own binary WASM module. Duplicates, Minecraft overrides, invalid geometry, opacity/identifiers, and resource changes after loading are rejected.
 
-Это ограниченный действующий API расширения, а не обещание произвольной совместимости с Forge/Fabric или доступа WASM к полному состоянию мира. Для нового hook необходима явная версия контракта. Spleef в этом MVP реализован серверным режимом Rust с сохраняемыми правилами.
+This is a limited, working extension API, with no claim of arbitrary Forge/Fabric compatibility or WASM access to full world state. A new hook requires an explicit contract version. Spleef in this MVP is implemented as a Rust server mode with persistent rules.
 
-## Клиентские ресурсы
+## Client resources
 
-`/api/manifest` возвращает публичный список с URL, точной версией, размерами и SHA-256. Браузер скачивает файлы, проверяет размер и хеш **до входа**, затем кладёт в CacheStorage по хешу. При повторном подключении содержимое кэша тоже проверяется. Ошибка хеша удаляет повреждённую запись и запрещает вход. Неподходящий `manifest_hash` сервер отвергает. Публичный хеш не подтверждает, что клиентское приложение не модифицировано.
+`/api/manifest` returns the public list with URLs, exact versions, sizes, and SHA-256 hashes. The browser downloads files, verifies their sizes and hashes **before joining**, then stores them in CacheStorage keyed by hash. Cached contents are verified again on subsequent connections. A hash error removes the corrupted entry and prevents joining. The server rejects a mismatched `manifest_hash`. A public hash does not prove that the client application is unmodified.
 
-Базовый пакет даёт пиксельную текстуру; trampoline — собственную текстуру, GLSL-функцию окраски, настройку стиля и короткий синтезированный звук. Они применяются собственным WebGL2-рендерером. В ядре и сервере отсутствует графический движок. Пакет не загружает произвольный привилегированный JavaScript.
+The base package provides a pixel texture; the trampoline provides its own texture, a GLSL color function, style settings, and a short synthesized sound. The custom WebGL2 renderer applies them. The core and server contain no graphics engine. Packages do not load arbitrary privileged JavaScript.
 
-Для изменения пакета пересчитайте размер и SHA-256 каждого изменённого ресурса, увеличьте версию и обновите точные зависимости. `scripts/catalog_assets.py` воспроизводимо генерирует встроенные авторские ресурсы и манифесты. Формат ориентирован на будущий лаунчер: лаунчер сможет получить тот же manifest и кэшировать по `(id,version,sha256)`; интеграция конкретного лаунчера в этот репозиторий не входит.
+When modifying a package, recalculate the size and SHA-256 of each changed resource, increase the version, and update exact dependencies. `scripts/catalog_assets.py` reproducibly generates the bundled original resources and manifests. The format is designed for a future launcher: it can consume the same manifest and cache by `(id,version,sha256)`; integration with a specific launcher is outside this repository's scope.