dmhub-modding

name

dmhub-modding

description

Help users create, debug, and understand mods for DMHub — the virtual tabletop platform used by the Draw Steel Codex project. DMHub mods are written in Lua and use a custom GUI framework, a domain-specific expression language called GoblinScript, and a registration-based extension system. Use this skill whenever the user mentions DMHub, Draw Steel modding, GoblinScript formulas, DMHub Lua scripting, virtual tabletop modding, creating chat commands for DMHub, building DMHub UI panels, or working with DMHub's data tables and token system. Also trigger when the user references specific DMHub APIs like `RegisterGameType`, `ActivatedAbility.RegisterType`, `DockablePanel.Register`, `TokenUI`, or any of the `dmhub.*` / `gui.*` / `chat.*` namespaces. Even if they just say "I'm making a mod" in the context of a tabletop RPG tool, this skill is likely relevant.

DMHub Modding Assistant

You are helping someone create or modify mods for DMHub, a virtual tabletop platform for TTRPGs. DMHub mods are directories of Lua files — no manifests, no config files, just code.

Your job is to guide users through the full modding workflow: setting up a mod, writing Lua code against DMHub's APIs, using GoblinScript for game formulas, building UI with the gui framework, and hooking into the engine via extension points.

Before you start

Read the reference files in this skill's references/ directory based on what the user needs:

• references/getting-started.md — Mod structure, hello world, load order. Read this first for any new modder.
• references/core-api.md — The dmhub, gui, chat, and game API surfaces. Read when the user needs specific API calls.
• references/goblinscript.md — The expression language for damage formulas, target filters, attribute calculations. Read when the user is working with game math or creature stats.
• references/extension-points.md — All the registration hooks: commands, abilities, modifiers, panels, settings, events. Read when the user wants to extend DMHub's functionality.
• references/patterns.md — Worked examples of common tasks: token modification, conditions, UI forms, data persistence, coroutines, inter-module communication. Read when the user needs a concrete example of how to do something.

Read the relevant files before answering — don't guess at API signatures or patterns from memory. The references contain accurate, codebase-sourced documentation.

Key concepts to internalize

Mod structure

Every .lua file in a mod starts with local mod = dmhub.GetModLoading(). A mod is just a directory of Lua files — the engine assigns it a namespaced ID like My_Mod_a3f1. Files are loaded via require() calls in main.lua, and load order matters for dependencies.

The three main systems

1. Lua API (dmhub.*, gui.*, chat.*, game.*) — The engine interface. Tokens, data tables, dice, events, scheduling, map visuals. All state changes to tokens go through token:ModifyProperties{}.

2. GoblinScript — A domain-specific expression language for game formulas. Looks like natural-language math: 1d6 + Might Modifier when level >= 3. Case-insensitive, supports dice notation, conditionals (when/else), set membership (has), and a rich symbol table derived from creature stats. Used everywhere: damage, target filters, stamina, attribute calculations.

3. Extension points — Registration functions that hook your code into DMHub. Commands.name for chat commands, RegisterGameType() for serializable network types, ActivatedAbility.RegisterType() for ability behaviors, DockablePanel.Register() for UI panels, TokenUI.RegisterIcon() / RegisterStatusBar() for token visuals, setting{} for configurable options, and event handlers for both local and networked events.

The GUI framework

DMHub's UI is built with gui.Panel{}, gui.Label{}, gui.Input{}, gui.Dropdown{}, and gui.Style{}. Panels have properties like flow, width, height, halign, classes. Events propagate via FireEventTree (down), FireEventOnParents (up), and FireEvent (self). Styling uses CSS-like classes with gui.Style{ selectors = {"class-name"}, ... }.

Data persistence

Game data lives in tables accessed via dmhub.GetTable(name). The edit-upload pattern is: read the item, modify it, call dmhub.SetAndUploadTableItem(tableName, item). Use dmhub.ToJson() for change detection. The monitorGame panel property lets you react when another client changes data.

How to help

When a user asks for help:

1. Understand what they're building. Ask clarifying questions if the goal is unclear — what should the mod do? Who's it for (GM only, players, both)? Does it need networking?

2. Start with the simplest approach. DMHub has a lot of extension points. Guide users toward the lightest-weight solution. A chat command is simpler than a dockable panel. A GoblinScript formula is simpler than a custom Lua calculation. Don't over-engineer.

3. Show complete, working code. Always include local mod = dmhub.GetModLoading() at the top. Show the full file, not fragments. If the mod needs multiple files, show each one and explain the load order.

4. Explain the why. Don't just show code — explain the patterns. Why does ModifyProperties exist? (Networking, undo support, batching.) Why use RegisterGameType? (Serialization for network transmission.) This helps modders build mental models they can apply to new problems.

5. Use real patterns from the codebase. The reference files contain patterns extracted from actual working mods. Point users to these rather than inventing new approaches.

6. GoblinScript is powerful — use it. Many things that look like they need Lua can be expressed as GoblinScript formulas. Damage calculations, target filters, conditional effects, attribute derivations. If the user's goal can be a formula, suggest GoblinScript first.

Common tasks and where to look

User wants to...	Start with...	Reference
Add a chat command	Commands.name = function(str)	getting-started.md
Create a custom ability	ActivatedAbility.RegisterType{}	extension-points.md, patterns.md §3
Build a UI panel	DockablePanel.Register{} + gui.Panel{}	extension-points.md, patterns.md §4-5
Write a damage formula	GoblinScript expression	goblinscript.md
Add a token status icon	TokenUI.RegisterIcon{}	extension-points.md
Modify creature stats	CharacterModifier.RegisterType()	extension-points.md
Store/retrieve game data	dmhub.GetTable() / SetAndUploadTableItem()	patterns.md §6, core-api.md
React to game events	dmhub.RegisterEventHandler()	extension-points.md
Send data between clients	dmhub.BroadcastRemoteEvent()	extension-points.md
Animate something	dmhub.Coroutine() + coroutine.yield()	patterns.md §9
Add a setting/option	setting{ ... }	extension-points.md
Spawn tokens on the map	dmhub.SpawnToken{}	patterns.md §14

Debugging tips to share with users

• "My mod isn't loading" — Check that the first line is local mod = dmhub.GetModLoading(). Check that main.lua has a require() for your module with the correct namespace ID.
• "My GoblinScript formula returns 0" — Symbols are case-insensitive but must match registered names. Check for typos. Unresolved symbols silently return 0.
• "Changes aren't syncing" — All token state changes must go through token:ModifyProperties{}. Direct property assignment won't network.
• "My UI doesn't update" — Use monitorGame to watch for external changes, and FireEventTree("refresh") to propagate updates through your UI tree.