Emil
c7e86663d8
MVP checks / mvp (push) Canceled after 0s
Add shared Rust/WASM physics, worker meshing and diagnostics, 64-chunk full-height streaming, atlas texture support, and baseline world import. Document the current implementation and include the supplied in-game lobby screenshot.
97 lines
7.8 KiB
Markdown
97 lines
7.8 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).
|
||
|
||
## 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.
|
||
|
||
```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, 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](docs/PHYSICS.md).
|
||
- **`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](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:
|
||
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](docs/VERIFICATION.md).
|
||
|
||
## 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)
|
||
- [Player physics, reference measurements and prediction](docs/PHYSICS.md)
|
||
- [Procedural worlds, streaming and movement diagnostics](docs/WORLD_STREAMING.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.
|