by tjlee
Description
Best used in conjunction with:
Table Edit Extension
Story Template Enhanced - Examples
New Features
Developed to be only dependent upon the CoreRPG ruleset. Currently, only tested on 5E, Shadowdark, and Pathfinder 2E, but should work with any CoreRPG-based ruleset.
Note: Stories and Advanced Stories created using this extension are fully shareable with non-extension users. You can export such stories as part of a module in a .mod file which are also usable by non-extension users. Exported templates, especially Advanced Story Templates and Simple templates that make use of the added template syntax will require the use of this extension.
New Parser
The Story Template Enhanced extension employs a new custom story template parser that evaluates the syntax in the template body from left to right, top to bottom with the title of the story template evaluated last (an options setting may set it to evaluate the title first). It enables better evaluation of the syntax and allows arbitrarily deep nesting in table name expressions and support for new features and new syntax listed below.
In technical terms, the enhanced parser is a forward chaining breadth-first, depth recursion parser with built-in limits of 5 breadth-first change detection iterations with a limit of 20 recursions. In practice, iterations rarely reach 3 and recursion depth of 7 is reached in only the most complicated template/table nesting scenarios.
Table Multipliers
As described in the CoreRPG ruleset, a table multiplier is a dice expression followed by 'x' such as [1d4x] which means roll on the following table 1d4 times and return the results.
In the following, 1d4 is used to represent a dice expression which can also be just a number such as 4 as in [4x]. This story template extension supports the following enhanced syntax to table multipliers:
- [1d4s][TableName] - same as [1d4x] above, but results are Sorted alphabetically in ascending order. Works with co-mingled link references and text.
- [1d4u][TableName] - same as [1d4s], but duplicates are removed to provide Unique results.
- [1d4r][TableName] - specify die Roll on TableName to override its default dice expression. A number is a valid die roll expression
Ex: [10r][TableName] means return the row that matches a roll of 10. You can use a dice expression to limit the result to a subset of the table. Values out of the range of the table are automatically resolved by TableManager in CoreRPG, so there shouldn't be any out of bounds failure cases. Note: you will get a result of nothing if the value rolled occurs within a numbering gap in the table and is CoreRPG behavior. - Additional comma separated syntax for the 'r' directive supports: [1d4,2,10r][TableName] which means give me three rows, random row matching 1d4, 2, and 10 from TableName. There's no enforced limit to the number of comma separated dice expressions allowed.
Comments
Support for XML style !-- comment --! or C-style /* comment */ expressions in story templates, so you can comment out portions/leave notations without them appearing in the generated story text.
Comments have an Option that specifies Text Only (default) or Text & Markup in the Options panel under Story Templates Enhanced.
Additionally, comments can override the Options setting by adding an additional - (dash) or * (asterix) at the start of the comment such as !--- or !--* or /*- or /** to force masking of Text & Markup.
Modular Templates
Support for new syntax: !^ TemplateName ^! (and support for link referenced Simple Story Templates) to allow for inclusion of Simple Story Templates in other Story Templates. Including Advanced Story Templates in this way is not allowed. See below for more on Advanced Story Templates.
The [1d4x,s,u] prefix to !^ TN ^! works as expected - include the template X times (Sorted, or with Unique results). Infinite recursion is detected and prevented during the first repeated occurrence. A template may include itself (or several inclusions removed), but only once before it is stopped with a warning message included in the resulting story at the point of potential infinite recursion.
Advanced Templates
Support for Advanced Templates to generate Advanced Stories is included. All text fields in Advanced Story blocks (text/formattedtext) are supported: image caption, text, text2 (dualtext).
Functions (added 2024.09.30)
Story Template Enhanced extension now supports function invocations with a syntax of functionName(stringExpression). The six functions supported are:
- capitalize - the first letter of the string expression is made uppercase.
- date - the system date according to the [DATE:format] callout is evaluated. Ex. date(format)
- fgdate - the game date (based upon selected calendar) according to the [FGDate:format] callout is evaluated.
- lower - the string expression is made all lower case. Ex. LOWER(Hi) is substituted by hi.
- titlecase - the string expression is made title case. Ex. titlecase(hello there) is substituted by Hello There
- upper - the string expression is made all lower case. Ex. upper(hi) is substituted by Hi.
These functions can be nested and can be co-mingled with the other template syntax elements where it makes sense. The results of the function are substituted in place of the function callout.
Example:
- capitalize([NPC Name]) - capitalizes the result of calling the table named NPC Name (first letter is capitalized).
Note: if the results of the table callout is not a string expression (such as formatted text), the function may produce unexpected results.
Run Templates in Group
Added a button at the top of the Story Template master index window to generate stories for all of the displayed story templates in the selected group (see README 2 in the Enhanced Story Template module for more details - separate product).
Filtering by name and share status can further limit the templates displayed. Pressing the button pops up a dialog box informing the user on the number of templates to evaluate and a summary of the current options settings to confirm. The resulting stories are stored in the currently selected Story group. It is recommended that the user create an empty destination story group to receive the generated stories so that they're kept separate from existing ones for easy identification.
Slash Command
The Enhanced Story Template extension introduces a slash command which may be used in the chat window to evaluate template text expressions.
Don't forget to also get the following to see examples of the above:
Story Template Enhanced - Examples
Change Log
2024.10.04 - Added complete set of functions to support Function-based template syntax:
The categories of Story Template Enhanced function syntax include:
- Control Functions (delim, get, set, setg, xget, xset, xsetg)
- String Functions (capitalize, cat, date, dcat, dice, fgdate, lower, pre, post, reverse, rsort, sort, titlecase, uniq, upper)
- Number Functions (avg, count, max, min, total)
- Formatting Functions (bold, bullets, italic, lines, underline, znum)
- Access Functions (head, pick, select, tail)
- Table and Template Functions (import, mult_import, mult_table, table)
2024.09.30 -
- Added functions: capitalize, date, fgdate, lower, titlecase, upper. Function syntax is: functionName(stringExpression).
2024.08.29 -
- Added logic to remove empty text blocks in Advanced Stories generated from Advanced Story Templates.
- Formalized support for use of Link IDs in place of Table names and Story Template names (see Story Template Enhanced - Examples).
- Added a click action to the Toolbar Drag Record Link button (top left corner) to report the Link ID associated with the window to chat.
2024.08.16 - Update for FGU 4.5.10.
2024.08.10 - Initial Release
UUID 80410df0-52e8-11ef-af21-0050562be458