Skip to content

Latest commit

 

History

History
49 lines (32 loc) · 2.61 KB

README.md

File metadata and controls

49 lines (32 loc) · 2.61 KB

The Blockheads Tools

A toolkit for viewing and editing save files for the mobile game The Blockheads.

Note

There are no pre-built releases yet. To use these tools, you will need to compile them yourself. This requires having the Rust toolchain and uv installed.

Warning

The tools are experimental as we don't fully understand every detail of the game save format yet. Always back up your save files and use the tools at your own risk.

What You Can Do

  • Explore your game world dynamically using a viewer on desktop or web.

    World Viewer (Zoomed In) World Viewer (Zoomed Out)

  • Use Python scripts to automate tasks such as modifying blocks, or changing blockhead inventories.

    Python Scripting Example: Chunk Modification Python Scripting Example: Inventory Modification

Check out docs for installation instructions, tutorials, examples, and guides.

Roadmap / TODOs

  • MVP of modifing blocks & saving MVP: ui exposing drop menu for block type
  • Dynamic world editing UI & python bindings
  • Ergonomic block editing

For Contributors

If you're interested in how the tools are built or want to learn more about the save file format, here is a breakdown of the workspace components:

  • crates/lib: The core Rust library for parsing and manipulating game data.
  • crates/gui: The 3D world viewer and editor, powered by eframe.
  • crates/web_gui: The WebAssembly (WASM) version of the GUI crate, allowing the viewer to run in a web browser.
  • crates/py_bindings: Python bindings with type stubs, bridging the Rust core to Python for ease of scripting.
  • crates/lmdb_rs: A custom LMDB parser and builder specifically built to handle the databases in the save files.
    • Goal: Parse and build both 32-bit and 64-bit databases natively.
    • Non-Goal: Feature-complete LMDB implementation. It does not support concurrent reading/writing or random writes.
  • crates/chunk_gen: A standalone binary for generate all chunks of a world on a server by fabricating chunk requests.

The Python examples in the docs has real source files in crates/py_bindings/examples/, and are type-checked with ty and are actually executed by github workflow to get output, which helps enforcing the docs to always be up-to-date.

Warning

The codebase is highly unstable and we recommend you to not create PRs for now as the code can get obsolete quickly.