README
¶
mcwss
A documentation and implementation of the Minecraft Bedrock Edition websocket protocol.
Minecraft Websockets
Minecraft has websocket connection commands that may be used to connect to a websocket server. These commands are /connect and /wsserver.
Both these commands have the same effect. Once connected to a websocket, the connection will last until the server closes it or until the
player completely exits the game. The connection will last when a player merely leaves a world, and will thus last when joining a server.
Websockets in Minecraft can be used for simple command communication between a player and a server. Additionally, the server can choose to
listen for certain events sent by the client and act upon receiving them.
In order to be able to execute the /connect and /wsserver commands, cheats must be enabled. This means that connecting on third party
servers is not possible, and only on the dedicated server when cheats are enabled. It is possible to connect on a singleplayer world and
join a server after that, but commands executed by the websocket server will not work. Events will still be sent by the client however.
In the settings tab, there is also a setting that enables/disables encrypted websockets. mcwss implements encryption between websockets, so changing this setting will not have an effect on the behaviour of mcwss.
Getting Started
Prerequisites
mcwss is a Go library. To use it, Go must be installed. The library may be downloaded using go get github.com/sandertv/mcwss.
Usage
package main
import (
"github.com/sandertv/mcwss"
)
func main() {
// Create a new server using the default configuration. To use specific configuration, pass a *wss.Config{} in here.
server := mcwss.NewServer(nil)
server.OnConnection(func(player *mcwss.Player){
// Called when a player connects to the server.
})
server.OnDisconnection(func(player *mcwss.Player){
// Called when a player disconnects from the server.
})
// Run the server. (blocking)
server.Run()
}
The server may now be connected to by joining a singleplayer game and executing the command /connect localhost:8000/ws.
Documentation
Documentation
¶
Overview ¶
Package mcwss implements a websocket server to be used with Minecraft Bedrock Edition. It aims to implement most of the protocol and abstraction around it to achieve and easy to use API for interacting with the client.
When using mcwss.NewServer(nil), the default configuration is used. Once the server is ran, (Server.Run()) your client may connect to it using `/connect localhost:8000/ws'. The client will remain connected to the websocket until it either connects to a new one or closes the entire game, or when the websocket server chooses to forcibly close the connection.
After connecting to a websocket server in a world that has cheats enabled, it is possible to join (online) games, like Mineplex, or other single player worlds, that do not have cheats enabled. Executing commands or other actions that would modify the world are not available on those servers, but events will still be sent by the client as expected.
Index ¶
- Constants
- type Agent
- func (agent *Agent) Attack(direction mctype.Direction)
- func (agent *Agent) DestroyBlock(direction mctype.Direction)
- func (agent *Agent) Move(direction mctype.Direction, metres int)
- func (agent *Agent) Position(f func(position mctype.Position))
- func (agent *Agent) Rotation(f func(yRotation float64))
- func (agent *Agent) TillBlock(direction mctype.Direction)
- func (agent *Agent) TurnLeft()
- func (agent *Agent) TurnRight()
- func (agent *Agent) UseHeldItem(direction mctype.Direction)
- type Config
- type Player
- func (player *Player) Agent() *Agent
- func (player *Player) CloseChat()
- func (player *Player) CloseConnection()
- func (player *Player) Connected() bool
- func (player *Player) EduInformation(f func(info *command.EduClientInfo))
- func (player *Player) EnableDebug()
- func (player *Player) Exec(commandLine string, callback interface{})
- func (player *Player) ExecAs(commandLine string, callback func(statusCode int))
- func (player *Player) Name() string
- func (player *Player) OnAwardAchievement(handler func(event *event.AwardAchievement))
- func (player *Player) OnBlockBroken(handler func(event *event.BlockBroken))
- func (player *Player) OnBlockPlaced(handler func(event *event.BlockPlaced))
- func (player *Player) OnBookEdited(handler func(event *event.BookEdited))
- func (player *Player) OnEndOfDay(handler func(event *event.EndOfDay))
- func (player *Player) OnGameRulesLoaded(handler func(event *event.GameRulesLoaded))
- func (player *Player) OnGameRulesUpdated(handler func(event *event.GameRulesUpdated))
- func (player *Player) OnItemAcquired(handler func(event *event.ItemAcquired))
- func (player *Player) OnItemCrafted(handler func(event *event.ItemCrafted))
- func (player *Player) OnItemDropped(handler func(event *event.ItemDropped))
- func (player *Player) OnItemEquipped(handler func(event *event.ItemEquipped))
- func (player *Player) OnItemInteracted(handler func(event *event.ItemInteracted))
- func (player *Player) OnItemNamed(handler func(event *event.ItemNamed))
- func (player *Player) OnItemSmelted(handler func(event *event.ItemSmelted))
- func (player *Player) OnItemUsed(handler func(event *event.ItemUsed))
- func (player *Player) OnMobBorn(handler func(event *event.MobBorn))
- func (player *Player) OnMobInteracted(handler func(event *event.MobInteracted))
- func (player *Player) OnMobKilled(handler func(event *event.MobKilled))
- func (player *Player) OnPlayerMessage(handler func(event *event.PlayerMessage))
- func (player *Player) OnScreenChanged(handler func(event *event.ScreenChanged))
- func (player *Player) OnScriptLoaded(handler func(event *event.ScriptLoaded))
- func (player *Player) OnScriptRan(handler func(event *event.ScriptRan))
- func (player *Player) OnSignInToXBOXLive(handler func(event *event.SignInToXBOXLive))
- func (player *Player) OnSignOutOfXBOXLive(handler func(event *event.SignOutOfXBOXLive))
- func (player *Player) OnSignedBookOpened(handler func(event *event.SignedBookOpened))
- func (player *Player) OnSlashCommandExecuted(handler func(event *event.SlashCommandExecuted))
- func (player *Player) OnStartWorld(handler func(event *event.StartWorld))
- func (player *Player) OnTeleported(handler func(event *event.PlayerTeleported))
- func (player *Player) OnTransform(handler func(event *event.PlayerTransform))
- func (player *Player) OnTravelled(handler func(event *event.PlayerTravelled))
- func (player *Player) OnVehicleExited(handler func(event *event.VehicleExited))
- func (player *Player) OnWorldGenerated(handler func(event *event.WorldGenerated))
- func (player *Player) OnWorldLoaded(handler func(event *event.WorldLoaded))
- func (player *Player) Position(f func(position mctype.Position))
- func (player *Player) Rotation(f func(rotation float64))
- func (player *Player) Say(message string, parameters ...interface{})
- func (player *Player) SendMessage(message string, parameters ...interface{})
- func (player *Player) Tell(message string, parameters ...interface{})
- func (player *Player) UnsubscribeFrom(eventName event.Name)
- func (player *Player) UnsubscribeFromAll()
- func (player *Player) World() *World
- func (player *Player) WriteJSON(v interface{}) error
- type Server
- type World
- func (world *World) Broadcast(message string, parameters ...interface{})
- func (world *World) DestroyBlock(position mctype.BlockPosition)
- func (world *World) SetBlock(position mctype.BlockPosition, block string, dataValue byte)
- func (world *World) SpawnParticle(particle string, position mctype.Position)
Constants ¶
const MinecraftWSEncryptSubprotocol = "com.microsoft.minecraft.wsencrypt"
MinecraftWSEncryptSubprotocol is the subprotocol used for encrypted websocket connections in Minecraft.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent is the agent of a player. The agent is an entity that can be created and controlled using websockets.
func (*Agent) DestroyBlock ¶
DestroyBlock makes the agent destroy a block in a direction. The agent can break any block, regardless of whether the block is breakable in survival mode or not. Bedrock, water etc. can be broken.
func (*Agent) Position ¶
Position requests the position of the agent and passes it into the function passed when a response is received.
func (*Agent) Rotation ¶
Rotation requests the rotation of the agent and passes it into the function passed when a response is received.
func (*Agent) TillBlock ¶
TillBlock makes the agent till a block in a given direction using a hoe. Tilling does not appear to work in non-edu mode, and seems to often crash the game instead.
func (*Agent) TurnLeft ¶
func (agent *Agent) TurnLeft()
TurnLeft turns the agent 90 degrees to the left.
func (*Agent) TurnRight ¶
func (agent *Agent) TurnRight()
TurnRight turns the agent 90 degrees to the right.
func (*Agent) UseHeldItem ¶
UseHeldItem makes the agent place its held item, provided it is a block, in a given direction.
type Config ¶
type Config struct {
// HandlerPattern is the handler pattern on which the websocket server may be found. By default, this
// value is '/ws'.
HandlerPattern string
// Address is the address+port on which the websocket server is running. By default, this is ':8000'.
Address string
}
Config is the configuration of the websocket server.
type Player ¶
type Player struct {
*websocket.Conn
event.Properties
sync.Mutex
// contains filtered or unexported fields
}
Player is a player connected to the websocket server.
func (*Player) CloseChat ¶
func (player *Player) CloseChat()
CloseChat closes the chat window of a player if the player has it open. This command is available also on third party servers.
func (*Player) CloseConnection ¶
func (player *Player) CloseConnection()
CloseConnection closes the socket connection with the player. The player will be closed shortly after this method is called.
func (*Player) Connected ¶
Connected checks if a player is currently connected. If not, the reference to this player should be released as soon as possible.
func (*Player) EduInformation ¶
func (player *Player) EduInformation(f func(info *command.EduClientInfo))
EduInformation requests information about the player (specifically education edition related, but education edition needs not to be enabled) and calls the function passed when a response is received.
func (*Player) EnableDebug ¶
func (player *Player) EnableDebug()
EnableDebug enables debug messages for a player. It will output messages about missing fields in events and related.
func (*Player) Exec ¶
Exec sends a command string with a callback that can process the output of the command. The callback passed must have one input argument, being the container of the output. This may be done using either a pointer to a struct, or a map, like so:
player.Exec("getlocalplayername", func(response *command.LocalPlayerName){}) player.Exec("getlocalplayername", func(response map[string]interface{}){})
Nil may also be passed if no callback needs to be executed.
func (*Player) ExecAs ¶
ExecAs sends a command string as if it were sent by the player itself with a callback that can process the output of the command. The callback passed must have one input argument, being the container of the output. The output of the command is captured by the player, not by the websocket server. Only a status code is captured by the server that indicates if the command was successful.
func (*Player) OnAwardAchievement ¶
func (player *Player) OnAwardAchievement(handler func(event *event.AwardAchievement))
OnAwardAchievement listens to achievements awarded to the player. Note that achievements are not awarded in worlds that have cheats enabled.
func (*Player) OnBlockBroken ¶
func (player *Player) OnBlockBroken(handler func(event *event.BlockBroken))
OnBlockBroken subscribes to blocks broken by the player.
func (*Player) OnBlockPlaced ¶
func (player *Player) OnBlockPlaced(handler func(event *event.BlockPlaced))
OnBlockPlaced subscribes to blocks placed by the player.
func (*Player) OnBookEdited ¶
func (player *Player) OnBookEdited(handler func(event *event.BookEdited))
OnBookEdited subscribes to edits by the player to a book after closing it.
func (*Player) OnEndOfDay ¶
OnEndOfDay subscribes to events called when the end of a day was reached naturally. (without commands)
func (*Player) OnGameRulesLoaded ¶
func (player *Player) OnGameRulesLoaded(handler func(event *event.GameRulesLoaded))
OnGameRulesLoaded listens for the game rules to be loaded for a player. This happens when the player joins a game, regardless whether it's multi-player or single-player.
func (*Player) OnGameRulesUpdated ¶
func (player *Player) OnGameRulesUpdated(handler func(event *event.GameRulesUpdated))
OnGameRulesUpdated listens for game rule updates for a player. This event is called whenever a specific game rule is changed.
func (*Player) OnItemAcquired ¶
func (player *Player) OnItemAcquired(handler func(event *event.ItemAcquired))
OnItemAcquired listens to items acquired by the player, for example by picking items up or by getting items from a chest.
func (*Player) OnItemCrafted ¶
func (player *Player) OnItemCrafted(handler func(event *event.ItemCrafted))
OnItemCrafted subscribes to items crafted by the player.
func (*Player) OnItemDropped ¶
func (player *Player) OnItemDropped(handler func(event *event.ItemDropped))
OnItemDropped listens for items dropped on the ground by the player.
func (*Player) OnItemEquipped ¶
func (player *Player) OnItemEquipped(handler func(event *event.ItemEquipped))
OnItemEquipped listens for items equipped by the player. This includes armour, pumpkins, elytras and other items that may be worn.
func (*Player) OnItemInteracted ¶
func (player *Player) OnItemInteracted(handler func(event *event.ItemInteracted))
OnItemInteracted subscribes to interactions made using items by the player.
func (*Player) OnItemNamed ¶
OnItemNamed listens for items named by a player using an anvil.
func (*Player) OnItemSmelted ¶
func (player *Player) OnItemSmelted(handler func(event *event.ItemSmelted))
OnItemSmelted listens for items smelted by the player and taken out of the inventory.
func (*Player) OnItemUsed ¶
OnItemUsed subscribes to items used by the player.
func (*Player) OnMobInteracted ¶
func (player *Player) OnMobInteracted(handler func(event *event.MobInteracted))
OnMobInteracted subscribes to events called when the player interacts with a mob, in a way that has actually has a result.
func (*Player) OnMobKilled ¶
OnMobKilled listens for entities that were killed by the entity. Note that indirect killing methods such as drowning an entity, hitting off an edge, suffocating it etc. does not trigger the event.
func (*Player) OnPlayerMessage ¶
func (player *Player) OnPlayerMessage(handler func(event *event.PlayerMessage))
OnPlayerMessage subscribes to player messages sent and received by the client.
func (*Player) OnScreenChanged ¶
func (player *Player) OnScreenChanged(handler func(event *event.ScreenChanged))
OnScreenChanged listens for the screen of the player being changed. Note that this is not sent every time anything is changed on the screen, but rather when a player switches to a completely different screen.
func (*Player) OnScriptLoaded ¶
func (player *Player) OnScriptLoaded(handler func(event *event.ScriptLoaded))
OnScriptLoaded listens for scripts that are loaded by the player.
func (*Player) OnScriptRan ¶
OnScriptRan listens for scripts that are ran immediately after they are loaded. This event is called once immediately hen the player spawns, even though the script might still be running after that.
func (*Player) OnSignInToXBOXLive ¶
func (player *Player) OnSignInToXBOXLive(handler func(event *event.SignInToXBOXLive))
OnSignInToXBOXLive listens for the player signing into XBOX Live.
func (*Player) OnSignOutOfXBOXLive ¶
func (player *Player) OnSignOutOfXBOXLive(handler func(event *event.SignOutOfXBOXLive))
OnSignOutOfXBOXLive listens for the player signing out of XBOX Live.
func (*Player) OnSignedBookOpened ¶
func (player *Player) OnSignedBookOpened(handler func(event *event.SignedBookOpened))
OnSignedBookOpened subscribes to signed books opened by the player.
func (*Player) OnSlashCommandExecuted ¶
func (player *Player) OnSlashCommandExecuted(handler func(event *event.SlashCommandExecuted))
OnSlashCommandExecuted listens for commands executed by a player that actually existed. Unknown commands do not result in this event being called.
func (*Player) OnStartWorld ¶
func (player *Player) OnStartWorld(handler func(event *event.StartWorld))
OnStartWorld subscribes to events called when the player starts a world by clicking it in the main menu. It includes both servers and singleplayer worlds. The event provides no information about the world.
func (*Player) OnTeleported ¶
func (player *Player) OnTeleported(handler func(event *event.PlayerTeleported))
OnTeleported listens for teleportations done by the player, such as using the /tp command or throwing an ender pearl.
func (*Player) OnTransform ¶
func (player *Player) OnTransform(handler func(event *event.PlayerTransform))
OnTransform subscribes to transformations done to the player, usually sent by means such as teleporting.
func (*Player) OnTravelled ¶
func (player *Player) OnTravelled(handler func(event *event.PlayerTravelled))
OnTravelled subscribes to the player travelling to places.
func (*Player) OnVehicleExited ¶
func (player *Player) OnVehicleExited(handler func(event *event.VehicleExited))
OnVehicleExited listens for the player exiting a vehicle such as a minecart or a horse.
func (*Player) OnWorldGenerated ¶
func (player *Player) OnWorldGenerated(handler func(event *event.WorldGenerated))
OnWorldGenerated subscribes to events called when a player generates a new singleplayer world.
func (*Player) OnWorldLoaded ¶
func (player *Player) OnWorldLoaded(handler func(event *event.WorldLoaded))
OnWorldLoaded subscribes to events called when the player loads a world. This happens both when joining servers and singleplayer worlds, and happens directly after the StartGamePacket is called. The event supplies some of the data of this packet.
func (*Player) Position ¶
Position requests the position of a player and calls the function passed when a response is received, containing the position of the player.
func (*Player) Rotation ¶
Rotation requests the Y-Rotation (yaw) of a player and calls the function passed when a response is received, containing the rotation of the player.
func (*Player) Say ¶
Say broadcasts a message as the player to all players in the world of the player.
func (*Player) SendMessage ¶
SendMessage sends a message that only the player receives. Its behaviour is synonymous with fmt.Sprintf(), putting all parameters in the string using formatting identifiers.
func (*Player) Tell ¶
Tell tells the player a private message. Its behaviour is synonymous with fmt.Sprintf(), putting all parameters in the string using formatting identifiers.
func (*Player) UnsubscribeFrom ¶
UnsubscribeFrom unsubscribes from events with the event name passed. The handler used to handle the event will no longer be called.
func (*Player) UnsubscribeFromAll ¶
func (player *Player) UnsubscribeFromAll()
UnsubscribeFromAll unsubscribes from all events previously listened on. No more events will be received.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the main entry-point of the mcwss package. It allows interfacing with clients connected to it and provides methods to ease the use.
func NewServer ¶
NewServer initialises and returns a new server. If the configuration passed in was non-nil, that configuration is used. If nil is passed, the default configuration is used. (see config.go/defaultConfig())
func (*Server) OnConnection ¶
OnConnection sets a handler to handle new connections from players. This method must be used to interact with players connected.
func (*Server) OnDisconnection ¶
OnDisconnection sets a handler to handle disconnections from players. Note that when setting the handler, sending packets to the player will not arrive.
type World ¶
type World struct {
// contains filtered or unexported fields
}
World represents a world a player has joined. This might be either a singleplayer world, or a multiplayer server. Multiworld servers are treated as if they had only one world.
func (*World) Broadcast ¶
Broadcast broadcasts a message with optional parameters (operates using fmt.Sprintf) to all players in the world. The message is prefixed with '[External]'.
func (*World) DestroyBlock ¶
func (world *World) DestroyBlock(position mctype.BlockPosition)
DestroyBlock destroys a block at the position passed. It will show the block breaking particles and sounds that would normally be sent when destroying a block.
Source Files
Directories