domwilliams0 / minecraft-fs Goto Github PK

🧰 FUSE filesystem for querying and controlling Minecraft

License: GNU General Public License v3.0

Rust 75.76% Kotlin 20.31% Shell 0.22% Python 3.71%

minecraft-fs's Introduction

minecraft-fs

A FUSE filesystem for querying and controlling Minecraft, as a universal mod platform (but mainly for fun). A blog post covering the technical details can be found here.

Warning: don't get your hopes too high, this is still WIP!

Examples GIFs
Installation
Usage
Directory structure

What?

This plugin makes it possible to control your game through the filesystem, and therefore with common Unix tools like cat, find, grep etc. This means you can easily write Minecraft mods with languages like bash and Python without needing to touch Java, gradle or Fabric.

Why?

For fun, to learn about FUSE, but most importantly - why not?

Examples

Controlling the player

Teleporting

Teleporting others to the player

Setting health

Setting blocks

Scripting

In ./scripts you can find some python that encapsulates the filesystem structure and makes for a nicer scripting experience. See the demo script for some examples.

import common
mc = Minecraft.from_args()

player = mc.player()
print(f"{player.name} is at {player.position}")

player.kill()

Installation

Download latest release, or build it yourself
- Build FUSE filesystem with cargo build --bin minecraft-fs --release
- Build Minecraft mod with cd plugin; ./gradlew build, which will build the jar file to build/libs
Install Minecraft mod
- Client version: 1.18.2
- Dependencies: Fabric Loader, Fabric API and Fabric Language Kotlin
- Install MCFS via mod manager/putting mod jar in mods/

Usage

Install as above
Start Minecraft
Mount the FUSE filesystem over an empty directory
- mkdir mnt; ./minecraft-fs ./mnt
Join a single player world - there's currently no support for multiplayer

Your mountpoint should contain something like the following:

$ cd mnt
$ ls
player  version  worlds

$ ls -l player
drwxr-xr-x   - dom 21 Feb 20:27 control
lrwxr-xr-x   0 dom 21 Feb 20:27 entity -> world/entities/by-id/135
.rwxr-xr-x 256 dom 21 Feb 20:27 health
.rwxr-xr-x 256 dom 21 Feb 20:27 name
.rwxr-xr-x 256 dom 21 Feb 20:27 position
lrwxr-xr-x   0 dom 21 Feb 20:27 world -> ../worlds/overworld

Congratulations, you can now manipulate the game through reading and writing to these special files.

Directory structure

; wo=write only, ro=read only, rw=read and write
├── command       ; wo, executes a command as the player
├── player
│   ├── control    ; all the files here are write-only
│   │   ├── jump   ; causes the player to jump on any input
│   │   ├── move   ; applies the given x,y,z force to the player
│   │   └── say    ; makes the player chat
│   ├── health     ; rw, the player's health
│   ├── name       ; ro, the player's name
│   ├── position   ; rw, the player's position
│   ├── gamemode   ; rw, the player's gamemode
│   ├── hunger     ; rw, the player's hunger
│   ├── exhaustion ; rw, the player's exhaustion
│   ├── saturation ; rw, the player's food saturation
│   ├── target     ; wo, a position to look at
│   ├── entity -> world/entities/by-id/135  ; symlink to player entity
│   └── world -> ../worlds/overworld  ; symlink to player world
└── worlds
    ├── overworld
    │   ├── blocks
    │   │   ├── 100,64,250
    │   │   │   ├── adjacent  ; dir of symlinks to adjacent blocks
    │   │   │   │   ├── above -> ../../100,65,250
    │   │   │   │   ├── below -> ../../100,63,250
    │   │   │   │   ├── east -> ../../101,64,250
    │   │   │   │   ├── north -> ../../100,64,249
    │   │   │   │   ├── south -> ../../100,64,251
    │   │   │   │   └── west -> ../../99,64,250
    │   │   │   ├── pos    ; ro, this block's position
    │   │   │   └── type   ; rw, the block's type
    │   │   ├── 100.2 64.555 250.1223  ; this works too
    │   │   │   └── ...
    │   │   └── README  ; ro, explains the dir structure
    │   ├── entities
    │   │   ├── by-id
    │   │   │   ├── 107  ; entity id
    │   │   │   │   ├── health     ; rw, the entity's health (if living)
    │   │   │   │   ├── living     ; inaccessible, exists to indicate living
    │   │   │   │   ├── position   ; rw, the entity's position
    │   │   │   │   ├── target     ; wo, a position to look at
    │   │   │   │   └── type       ; ro, the entity's type
    │   │   │   ├── 108
    │   │   │   │   ├── health
    │   │   │   │   ├── living
    │   │   │   │   ├── position
    │   │   │   │   ├── target
    │   │   │   │   └── type
    │   │   │   ...
    │   │   └── spawn ; rw, spawns an entity, read file for help
    │   └── time      ; rw, the world's time
    ├── nether
    │   ├── blocks
    │   │   └── ...
    │   ├── entities
    │   │   └── ...
    │   └── time
    └── end
        ├── blocks
        │   └── ...
        ├── entities
        │   └── ...
        └── time

TODOs

Recommend Projects