Help users understand, write, and debug GoblinScript formulas, or expose new fields to GoblinScript from Lua. Use when the user mentions GoblinScript, creature formulas, damage formulas, target filters, ability costs, prerequisite expressions, custom attributes, RegisterGoblinScriptField, RegisterSymbol, EvalGoblinScript, ExecuteGoblinScript, or the Character Inspector panel. Also trigger when the user asks "how do I make a formula for...", "how does the damage calculation work", "what symbols can I use in...", or wants to add a new computable field to creatures or abilities.
GoblinScript is the domain-specific expression language used throughout DMHub for game math: damage rolls, ability costs, target filters, prerequisites, custom attributes, and more. It looks like natural-language formulas -- e.g. 2d6 + Might or Stamina <= Maximum Stamina / 2.
| Category | Operators |
|---|---|
| Arithmetic | +, -, *, /, % |
| Comparison | =, !=, <, >, <=, >= |
| String comparison | is, is not |
| Logical | and, or, not |
| Conditional | EXPR when COND, |
EXPR when COND else EXPR| Set membership | SET has "value", SET has not "value" |
| Local binding | EXPR where VAR = EXPR |
| Dice (non-deterministic only) | NdM (e.g. 2d6, 1d10) |
| Function | Description |
|---|---|
min(a, b, ...) | Minimum of values |
max(a, b, ...) | Maximum of values |
floor(x) | Round down |
ceiling(x) | Round up |
friends(a, b) | True if creatures a and b are friendly |
lineofsight(a, b) | Line of sight modifier (0-1) |
substring(haystack, needle) | True if needle is found in haystack |
Stamina, stamina, and STAMINA are equivalent.Walking Speed and walkingspeed resolve to the same symbol.self. prefix references the subject creature explicitly: self.Stamina, self.Conditions has "Poisoned".| Type | Contains dice? | Evaluation function | Returns |
|---|---|---|---|
| Deterministic | No | ExecuteGoblinScript() or dmhub.EvalGoblinScriptDeterministic() | number |
| Non-deterministic | Yes (e.g. 2d6) | dmhub.EvalGoblinScript() | string (e.g. "1d10+5") |
Most GoblinScript fields are deterministic (costs, prerequisites, attribute values). Damage rolls and quantity formulas can be non-deterministic.
-- Simple constant
3
-- Arithmetic with creature stats
2 * Might + 4
-- Conditional
5 when Level >= 5 else 3
-- Complex conditional
2 + 5 when Stamina > 5 and Level = 1 else 12
-- Set membership (conditions, keywords)
self.Conditions has "Poisoned"
-- Dice roll (non-deterministic)
2d6 + Might
-- Using max/min
Max(1, Max(Might, Agility))
-- Local variable binding
Stamina + x where x = 7
-- Checking winded status
Stamina <= Maximum Stamina / 2
-- Resource check
Resources.Heroic Resource < 0
-- Function call symbol
AdjacentAlliesWithFeature('Captain') >= 1
-- Potency check (on ActivatedAbilityCast)
PassesPotency('2')
These are available on any creature via self.SYMBOL or just SYMBOL:
| Symbol | Type | Description |
|---|---|---|
Name | text | Creature name |
Type | text | Monster type (e.g. "Undead") |
Subtype | text | Monster subtype |
Level | number | Creature level |
Stamina | number | Current stamina (hit points) |
Maximum Stamina | number | Max stamina |
Armor Class | number | AC value |
Size | number | Creature size |
Walking Speed | number | Walking movement speed |
Might | number | Might characteristic |
Agility | number | Agility characteristic |
Reason | number | Reason characteristic |
Intuition | number | Intuition characteristic |
Presence | number | Presence characteristic |
Conditions | set | Active conditions -- use has operator |
Weapons Wielded | number | Number of weapons wielded |
Two Handed | boolean | Wielding a two-handed weapon? |
Victories | number | Hero victories count |
Hero | boolean | Is this a hero (PC)? |
| Symbol | Type | Description |
|---|---|---|
Maneuver | boolean | Is this a maneuver? |
Trigger | boolean | Is this a trigger ability? |
Heroic | boolean | Costs heroic resources? |
HeroicResourceCost | number | Number of heroic resources |
MaliceCost | number | Malice cost |
Categorization | text | Category name |
Keywords | set | Ability keywords -- use has operator |
| Symbol | Type | Description |
|---|---|---|
Boons | number | Number of boons on this cast |
Banes | number | Number of banes on this cast |
HighestNumberOnAttackDice | number | Highest die result |
PassesPotency | function | Check potency tier: PassesPotency('2') |
Custom Attributes are user-definable creature fields visible in GoblinScript and editable via Character Modifiers. They live in userdata/tables/customattributes/.
__typeName: CustomAttribute