The package

The folder

A package is a folder whose name is the mod’s id. Perch loads packages from three places: the builtin set that ships with Perch, Steam Workshop subscriptions, and the package Perch Studio hands over on Run in Perch. The Workshop is the distribution channel; there is no mods folder to drop files into.

require reaches only .luau files in the package root. Other files are ignored by the loader.

mod.json

Pure data, no code. Widgets and settings are created in Luau, never here.

{
  "id": "steam-player-count",
  "title": "Steam Player Count",
  "version": "0.7",
  "api": 3,
  "author": "hlpdev",
  "description": "Live player counts for the Steam games you pick, one widget per game.",
  "entry": "main.luau",
  "preview": "preview.luau",
  "scopes": ["steam"],
  "palette": { "brand": "#66c0f4" }
}

Unknown keys are ignored by the loader; Perch Studio’s validator flags them, which is what you want while editing.

The palette

Named colours declared here can be remapped by a user’s theme; hex literals in trees cannot.

ui.text { text = f.count, color = "@brand" }
ui.box { bg = "@brand", radius = 6 }

The entry file

The loader runs one Luau file, once, when the package loads. It creates objects and connects handlers, and returns nothing.

--!strict
local displays = require("displays")

perch.settings.declare {
  trend = settings.toggle("Show the trend line", { default = true }),
}

local w = widget.new { id = "card", label = "My card", urgency = urgency.ambient,
  fields = { count = field.string("-") } }
w:place(surface.page, displays.card)
w:register()

local poll = timer.new(60000)
poll.on_fire:connect(function() refresh() end)

perch.on_start:connect(function()
  w:present({ count = "-" })
  poll:start()
end)

Nothing is wired by name: a function called on_start that is never connected to perch.on_start is dead code. The entry runs under the same budget as a handler; keep it to declarations and connections.

The nine globals (perch, ui, field, settings, widget, timer, key, surface, urgency) are injected before the entry runs. Never require them, and do not shadow them with locals.

require

require("name") loads <package>/name.luau once and caches the result. Names are letters, digits and underscores; there are no subfolders. displays.luau conventionally exports a fields_t type and returns a table of display functions:

--!strict
export type fields_t = { game: field_ref_t<string>, count_text: field_ref_t<string> }

return {
  card = function(f: fields_t): node_t
    return ui.column { gap = ui.gap.xs, flex = 1, pad = { 4, 10, 4, 10 },
      ui.text { text = f.game, role = ui.role.h2 },
      ui.text { text = f.count_text, role = ui.role.huge, size = 34, color = ui.color.accent_warm },
    }
  end,
}

preview.luau

An optional script that gives the Workshop item a real thumbnail. Perch Studio runs it with no scopes granted and renders what it returns through the real renderer, in that surface’s chrome.

--!strict
local displays = require("displays")

return {
  surface = surface.page,
  fields = displays.schema(),
  display = displays.card,
  data = { game = "Team Fortress 2", count_text = "1,436,921" },
}

fields is the schema the display binds against, display the function, data the payload, validated against fields. See Testing and publishing.

Glyph files

Vector art lives in .svg files under the package, referenced from ui.shape:

ui.shape { src = "glyphs/phone.svg", w = 13, h = 13 }
ui.shape { pick = f.icon, srcs = { sun = "glyphs/sun.svg", rain = "glyphs/rain.svg" }, w = 34, h = 23 }

At load Perch compiles each file to sanitized path data. Only <path> elements and the root viewBox survive; fill, stroke, stroke-width, stroke-linecap and stroke-linejoin are kept, and currentColor becomes current. Export shapes as paths: a file with no <path> fails with svg holds no <path> elements (paths only: convert shapes to paths on export); a file without a viewBox with svg needs a viewBox.

What ships

A published Workshop item is one file, mod.pak: every package file under its package-relative path, with the .luau files stored as source. Studio compiles each file while packing as a syntax check and stops the publish on a file that does not parse. Perch compiles the source again at load. Bytecode is never accepted from a Workshop package.

What fails a load

Every failure is contained to the package and printed on its card under Settings, Installed mods, and in the Studio log window.