Skip to content

Data structure overview

Jump to bottom
Will Pattison edited this page Jun 5, 2018 · 15 revisions

Overview

Here you can find the description of basic building blocks of datafiles.

Files

All files are saved as XML (.cat/.gst/.ros), or as a zip archive containing XML files (.catz/.gstz/.rosz/.bsr/.bsi).

Datafiles

Datafiles are essentially either Catalogues or Rosters, both using similar but separate schemas.

  • Rosters (.ros/.rosz) define the actual list of selections, grouped into forces, and are the final product of using BattleScribe.
  • Catalogues (.cat/.catz) are datafiles containing very detailed templates from which one can later create and validate rosters.
    • There is a very special type of catalogue that acts as a "root" - it's called the game system (.gst/.gstz). Game systems are datafiles that define gameSystemId which is referenced in every other catalogue belonging to the system. This allows BattleScribe to detect what game systems are defined in the data, and show only catalogues that are associated with it.

Supporting files

There are also two additional file types that support file distribution:

  • Indexes (index.xml/index.bsi) are a kind of a protocol/manifest whose URL acts as an identifier of an internet data source for BattleScribe. They are lightweight index files that list files and versions (and these files' URLs), and based on this info, BattleScribe decides whether a file has an updated version for download.
  • Repository distributions (.bsr) are zip archives containg whole data package:
    • an index.xml file defining contents of the archive, and possibly additional repository URLs to subscribe to;
    • catalogues and gamesystems.

Detailed description

Catalogues

The structure is a tree as follows:

Catalogue

Catalogues are the complete datafile structure, containing all building blocks required for BattleScribe to create a roster. Game system catalogues are the root of the logical file structure, and the root of the file is a catalogue structure.

Children:

Properties:

Category Entry

Category entries are tag-like entities. They can be a target of condition (e.g. count all Big units where Big is a category these units have). A SE may define a primary category, under which that selection will be available in roster.

Children:

Properties:

Characteristic

Characteristic defines a value for a given characteristic type. This value is always textual, although for certain modifiers it can be parsed by BattleScribe as a numeric, just for the duration of modification.

No children.

Properties:

  • Characteristic Type Id only visible in internal xml representation, references what characteristic type this value represents.
  • Name is copied from characteristic type's name property, not editable.
  • Value the actual editable field, textual value of this characteristic.

Characteristic Type

Characteristic type defines a name for a single field of profile type, later referenced by an actual characteristic to identify which field's value it represents.

No children.

Properties:

Cost Type

Cost types are an extension of the old points-only system. They abstract away points and any other cost system for your game. Cost types define a countable resource that should be summed up and/or limited in rosters.

No children.

Properties:

Force Entry

Force entries define the structure of the roster and are a representation of a detachment, battalion or strike force. All selections within must originate from a single catalogue.

Children:

Properties:

Profile Type

Profile types define a name for a list of characteristic types, which is then selected as a type for a profile. You can think of a profile type as a column set, where each column is a characteristic type. Multiple profiles with the same profile type will be displayed together, creating a table.

Children:

Properties:

Profile

Profiles are a named list of characteristics. They are used both in catalogues and rosters.

Children:

Properties:

Rule

Rule is the only multi-line textual entity in all of BattleScribe data structure (you may enter line breaks in other places, but only this one is guaranteed to preserve them). It also has a displayable name.

Children:

Properties:

Selection Entry

This is the most core, ubiquitous construct, along with SEG. These two are absolutely fundamental, and define the actual selection tree presented to the user. These entities are displayed during roster creation/editing, and represent units, models, upgrades and other equipment/abilities that require similar semantics.

Selection Entry Group

SEG groups together SEs that should be constrained together, or just to visually group some selections in Roster Edit view.

Links

Category Link

Entry Link

Info Link

Constraint

Modifier

A modifier may change the properties of a Category, Force, Selection Entry, Selection Entry Group, Profile, or Rule. A modifier may set any property to a given value. Numerical properties may be incremented or decremented by a given value. Non-numerical, non-binary properties may have text appended to them (note that appending text implicitly adds a space between the original text and the appended text). A modifier with a Condition may be referred to as a "Conditional Modifier".

Condition

A condition may be added to a Modifier in order for it to require a given prerequisite to be met before the modifier's effects will apply. Applying multiple conditions to a modifier without the use of a Condition Group will require all of the conditions to be met. A condition consists of three major parts:

  • Condition: The test that is made to determine the outcome, such as whether a value is less than, greater than, or equal to a given value.
  • Query: The value that will be tested and the scope in which to test, such as the number of selections in a roster or the cost of a parent.
  • Filter By: The filter to apply to determine the tested value, such as a category or shared selection entry.

Condition Group

A condition group allows logic to be applied to a group of Conditions. An (and) condition group requires all of its child conditions to be met. An (or) condition group requires any of its child conditions to be met. Condition groups may also be nested in order to provide more complex logic.

Repeat

A repeat functions in the same manner as a Condition, with the exception that it may cause the Modifier multiple times. This is most commonly used for increment and decrement conditions.

Rosters

Following are elements of rosters.

Roster

Force

Selection

Common property groups:

Props: Basics

Basics

  • Unique Id short UUID, actually can be any unique text, internally used to distinguish, identify and reference entities. Almost every entity has it.
  • Name a common, visual, textual name of the entity, non-unique, displayed in the GUI (visual interface) of both Roster and Data editor.

Props: Reference

Reference:

  • Book is a textual field containing name of book or similar publication where the entity originates from.
  • Page is a textual field describing the part of the publication to look for this entity in.

Props: Revision

Revision

  • Revision Number is a numeric, integral value. This value is used in [data index][], and if it's higher, the file will be updated.

Props: Entry

Entry:

  • Hidden? if this field is checked, the entity will not be visible to the user, and any already selected entries will cause error showing up in error list in Roster Editor. You can change the value of this field through a modifier which is the primary use case of this property.

Props: Author Details

Author Details:

  • Name
  • Contact
  • Website
Clone this wiki locally