Scripting

This page shows you how to script your very own gamemodes.

Writing a simple gamemode

Without any script loaded, any player who joins the game will only be allowed to spectate. Most of the game rules are scripted with Lua.

Sample gamemode

Below is an example of a sandbox gamemode where you spawn as a human with 5000 coins. It's a good starting point for making a new gamemode.

setup_default_game = dofile("scripts/modules/setup_default_game.lua")
simple_shop = dofile("scripts/modules/simple_shop.lua")
local shop = addSimpleShop()

-- Sandbox gamemode
Game:updateConfigs({
    gameMode = "Sandbox",
    gameDescription = [===[There is no specific aim with this gamemode.
Press B to open the shop.
You start with a lot of money!]===],
    friendlyFire = "true",
    spawnItems = "false",
})

-- Spawn players when they join the game
Event:addPeerReadyListener(function(peer)
    handleSpawnPeer(peer)
end)

-- Just returns an inventory with 5000 coins
function getHumanStartInventory()
    local inventory = {}

    table.insert(inventory, {
    type = "coin",
    quantity = 5000
    })

    return inventory
end

-- Spawns a peer as a human
function handleSpawnPeer(peer)
    local inventory = getHumanStartInventory()

    spawnPeerWithTimerAndCounter(peer, playerSpawnDelay, "Human", Level:getRandomSpawnPoint("playerSpawn"), "Respawning in", nil, inventory)
end

Executing

Save the above code sample as sandbox.lua next to your server.jar, then run the server with:

java -jar server.jar script="sandbox.lua"

Next Steps / More Examples

Please see Cheat Sheet for a list of useful Lua commands.

You can also view the official gamemode Lua scripts. Open the server.jar with an unarchiving tool to see the official Lua scripts inside the /assets/scripts folder.

Lua Reference

See the Lua Reference for a list of all the available commands.

Debugging (Mobdebug)

It is possible to use Mobdebug to step through the Lua scripts. I recommend using IntelliJ IDEA with the EmmyLua plugin.

  1. Install IntelliJ IDEA Community Edition (it's free)
  2. Download the EmmyLua plugin
  3. Open your folder that contains your Lua scripts
  4. Start the Lua Remote(Mobdebug) run configuration, it should be listening on port 8172
  5. Launch your server. The debugger should now connect to your listener, you can set breakpoints, step through the code and see the stack trace and variables.

Enabling debugger after starting server

For production servers it can be useful to have the debugger disabled by default but still have the option to enable it if we need it. This can be achieved by running this command in chat:

/lua dofile("scripts/modules/debugger.lua")

By default, the debugger is only enabled if the server is started in dev mode.

Socket (LuaSocket)

We also have support for the LuaSocket library (https://lunarmodules.github.io/luasocket/) through https://github.com/AlexanderSchuetz97/luajsocket. This can be used for socket connections through Lua.

JavaScript Scripting

We have JS scripting support using RhinoJS.

Note: It is not well supported yet since the Lua specific API's are not available yet.

Usage:

-- gamemode.lua
Game:log("Hello, world!")

// gamemode.js
Game.log("Hello, world!")

See sandbox.js for an example.