86 lines
6.4 KiB
Markdown
86 lines
6.4 KiB
Markdown
# Shacraft Core
|
|
|
|
[](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**.
|
|
|
|
> 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
|
|
```
|
|
|
|
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.
|
|
|
|
- **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.
|
|
|
|
## What's included
|
|
|
|
- **`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.
|
|
|
|
## 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
|
|
# Configure your MCP client to launch this process:
|
|
target/release/shacraft-mcp --server http://127.0.0.1:4000 --data data
|
|
|
|
# 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
|
|
```
|
|
|
|
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 checks, crash recovery, JavaScript tests, and real HTTP/WebSocket clients:
|
|
bash scripts/verify.sh
|
|
# Release benchmark with budgets set before the run:
|
|
cargo build --release --workspace --locked
|
|
node scripts/benchmark_server.mjs --output artifacts/server-benchmark.json
|
|
```
|
|
|
|
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
|
|
|
|
- [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)
|
|
|
|
## 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.
|