Scripting Examples

Scripting: Complete Examples

Here are two complete, copy-pasteable examples showing how to write a custom Provider script and a custom Automation script.

Example 1: Custom Provider (Purpur)

This example models a provider for the Purpur server (a Paper fork). It lists versions from Purpur's REST API, downloads the build jar, and returns the launch spec.

-- purpur.lua — A custom provider for the Purpur server (a Paper fork).
--
-- The user must grant the `network` permission.

meta = {
  id          = "purpur",
  name        = "Purpur",
  website     = "https://purpurmc.org",
  description = "A drop-in Paper fork with extra configuration and gameplay options.",
  version     = "1.0.0",
  author      = "you@example.com",
  mod_layout  = "plugins",                 -- Purpur is Paper-compatible: plugins/ folder
  permissions = {
    { kind = "network", reason = "Download Purpur's build manifest and the server jar." },
  },
}

local API = "https://api.purpurmc.org/v2/purpur"

-- versions() -> newest-first list of MC versions Purpur builds for.
function versions()
  local project = jhmc.http_json(API)
  local out = {}
  -- The API returns versions oldest-first; reverse for newest-first.
  for i = #project.versions, 1, -1 do
    out[#out + 1] = project.versions[i]
  end
  return out
end

-- install(ctx) downloads the latest Purpur build for ctx.version into ctx.dir
-- and returns the launch spec.
function install(ctx)
  ctx.step("install.progress.resolving_version", -1)

  -- Resolve the latest build for the chosen version.
  local meta_for_ver = jhmc.http_json(API .. "/" .. ctx.version)
  local build = meta_for_ver.builds.latest
  if not build then
    error("version not found: " .. ctx.version)
  end

  local detail = jhmc.http_json(API .. "/" .. ctx.version .. "/" .. build)
  local jar_url = API .. "/" .. ctx.version .. "/" .. build .. "/download"

  ctx.step("install.progress.downloading_server", 0)
  ctx.log("Downloading purpur-" .. ctx.version .. "-" .. build .. ".jar")
  jhmc.download(jar_url, { dest = "server.jar" })

  if detail.md5 then
    ctx.log("published md5: " .. detail.md5)
  end

  ctx.step("install.progress.done", 1)
  
  -- Return the Launch Specification
  return {
    java_major = jhmc.java_major_for(ctx.version),
    args       = { "-jar", "server.jar", "nogui" },
  }
end

Example 2: Automation (Auto-Restarter)

This example shows an automation script that monitors a server's console for an OutOfMemoryError crash and schedules a restart automatically.

-- restart_on_crash.lua — An automation script to restart crashed servers.

meta = {
  id = "auto_restart",
  name = "Auto Restarter",
  permissions = {
    { kind = "console_read", reason = "Detect crashes from the console" },
    { kind = "server_control", reason = "Restart server on crash" },
    { kind = "schedule", reason = "Delay restarts" }
  },
}

function register()
  local target_server = "my-survival-server"

  on_log(target_server, function(line)
    -- Look for a common Out of Memory crash signature
    if string.find(line, "OutOfMemoryError") then
      print("OOM detected on " .. target_server .. "! Restarting in 10s...")
      
      -- Delay the restart slightly to allow the server to fully shut down
      schedule(10, function()
        server.restart(target_server)
      end)
    end
  end)
end

Navigation

• Back to the Scripting Hub