How domwilliams0/minecraft-fs works
Main Components
• FUSE Filesystem Component:
– Built in Rust (see the “filesystem” crate, whose source files like fuse.rs, state.rs, and the structure directory define the in-memory representation of the game’s state).
– The “minecraft-fs” binary uses this FUSE component to mount a virtual file hierarchy that mimics the game environment (with directories for player data, worlds, blocks, entities, etc.).
• IPC Layer:
– Implemented in the “ipc” crate.
– Uses generated code (the FlatBuffers schemas in the “shared” directory and files in “ipc/src/generated”) to serialize and transmit commands and game state information between the filesystem and the Minecraft plugin.
• Minecraft Mod Plugin:
– Located in the “plugin” directory and built via Gradle, this module (with its Java/Kotlin code) integrates with the Fabric mod loader and Fabric API.
– It receives IPC commands, processes them, and then manipulates the Minecraft game accordingly (e.g., controlling player actions, updating block states, teleporting entities).
• Supporting & Testing Tools:
– “scripts” (e.g., a demo Python script) to facilitate scripting interactions with the mounted filesystem.
– “test-client” (another Rust-based client) for testing or simulating interactions.
• Shared Communication Schemas:
– The “shared” directory contains FlatBuffers definitions (like all.fbs, common.fbs, request.fbs, response.fbs) used for standardized message formats between components.
Relationships and Data Flow
• Users (or automated scripts) interact with the FUSE mountpoint. Their filesystem operations (reads, writes, symlink accesses) trigger events in the FUSE Filesystem Component.
• The Filesystem Component processes these events (using the code in files such as fuse.rs, mount.rs, and various state/structure modules) to generate commands.
• These commands are passed to the IPC layer (in the “ipc” crate), where they are serialized into FlatBuffer messages adhering to the shared schemas.
• The serialized messages are sent to the Minecraft Mod Plugin. In the “plugin” module, the IPC handling classes (e.g., IpcChannel, Executor) receive and decode these messages.
• Once processed by the mod, the plugin executes the corresponding actions in Minecraft (e.g., altering player health, moving the player, spawning entities).
• Finally, responses or updates are sent back (if applicable) along the reverse path to update the FUSE filesystem state as seen by the user.
Architectural Patterns and Technologies
• The system uses a layered architecture where the FUSE Filesystem is the front door to the game’s internal state, the IPC module serves as the communication bus, and the plugin forms the backend that directly interacts with the game.
• That different technologies are used across layers:
– Rust for the FUSE filesystem and IPC.
– FlatBuffers for efficient cross-language serialization.
– Java/Kotlin (via Gradle) for the Minecraft mod integrated with Fabric.
– Scripting utilities in Python (in the scripts folder) provide an alternative interface for automation.
• The design demonstrates separation of concerns and clear boundaries between the “input” layer (filesystem interactions), the “communication” layer (IPC), and the “processing” layer (Minecraft mod).