shacraft-core/README.md

Shacraft Core

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.

In-game demonstration

An imported minigames lobby running in Shacraft, with multiplayer avatars and block lighting. This development screenshot uses original Minecraft textures for a local compatibility test; the world and texture pack are not bundled with the repository. Render distance supports up to 64 chunks (1,024 blocks), with progressive loading across the full world height, Y=−64 through 319.

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.

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, two Spleef arenas and a procedural Overworld automatically. Open http://localhost:4000/?world=overworld for the large world. 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.
• Ctrl to sprint, Shift to crouch, double-Space / F to toggle permitted creative flight; Space/Shift ascend/descend.
• 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. The seeded Overworld spans 384 vertical layers and nearly ±30 million horizontal blocks, with bounded CPU generation and section streaming.
• shacraft-physics — shared 20 Hz Rust/WASM player movement, client prediction and reconciliation, tested against measured Java 26.2 movement kernels, collision cases and block callbacks. See physics and its limits.
• 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, texture packs, and audio files are not bundled.

The earlier MVP 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 measurements predate the shared movement solver and are results from a short local workload, not a comparison with Paper or a production capacity guarantee. See verification and limits.

MCP and world conversion

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, converter commands, server protocol, and package development.

Verification

# Rust checks, crash recovery, JavaScript tests, and real HTTP/WebSocket clients:
rustup target add wasm32-unknown-unknown
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. Verification rebuilds the physics WebAssembly with the Rust wasm32-unknown-unknown target; playing uses the included artifact. The independent MCP SDK and Java/NBT verification procedures are documented in VERIFICATION.

Documentation

• Project status and limitations
• Requirements, implementation plan, and design decisions
• Core contracts, memory and storage, and development tools
• Server, client, and MCP
• Player physics, reference measurements and prediction
• Procedural worlds, streaming and movement diagnostics
• Content catalog, compatibility, world interchange, and packages
• Acceptance criteria and verification evidence

License

The code and original resources are available under MIT OR Apache-2.0, at your option. See LICENSE-MIT and 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.