Arana Data Types
The HashArray data type is a key-value container.
It is typeless, but a specific type can be asserted (e.g. setBool()) or retrieved (e.g. getBool(), getInt(), etc). It is up the the application to store/retrieve by type consistently.
This data type is very convenient for messaging. Calling the toString() method converts the HashArray into a string. Using the fromString() method or constructor converts it back.
What makes this XML class special is that the XML is generated from records, so it
follows a readily parsable pattern when read back in.
<recordtype id="n" pname="paramname" >
<propname >propvalue </propname >
... additional properties
<subnodename >
<recordtype id="n" >
...
</recordtype >
</subnodename >
... additional subnodes
</recordtype >
Properties a simple values inside a record. Subnodes are sub-records inside a record.
*
Note that when writing out XML property values, substitutions happen for <, >, &, " and '.
This class uses the HashArray class for key-value properties.
This is a simple graph class for general application.
Each node has a label, adjacency list, visited flag, and app-specific data.
Dice play central roll in this game. When rolled by the computer, they must be specified in an understandable format.
Dice follow this general format:
[qty]dsides[+offset][xmultiplier]
where
Term |
Description |
qty |
Optional. An integer that specifies the number of dice to roll. |
sides |
The number of sides on the dice. |
offset |
Optional. How much to add to the result of the dice roll. |
multiplier |
Optional. How much to multiply the dice roll by. Multiplication is applied last, even after offset. |
+4
-4, 4
%d, %d+5
d4, 1d4, 2d4, 2d4+3, d20+4
d4x10, 1d4x10, 2d4x10, 2d4x10+3, d20+4
d0+5
The Entity data type identifies a unique entity in the world. It may contain additional core information. An Entity may be a
Each entity has its own core information, detailed below.
A PC entity may be permanent (pc_id > 0) or temporary (pc_id==0, group & pos are reasonably unique).
A PC Entity follows this form:
pc:/settingid/pc_id,group#,pos#/size/hp,maxhp/name
where
Part |
Description |
settingid |
The id that identifies the world / game setting. id from Setting datastore. |
pc_id |
The unique id of this player. id from PC datastore. |
group# |
The combat group number where this PC was instantiated, as assigned by setting. Typically, this is 1 for the primary PC team. Required non-zero if pc_id=0. |
pos# |
The combat position number within the combat group where this PC was instantiated, as assigned by setting. Required non-zero if pc_id=0; if pc_id=0, typically ignored. |
size |
The size of the player, typicall M for mediaum. It may alternately be S for small or L for large. |
hp |
Hit points (health) remaining for the PC. |
maxhp |
Maximum hit points (health) for this Entity |
name |
The name of the entity; the preferred way to identify this entity by humans. |
A monster entity may be permanent (monsterid > 0) or temporary (mosnterid==0, group & pos are reasonably unique).
A monster Entity follows this form:
m:/settingid/monsterid/group#/pos#/size/hp,max/name
where
Part |
Description |
settingid |
The id that identifies the world / game setting. id from Setting datastore. |
monsterid |
The type of monster of this Entity. id from Monster datastore. |
group# |
The combat group number where this monster was instantiated, as assigned by setting. |
pos# |
The combat position number within the combat group where this monster was instantiated, as assigned by setting. |
size |
The size of the monster. It is S for small, M for human-sized or L for large. |
hp |
Hit points (health) remaining for the monster. |
maxhp |
Maximum hit points (health) for this Entity |
name |
The name of the entity; the preferred way to identify this entity by humans. |
A device Entity follows this form:
d:/settingid/dev_id/size/hp,max/name
where
Part |
Description |
settingid |
The id that identifies the world / game setting. id from Setting datastore. |
dev_id |
The id of the device. id from Possession datastore. |
size |
The size of the device. It is S for small, M for human-sized or L for large. |
hp |
Hit points (health) remaining for the device (if relevant). |
maxhp |
Maximum hit points (health) for this Entity (if relevant). |
name |
The name of the entity; the preferred way to identify this entity by humans. |
A phenomenon Entity follows this form:
p:/settingid/name/location...
where
Part |
Description |
settingid |
The id that identifies the world / game setting. id from Setting datastore. |
name |
The name of the entity; the preferred way to identify this entity by humans. |
location |
The unique location where this phenomenon occurs. See the Location data type. |
A vendor Entity follows this form:
v:/settingid/vendor_id/Place_id/areaid/name
where
Part |
Description |
settingid |
The id that identifies the world / game setting. id from Setting datastore. |
vendor_id |
A number that uniquely identifies this vendor. id from Vendor datastore. |
Place_id |
The place where this vendor operates. id from Place datastore. |
name |
The name of the entity; the preferred way to identify this entity by humans. |
example ids:
* pc:/3/3/M/60,72/Caric
* m:/3/421/23/1/M/12,12/Giant Spider[4]
* d:/3/334/M/60,72/Flame Tongue
* p:/3/Howling kettle/in:/4,5,0,0,0/1,1,3,/1.57,100,0,0,0
* v:/3/0/0/adhoc/AdHoc
where pc=PC, m=Monster, d=Device, p=Phenomenon, v=Vendor
The Location data type identifies a specific place in the world, both physically and logically, both outside and inside.
The world is composed of a matrix of hexagons. Each hexagon is subdivided into 10-wide sub-hexagons. Each sub-hexagon is divided into 10-wide sub-sub-hexagons. And so forth.
An outside location follows this general form:
out:/longitude,latitude,altitude,dir,place-id,place-building]
The old form was
out:/longitude,latitude[,xo,yo,z0]
where
Part |
Description |
longitude |
The east-west offset (x-axis) from the prime meridian |
latitude |
The north-south offset (y-axis) from the equator |
altitude |
The height above sealevel. |
dir |
The facing direction (if relevant), in radians, where 0 is East |
place-id |
The id of the Place, which may or may not have a map associated with it |
place-building |
The name of the building, as known at the Place |
An inside location follows this general form:
in:/longitude,latitude,altitude,dir,place-id,place-building/map-id;map-building;Level;areaId[;subAreaId]/phi,elevation,xi,yi,zi
Note the obsolete form:
in:/longitude,latitude,x0,y0,z0,map-building/map-d,Level,areaId[,subAreaId]/phi,elevation,xi,yi,zi
where
Part |
Description |
longitude |
The east-west offset (x-axis) from the prime meridian |
latitude |
The north-south offset (y-axis) from the equator |
altitude |
The height above sealevel. |
dir |
The facing direction (if relevant), in radians, where 0 is East |
place-id |
The id of the Place, which may or may not have a map associated with it. Note that an ad hoc encounter like a farm house may have place-id=0, but map-id non-zero. Likeways, a location may have a place-id, but no map, so map-id is 0. |
place-building |
The name of the building, as known at the Place. A building name may have commas in it (but not semi-colons or /). |
map-Id |
The id of the Map for inside navigation (e.g. town, dungeon) |
map-building |
The building name as known inside the Map. A building name may have commas in it (but not semi-colons or /). Places sometimes recycle maps with buildings, using the same map for multiple buildings. |
Level |
The level inside the place. Positive integers are levels above ground; negative integers are levels below ground. |
areaId |
The name of the area within the level as defined by that place. |
subAreaId |
The name of the sub-area within the area of the level as defined by that place. Note that subAreaId may contain commas, but it may not contain ";" or "/". |
phi |
The direction (in radians) of the object in this location from the x-axis that is face-forward. |
elevation |
The elevation (offset) of the object in this location above the floor. |
xi |
The x-offset on the map. |
yi |
The y-offset on the map. |
zi |
The z-offset on the map. |
Here are some example Location strings:
out:/4,5,0,1.57,
out:/4,5,0,1.57,103,Bill's Tavern
in:/4,5,1,1,3,/1;outside;-1;2A;Table #1
in:/4,5,0,0,0,1.57/105;Hotel Blue;2;204;Bedroom/1.57,100,0,0,0
A Moment identifies a moment in time down to the second.
As a string, time is specified as
year-month-day-hour:minute:second
where
Term |
Description |
year |
The year in the current age, starting with 0. |
month |
The month of the year, from 0 to 11. |
day |
The day of the month, from 0 to 29. All months have 30 days. |
hour |
The hour of the day, from 0 to 23. |
minute |
The minute of the hour, from 0 to 59. |
second |
The second of the minute, from 0 to 59. |
The Movement type is used to determine how fast something is in a particular mode of travel, e.g. over land, through water, across a web, through the air, etc.
Movement is specified as a list of properties and numbers. Each property and number is separated by a colon; each property/number pair is separated by a comma. The number is the movement rate.
The syntax is:
prop1:n1[,prop2:n2[,prop3:n3...]]
where
Property |
Meaning |
onland |
Speed over flat land. |
swim |
Speed through water. |
flying |
Speed through air. |
web |
Speed across a web. |
burrow |
Speed through the earth/land. |
hop |
Speed over land by hopping. |
For example,
onland:9
onland:12,swim:1
The Money data type represents currency, whether in the gold standard (using platinum, gold, electrum, silver and copper pieces) or dollar standard (where dollars and cents are separated by a comma).
The gold standard is represented as a commas delimited list of 5 numbers representing (in order): cp, sp, ep, gp, and pp
These coins are related using this scale: 1pp = 10gp = 20ep = 200sp == 2000cp.
The dollar standard uses an integer for the count of dollars, a comma, and count of cents from 0 to 99.
gp:1,2,3,4,5
$:100,34
This data type represents a collection of valuable items, including money, gems, and objects.
Booty is specified as a list of items, separated by spaces. Items may be coins,
Coins may be specified as
qty coin
where
Term |
Description |
qty |
A quantity is specified in one of two ways:
|
coin |
The coin name, e.g. cp, sp, ep, gp, pp |
Gems may be specified as:
where
Term |
Description |
amount |
The number of gems. It is optional; if omitted, 1 is assumed. It is an ineger or dice inside parenthesis, such as (3d6+2x1000). Note that dice represent an indetermined number; the quantity has not been determined yet. |
value |
The value of each gem. A value is specified in one of two ways:
|
Jewelry may be specified as:
where
Term |
Description |
amount |
The number of jewelry items. It is optional; if omitted, 1 is assumed. It is an ineger or dice inside parenthesis, such as (3d6+2x1000). Note that dice represent an indetermined number; the quantity has not been determined yet. |
value |
The value of each jewelry item. A value is specified in one of two ways:
|
A possession (an item that can be possessed) may be specified as:
where
Term |
Description |
amount |
The quantity of possessions. It is optional; if omitted, 1 is assumed. It is an ineger or dice inside parenthesis, such as (2d4). Note that dice represent an indetermined number; the quantity has not been determined yet. |
possessionId |
A very specific item. The id number for a possession from the Possession datastore. |
A misc object is an item that does not have an instance in the Possession datastore, presumably because it has a temporary life in the game. It may be specified as:
where
Term |
Description |
amount |
The quantity of misc objects. It is optional; if omitted, 1 is assumed. It is an ineger or dice inside parenthesis, such as (2d4). Note that dice represent an indetermined number; the quantity has not been determined yet. |
label |
A label with no space (use underscores) to give the item a name. The name does not correlate to anything. |
value |
The object's value. A value is specified in one of two ways:
|
coin |
The coin name, e.g. cp, sp, ep, gp, pp |
These are example lists of Booty:
10cp 7sp (3)ep (2d4)gp 20pp
gem:50gp (d6)gem:(d6x100)gp
(d4)misc:gold_plate:1gp (d4)misc:gold_plate:(2d6)ep
This is a HashArray of properties and values to represent change due to magic.
A HashArray is a series of keys and values. They keys are inside square backets, followed by equals sign, followed by the value. This is the syntax:
[key]=value
Needs work. These are the keys:
Key Value |
...propertyMod... |
magicid Id of the enchantment (program). |
magicmid Id of this specific manifestation of magic, and id from the Manifestation datastore. |
source The origin that initiated this magic. |
states |
time The time when this magic will take or did take effect. |
caster The Entity that controls this magic. |
affected A list of Entities that are effected by this magic. |
A Setting is a game instance where players are associated with a world and the state of that world is maintained as well as player progress/actions.
A SettingId is a datastore id (integer) that points to a specific Setting.
For a data schema, see Setting table.
The UserDevice class is used to identify an I/O endpoint abstractly so an application can have a handle to that endpoint without needing to understand protocols, terminal information, graphics standards, etc. This class abstracts all of that.
An I/O endpoint is a user. The user operatates in a role, presently the roles are dm (referee) and pc (player). A pc is unique to a setting or game milieux/environment/system. A dm may referee multiple settings. A pc connection may be from the owning user id, a proxy user id (friend), or the dm.
An I/O endpoint runs one or more applications inside the system. This is called the app mode.
The UserDevice class captures the role, user id, pc id, setting id, and app mode. Those elements uniquely identify a endpoint/connection.
The endpoint has predefined elements: menus, attention box, and chat box. The menus are implmented using the local graphics system. Menus are only two-levels. An attention box is a prominent way to present a message/alert to the user. The chat box is used for communicating among multiple users.
The UserDevice class also has an optional pararameter known as a region. This is an area/hotspot/named element of the interface. To format text into something attractive, the various elements of the screen/page/display are named. Text is sent to that named region so output appears comprehensible (and hopefully user-friendly!) to the end-user. When the user enters data, clicks or otherwise activates an element of the interface, that element's name is passed through UserDevice as the region.
The UserDevice class has a method toString() which can be later passed to instantiate another UserDevice with all the key information.
Syntax:
This string follows the format:
role:/userid/pcid/wid/app[/region[/group]
where
Term |
Description |
role |
The role is either dm or pc. In DM role, the userid must be non-zero; and the pcid is 0. |
userid |
The id from the User datastore. In PC role, the userid may be 0 to broadcast something to all endpoints in used by the pc. In PC role, pcid must be non-zero. |
pcid |
The id from the PC datastore. In DM mode, the pcid is 0 for privileged/referee interaction. |
wid |
The id from the Setting datastore. |
appmode |
The appmode can be one of: console, userman, mapedit, hexit, market, supervisor. The label for the appmode may be 100 characters or less. |
region |
The region varies based upon the appmode. It identifies the UI area of focus, whether for input or output. The region 'attn' is common to all apps; it represents the attention box. The label for the region may be 100 characters or less. |
group |
This is an internal value used for routing. |
Example UserDevice endpoint identification strings:
dm:/1/0/console
pc:/1/3/console
pc:/3/3/3/console//E3
pc:/3/3/3/console/attn/E3
pc:/3/3/console/attn
UserDevice is implmented using messages across a message bus to two daemons: usergw (channel: display) and guibroker (channel: input, gui). The usergw daemon is like a device driver - it knows how to convert the request into the graphical display's protocol/API/syntax. It also knows how to take input from the endpoint and standardize it into an understandable input in this system. It forwards those inputs to the guibroker daemon. The guibroker daemon plays two key roles: it responds to user input (such as user keystroke, mouse click, hotspot activiaction or command request) and it handles non-simple I/O (such as prompting user with a question, sending a user interface control (selector, textbox), or handling a form with multiple input entry areas). The guibroker daemon is more abstract than the device-aware usergw daemon.
Input initiated by the user and non-simple I/O is then translated into requests on the message bus to which system applications subscribe and process. For example, the setting daemon as a SettingApp class with a method to process messages on the 'setting' channel. These messages often come from guibroker, but they may come from other daemons in the system as well. The SettingApp daemon acts as a setting processor that responds to its defined set of requests.
This data structure abstracts a vector image. The API is used to describe the image. It is not rendered into JPG, PNG, SVG, or other specific image technology until it is ready to be rendered to the end-user. Rendering is performed by the imager daemon.
The API could be richer, but the API must be able to render to each of the ultimate image types.
The Image class may refer to an existing image file in a specific format via ImageLib class, which specifies where to retrieve the image and the image's size.
setSize(double newWidth, double newHeight, int newUnitSize)
Set the canvas dimensions and specify how many pixes per unit. For example, a 4.0x5.0 image where unit size is 10 would create a 40x50 pixel image.
setOrigin(double newOriginX, double newOriginY)
Specify how many units over the origin should be located if (0,0) is the lower left
setWindow(double minX, double minY, double maxX, double maxY, int newUnitSize)
Specify the width and origin implicitly by specifying the window into the view. Use this instead of setSize() setOrigin()
drawBox([[#Point]] corner1, Point corner2, string color, bool fill, string link)
Draw a rectangle with the corners specified. Default color is black. The box may be an outline or solid/fiilled.
An optional link (e.g. URL) may be provided if resulting image supports linking.
drawLine([[#Point]] p1, Point p2, string color, string link)
Draw a line from p1 to p2 of the color specified.
An optional link (e.g. URL) may be provided if resulting image supports linking.
drawCircle([[#Point]] center, double radius, string color, bool fill, string link)
Draw a full circle with the specified center and radius. The default color is black. The circle may be an outline or solid/fiilled.
An optional link (e.g. URL) may be provided if resulting image supports linking.
drawText([[#Point]] start, string text, string color, string link)
Draw text into the image with the lower left corner of the text at the start point.
bool drawArc([[#Point]] center, double startang, double endang, double radius, string color, bool fill)
drawPolygon([[#Point]]List p, string color, bool fill, string link)
Given a series of points, draw the enclosed polygon. The default color is black. The polygon may be an outline or solid/fiilled.
An optional link (e.g. URL) may be provided if resulting image supports linking.
drawPolyline([[#Point]]List p, string color, string link)
Given a series of points, the the line that connects them from start to end. The default color is black.
An optional link (e.g. URL) may be provided if resulting image supports linking.
This class holds a reference to and then ultimately delivers the binary content of an image in the Image Library (the ImageLib table). This class holds the image id, name, category, image type, height and width of the image.
The IniFile class is used to read .ini files and provide methods to query values from its various sections.
The IniFile class reads a standard INI file format.
Syntax:
The first line of output is the headers:
AppName,Section,Variable,Value
where,
Header |
Description |
AppName |
The name of the application for these properties. |
Section |
The section (grouping) of the application for these properties. |
Variable |
The keyword for the property. |
Value |
The value of the property. |
A document is a abstract document that is not format specific until it is rendered.
Today, a document can be output to HTML or PDF. Other formats are expected for the future.
A document is made up of a series of blocks.
An example block is: header, paragraph, table cell, image
A block is made up of a series of items.
An example item is: text fragment of a particular style.
White space is not automatically added between items.
A region is a block.
Text written to a region is appended.
A bookmark is an anchor where a link from elsewhere in the document points to.
A link points to a bookmark inside the document. An external link points to somewhere outside the document.
An index key is the text that appears in a generated index, perhaps different from the text it references.
When headers are used, Document can generate a table of contents for the document.
When named indexes are used, Document can generate an index for each named index.
A MetaDocument can be thought of as a formatting/reporting language that generates a Document. This class takes three inputs to render a Document:
The template text is processed; it pulls in content from data and params when directed to do so.
Template text format:
Text is read a line at a time. Commands are arranged one per line. See metadoctool for language details.
Metavariables and metafunctions may be defined to reach out into the calling application to retrieve text that may be more dynamic or programmatic to derive.