MC COAL is an open-source project aimed at helping to build and maintain community around multi-player Minecraft worlds. It can also optionally provide powerful and simple Minecraft multi-player server hosting and management.
COAL is a web application. It is written in python and runs on the Google Cloud Platform. It is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3
- Server status display including in-game time, weather, and currently logged in players
- Live chat and searchable chat history
- Chat into the game from the web
- Player session information
- Share screen shots
- Detailed and well-documented API
- Easily host and manage powerful multi-player servers on Google Compute Engine
- Works with vanilla Minecraft multi-player servers
- A free Google Cloud Platform account.
- Optional But Recommended: A free Github account.
- Create a Google Cloud Project for your new COAL installation. Take note of the Project ID you select (e.g. [my-project-id]).
- Optionally, in
Settings
, enable billing. COAL should be able to run comfortably under the daily free App Engine quota for most relatively small, lightly-populated worlds. - Fork, clone, or download the MC COAL code repository. Make sure any new fork or clone is a private repository as it will contain sensitive information (like the
main_SECRET_KEY
).
Note
The master/trunk of the MC COAL code repository will always contain the latest tagged, stable release. Ongoing (potentially unstable) development will be done on branches.
- Change the application name (i.e.
mc-coal
) in the first line of your repository's app.yaml to the Project ID you created above. - Update your installation settings in your repository's appengine_config.py file:
- Change the
main_SECRET_KEY
value to a unique random string. You can use this random.org link to generate a unique string value.- Change the
main_TITLE
andmain_DESCRIPTION
to strings that are appropriate for your COAL installation.- You do not have to change
oauth_SECRET_KEY
oroauth_TOKEN_EXPIRES_IN
. The defaults will work just fine.
- Complete the sub-steps below if you intend to host worlds on Google Compute Engine:
- In
Settings
enable billing if you haven't already. There is no daily free Google Compute Engine quota.- In
APIs
, make sure thatGoogle Compute Engine
,Google Cloud Storage
andGoogle Cloud Storage JSON API
areON
.- In
Permissions
make note of the Google Compute Engine service account email address. This should be of the form[project number]@developer.gserviceaccount.com
or[project number]@project.gserviceaccount.com
. Also, make sure there is an entry for[my-project-id]@appspot.gserviceaccount.com
. If it isn't there, add it as a owner member.- Add the Google Compute Engine service account email address to the
acl
section of queue.yaml. When finished, the file should look something like thisqueue: - name: default rate: 5/s - name: controller mode: pull acl: - user_email: 1234567890@developer.gserviceaccount.com
- Deploy your modified code in either of two ways:
Use the Push-to-Deploy Release Pipeline to deploy automatically from your github repository.
- Finish the steps under Setting up a Release Pipeline
Note
You do not have to complete Step 1 (install Git on your local system) if you intend to deploy only from a Github-hosted fork of the MC COAL code repository.
- Click the "Connect to a repository hosted on Github" button.
- After authenticating with github, choose the clone or fork of the repository you created in step 3 above.
- Choose the "Deploy Source Only" option.
- Optionally enter your email address to receive status updates for your deployments.
- Make a change to any file in your repository (for instance, add a blank line or comment to appengine_config.py) and save/push the change. This should cause google to initiate a deploy. If you entered your email address when setting up the Release Pipeline you should get an email when the deploy completes.
If you are familiar with Google Cloud Platform python development, feel free to use the App Engine python developer tools
- After the deployment has completed, browse to your COAL administrator page at
https://[my-project-id].appspot.com/admin
.
Note
It may take a few minutes after an initial successful deployment for database indexes to build. If you get a 500 error response when browing your COAL site right after deployment, you might have to wait a few minutes for the indexes to finish building.
Warning
For bootstrapping purposes, the first user to request this page is made an administrator, so make sure to do this as soon as possible.
Next, you'll set up your minecraft world(s). There are two options: let your COAL host your world on Google Compute Engine (easy!) or host your world elsewhere (more work for you!). You can mix both kinds of hosted worlds on a single COAL install.
- Define a new minecraft version in
Admin/Define New Minecraft Version/URL
. Enter a version name (i.e.1.7.10
) and the URL where the Minecraft Server JAR for that version can be downloaded (i.e.https://s3.amazonaws.com/Minecraft.Download/versions/1.7.10/minecraft_server.1.7.10.jar
).
Note
A list of all available versions and server JAR download links is available at mcversions.net. COAL has been tested with versions as far back as 1.4.7.
- Create a new server in
Admin/Create GCE-Hosted World
. Then hit the play button to start the server. This can take a few minutes if a GCE instance has to be started up for the first time. - When the world status is "Playing" the IP address of the server will be shown. Use this IP address to connect your minecraft client to the new world.
- Play! No additional infrastructure set up needed.
- Additional administrator settings are available in
Admin/Configure
. Here you can modify settings such as the type of machine instance to use (which determines the speed of the CPU and amount of memory available), the size of the disk (larger disks are faster), the number of saved game versions to keep in the cloud, and whether to use a static IP address.
Note
Changes made on the Admin Configuration page won't be live until a new GCE instance is started. To shut down the currently running instance, click the "Kill Instance" button on the
Admin
page. To start a new instance, hit "Play" for one of your worlds.Warning
Make sure all worlds are paused before killing the instance. Failure to do so may result in corrupted world files. Note that large worlds can take a few minutes to shutdown and save.
If you already have a Minecraft multi-player world running on a UNIX-based server you can connect it to your COAL.
The following libraries are required to be installed on the server that is hosting your world.
- Create a new directory called
mc-coal
in your minecraft server's directory (the one withserver.properties
). - Download the following files from your COAL into the new
mc-coal
directory:
wget https://[my-project-id].appspot.com/mc/timezones.py -o timezones.py wget https://[my-project-id].appspot.com/mc/mc_coal_agent.py -o mc_coal_agent.py
- Download the following files from your COAL into your minecraft server's directory
wget https://[my-project-id].appspot.com/mc/log4j2.xml -o log4j2.xml wget https://[my-project-id].appspot.com/mc/mc-start.sh -o mc-start.sh wget https://[my-project-id].appspot.com/mc/mc-stop.sh -o mc-stop.sh
- Create a new COAL world by clicking the
Admin/Create External-Server-Hosted World
and note theAgent Client ID
andAgent Secret
. - On your Minecraft server host, in the
mc-coal
directory, runmc_coal_agent.py
with thecoal_host
,agent_client_id
, andagent_secret
for your server:
[~/minecraft-server/mc-coal] $ python mc_coal_agent.py --coal_host=[my-project-id].appspot.com --agent_client_id=mc-coal-agent-12345 --agent_secret=ow9mLT8rev1e8og5AWeN1TyBM7EXZYiCntw8dj4d 2014-01-01 23:00:01 : main INFO Monitoring '../server.log' and reporting to '[my-project-id].appspot.com'...
- Edit the java configuration parameters within the mc-start.sh script as desired.
- Start the minecraft server with the
mc-start.sh
script:
[~/minecraft-server] $ ./mc-start.sh 2014-01-21 22:15:09,540 DEBUG Generated plugins in 0.000023000 seconds ... 2014-01-21 22:15:09,588 DEBUG Shutting down OutputStreamManager SYSTEM_OUT 2014-01-21 22:15:09,588 DEBUG Reconfiguration completed
- To stop the minecraft server later, use the
mc-stop.sh
script:
[~/minecraft_server] $ ./mc-stop.sh Stopping MineCraft Server PID=5989 2014-01-22 22:12:19,540 DEBUG ServletContext not present - WebLookup not added 2014-01-22 22:12:19,541 DEBUG Shutting down FileManager server.log MineCraft shutdown complete.