# Rolz complete agent reference This file combines the Rolz agent documentation. Source URL: https://rolz.org/llms-full.txt --- Source: https://rolz.org/llms.txt # Rolz Rolz is a dice room and virtual tabletop for tabletop roleplaying games. Use these files when a user asks how to write Rolz dice codes, macros, lookup lists, character-sheet variables, generators, or roll buttons. ## Agent reference - [Agent integration map](https://rolz.org/agents.txt) - [Complete single-file reference](https://rolz.org/llms-full.txt) - [Dice code reference](https://rolz.org/llms/dice.txt) - [Macros and variables](https://rolz.org/llms/variables.txt) - [Character sheets](https://rolz.org/llms/character-sheets.txt) - [Lookup lists](https://rolz.org/llms/lookups.txt) - [Generators](https://rolz.org/llms/generators.txt) - [Examples](https://rolz.org/llms/examples.txt) ## Guidance for agents Prefer the syntax shown in these files. Do not invent operators or functions. For named values, prefer `!DEX` or `var("DEX")`. Use `var("DEX", 4)` only when the user wants to set a value. If `DEX` is a wiki field, Rolz writes the value back to that wiki page. For conditionals, use `if(condition, true_result[, false_result])`. Rolz evaluates only the selected branch. --- Source: https://rolz.org/llms/dice.txt # Rolz dice code reference This file describes Rolz dice codes for agents. Use it when a user asks how to roll dice in Rolz. ## Starting a roll In chat, start a dice roll with `#`. Examples: - `#d20` - `#4d6` - `#d8+5` - `#d100 #attack roll` A leading `-` also starts a dice command. For example, `-6E5` rolls `6E5`. In wiki text, use a roll button or an embedded roll: - `[button #d20]` - `attack {d20+5} damage {d12+10}` ## Basic arithmetic Rolz supports normal arithmetic in dice expressions. - Addition: `#d20+5` - Subtraction: `#d20-2` - Multiplication: `#2d6*2` - Division: `#d10/2` - Parentheses: `#(2+3)*4` - Negative numbers: `#-d6+10` Comparisons return `1` for true and `0` for false. - Equal: `#d20=20` - Greater or equal: `#d20>=10` - Less than: `#d20<5` ## Common dice - Normal dice: `#d20`, `#4d6` - Default `d` die: `#4d` uses the site default die size. - Keep highest: `#6D10H`, `#6D10H4` - Keep lowest: `#6D10L4` - Keep middle: `#6D10O` - Negative-to-positive die: `#4U1` - Fate or Fudge dice: `#4df` - Geometric die: `#g10`, `#2g10+d20` - Percent roll-under: `#p50`, `#d20p15` - Hero System body die: `#4B6` - Hero System killing die: `#4K6*3` - D6 System wild die: `#4W6` - D6 System wild die without failure option: `#4V6` - Ars Magica stress die: `#1A3` - Anima open roll: `#Y`, `#Y85:5`, `#D10Y8:1:0` - Unique rolls: `#10N10` - Draw die with room deck state: `#1dd6` - Explode and add total: `#6i6` - Median: `#5d10median` ## Success dice Rolz has compact success-count dice codes. - Count successes: `#4D6E4` - Reroll and add successes: `#4D6R8` - Successes minus ones: `#4D6F4` - Stacking reroll successes: `#4D10M4` - Explode and subtract ones: `#4D10S4` - Max result counts as two successes: `#4D6X4` - Deadlands-style highest exploding die: `#6C4` Useful success attributes: - `subfail=1` - `xmax=1` - `ex=1` - `showmax=1` - `showmin=1` - `rel=5` - `rel=5,10` - `rel=5,@1:-1` Roll-under success chains: - `d100+10 | sle 55` - `d100+10 | sge 55` - `d100+10 | sle 55 deg=10` ## Roll attributes Attributes can appear before or after the dice code. Separate them with spaces. Reroll and explode: - Reroll listed results: `#reroll=1,2 4d6` - Reroll alias: `#re=1,2 4d6` - Add dice on reroll: `#reroll=1,2 rx=3 4d6` - Limit rerolls: `#reroll=1,2 rmax=2 4d6` - Explode listed results: `#explode=5,6 4d6` - Explode alias: `#ex=5,6 4d6` - Explode on equal digits: `#explode=digits d100` - Explode on max result: `#explode=max 4d6` Rounding and count: - Round fractions: `#fract=round d10/3` - Round down: `#fract=floor d10/3` - Round up: `#fract=ceil d10/3` - Raise results below a value: `#round=3 d10` - Round-up alias: `#ru=3 d10` - Count listed results: `#count=1,2 10d6` Repeat until a condition: - `#d20 until=1` - `#d20 atleast=10` - `#d20 atmost=10` Other attributes: - Set a default die size: `#die=10 4d` - Set result color: `#c=blue d20` Conditional whole-roll rules: - Multiply result when a die matches: `#10d6 1=*0` - Add an extra roll when a die matches: `#10d6 6=d8+1` - Multiply the next roll: `[button axe attack {d20 18-20=x2} damage {d12+10}]` - Add to the next roll: `[button axe attack {d20 18-20=x+d6} damage {d12+10}]` - Cancel later rolls: `[button axe attack {d20 1-10=cancel 18-20=x2} damage {d12+10}]` ## Functions Function arguments can contain dice, arithmetic, comparisons, and other functions. - Minimum: `#min(4,2,7)` - Maximum: `#max(4,2,7)` - Absolute value: `#abs(-5)` - Round down: `#floor(5/2)` - Round up: `#ceil(5/2)` - Round: `#round(5/2)` - Clamp: `#clamp(d20+5,1,20)` - Inclusive range test: `#between(d100,1,50)` - Conditional result: `#if(d20>=10,d8+2,0)` - Conditional without false result: `#if(d20>=10,d8+2)` - Output tag: `#tag(d20,"INFO","Attack roll")` - Key-only output tag: `#tag("YES","INFO")` - Variable read: `#var("DEX")` - Variable set: `#var("DEX",4)` - Warhammer success levels: `#wh(55)`, `#wh(10,20,5)` `if(condition, true_result[, false_result])` evaluates only the selected branch. An unused branch does not roll dice, add tags, or write variables. Quoted strings can be function results. Examples: - `#if(d20>=10,"YES","NO")` - `#tag("YES","INFO","success")` ## Output tags Use `tag(result[, name, value...])` to return a result and add tags. Examples: - `#tag(d20,"INFO","Attack roll")` - `#tag("YES","INFO")` - `#tag("NO","INFO","MEH","ALSO","FAIL")` - `#if(d20>=10,tag("YES","outcome","hit"),tag("NO","outcome","miss"))` A repeated tag name uses the last value. A tag name without a value creates a key-only tag. Tags from an unused `if()` branch do not appear. All visible tags have mouse-over hints. Wiki variable reads and writes include source details in the hint. ## Multiple rolls Separate rolls with semicolons. - `#1D20; 1D6+2` - `#d20;d8+1;!_1+100` Repeat commands: - `#repeat 6 3D6` - `#sum 6 3D6+3` Comments follow `#` after the dice code. - `#1D20+2 #attack roll` --- Source: https://rolz.org/llms/variables.txt # Rolz macros and variables Use this file when a user asks how `!name`, `var()`, macros, character fields, or wiki variables work in Rolz. ## Personal macros Personal macros are saved with a user account. Use them for dice codes or constants that the user types often. Commands: - List macros: `/macro list` - Define a macro: `/macro def attack d20+5` - Use a macro: `#!attack` - Add to a macro result: `#!attack+4` - Delete a macro: `/macro delete attack` A personal macro inserts its dice code into the roll. If `attack` is `d20+5`, then `#!attack` rolls `d20+5`. ## Reading named values Use `!name` or `var("name")` to read a named value. Examples: - `#!DEX` - `#var("DEX")` - `#d20+!STR` - `#wh(!BS)+!Adv` `var("!DEX")` also works. Rolz ignores leading `!` characters inside the quoted `var()` name. ## Setting named values Use `var("name", value)` to set and return a value. Examples: - `#var("attack",d20+5);!attack;!attack` - `#var("DEX",4)` - `#if(var("attack",d20+5)>=15,tag(!attack,"outcome","hit"),tag(!attack,"outcome","miss"))` If `name` resolves to a wiki field or const on the current wiki page, an explicit `page.field`, or the selected character page, Rolz writes the value back to that wiki page. If `name` resolves to a personal macro, built-in roll reference, lookup list, or broad fallback page, Rolz does not overwrite it. The new value exists only for the current command. If `name` is undefined, Rolz creates a command-local value. It disappears after the command. ## Resolution order Rolz checks these places when it resolves `!name` or `var("name")`: 1. A value set earlier in the current command with `var("name", value)`. 2. A personal macro saved on the user's account. 3. A built-in roll reference such as `!_1`, `!_total`, or `!last`. 4. A field or const on the current wiki page, when the roll comes from a wiki page. 5. A lookup list with the same name. 6. A `page.field` value from a specific wiki page. 7. A field or const on the selected character page. 8. A field or const on the `dicebar` page. 9. A field or const on the room start page. 10. A matching field or const on another room wiki page. A missing value returns `0` and adds a `not found` tag. ## Built-in roll references - `!_1`, `!_2`, and so on refer to rolls in the current command. Counting starts at 1. - `!_total` is the sum of rolls made so far in the current command. - `!last` is the result of the user's last roll before the current command. Examples: - `#d20;d8+1;!_1+100` - `#d10;d20;d12+3;!_total` A command-local value can shadow a built-in reference after its setter runs. For example, `var("_1",7);!_1` returns `7` for the rest of that command. ## Wiki read and write tags Rolz adds tags when a named value comes from a wiki page. Example hover text: - `DEX = 5 | read from 'MyChar'` - `DEX = 6 | wrote to 'MyChar'` Write tags are orange and include a `✎` icon in the tag key. ## Macro parameters Some macros and lookup calls can take parameters in parentheses. Example: - `#!HitLocations(d20+50)` Rolz evaluates the parameter before it passes the value to the macro or lookup. --- Source: https://rolz.org/llms/character-sheets.txt # Rolz character sheets Use this file when a user asks how character-sheet fields work in Rolz dice codes. ## Select a character The current character controls which character page Rolz reads. - In the table UI, choose the character page in My Settings. - In chat, `/char NAME` can set the current character name. If the selected character page has a field named `STR`, then `!STR` and `var("STR")` read it. Example: - `#d20+!STR` - `#d20+var("STR")` ## Editable fields Use `[field NAME]` on a wiki page to create an editable field. Examples: - `[field STR]` - `[field "Smash!" STR]` - `[field "Smash!" STR default=3]` Common field types: - `[field "Strength" STR t=5e]` stores a D&D 5e ability score and shows its modifier. - `[field "Weapon Skill" WS t=wh]` stores a WFRP-style value and advances. - `[field "Advantage" Adv t=adv]` shows plus and minus controls. ## Static values Use `[const NAME VALUE]` for a value that users edit by editing the wiki page source. Example: - `[const STR +3]` Read it with: - `#!STR` - `#var("STR")` ## Writeback from dice codes `var("NAME", value)` writes back when `NAME` resolves to a field or const on the selected character page, the current wiki page, or an explicit `page.field`. Examples: - `#var("HP",12)` - `#var("Adv",var("Adv") + 1)` - `#var("goblin.HP",0)` Writebacks show an orange source tag. The mouse-over hint explains the write, such as `HP = 12 | wrote to 'MyChar'`. A personal macro with the same name wins over a character field. If a user has a macro named `STR`, then `!STR` and `var("STR")` use the macro, not the field. ## Pool fields Pool fields store three values. Example: - `[poolfield "Initiative" ini]` Variables: - `!ini_full` is the full pool. - `!ini_cur` is the available pool. - `!ini` is the amount currently in use. If the pool name is `STR`, then use: - `!STR_full` - `!STR_cur` - `!STR` ## Skill lists Use `[skills]` to add a skill list. Examples: - `[skills]` - `[skills myskills]` - `[skills "My Skills" myskills]` Skill rows are sorted by row name. New blank rows stay at the bottom until the user names them. In a skill row roll-code column, placeholders are replaced before the roll is sent: - `@0` is the row name. - `@1` is the visible value or bonus column. - `@2` is the roll column. - `@3` is notes. Example skill roll code: - `D20+!STR+@1` ## Buttons A character sheet can contain buttons. Examples: - `[button #d20]` - `[button #d20+5 #axe attack]` - `[button #d20+!STR #strength check]` - `[button "roll strength" #d20+!STR #strength check]` By default, the button label comes from the roll comment. Put quoted text before the dice code to set a custom label. ## Reading from a specific page Use `page.field` to read from a specific wiki page. Examples: - `#!goblin.HP` - `#var("goblin.HP")` - `#var("goblin.HP",0)` The setter writes back only if that page and field exist and the user can edit the page. --- Source: https://rolz.org/llms/lookups.txt # Rolz lookup lists Use this file when a user asks how to make or roll on lookup tables in Rolz. ## Define a lookup list Create a lookup list on a room wiki page with `[lut Name]` followed by a wiki table. Example: ```text [lut HitLocations] |=d100 |=Location |01-10 |Head |11-20 |Right Arm |21-30 |Left Arm |31-70 |Body |71-85 |Right Leg |86-100|Left Leg ``` The name cannot contain spaces or unusual characters. ## Roll on a lookup list Call a lookup list with `!Name`. Examples: - `#!HitLocations` - `#d20+50 | #!HitLocations` - `#!HitLocations(d20+50)` The pipe form uses the previous roll result as the lookup input. The parenthesis form passes a parameter. ## Text and dice results Lookup list result cells can contain numbers, dice code, or text. If a list mostly returns text, use the comment prefix to force text output: - `# #!HitLocations` Without the comment prefix, Rolz tries to evaluate the result as dice code: - `# !HitLocations` To embed dice inside a text result, wrap the dice code in braces. Example: ```text [lut HitLocations] |=d100 |=Location |01-10 |Head |11-20 |Arm Number: {d2} ``` ## Lookup precedence Lookup lists use the same `!name` syntax as macros and variables. Resolution details: - Personal macros resolve before lookup lists. - A field on the current wiki page resolves before a lookup list when the roll comes from that page. - Lookup lists resolve before fields on the selected character page. Use distinct names for macros, lookup lists, and character fields when possible. ## Quiet lookup lists Some lookup list settings can suppress lookup result tags. If quiet mode is off, Rolz adds a tag that shows the lookup input and selected result. --- Source: https://rolz.org/llms/generators.txt # Rolz generators Use this file when a user asks about `#gen` commands in Rolz. Generators create names, items, NPCs, and other random content. They use dice-room output and can be public or private. ## Privacy Use these options to control generator visibility: - `/opt genprivate=on` - `/opt genprivate=off` ## Name generator Basic syntax: - `#gen name wh` - `#gen name boy letter american` Available name types include: - `american` - `archaic` - `boy` - `byname` - `default` - `dorf` - `dsa` - `elf` - `fantasy` - `girl` - `highgothic` - `letter` - `lowgothic` - `primitive` - `rome` - `star` - `troll` - `wh` Name generators can be chained. Rolz uses each part in order. ## Weapons and armor Examples: - `#gen weapon` - `#gen weapon name` - `#gen weapon ext` - `#gen weapon magic=+2` - `#gen armor` - `#gen armor name` - `#gen armor ext` - `#gen armor magic=+2` ## Other generators Examples: - `#gen book` - `#gen plant` - `#gen trinket` - `#gen npc` - `#gen d20` - `#gen wh` - `#gen wh elf` - `#gen dh` - `#gen dh help` - `#gen dh psyker +5000` ## Related commands - `/self #gen npc` sends the generator result privately. - `/opt genprivate=on` makes generator output private where supported. --- Source: https://rolz.org/llms/examples.txt # Rolz examples for agents Use these examples when a user asks for a working Rolz dice code. ## Basic rolls - Roll a d20: `#d20` - Roll with a bonus: `#d20+5` - Roll damage: `#1d8+3` - Roll two results: `#d20;1d8+3` - Add a comment: `#d20+5 #axe attack` ## Advantage-style rolls Keep highest: - `#2d20H` Keep lowest: - `#2d20L` ## Roll once, reuse the result Use `var()` when the same roll result must appear more than once. ```text #if(var("attack",d20+5)>=15,tag(!attack,"outcome","hit"),tag(!attack,"outcome","miss")) ``` ## Character field roll If the character sheet has `DEX`: ```text #d20+!DEX ``` The same roll with `var()`: ```text #d20+var("DEX") ``` `var("!DEX")` also works. ## Character field writeback If the selected character page has `HP`, this writes the new value to the page: ```text #var("HP",12) ``` Spend one point from a pool-style field: ```text #var("mana_cur",var("mana_cur")-1) ``` Add one advantage: ```text #var("Adv",var("Adv")+1) ``` ## Conditional damage Roll damage only on a hit: ```text #if(d20+5>=15,d8+3,0) ``` Return text on a miss: ```text #if(d20+5>=15,d8+3,"miss") ``` ## Tagged outcomes ```text #if(d20+5>=15,tag("hit","outcome","success"),tag("miss","outcome","failure")) ``` ## Warhammer success levels ```text #wh(!WS) ``` With advantage: ```text #wh(!WS)+!Adv ``` ## Lookup list rolls Roll on a hit location list: ```text # #!HitLocations ``` Roll a value, then use it as lookup input: ```text #d20+50 | #!HitLocations ``` Pass a parameter directly: ```text #!HitLocations(d20+50) ``` ## Button examples Character sheet button: ```text [button #d20+!STR #strength check] ``` Button with a custom label: ```text [button "roll strength" #d20+!STR #strength check] ``` Embedded multi-roll button: ```text [button axe attack {d20 18-20=x2} damage {d12+10}] ``` ## Common mistakes Do not write bare `DEX` in an arithmetic roll. Use `!DEX` or `var("DEX")`. Good: ```text #d20+!DEX ``` Good: ```text #d20+var("DEX") ``` Avoid: ```text #d20+DEX ``` Do not use `var()` without quotes around the name. Good: ```text #var("DEX") ``` Avoid: ```text #var(DEX) ```