Parameter Syntax

Complete reference for placeholder parameter syntax, including formatting rules, data types, and validation.

Read this first: not every parameter documented here actually filters anything. sameState and withinRange (on both {randomBurg} and {randomDungeon}) were written for the sibling product's live map data, which Campaign Cookbook doesn't have - they're silently ignored rather than throwing an error. The Complete Parameter Reference table below marks exactly which ones work today. minPopulation/maxPopulation/type/ difficulty all work as documented.

Basic Syntax

Parameters are added after the placeholder name, separated by a colon:

{placeholderName:parameter=value}

Example

{randomBurg:minPopulation=1000}

{randomBurg:maxPopulation=300}

{nearestDungeon:type=Cave}

Multiple Parameters

Separate multiple parameters with commas. No spaces allowed.

{placeholderName:param1=value1,param2=value2,param3=value3}

Example

{randomBurg:minPopulation=500,maxPopulation=2000}

{nearestDungeon:type=Cave,difficulty=hard}

Formatting Rules

Critical Rules:

No spaces around = or ,
Parameter names are case-sensitive
Value types must match parameter type
Invalid parameters are ignored

Valid Syntax

✓ {randomBurg:sameState=true}

✓ {randomBurg:withinRange=50}

✓ {randomBurg:sameState=true,minPopulation=500}

✓ {nearestDungeon:type=Cave,difficulty=hard}

Invalid Syntax

✗ {randomBurg:sameState = true}        // Spaces around =

✗ {randomBurg:sameState=true, minPop=500}  // Space after comma

✗ {randomBurg:SameState=true}          // Wrong case

✗ {randomBurg:withinRange=fifty}       // Should be number

✗ {randomBurg:sameState=yes}           // Should be true/false

Data Types

Boolean

True/false values. Must use lowercase true or false.

sameState=true

sameState=false

Note: yes, no, 1, 0 are NOT valid boolean values.

Number

Integer or decimal numbers.

withinRange=50

withinRange=100

minPopulation=1000

maxPopulation=500

String

Text values. Do not wrap in quotes.

type=Cave

type=Ancient-Crypt

difficulty=hard

difficulty=easy

Important: Do NOT use quotes around string values:

✓ type=Cave
✗ type="Cave"

Complete Parameter Reference

Settlement Parameters

Parameter	Type	Description	Valid Values	Works Today?
`minPopulation`	number	Minimum population	Any positive number (e.g., 500, 1000)	✓ Yes
`maxPopulation`	number	Maximum population	Any positive number (e.g., 300, 2000)	✓ Yes
`sameState`	boolean	Intended to limit to same state/province	true, false	✗ No - see warning above
`withinRange`	number	Intended max distance in units	Any positive number (e.g., 50, 100)	✗ No - see warning above

Dungeon Parameters

Parameter	Type	Description	Valid Values	Works Today?
`type`	string	Dungeon type filter	Cave, Underground-Ruins, Sewer, Ancient-Crypt, Monster-Lair, Ruin	✓ Yes
`difficulty`	string	Difficulty level filter	easy, medium, hard, deadly	✓ Yes
`sameState`	boolean	Intended to limit to same state/province	true, false	✗ No - see warning above

Both of these placeholders are flavor-text only, drawn from an optional hand-authored data/maps/locations.json - see {nearestDungeon} for what that means and how it differs from a real, campaign-authored {dungeon:id}.

Parameter Compatibility

Not all parameters work with all placeholders:

Placeholder	Supported Parameters
`{nearestBurg}`	None (no parameters)
`{randomBurg}`	minPopulation, maxPopulation (sameState, withinRange accepted but non-functional)
`{capitalCity}`	None (no parameters)
`{nearestDungeon}`	type, difficulty
`{randomDungeon}`	type, difficulty (sameState accepted but non-functional)

Examples by Use Case

Find Specific Settlement Size

{randomBurg:maxPopulation=200}                // Small village

{randomBurg:minPopulation=500,maxPopulation=2000}  // Medium town

{randomBurg:minPopulation=2000}               // Large city

Match Dungeon to Story

{nearestDungeon:type=Cave}                     // Bandit hideout

{nearestDungeon:type=Ancient-Crypt}            // Undead quest

{nearestDungeon:type=Sewer}                    // Urban adventure

Match Dungeon to Party Level

{nearestDungeon:difficulty=easy}      // Level 1-3

{nearestDungeon:difficulty=medium}    // Level 4-7

{nearestDungeon:difficulty=hard}      // Level 8-12

{nearestDungeon:difficulty=deadly}    // Level 13+

Complex Filters

// Medium town

{randomBurg:minPopulation=800,maxPopulation=1500}

// Hard cave

{nearestDungeon:type=Cave,difficulty=hard}

// Deadly ancient crypt

{randomDungeon:type=Ancient-Crypt,difficulty=deadly}

Error Handling

Invalid Parameter Names

Unknown parameters are ignored:

{randomBurg:minPopulation=500,invalidParam=value}

Result: minPopulation is applied, invalidParam is ignored.

Invalid Parameter Values

Invalid values cause the parameter to be ignored:

{randomBurg:minPopulation=notANumber}

Result: Parameter is ignored, placeholder acts as if parameter wasn't specified.

No Matching Locations

If filters are too strict and no locations match:

{randomBurg:minPopulation=10000}

Result: Fallback text like "a nearby settlement" if nothing in your party's generated roster (or hand-authored locations.json) meets it.

Tip: If you see fallback text, your filters may be too strict. Try relaxing one or more parameters.

Best Practices

1. Order Doesn't Matter

These are equivalent:

{randomBurg:minPopulation=500,maxPopulation=2000}

{randomBurg:maxPopulation=2000,minPopulation=500}

2. Use Meaningful Population Values

Choose values that make sense for your world:

✓ Good:  maxPopulation=300   // A small village

✓ Good:  minPopulation=2000  // A real city

3. Test Your Filters

After writing, test to ensure locations resolve correctly:

Load your campaign in Campaign Cookbook
Navigate to scenes with placeholders
Verify locations appear (not fallback text)
Check the console (see Debugging Tips below) for resolution details

Debugging Tips

Campaign Cookbook has no map to "load" or "configure" in the sense the sibling product does - having no data/maps/locations.json at all is the normal, common, out-of-the-box state, not an error condition. Towns generate automatically the first time your party needs one; dungeon flavor-text ({nearestDungeon}/ {randomDungeon}) only resolves to something specific if you've hand-authored that optional file - otherwise it's generic text, which is expected and fine.

Check Console Logs

The renderer process's console (View → Toggle Developer Tools in a dev build; not available in a packaged release, see Introduction) logs placeholder resolution via debugLog(), prefixed [DM Toolkit].

Common Issues

Issue	Cause	Solution
Generic fallback text ("the nearest settlement," "a nearby dungeon") appears	Normal for a fresh campaign with no towns generated yet, or no `locations.json` for dungeon flavor text	Towns generate automatically the first time they're needed; for dungeon flavor text, author an optional `data/maps/locations.json`
`sameState`/`withinRange` seem to do nothing	They're not currently functional (see the warning near the top of this page)	Use `minPopulation`/`maxPopulation` instead
Parameter ignored	Invalid parameter name or value	Check spelling and data type
Same location every time	Working as intended (caching)	Use different parameters for different locations

Campaign API Reference

Getting Started

Placeholders

Quest Actions

Advanced

Examples

Tools

Parameter Syntax

Basic Syntax

Example

Multiple Parameters

Example

Formatting Rules

Valid Syntax

Invalid Syntax

Data Types

Boolean

Number

String

Complete Parameter Reference

Settlement Parameters

Dungeon Parameters

Parameter Compatibility

Examples by Use Case

Find Specific Settlement Size

Match Dungeon to Story

Match Dungeon to Party Level

Complex Filters

Error Handling

Invalid Parameter Names

Invalid Parameter Values

No Matching Locations

Best Practices

1. Order Doesn't Matter

2. Use Meaningful Population Values

3. Test Your Filters

Debugging Tips

Check Console Logs

Common Issues

See Also