README.md

minecraft-wrapper

What is minecraft-wrapper?

Wrapper is a Go package that wraps a Minecraft Server (JE) and interacts with it by pushing in commands and reading the server logs. This package is meant to provide nicer APIs for your Go program to manage your minecraft server.

Installation

go get github.com/wlwanpan/minecraft-wrapper

Usage

• Starting the server and listening to game events:

wpr := wrapper.NewDefaultWrapper("server.jar", 1024, 1024)
wpr.Start()
defer wpr.Stop()

// Listening to game events...
for {
  select {
  case ev := <-wpr.GameEvents():
    log.Println(ev.String())
  }
}

• Broadcast a "Hello" message once the server is loaded:

wpr := wrapper.NewDefaultWrapper("server.jar", 1024, 1024)
wpr.Start()
defer wpr.Stop()

<-wpr.Loaded()
wpr.Say("Hello")

• Retrieving a player position from the /data get command:

out, err := wpr.DataGet("entity", PLAYER_NAME|PLAYER_UUID)
if err != nil {
	...
}
fmt.Println(out.Pos) // [POS_X, POS_Y, POS_Z]

• Save the game and Tell a game admin "admin-player", when the server is overloading.

wpr := wrapper.NewDefaultWrapper("server.jar", 1024, 1024)
wpr.Start()
defer wpr.Stop()
<-wpr.Loaded()

for {
  select {
  case ev := <-wpr.GameEvents():
    if ev.String() == events.ServerOverloaded {
      if err := wpr.SaveAll(true); err != nil {
        ...
      }
      broadcastMsg := fmt.Sprintf("Server is overloaded and lagging by %sms", ev.Data["lag_time"])
      err := wpr.Tell("admin-player", broadcastMsg)
      ...
    }
  }
}

For more example, go to the examples dir from this repo (more will be added soon).

Note: This package is developed and tested on Minecraft 1.16, though most functionalities (Start, Stop, Seed, ...) works across all versions. Commands like /data get was introduced in version 1.13 and might not work for earlier versions. ⚠️

Overview

If you are interested, you can visit this Medium article to learn some of the basic inner working of the wrapper.

Commands 🚧

The following apis/commands are from the official minecraft gamepedia list of commands unless otherwise specified.

• Attributes
• Advancement
• Ban
• BanIp
• BanList
• Bossbar
• DataGet
• DataMerge
• DataModify
• DataRemove
• DefaultGameMode
• DeOp
• Difficulty
• Effect
• Enchant
• ExperienceAdd
• ExperienceQuery
• Fill
• ForceLoad
• ForceLoadRemoveAll
• Function
• GameEvents - A GameEvent channel of events happening during in-game (Unofficial)
• GameMode
• GameRule
• Give
• Kick
• Kill - Terminates the Java Process (Unofficial)
• List - Returns an arr of connected player struct
• Loaded - Returns bool from a read-only channel once the server is loaded (Unofficial)
• Reload
• SaveAll
• SaveOff
• SaveOn
• Say
• Schedule
• Scoreboard
• Seed
• SetBlock
• SetIdleTime
• SetWorldSpawn
• SpawnPoint
• Spectate
• SpreadPlayers
• Start (Unofficial)
• State - Returns the current state of the Wrapper (Unofficial)
• Stop
• StopSound
• Summon
• Tag
• Team
• TeamMsg
• Teleport
• Tell
• TellRaw
• Tick - Returns the running game tick (Unofficial)
• Title
• Trigger
• Weather
• Whitelist
• WorldBorder

Note: this list might be incomplete...

GameEvents 🚧

List of game events and their respective data...

Minecraft resources

• Gamepedia
• DigMinecraft

Help and contributions

Feel free to drop a PR, file an issue or proposal of changes you want to have.