Skip to content

Latest commit

 

History

History
183 lines (124 loc) · 9.29 KB

README.md

File metadata and controls

183 lines (124 loc) · 9.29 KB

wsmc

WebSocket proxy to Minecraft servers

Allows you to write Minecraft clients connecting over WebSockets

Proxy Usage

WSMC for Java

Install Maven and build with:

mvn clean install

Current protocol support: 1.8.9, 1.9 snapshot 15w40b (details)

For Bukkit servers

To load the plugin with software implementing the Bukkit API, simply copy the jar into the plugins directory. Tested with:

  • Glowstone++ - an open source server for Minecraft and Bukkit
  • Spigot - a modification to Minecraft implementing Bukkit
  • Junket - partial implementation of Bukkit (no server)

For Sponge servers

WSMC also includes Sponge API support, simply copy the jar to the mods folder. For use with:

For other servers (standalone mode)

If your server does not support Bukkit or Sponge plugins, then WSMC can be ran standalone from the command-line:

java -jar target/wsmc*.jar 0.0.0.0 24444 localhost 25565

Tested with:

  • vanilla server

User authentication is not supported in this mode.

Configuration

The proxy must be able to connect to the Minecraft server without authentication, i.e., in "offline mode". This does not mean the Minecraft server has to be remotely accessible without authentication (although that is a sufficient condition), it can be behind another proxy in "online mode" such as BungeeCord. See below for how to setup authentication in WSMC.

Configure the plugin in plugins/WSMC/config.yml (Bukkit) or config/wsmc.conf (Sponge):

  • websocket: configuration options for the WebSocket (WS) server side

  • bind-address (): the network address to listen for incoming connections on

  • bind-port (24444): the TCP port to serve the WebSocket and HTTP server on

  • external-scheme (http), external-domain (), and external-port (24444): used to construct the externally-accessible URL for users to click on for accessing the web client. You'll want to set the domain to your externally-facing IP or domain name, and the port may need to be changed if you forward the bind-port. If empty or "auto", will try to auto-detect.

  • minecraft: configuration options for the Minecraft (MC) client side

  • connect-address (localhost): Minecraft server to connect to, usually this will be localhost if the WSMC proxy is running on the same system as the Minecraft server.

  • connect-port (25565): Minecraft server port, if available this will default to the port configured in Bukkit, or the Minecraft default of 25565

  • announce-on-join (true): when new users connect, send them their web login link

  • allow-anonymous (false): allow any user to login as anyone (intended for testing only)

Authentication

By design, wsmc does not handle user passwords. Several techniques to authenticate are available:

First login through the regular Minecraft client: by default, the wsmc/Java plugin will announce "Web client enabled (click to view)" to each user who logs in. You can click this link to go to a per-user URL to login to the web client. The link can be saved and reused as long as the server is up.

If desired, the join message can be disabled by setting announce-on-join: false in plugins/WSMC/config.yml. Users can manually retrieve this URL by typing the /web command. The URL contains your username and a per-user key; it should be kept secret or users will be able to impersonate each other.

Manual setup by administrator via console: an administrator can type the /web username command to create a new key for a given username. The URL can be distributed however you like, and will be used to login with the specified username. Useful for testing with multiple users.

No authentication: setting allow-anonymous: true will disable authentication completely. Use this setting with caution, as it allows logging in as any user.

WSMC for JavaScript (Node.js script)

The first version of WSMC was written in JavaScript. It is still functional but lacks authentication and requires installing Node.js. Java-based servers will likely find WSMC/Java more useful, but WSMC/JavaScript is also provided as an alternative.

To use it, run:

node wsmc.js

Options default to:

--wshost=           websocket host to listen on
--wsport=24444      websocket port to listen on
--mchost=localhost  minecraft host to connect to
--mcport=25565      minecraft port to connect to
--prefix=webuser-   prefix for usernames of websocket-connecting users

When the proxy receives a WS connection, it will connect to the MC server, perform the handshake, negotiate encryption, then pass raw binary packets between the WS client and MC server using websocket-stream.

Limitation: WSMC/JavaScript doesn't perform user authentication. Users currently can connect with no password and they will be given a username beginning with 'webuser-' followed by a number.

Client Example

mcwebchat - a simple web-based chat client

The WS client is responsible for decoding the packets received and encoding packets sent. Protocol encryption is automatically handled by the proxy, but clients still need to unpack/pack the binary data transmitted over the wire for efficiency.

A nice benefit of using WebSockets is that the protocol is already message-based, so the client doesn't have to concern itself with packet lengths (each WS message contains exactly one MC packet).

WSMC Protocol Differences

Although WSMC proxies the MC protocol over WS mostly unscathed, there are some changes to cope with the WS environment:

MC packets have a varint length field prefix; WSMC packets lack this field because WS is already message-based and it would be redundant. But only in one direction, currently (TBD).

MC login uses a complicated handshake phase; WSMC begins with the WS client sending the username and login key in the initial packet (separated by a colon, or only the username if logging in without authentication), and then immediately switching to the login phase.

MC's login success packet contains fields for the UUID and username. WSMC extends the username field with a \0 byte followed by the JSON response from the server list ping. This information is included because WS otherwise has no mechanism to retrieve the server ping information.

Project Ideas

Now that your Minecraft server is accessible via WebSocket, what can you do with it? The mcwebchat example isn't very useful, so here are a few more ambitious project ideas possible with a WSMC backend, for anyone up for the challenge:

  • (Medium) A viewer-only graphical web-based Minecraft client. Allow the player to walk around, browse the server but not interact. Server owners could place this client on their website, as a quick preview for prospective players on their server, to easily check out without having to fire up the game itself. No authentication needed since the viewer would be anonymous and read-only, but could possibly benefit from packet filtering and/or server-side permissions to restrict unintentionally allowing clients to modify the server in any way.

  • (Hard) A fully-functional interactive 3D web-based Minecraft client, supporting most of the features of the game. Likely needs authentication to be useful, but the idea would be players could casually join through the web without having to keep up with Java updates etc. and using the official Minecraft client; the web-based client should be functional enough to allow a reasonable level of ordinary gameplay. Including interacting with the world and any feature you might expect.

  • (Extreme) A highly customizable flexible modular interactive 3D web-based Minecraft client, with support for adding new game content. Taking the above idea a step further, turning it into the ultimate gameplay experience. Instead of messing with installing modifications to Minecraft, you could use this hypothetical web-based client and it would deliver everything you need through the web server. No need for the player to concern themselves with updates since it all comes from the web and is controlled by the webmaster, and it would even be safer since like all webpages it runs in the browser sandbox. May or may not be feasible, but could be interesting. Compare to: Feed the Beast, Technic Platform, etc.

For a very incomplete WebGL/voxel.js-based client which doesn't implement any of these ideas or work very well at the moment, but could be a good place to start or for reference purposes, see voxel-clientmc (any help welcome).

License

MIT