Skip to content

Latest commit

 

History

History
296 lines (256 loc) · 7.64 KB

docs.md

File metadata and controls

296 lines (256 loc) · 7.64 KB

Documentation

note: this file was auto-generated by docsgen.sh

Getting started

Make a new file, and import minecraft.sh with the source keyword. run "start_login" and make sure to use "wait_on_login" before sending any packets. See the documentation for start_login to see the full list of options

source src/minecraft.sh

start_login
wait_on_login

And that's it! your bot will log in and do nothing. To get it to actually do something, look at the methods here or the examples in examples/

Listening to events

minecraft.sh works on a system of "hooks", function handlers that are called whenever certain packets are recieved. scroll down for the full list For example, to respawn and print a method whenever the bot dies, add this code to your script

pkt_hook_combat_death() {
  echo "I died! Full information: $1"
	pkt_respawn
}

If you just want to play around with the methods, ./interactive will give you an interactive shell with all the methods loaded

If you need to ask any questions, feel free to ask me @coolelectronics on discord

List of methods and hooks

pkt_hook_login()

called after login and the state switches to "play"
it is NOT safe to send packets until this function is called

arguments

(username:string)

pkt_hook_entity_move()

called whenever an entity in render distance moves

arguments

(eid)

pkt_hook_chat()

called whenever a player chat message is sent

arguments

(uuid, message: hex string, timestamp: hex long, metadata: json string as hex)

pkt_hook_system_chat()

called whenever the system sends you a chat event
player death, running an invalid command, actionbar, etc

arguments

(metadata: json string as hex)

pkt_hook_disguised_chat()

called on certain types of chat events, i don't know which ones
not entirely sure what the arguments mean

arguments

(message: hex string, typename: hex string, hasname: 0 | 1, name: hex string)"

pkt_hook_synchronize_player_position()

called whenever the player joins the game or is teleported
after this packet, player position will be accessible inside $PLAYER/x, $PLAYER/y, etc

arguments

(x: decimal string, y: decimal string, z: decimal string)

pkt_hook_combat_death()

called when the player dies in any way
unless you have a reason not to, you should call pkt_respawn inside the hook

arguments

(reason: json string as hex)

pkt_hook_set_health()

called whenever the player's health changes

arguments

(health: decimal string, food: int, saturation: decimal string)

example

# attempt to leave when health falls below THRESHOLD 	
pkt_hook_set_health () { 	
  if (( $(echo "$1 $THRESHOLD" | awk '{print ($1 < $2)}') )); then 	
	  echo "health was $1, leaving!" 	
	  disconnect 	
  fi 	
}

pkt_hook_unknown()

called whenever an unhandled packet gets processed

arguments

sets "pkt_id", data is read from stdin

example

pkt_hook_unknown () { 	
  case $pkt_id in 	
    24) # "24" would be the packet name in hex 	
      a=$(fromvarint) 	
      b=$(readhex 4) 	
      # etc etc 	
    ;; 	
  esac 	
}

pkt_hook_entity_spawn()

called whenever an entity enters view distance (NOT A PLAYER)

arguments

(eid)

pkt_hook_player_spawn()

called whenever a player enters view distance

arguments

(eid)

pkt_hook_entity_remove()

called whenever an entity (OR PLAYER) is removed or exits view distance
the entity directory gets deleted immediately after the hook exits

arguments

(eid)

pkt_hook_kicked()

called when the server kicks you for any reason
this is differnt from pkt_hook_disconnect because it only fires when the server kicks you, not if you lose connection for unrelated reasons

arguments

(reason: json string as hex)

example

echo -n "kicked from server: " 	
echosafe "$1" | fromhex 	
echo

pkt_hook_disconnect()

called when the underlying TCP connection to the server closes, after pkt_hook_kicked

m_get_player_pos()

stores player position in "x" "y" and "z"

m_cleanup_on_exit()

terminates all jobs on exit

m_mine_relative()

mine block XYZ bocks relative to the player
"delay" is the number of seconds it should take to fully mine the block

arguments

(x,y,z,delay)

m_move_relative()

moves XYZ blocks relative to the current location

arguments

(x,y,z)

server_list_ping()

gets the ping of a server, player count, MOTD, icon, etc

arguments

returns a JSON string

example

HOST=endcrystal.me 	
json=$(server_list_ping) 	
echo "$json" | jq ".description.text" 	
echo "players: $(echo "$json" | jq ".players.online")/$(echo "$json" | jq ".players.max")" 	
echo "version: $(echo "$json" | jq ".version.name")" 	
echo "ping: ${ping}ms"

start_login()

start the login process
PORT is 25565 by default, HOST is localhost by default, USERNAME is sh

arguments

pkt_swing_arm $ARM_LEFT

example

HOST=tf2.mercurywork.shop 	
PORT=25565 	
USERNAME=juliet 	
start_login 	
# you must call wait_on_login before sending packets 	
wait_on_login

wait_on_login()

wait for login to finish
you MUST call this at least once before sending any packets

pkt_send()

send a raw serverbound packet

arguments

(packet_num: hex(2), data: hex)

example

pkt_send 2f "$(tovarint 1)" 	
# "2f" is the serverbound packet id for "swing arm" and 1 here means "left hand" 	
# see the full list of packets at https://wiki.vg/Protocol

pkt_respawn()

respawn the player after a death

arguments

no arguments

example

pkt_hook_combat_death() { 	
	pkt_respawn 	
}

pkt_chat()

sends a message in public chat

arguments

(message: string)

example

pkt_chat "hello! I sent a chat message!"

pkt_chat_command()

runs a server command
the command response is recieved in pkt_hook_system_chat

arguments

(command: string)

example

pkt_chat_command "kill CoolElectronics"

pkt_swing_arm()

swings the player arm

arguments

(arm: ARM_LEFT | ARM_RIGHT)

example

pkt_swing_arm $ARM_RIGHT

pkt_interact()

interact with an entity
in the standard client, this happens when right clicking something (mounting a horse, trading with a villager, etc)

arguments

(eid, arm: arm_left | arm_right, sneaking: 0 | 1)

example

# attempt to interact with every entity in view distance 	
hook_entity_move(){ 	
	eid=$1 	
	pkt_interact $eid $ARM_RIGHT 0 	
}

pkt_attack()

attack an entity

arguments

(eid)

example

# attempt to attack every entity in view distance whenever it moves 	
pkt_hook_entity_move(){ 	
	eid=$1 	
	pkt_attack $eid 	
}

pkt_drop()

drop the currently held item

arguments

(DROP_ITEM|DROP_STACK)

pkt_dig()

attempt to mine a block

arguments

(DIG_START | DIG_CANCEL | DIG_FINISH, x, y, z, face)

example

pkt_dig $DIG_START 12 50 14 	
sleep 4 # wait for enough time to mine the block 	
pkt_dig $DIG_FINISH 12 50 14

pkt_sneak()

sneak or unsneak

arguments

(SNEAK|UNSNEAK)

pkt_set_position()

teleport to a coordinate, within reason

arguments

(x: decimal string, y: decimal string, z: decimal string, onground: 0 | 1)

pkt_set_on_ground()

tell server if you're grounded or not

arguments

(0 | 1)

pkt_pick_item()

select an item from the hotbar

arguments

(item: 0-8)

pkt_use_item()

use item (eg, throw snowball)