Example mods

Every example below is a complete mod. Copy the files into mods/<id>/, set enabled = true, and run ./rsmm apply. Source lives in docs/ExampleMods/.

Pick a starting point

Hello (Lua) The minimal SDK mod: log on ready, count ticks.

Magic item (data) A custom magical object via a [[content]] block — no code.

Hello — smallest Lua mod

The minimum to prove the loader + SDK work: log once when the game is ready and count ticks. No assets, just manifest.toml + init.lua.

manifest.toml
init.lua

[mod]
id          = "ExampleSdkHello"
name        = "Example: SDK hello"
version     = "0.2.0"
author      = "rsmm-examples"
description = "Smallest possible mod using SDK v3. Logs once on ready + bumps a counter every tick."
enabled     = false
sdk_version = ">=3.0,<4"

-- Smallest possible mod using SDK v3.
-- Demonstrates: require "rsmm", R.health.checkpoint, R.on, R.log, R.kv.

local R = require "rsmm"
R.health.checkpoint("per_mod:ExampleSdkHello")

R.on("ready", function()
    R.log("[Hello] loaded; SDK ready")
end)

R.on("tick", function()
    local n = R.kv.inc("tick_count")
    if n == 1 or n % 20 == 0 then
        R.log("[Hello] tick #" .. n)
    end
end)

Magic item — declarative content

A custom magical object, cloned-and-patched from a vanilla rare item. No code — the [[content]] block tells the SDK to cook a new item end-to-end.

[mod]
id          = "ExampleMagicItem"
name        = "Example: Magic Item"
version     = "0.3.0"
author      = "rsmm-examples"
description = "Declarative custom magical object via [[content]] block."
enabled     = false
sdk_version = ">=3.0,<4"

[[content]]
kind        = "item"
id          = "Iron_Crab_Hide"
base        = "Common/Armor_Per_Object"
name        = "Iron Crab Hide"
description = "Bonus armor per rare object collected."
rarity      = "Common"

The kind = "item" builder resolves the base donor, cooks the new item, and rsmm apply syncs the game-side registration (versiondef + UsedRscCache). You write the manifest; the SDK does the rest. See Authoring mods for every [[content]] kind.

Apply any example

Copy the example folder into your mods/ directory.
Set enabled = true in its manifest.toml.
Apply and launch:
Terminal window
```
./rsmm apply
./rsmm run
```

More examples in the repo

ExampleSeedPin — pin the run RNG seed via the R._internal escape-hatch + per-mod config (R.config.get).
ExampleSdkAll — exercises the full SDK surface.
HyperAggro — a gameplay tweak mod.

Browse them all in docs/ExampleMods/.