Tutorial 1 - Build a shed

By the end you’ll have a small mod that adds a “Build Shed” option to the inventory context menu, opens the framework’s placement UI, and lets the player drag a footprint, paint walls and a floor, and build a real, lit, persisted shed - consuming planks, validated, and multiplayer-safe.

This is the RCSFExampleShed example, explained.

Prerequisites

  • Project Zomboid Build 42.13+.

  • A mod skeleton (mod.info + media/lua/). If you don’t have one, scaffold any empty B42 mod first.

Step 1 - Declare the dependency

In your mod.info:

name=My Shed Mod
id=MyShedMod
require=RCStructureFramework

require= makes the game load the framework before your mod, so require("RCStructureFramework") works.

Step 2 - Register the structure and pieces (shared)

Create media/lua/shared/MyShedMod/Shed.lua. This runs on both client and server.

media/lua/shared/MyShedMod/Shed.lua
 1local RCSF = require("RCStructureFramework")
 2
 3local Shed = {}
 4Shed.STRUCTURE_ID = "MyShedMod_Shed"
 5
 6-- This shed has no door/window frames, no blueprints, and pays from inventory,
 7-- so we switch off three auto-systems we don't need. (Optional; safe to omit.)
 8RCSF.disable("spritePatcher")
 9RCSF.disable("plannedConstructions")
10RCSF.disable("materialContainers")
11
12RCSF.Registry.registerStructure({
13    id                = Shed.STRUCTURE_ID,
14    roomName          = "MyShedRoom",        -- a real, lit, persisted IsoRoom
15    useGenericBuilder = true,                 -- the built-in per-piece builder
16    materialSource    = "raw",                -- pay from the player's inventory
17    variants          = { default = true },
18    editor            = { allowCells = true, pieceTypes = { "wall", "floor" } },
19    validation        = { useDefaults = { "noEmptyPlan", "noOverlap", "slotKindCompatible" } },
20})
21
22RCSF.Registry.registerPieces(Shed.STRUCTURE_ID, {
23    { spriteName = "walls_exterior_wooden_01_0", category = "wall", pieceType = "wall",
24      categoryGroup = "wall", materialRequirement = { fullType = "Base.Plank", count = 2 } },
25
26    { spriteName = "floors_exterior_natural_01_0", category = "floor",
27      categoryGroup = "floor", materialRequirement = { fullType = "Base.Plank", count = 1 } },
28})
29
30return Shed

What each part does:

  • roomName turns the finished shed into a real room - so lighting and room detection work. Omit it for a wall-only structure.

  • materialSource = "raw" + each piece’s materialRequirement means a wall costs 2 planks, a floor 1, taken from the builder’s inventory.

  • validation.useDefaults rejects empty plans, overlapping pieces, and illegal door/window slots. (We have no doors here, but slotKindCompatible is cheap insurance.)

  • The three RCSF.disable(...) lines are a subset opt-out - purely an optimization for a mod that doesn’t use those systems.

Tip

Don’t have these exact sprite names? Use the in-game tile picker (debug mode) to find a wall and floor sprite, and swap them in.

Step 3 - Open the builder (client)

Create media/lua/client/MyShedMod/OpenBuilder.lua. This is client-only - the UI is presentation; the build itself runs server-side through the framework’s timed action.

media/lua/client/MyShedMod/OpenBuilder.lua
 1require("RCStructureFramework/PlacementUI")     -- loads the RCStructurePlacementUI panel
 2local Shed = require("MyShedMod/Shed")
 3
 4local function onFillInventoryContextMenu(playerIndex, context, items)
 5    local player = getSpecificPlayer(playerIndex)
 6    if not player then return end
 7    context:addOption("Build Shed", nil, function()
 8        -- (structureId, playerIndex, character, container)
 9        RCStructurePlacementUI.open(Shed.STRUCTURE_ID, playerIndex, player, nil)
10    end)
11end
12
13Events.OnFillInventoryObjectContextMenu.Add(onFillInventoryContextMenu)

For clarity this adds the option to every inventory item. A real mod would gate it on a specific kit/blueprint item (pass that item as the 4th container argument).

Step 4 - Try it

  1. Enable My Shed Mod and RCStructureFramework in the mod list, start a world.

  2. Make sure you’ve got a stack of planks.

  3. Right-click any inventory item → Build Shed.

  4. Drag a footprint, paint the walls and floor, and confirm.

You’ll watch the timed action build it plank by plank, get a real room (try a light switch inside after dark), and - on a server - see it appear for every other player.

What you have

Without writing any of it yourself: footprint selection, a paint UI with live material and validation feedback, atomic build-or-rollback, runtime room creation, lighting, and full multiplayer sync.

Next