Your first resource

A resource is a folder under resources/ that contains a manifest and Lua scripts. This page walks through hello, a resource bundled with the server that greets each player who joins and adds a /heal command.

The manifest

Create resources/hello/resource.toml. name must match the folder name; the scripts run in order in the resource's own Lua VM.

name = "hello"
type = "gamemode"

[server]
scripts = ["server.lua"]

An event handler

Create resources/hello/server.lua. An event handler runs every time the server raises its event; passing dlmp.root as the source subscribes to the event for every player.

dlmp.add_event_handler("player_connect", dlmp.root, function(player)
    player:send_message("Welcome, " .. player:name() .. "! Type /heal to restore your health.")
end)

player is a handle: its methods read and change that player's state on the server at the moment you call them. See Player for the full list.

A command

A player command is a chat line that starts with /. The handler receives the player and the words that follow the command name, each as a string.

dlmp.add_command_handler("heal", function(player, amount)
    local health = tonumber(amount) or 100
    local ok, err = player:set_health(health)
    if ok then
        player:send_message("Health set to " .. health .. ".")
    else
        player:send_message("Cannot heal: " .. err)
    end
    return true
end)

Two conventions in this handler apply to the whole API:

• An action that the server can refuse returns true on success, or nil and an error message. /heal 500 fails because health cannot exceed 200, and the player sees the reason. Passing an argument of the wrong type is a bug in the script and raises an error instead; Errors and the sandbox explains the difference.
• Returning true marks the command as handled. Otherwise the server tries the next handler, and if no handler takes the command, the player sees Unknown command.

Run it

While the server is running, start the resource from the server console:

resource start hello

After editing the script, run resource reload hello to load the change; the reload starts from a clean state. To start the resource with the server, add it to the startup list in server.toml:

[resources]
startup = ["demo", "hello"]

Then join the server and type /heal 50.

Editor support

resources/.types/dlmp.lua describes the whole API for the Lua Language Server, and .luarc.json at the repository root configures the language server to use it. Open the repository in an editor with the Lua extension to get completion and type checking in your scripts.

Next steps

• Resources: the manifest, modules, dependencies, storage and the resource lifecycle.
• Events, commands and timers: every event and the order in which handlers run.
• Guides: chat, dialogs, the HUD and storage, with code from the bundled resources.
• The demo resource: a complete freeroam game mode.