User Tools

Site Tools


Passage markup










data structure

date and time

game state






showing and hiding





Types of data

Special keywords

Special passage tags


Datamap data

There are occasions when you may need to work with collections of values that “belong” to a specific object or entity in your story - for example, a table of numeric “statistics” for a monster - or that associate a certain kind of value with another kind, such as a combination of adjectives (“slash”, “thump”) that change depending on the player's weapon name (“claw”, “mallet”) etc. You can create datamaps to keep these values together, move them around en masse, and organise them.

Datamaps are one of the two major “data structures” you can use in Harlowe. The other, Array, are created with (a:). You'll want to use datamaps if you want to store values that directly correspond to string, and whose order and position do not matter. If you need to preserve the order of the values, then an array may be better suited.

Datamaps consist of several string names, each of which maps to a specific value. $animals's frog and frog of $animals refers to the value associated with the name 'frog'. You can add new names or change existing values by using (set:) - (set: $animals's wolf to "howl").

You can express the name as a bare word if it doesn't have a space or other punctuation in it - $animals's frog is OK, but $animals's komodo dragon is not. In that case, you'll need to always supply it as a string - $animals's "komodo dragon".

Datamaps may be joined by adding them together: (dm: "goose", "honk") + (dm: "robot", "whirr") is the same as (dm: "goose", "honk", "robot", "whirr"). In the event that the second datamap has the same name as the first one, it will override the first one's value - (dm: "dog", "woof") + (dm: "dog", "bark") will act as (dm: "dog", "bark").

You may notice that you usually need to know the names a datamap contains in order to access its values. There are certain macros which provide other ways of examining a datamap's contents: (datanames:) provides a sorted array of its names, (datavalues:) provides a sorted array of its values, and (dataentries:) provides an array of names and values.

To summarise, the following operators work on datamaps.

Operator Meaning Example
is Evaluates to boolean true if both sides contain equal names and values, otherwise false. (dm:“HP”,5) is (dm:“HP”,5) (is true)
is not Evaluates to true if both sides differ in items or ordering. (dm:“HP”,5) is not (dm:“HP”,4) (is true), (dm:“HP”,5) is not (dm:“MP”,5) (is true)
contains Evaluates to true if the left side contains the name on the right. (To check that a datamap contains a value, try using contains with (datavalues:) (dm:“HP”,5) contains “HP” (is true), (dm:“HP”,5) contains 5 (is false)
is in Evaluates to true if the right side contains the name on the left. “HP” is in (dm:“HP”,5) (is true)
+ Joins datamaps, using the right side's value whenever both sides contain the same name. (dm:“HP”,5) + (dm:“MP”,5)
's Obtaining the value using the name on the right. (dm:“love”,155)'s love (is 155).
of Obtaining the value using the name on the left. love of (dm:“love”,155) (is 155).
harlowe/datamap.txt · Last modified: 2017/06/18 23:32 by l