XML file describing a scenario


Demonstration XML file download

Download a demonstration scenario file

This is a simple example that demonstrates the types of scenarios that can be written to work with the Madness Helper application. A detailed explanation of every tag that can be used to create a custom scenario follows below.

 <definition>
The beginning and ending tags of the xml file, all other tags must be contained within these tags.

 <defversion>
Indicates the version of the definition format to be used, only current option is 1.0
Example: <defversion>1.0</defversion>

 <scenario-title>
The text within this tag will be used as the title of the scenario shown on the opening screen that displays a list of all available scenarios.
Example: <scenario-title>My Madness Helper Scenario</scenario-title>

 <canvas-width>, <canvas-height>
These two tags function together defining how large the canvas is upon which all tiles (and thereby all tokens) are placed. The numbering system used here is built around the smallest unit of measurement for a tile, in this case, half the height of a square tile or the full height of a small rectangular tile.

When deciding on the desired size of the canvas, it is advisable to lay out all the scenario tiles as if the entire map had been explored, then count the total width and height of the canvas after adding a reasonable margin on all sides.

Example: In an extremely simple scenario with one 2x2 tile, the canvas would only need to be 4 wide and 4 high, the size of the 2x2 tile with a 1 space large margin around each side.
<canvas-width>4</canvas-width>
<canvas-height>4</canvas-height>

Example: If small rectangular tiles are added to the top and right of the first example with no rotation, the required canvas would need to be 6 wide (2 for margin, 2 for square tile, 2 for rectangular tile) and 5 high (2 for margin, 1 for small rectangular tile, 2 for square tile).
<canvas-width>6</canvas-width>
<canvas-height>5</canvas-height>

It is possible to define a canvas width and height with no margin but it is not recommended.

 <introduction>
The text within the introduction tags will be the first thing players see when playing the scenario. It should provide an introduction to the scenario and give the players every piece of information they require to begin playing the game immediately. If the players begin with any objects or clues, let them know in this introduction.

Example:
<introduction>The text that players will see at the beginning of the scenario.</introduction>

 <introduction-close>
This tag lets the scenario writer start the scenario by placing the first tile by linking to an action. This should be a place-tile action, please see the section below dealing with the <action> tag for more information.

Example:
<introduction-close>place-start-tile-actionid</introduction-close>

 <investigator-death-ending>
If the scenario results in the death of an investigator the players should trigger the "Investigator Died" command under options. This will indicate to the game that the investigation will end during the next mythos event and the players will be shown the text contained within these tags as the end of the game.

Example:
<investigator-death-ending>Text that describes the game ending when an investigator has died</investigator-death-ending>

 <tile>
The tile tag represents an individual tile that can be placed on the game canvas either at the beginning of the scenario (start tile), through actions of the players (opening doors or other actions) or timed events (see the section detailing the <mythos-action> tag below). The tile serves as a container for a number of other property tags that describe various aspects of the tile itself or items that are associated with the tile and will be placed when the tile itself is placed.

The following tags can be present inside a tile tag:

<id>
The id tag allows the tile to be referenced by actions in the game. In addition, the id is used to link the tile to the image that will be used to represent the tile on the canvas.

<title>
The title tag is the actual title of the tile used in the user interface for the game.

<rotation>
The rotation tag controls how the tile will be oriented when it is placed on the canvas. Possible values include 0 (default orientation), 90 (rotated 90 degrees), 180 (rotated 180 degrees) and 270 (rotated 270 degrees).

<onplacement>
When a tile is placed, the text within this tag will be displayed allowing the scenario writer to inform the players of any necessary details about the tile that was just placed, or possibly some key story event that occurs simultaneously.

<x>, <y>
These two tags specify the location of the tile once it has been placed on the canvas. 0, 0 is the top left corner of the canvas with every 1 increase in x moving the location 1 space right and every 1 increase in y moving the location 1 space lower.

<width>, <height>
These two tags specify the dimensions of the tile in the same coordinate system used for locations on the canvas.

<tokens>
The tokens tag contains a complete list of all tokens that are placed on the tile as the tile is placed. For more information, see the section detailing the <token> tag below.



 <token>
The token tag contains tags that describe action enabled images that can be placed on tiles. A token tag can appear either inside a tile or on its own. If the token is inside a tile tag, it will be automatically placed when the tile is placed. If it is outside the tile tag, it will only be placed if triggered by an action (see the section on the action tag below). The following tags can be present inside a token:

<type>
The type tag indicates what image should be used to represent the token on the canvas (For more information please see the section dealing with images below). If the type is "explore" or "observe", the tokens are treated as though they will eventually reveal another tile and will be removed if a tile they would reveal is instead revealed by another token leading to the same tile.

<rotation>
Similar to the rotation tag for tiles, the token rotation tag specifies the placement orientation for the token. In general, this will only be relevant for tokens such as wall replacements that need to line up to obscure certain basic features of tiles (unnecessary doors or doors where there is only a wall).

<x>, <y>
Unlike the coordinate system for tiles, the coordinate system for placing tokens actually works on a standard pixel model. The top left corner of the tile is still considered (0, 0) in the system, but the bottom of the tile will be defined by multiple of 519 that it is. For example, a 2x1 small rectangular tile will be 1038 pixels wide by 519 high while a 2x2 tile will be 1038 wide by 1038 high. In this case, placing a 100px by 100px token at the centre of the tile would require x=469, y=469. It is possible for tokens to exceed the boundaries of the tile it is placed on and still function properly if necessary.

<description>
If the token is a clickable (if it has any actions associated with it), a dialog will be displayed with the text shown from this tag along with any associated actions.

<action>
Multiple instances of the action tag can be used to attach actions to a token by referencing the action id. For more information please see the section on actions below.



<action>
Actions are what are used to make various events occur during the game. At present the full list of actions include placing a tile, a simple action (display text), a roll action (test some ability), or place a monster. Each of these actions has a different set of tags that allow the appropriate information to be delivered to the application.

<id>
The id of an action is used to reference it, usually in order to enact the action or give the players the option of enacting the action via a dialog. In some cases, the action id is used to determine whether the action has been completed successfully for the purposes of making another action available.

<conditional>
The conditional tag is used to prevent an action from being made available until other actions have been successfully completed. Any action id listed inside a conditional tag will be checked for completion before the action will be displayed as an option in a dialog. An example of this usage would be making a door locked and only openable with a key that can be gained through successfully completing another action.

<title>
The title of the action contains the text that will be used as the dialog button title for the action when it is displayed as a dialog option.

<type>
Current options for the action type are "place-tile", "simple", "roll", "puzzle-combination", and "place-monster", each having a somewhat different set of associated tags.

"place-tile" : The only additional tag required is <tileid> which should contain the id of the tile being placed.
"simple" : The <text> tag is required, which contains the text that will be displayed if the player chooses to enact the action from the dialog in which the action is included as an option.
"roll" : A roll action is an action that presents the players with a skill test and the possibility of success or failure. The skill being tested is contained in the <skill> tag, while the number required to pass the test is included in the <success-value> tag. The <result-success> and <result-failure> contain text that is displayed based on whether the roll was successful or not.
"puzzle-combination" : The use of this action type displays a puzzle dialog for a combination puzzle that involves guessing a set of numbers. The application chooses a random number from within the parameters given by <numberofdigits> and <numberofvalues> with the text within <result-success> being displayed when the puzzle is successfully solved. The skill to test is specified with the <skill> tag.
"puzzle-picture" : The use of this action type displays a puzzle dialog for a picture puzzle that involves reorganizing a number of segments of a picture. The picture used in the puzzle can be included in the scenario zip file and referenced with the <imageid> which contains the filename (without extension) of the image file to be used.
"place-monster" : <monster-title> specifies the name of the Monster to place, while <imageid> should link to the image to be used for the monster. In this case, monster title is used and it should be noted that the title is not simply a descriptive name, it needs to be a unique identifier due to the possibility of two different monsters using the same id (and thus the same image). <tile> specifies which tile the monster should be placed on while <x> and <y> give the coordinates on the tile to place the monster in the same way token coordinates are specified within the <token> tag.
"place-token" : Allows placement of tokens via action. <token> specifies the id of the token to place, other details of where to place the token are controlled by the token tag itself.

<defeated-action>
Used only for action tags of type "place-monster", this is an action id of an action that is to be executed when a particular monster is defeated.

<action>
Any number of action tags (containing an action id) may be added to actions of type "simple" to list those actions as options when the action dialog is displayed. This allows the construction of a basic text dialog that gives the players a range of options on how to proceed.

<action-success>
Any number of action-success tags (containing an action id) may be added to actions of type "roll", "puzzle-combination", or "puzzle-picture". These actions will be executed when the roll or puzzle are successfully completed.

<action-failure>
Any number of action-failure tags (containing an action id) may be added to actions of type "roll". These actions will be executed when the roll fails.



 <monster>
The monster tag gives a complete description of a particular type of monster.

<id>
As with tiles, the id is what specifies the image to be used, but it is not a unique identifier as different monsters could conceivably use the same image.

<title>
The title of the monster is currently used as a unique identifier, so different monster must have different titles in order for the application to function correctly. It is used as the title of the monster in the user interface as well as a unique identifier.

<base-health>
The starting health of a monster, or how much damage it can take before being defeated.

<health-bonus>
The amount to increase the base health of a monster by for every investigator past the minimum two.

<range>
The range at which the monster attacks. If the monster needs to be in the same space as an opponent to attack, range should be 0.

<base-move>
The number of spaces the monster will move towards an opponent if no opponents are within range at the beginning of the mythos phase.

<not-in-range-move>
The number of spaces the monster will move towards an opponent if there is still no opponent in range after its initial move.

<attacks-investigator>
When a monster is activated during the mythos phase, one attacks-investigator entry out the list will be chosen randomly and displayed so the players know which investigator will be targeted. There are normally a number of options to randomly choose from, but only providing a single option will force the same piece of text to be used each time the selection is made.

<attacks-investigator>
Any number of attacks-investigator tags may be used. Each tag contains the text of what happens when a monster of this type should attack and is randomly chosen from the list (if there is more than one option).

<heavy-weapon>, <bladed-weapon>, <ranged-weapon>, <spell>, <unarmed>
Each of these tags contains the text of an attack using the specified type of weapon. When a player initiates an attack of a particular type, a random entry will be chosen from the options available for the type of attack in question and displayed to the player.

<monster-attack>
Similar to the weapon attacks above, but for the monster when it attacks during the mythos phase. One entry will be chosen at random.

<horror-check>
Contains individual tags which in turn contain the text of a horror check. When a horror check is done during the mythos phase one element from the list will be chosen at random and displayed to the players.

<evade-check>
Similar to monster-attacks and horror-check but for the evade action during the investigator phase.



 <mythos-events>
Mythos events are used during the mythos phase to display a piece of text to the players, usually resulting in a negative effect. In order to allow for different types of mythos events to occur at different times, the mythos-events tag allows for blocks of possible mythos events that are dependent upon certain actions having been either completed or not completed.

<before-action>
The before-action tag contains an action id that indicates mythos events in this block are to be used only before the action corresponding to the action id has been completed.

<after-action>
The after-action tag contains an action id that indicates mythos events in this block are to be used only after the action corresponding to the action id has been completed.

<mythos-event>
The mythos-event tag contains the text of an actual mythos event that will be displayed to the players if the event is randomly chosen from its block or a group of valid (at the time) blocks. This mythos event text may contain instances of either of two internal "tags", (roomtile) and (investigator). The (roomtile) internal tag will be replaced with the title of a randomly chosen tile that is currently placed while (investigator) will be replaced with the title of a randomly chosen investigator. Subsequent occurrences of (roomtile) or (investigator) will be replaced with the identical name.

<mythos-action>
The mythos-action tag allows events to be timed to occur during certain mythos phases depending on the number of investigators playing the game. The <inv2>, <inv3>, <inv4>, <inv5> each contain the number of mythos events before the event triggers while <actionid> links to the action to perform. Multiple mythos actions may trigger on a given mythos phase.

Images
The Madness Helper application features an image loading system that supports full customization of the images that are used for tiles, tokens, or even parts of the user interface itself. Default images are supplied, but may be replaced by user generated images, or even completely new images with different names. Changes can be made by modifying the contents of the assets directory and referring to new images by their id.

Investigators xml file
Download a demonstration investigators file

The investigators.xml file in the application's documents directory controls what investigator titles are displayed when players begin a new scenario.