shacraft-core/docs/CONTENT.md

MVP catalog, geometry, and unified packages

The built-in catalog was extracted from Minecraft Java 26.2, DataVersion = 4903: 1,196 blocks, 32,366 states, and 158 entity types. Validation compares the complete sets of states, source numeric IDs, default states, properties, and entity types against a separate projection of the official reports. The project's own shacraft:trampoline is also registered, bringing the total to 1,197 blocks and 32,367 states.

The numeric minecraft_id identifies a state in the source only. The server registers canonical strings separately in WorldStore; its internal BlockId depends on the history of that particular store. Do not use minecraft_id in world editing operations. For a custom state, minecraft_id = u32::MAX means that no Minecraft ID exists.

Provenance and reproduction

Source: official Java 26.2 server.jar. SHA-1: 823e2250d24b3ddac457a60c92a6a941943fcd6a; size: 60,894,273 bytes. Full SHA-256 hashes, the Java version, commands, and report checksums are recorded in crates/shacraft-content/data/provenance.json.

The generator checks the pinned size and SHA-1 before using the JAR:

python3 scripts/catalog_generate.py --java /path/to/java25/bin/java
python3 scripts/catalog_assets.py
cargo test -p shacraft-content
cargo run -p shacraft-content --example catalog_report

An installed JDK 25 or later, including javac, is required. The verified local runtime is Microsoft OpenJDK 25.0.1+8-LTS. The script does not change the system Java installation. --reuse-reports repackages previously generated local reports; omit it for a full reproduction. Gzip uses a fixed mtime=0, and the catalog content is deterministic. The run timestamp changes in the provenance record.

The following entry point was verified:

java -Xmx1G -DbundlerMainClass=net.minecraft.data.Main -jar server.jar --reports --output generated

catalog_extract.java is a small original program that calls the public registry and collision APIs in 26.2. It contains no decompiled code. The data generation and measurements run without launching the Minecraft game/server, creating an eula=true file, or accepting its server startup prompt. The JAR, extracted libraries, reports, and Java classes remain in the ignored artifacts/catalog-cache directory; the distribution contains only minimal factual compatibility data and original code.

Geometry verification

getCollisionShape was obtained from the official executable API for each of the 32,366 states. Measurement uses no textures or visual models. All measurements completed without errors, yielding 326 distinct sets of axis-aligned boxes after deduplication.

The baseline measurement context uses BlockPos.ZERO, neighboring air, and no entity (CollisionContext.empty()). Additional comparisons used stone neighbors and CollisionContext.positionContext(+10/-10); these revealed differences in 32 scaffolding states. Classes that depend on entities, block entities, or dynamic state are also explicitly marked: powder snow, shulker box, moving piston, and big dripleaf. Collision coverage is therefore divided into:

• 32,187 states: measured-empty-context — geometry measured in the context described above.
• 179 states: approximate-context — baseline geometry is available, but dynamic conditions are not fully equivalent.
• 1 custom state: authored-exact.

The first label does not claim equivalence in every arbitrary context. Player position, special equipment, piston block entities, opening shulker boxes, updates to connections with neighbors, AI, redstone, and fluid flow cannot be inferred from the catalog. The server provides its own simulation and modules with explicit boundaries.

Separate regression checks cover top/bottom slabs, stair volumes and orientations, door opening, empty water collision, the 1.5-block fence collision height, context labels for scaffolding/powder snow, and valid bounds for every shape. Collision geometry can extend outside a block cell; Y must not be unconditionally clamped to [0,1].

Original rendering

render and collision are separate sets of Aabb { min, max }, with coordinates relative to the block. The renderer uses Shacraft's own procedural geometry and palette. The bundled PNG files, WAV audio, and GLSL were authored or generated in this repository; no original Minecraft assets are included.

Slabs, stairs, doors, trapdoors, panes, chests, and many complex solid block families use measured volumes as a basis for original geometry. Fences, walls, open fence gates, signs, rails, liquids, plants, buttons, levers, carpets, and other non-solid forms have separate parametric templates. A fence is drawn up to Y=1 while its collision reaches Y=1.5. Ascending rails have stepped geometry; curved rails use an angular approximation made of rectangles. This is a readable original style, not a visually exact reproduction of Minecraft.

Coverage: 32,317 authored-procedural states and 50 intentionally-invisible states, including air, technical light/barrier/structure void blocks, and moving pistons without their original dynamic block entities. No built-in catalog families currently fall back to a generic visual cube. The existence of a state does not automatically reproduce every decorative detail, sign text, animation, waterlogged fluid inside a model, or lighting simulation.

For 158 entity types, the extracted data includes initial width/height/eye height, fixed dimensions, category, summonable/serializable/fire immune flags, tracking/update interval, and all available base numeric attributes. These properties are stored in EntityDefinition.properties. Models are positioned relative to the feet and use original biped, quadruped, aquatic, winged, boat, cart, dragon, arthropod, and other families. Technical marker/interaction/area effect cloud/lightning bolt entities are intentionally invisible. Display entities explicitly declare their dependence on instance properties. Age/pose/scale dimensions and arbitrary NBT are preserved by the instance layer; the catalog stores default dimensions. Having a model does not imply vanilla AI support.

Rust API

• Catalog::load_builtin() -> Result<Catalog>: the complete built-in catalog and trampoline.
• catalog.state(canonical_or_block_name), catalog.entity(name), catalog.default_state(name).
• catalog.palette(): 12 convenient canonical states for the test client.
• catalog.sampler(): 1,197 default samples in a 32-column grid with spacing 3; individual cells are positioned relative to a floor at Y=0, with X/Z within ±64. The server is responsible for creating the floor and writing blocks to the world.
• catalog.summary(): counts, separate coverage categories, version, and limitations.
• canonical_state(name, properties): key sorting and limited validation without losing unknown properties.
• All public definitions implement Clone, Serialize, and Deserialize. After deserializing a complete Catalog, call rebuild_indexes() before performing lookups.

The built-in binary catalog occupies about 246 KiB as gzip. Loading decompresses it and creates strings, geometry, and indexes. File size is not the catalog's RAM usage. The complete strings for 32 thousand states and the WorldStore registry must be accounted for separately in process RSS measurements.

Unified package format v1

Each subdirectory of packages/ contains a manifest.json:

{
  "schema": 1,
  "id": "shacraft.trampoline",
  "version": "1.0.0",
  "license": "MIT OR Apache-2.0",
  "dependencies": [{"id": "shacraft.base", "version": "1.0.0"}],
  "capabilities": ["blocks.define", "client.texture", "client.style", "server.on_jump"],
  "resources": [{
    "path": "server/trampoline.wasm", "scope": "server", "role": "wasm-on-jump",
    "sha256": "<64 lowercase hexadecimal characters>", "size": 40
  }]
}

This example illustrates the schema; actual sizes and hashes come from the generated manifests. Dependency versions are exact. load_packages(root) validates the entire graph before exposing resources: schema, uniqueness, dependencies, matching versions, cycles, allowed capabilities, paths, sizes, and SHA-256 hashes of all declared resources. A resource is limited to 16 MiB and an entire package to 64 MiB; symlinks and traversal in resource paths are rejected. read_resource checks the hash and size again when reading.

Scopes: common contains shared definitions; client contains client assets; server contains internal server data and code. PackageManifest::client_manifest() excludes server resources and capabilities. Package::public_resource(path) denies access to server-scope resources; the HTTP route must use this method. The static server must not serve the entire packages/ directory directly.

shacraft.base includes the catalog description, an original 64×64 noise texture, and client styling. shacraft.trampoline includes a shared block definition, a 32×32 grid texture, a client visual effect, a short original sound, an optional GLSL function, and an executable server WebAssembly module. Its on_jump() -> f32 export returns a velocity of 10 blocks/s; the module has no imports, memory, or external system calls. The WAT source is included alongside it. The server executes the binary module in a restricted environment; the contract specifies a fuel limit of 10,000, a memory limit of 1 page, and range validation of the result. The client uses the built-in bounce effect according to package data, rather than arbitrary JavaScript from the network. An arbitrary client code runtime and a complete mod ecosystem are not claimed as implemented.

python3 scripts/catalog_assets.py deterministically regenerates all original assets and hashes. Package assets are available under MIT OR Apache-2.0, like the project's original code. Generation downloads nothing.