Emil_Shanaty/shacraft-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: present Shacraft Core and its documentation in English

Browse Source
This commit is contained in:
Emil
2026-09-14 17:58:30 +03:00
parent b6ba064339
commit 26748912c6
18 changed files with 643 additions and 620 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+51 -26
View File
@@ -1,60 +1,85 @@
# Shacraft Core
Самостоятельный открытый воксельный движок на Rust и работающий локальный MVP: сервер с несколькими мирами, собственный WebGL2-клиент, Spleef, отдельный MCP, каталог Java 26.2, пакеты расширений и конвертер миров. Приоритет — измеренное потребление **серверной RAM**.
[![MVP checks](https://github.com/emil28092005/shacraft-core/actions/workflows/ci.yml/badge.svg)](https://github.com/emil28092005/shacraft-core/actions/workflows/ci.yml)
## Запустить
An independent, open-source voxel engine written in Rust. The local MVP includes an authoritative multiplayer server, a custom WebGL2 client, Spleef arenas, an MCP server, content packages, and Minecraft world import/export. The main engineering priority is **measured server memory use**.
Требуются Rust 1.96+, C-компилятор для SQLite и браузер с WebGL2. Java и Node для игры не нужны. Первый запуск скачает Cargo-зависимости и соберёт release; следующие используют готовый бинарный файл.
> NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.
Minecraft is mentioned to identify compatibility targets and data sources. Minecraft names, brands, and assets remain the property of their respective owners. See the [Minecraft Usage Guidelines](https://www.minecraft.net/en-us/usage-guidelines).
## Quick start
You need Rust 1.96+, a C compiler for bundled SQLite, and a browser with WebGL2. Java and Node.js are not required to play. The first run downloads Cargo dependencies and builds the release binaries; subsequent runs use the existing binaries.
```bash
git clone https://github.com/emil28092005/shacraft-core.git
cd shacraft-core
bash scripts/run.sh --data data --listen 127.0.0.1:4000
```
Открыть **http://127.0.0.1:4000**. WASD — движение, пробел — прыжок, мышь — обзор, ЛКМ/ПКМ — убрать/поставить блок, E — библиотека, T — чат, F3 — диагностика. Если браузер не даёт захват мыши, обзор работает перетаскиванием. Мир выбирается слева сверху. Для Spleef два игрока входят в одну арену и запускают матч через меню. Лобби, галерея всех типов блоков и две арены создаются автоматически.
Open **http://127.0.0.1:4000**. The server creates a lobby, a block gallery, and two Spleef arenas automatically. The MVP client currently uses Russian interface text.
Вся работа хранится в `--data`. Для остановки используйте Ctrl+C. Подтверждённые правки сохраняются до ответа сервера; проверены аварийные остановки и восстановление.
- **WASD** to move, **Space** to jump, and the mouse to look around. Drag to look if pointer lock is unavailable.
- **Left/right click** to remove/place a block; **E** for the material library, **T** for chat, and **F3** for diagnostics.
- Select a world in the upper-left corner. To play Spleef, two players join the same arena and start a match from the menu.
## Что входит
World data is stored under `--data`. Stop the server with Ctrl+C. Acknowledged block edits are persisted before the server responds; crash recovery is covered by automated checks.
- `shacraft-core`: компактные секции 16³, общий ограниченный кэш, SQLite/WAL/FULL, неизменяемые снимки, независимые изменения миров, ревизии, идемпотентные правки, undo/reset. Без графики и сети.
- `shacraft-server`: авторитетные движение, формы столкновений и взаимодействия, WebSocket/HTTP, сохраняемые сущности и настройки, законченный цикл Spleef.
- `client/`: собственный рендерер, библиотека материалов, игроки и сущности, чат, переключение миров, переподключение, загрузка и проверка пакетов.
- `shacraft-mcp`: настоящий отдельный stdio MCP с 17 инструментами, ресурсами и prompt; строительство по плану, чтение, отмена, сущности, арены, метрики и PNG результата.
- `shacraft-content`: **1 196 блоков, 32 366 состояний, 158 типов сущностей Java 26.2**, DataVersion 4903. Официальные идентификаторы и измеренные коллизии, авторские модели. Плюс блок trampoline.
- `shacraft-compat`: Anvil и Sponge `.schem` v3 в обе стороны, типизированный NBT, сохранение оригинала, отчёты о преобразованиях и перенос правок сущностей.
- `packages/`: собственные текстуры, звук, шейдер и исполняемый WASM-модуль прыжка с ограничениями памяти и fuel.
## What's included
Ванильные AI, redstone, инвентари и симуляция жидкостей не входят в этот MVP. Контекстные формы отмечены отдельно. Конвертер после правок использует явный `best-effort`; неизменённый оригинал может вернуть побайтно. Это не обещание полной совместимости с механиками Minecraft или модами NeoForge. Оригинальные ресурсы и код Minecraft не распространяются.
- **`shacraft-core`** — compact 16³ sections, a bounded shared cache, SQLite with WAL and FULL synchronization, immutable snapshots, independent world edits, revisions, idempotent operations, undo, and reset. No graphics or networking dependencies.
- **`shacraft-server`** — authoritative movement, collision shapes and interactions, WebSocket/HTTP, persistent entities and settings, and a complete Spleef match cycle.
- **`client/`** — a custom renderer, material library, players and entities, chat, world switching, reconnection, and verified package downloads.
- **`shacraft-mcp`** — a separate stdio MCP server with 17 tools, resources, and a prompt; build plans, reads, undo, entities, arenas, metrics, and PNG previews.
- **`shacraft-content`** — **1,196 blocks, 32,366 states, and 158 entity types from Java 26.2**, DataVersion 4903. Source identifiers, measured collision shapes, and independently authored rendering templates. An additional trampoline block demonstrates extensions.
- **`shacraft-compat`** — Anvil and Sponge `.schem` v3 import/export, typed NBT, preserved originals, conversion reports, and entity edit transfer.
- **`packages/`** — original textures, audio, a shader, and an executable WASM jump module with memory and fuel limits.
## MCP и конвертация
## Compatibility and scope
This MVP does not implement full vanilla AI, redstone, inventories, or fluid simulation. Context-dependent shapes are marked separately. After edits, the converter uses an explicit `best-effort` mode; an unchanged original can be returned byte for byte. Full Minecraft gameplay or NeoForge mod compatibility is not claimed. Minecraft source code, binaries, and original visual/audio assets are not distributed.
The release benchmark measured a maximum of **59.65 MiB RSS/VmHWM with 10 moving clients** and **50.50 MiB RSS with 100 idle world forks**. These are results from a short local workload, not a comparison with Paper or a production capacity guarantee. See [verification and limits](docs/VERIFICATION.md).
## MCP and world conversion
```bash
cargo build --release --locked --workspace
# В конфигурации MCP-клиента запускается этот процесс:
# Configure your MCP client to launch this process:
target/release/shacraft-mcp --server http://127.0.0.1:4000 --data data
# Импорт в новый каталог, затем запуск сервера с --data data/imported:
# Import into a new directory, then run the server with --data data/imported:
target/release/shacraft-compat import-anvil /path/to/java-world data/imported
# Экспорт выполняется при остановленном сервере, в отсутствующий каталог:
# Stop the server before exporting. The destination directory must not exist:
target/release/shacraft-compat export-anvil data/imported artifacts/java-export --mode best-effort
```
Токен Control API создаётся в `data/control.token` (0600 на Unix) и не передаётся браузеру. [MCP](docs/MCP.md), [форматы и команды конвертера](docs/interop.md), [сервер и протокол](docs/SERVER.md), [расширение пакетами](docs/PACKAGES.md).
The Control API token is created at `data/control.token` with mode 0600 on Unix and is never sent to the browser. See [MCP configuration](docs/MCP.md), [converter commands](docs/interop.md), [server protocol](docs/SERVER.md), and [package development](docs/PACKAGES.md).
## Проверить
## Verification
```bash
# Rust, Clippy, аварийное восстановление, JS и реальные HTTP/WebSocket-клиенты:
# Rust checks, crash recovery, JavaScript tests, and real HTTP/WebSocket clients:
bash scripts/verify.sh
# Release-стенд с заранее заданными бюджетами:
# Release benchmark with budgets set before the run:
cargo build --release --workspace --locked
node scripts/benchmark_server.mjs --output artifacts/server-benchmark.json
```
Node 22+ нужен для сетевых/JS-проверок, Python 3 — для проверки аварийного хранения. Настоящий MCP SDK и независимая Java/NBT-проверка описаны в [VERIFICATION](docs/VERIFICATION.md). Проверенные числа и ограничения находятся там; сравнение с Paper не заявляется без сопоставимого стенда.
Node.js 22+ is required for network and JavaScript checks; Python 3 is required for the storage crash test. The independent MCP SDK and Java/NBT verification procedures are documented in [VERIFICATION](docs/VERIFICATION.md). Recorded checks include 84 Rust tests, 6 JavaScript tests, and 14 HTTP/WebSocket scenario groups.
## Контекст
## Documentation
[Требования](docs/REQUIREMENTS.md) · [исходный план](docs/PLAN.md) · [решения](docs/DECISIONS.md) · [контракты ядра](docs/CONTRACT.md) · [состояние и ограничения](docs/STATUS.md) · [контент](docs/CONTENT.md).
- [Project status and limitations](docs/STATUS.md)
- [Requirements](docs/REQUIREMENTS.md), [implementation plan](docs/PLAN.md), and [design decisions](docs/DECISIONS.md)
- [Core contracts](docs/CONTRACT.md), [memory and storage](docs/MEMORY_AND_STORAGE.md), and [development tools](docs/DEVELOPMENT.md)
- [Server](docs/SERVER.md), [client](docs/CLIENT.md), and [MCP](docs/MCP.md)
- [Content catalog](docs/CONTENT.md), [compatibility](docs/COMPATIBILITY.md), [world interchange](docs/interop.md), and [packages](docs/PACKAGES.md)
- [Acceptance criteria](docs/ACCEPTANCE.md) and [verification evidence](docs/VERIFICATION.md)
Проект заново реализован локально после зависания прежней среды. План сохранён до кода отдельным коммитом. Лицензия кода и собственных ресурсов — **MIT или Apache-2.0** на выбор. Существующий лаунчер и продакшен-серверы не изменяются этой поставкой.
## License
The code and original resources are available under **MIT OR Apache-2.0**, at your option. See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE). These licenses do not grant rights to third-party names, brands, or assets.
This project was rebuilt locally after the previous development environment stalled. The plan was committed before implementation. Existing Shacraft launcher and production servers are outside this MVP's integration scope.