Templates

In a tome, each individual file should be preceded by a line starting with at least five exclamation points and containing the name of the file to be generated. Additional spaces, tabs, and exclamation points will be ignored on this line. The example tome below will install a campaign and a scenario (and really is only useful for testing).

This is a very quick introduction to the template system for Orne Archives, with a focus on campaign and scenario templates. At the moment, there are not many tools for checking the accuracy of your template other than loading it and seeing if it produces the output you expect. I am hoping to provide better logging of template loading so that authors can better debug their templates.

How Templates are Read

The template is an xml document that is parsed and each xml element is converted into a node in the app. You can directly access these nodes by exporting a log and you will obtain both the html output as well as a json file which contains a sequence of nodes that make up the log. These nodes contain the information to reconstruct the log up to the last decision made by the user.

From Scenario/Campaign Template to Element List

This is currently a work in progress.

Campaigns and scenarios are being parsed by the same parser, so the same elements are used by both types of templates. Currently, the following elements have been developed.

campaign

scenario

notes

A block of text displayed in the app to help the user select the right campaign. This information is not included in the html output.

intro

A text block typically with a title attribute which is put into a header and text.

setup

A text block with a app generated header.

campaignInvestigators

Allows players to select investigators to be used in this campaign and to assign player names to those investigators. This should be added at any point where players might wish to change investigators.

scenarioInvestigators

Allows players to select which campaign investigators are going to be used in a scenario. Investigators chosen here will gain the scenario experience and trauma. This also requires to select a lead investigator before proceeding who will take both the investigator experience and trauma as well as the lead experience and lead trauma.

difficulty

Allows the investigators to select the difficulty level for the campaign. The names of the attributes are the different difficulty levels available and the values are the chaos bag contents.

investigatorResolution

Element allows players to indicate whether scenario investigators resigned, were mentally defeated, were physically defeated, or remained.

counter

Element allows you to set or increment a counter. If the counter does not exist, it will be created.

logOption

This allows investigators to select an option to be added to the log. Available options are in <option> elements.

option: Each option has a required label which appears as a choice for the player and an optional entry which is what is added to the log. If the entry is omitted, choosing that option will not add anything to the log.

resolution

This allows you to specify a scenario resolution. These are included as a comma separated list in the options attribute.

nextScenario

This allows users to choose the next scenario. You can supply a suggestion for the next scenario in the campaign or they can choose a different scenario. At the moment, I do not think this will work correctly as it will lose track of the next campaign scenario if someone chooses a stand-alone scenario.

section

You can set the title and the body content of a h2 header section.

subsection

You can set the title and body content of a h3 header section.

text

This does not include a header, but will allow you to add text to the html file.

investigatorStatus

This allows players to update their investigator's experience and trauma.

logEntry

This allows players to add items directly to the log.

From Element List to HTML

Counters in sidequest scenarios: the campaign and campaign-scenario files should choose counter names which do not conflict with each other or with campaign counters. As a naming convention, campaign and campaign scenario counters start with a + while side-quest counters should start with a -. Hyphen preceded counters should be cleared every time a sidequest scenario starts, which means that they won't conflict with other sidequests either.

The contents of each element are converted to html one node at a time, so the processing of any node can use any values that have been set in previous nodes (but not values set in itself).

The following describes how the content of each node is converted from the text in the template to the html displayed in the app.

Stage One: Basic Substitutions

A basic Search and Replace operation.

All tags of the form [img:XXX] are converted to <img src='img/XXX.png' alt='XXX' title='XXX'>. At this point, I have no way for you to insert your own images into the app, but it is a feature I would like to add. The app is pre-loaded with images for the core set. If the image is unavailable, the title will appear, so users can still use the app.
The following elements: [narrative], [log], [unlog], [location], and [card] are converted to html <span> elements with the class of the same name.
All [counter:XXX] elements are replaced with the counter's value.

Stage Two: Including/Omitting Text

Sections of the text are removed based on whether we have a set branch, whether counters are at particular values, and whether items are in (or not in) the log. I've tried to leave traces of where omissions/inclusions have occurred in the html comments produced by this process so that you can track what the app is doing. The description of how to set branches, set counters, and add items to the log are described in Stage 3 below. You have the following optoins available to you.

Elements marked as [branch name='XXX'] are included if and only if the branch has been set to XXX. A branch is supposed to be a short-term decision the users made that will not directly affect later elements. Currently they are only being used in the Resolution element. For example, deciding which resolution should only affect the resolution text. If you want a more persistent effect, you will need to use the campaign log (described below).
Elements marked as [ifcounterequal:XXX:YYY], [ifcountergreater:XXX:YYY], [ifcountergreatereq:XXX:YYY], [ifcounterless:XXX:YYY], [ifcounterlesseq:XXX:YYY] will be included if the value of the counter with the name XXX bears the appropriate relationship to the number YYY. There is also [ifcounterrange:XXX:YYY:ZZZ] which includes the material provided the YYY <= counter(XXX) < ZZZ. Notice that we include the left end point and exclude the right endpoint.
Notice that at this point we have already replaced all the [counter:XXX] values in the text, so you can write things like [ifcounterequal:firstCounter:[counter:secondCounter]] to generate text if the value of firstCounter is equal to the value of secondCounter.
Elements marked as [logged:XXX] will only appear if the exact string XXX appears in the log.
Elements marked as [unlogged:XXX] will only appear if the exact string XXX does not appear in the log.

Stage Three: Setting Values

This is where you can update counters, and add items to the log. As before, I've tried to leave traces of where values are set in the html comments produced by this process so that you can track what the app is doing.

Branches are not set in the text, they are set using the <resolution> elements in the xml file (see From Template to Elements above).
The [setCounter:XXX:YYY] element (or [addCounter:XXX:YYY] element) sets (or increments) the value of the counter XXX to the value of YYY. This will create new counters if XXX is not an existing counter. Currently there are built in counters with names "Experience", "Mental Trauma", "Physical Trauma", "Lead Experience", "Lead Mental Trauma", and "Lead Physical Trauma" which are used to update investigator traits at the end of a scenario. Every investigator (including the lead) is affected by the first three and the lead is also affected by the later three.
The [log:XXX] element will add the string XXX to the log.
The [killed:XXX] element (or [insane:XXX] element) will kill (or drive insane) an investigator with the status of XXX at the end of a scenario (possibilities for XXX are "resigned", "mentalDefeat", "physicalDefeat", or "remained").