README.md

minecraft.sh

A minecraft client/bot library written in pure bash + coreutils

Why?

I wanted to learn more about bash, maintaining libraries, and the minecraft protocol. This is mostly a learning excersize on my end. If you were looking for an actual featured bot library, there are probably better options.

Features

Feature	Supported?
1.20.1	✅
Mining	✅
Placing Blocks	✅
Entities	✅
Chat	✅
Metadata Retrival	✅
Movement	➖
Inventory Management	➖
Chunk/Biome data	❌
Pathfinding	❌
Vehicles	❌
Chat encryption	❌
Online-Mode support	❌
Old protocol versions	❌

Cool demos

Chat client (see examples/chatclient.sh)

chatclient.mp4

Auto-stripminer (see examples/stripminer.sh)

stripminer.mp4

How to use

minecraft.sh provides a simple high level library API for creating bots that can be easily used in any shell script. For example, here's a simple bot that will automatically "strip mine" in a straight line

source src/minecraft.sh
source examples/demohooks.sh
DELAY=0.25
start_login

sleep 4
while true; do
  wait_on_login
  m_get_player_pos
  for i in {0..2}; do
    for j in {0..1}; do
      m_mine_relative "$i" "$j" 0 "$DELAY"
      m_mine_relative "$i" "$j" 0 "$DELAY"
    done
  done
  for i in {0..4}; do
    m_move_relative 1 0 0
    sleep 0.1
  done
  for i in {1..3}; do
    m_mine_relative -1 1 "$i" "$DELAY"
    m_mine_relative -1 1 "$i" "$DELAY"
  done
  for i in {1..3}; do
    m_mine_relative -1 1 "-$i" "$DELAY"
    m_mine_relative -1 1 "-$i" "$DELAY"
  done
  sleep 0.1
done

More examples can be found here, and make sure to check out the documentation

Note: ksh is recommended for running any of the examples

Dependencies

The only non-coreutil dependencies are zlib-flate and xxd. zlib-flate is optional if compression is disabled in server.properties, and if you swap out util.sh with util-pure.sh xxd is optional too.