Skip to content

Data structure overview

Jump to bottom
Amadeusz Sadowski edited this page Jun 6, 2018 · 15 revisions

Overview

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

ToC

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

Catalogue entries

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.

Children:

Properties:

  • Basics
  • Reference
  • Hidden
  • Collective
  • Type - can be one of: upgrade|model|unit, this is a metadata-like property that doesn't directly impact Roster Edit View, but might impact how given selection is displayed in Roster Display View, and also is taken into account for roster statistics e.g. model count.

Selection Entry Group

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

Children:

Properties:

  • Basics
  • Reference
  • Hidden
  • Collective
  • Default Selection - this is an optional field referencing child SE, that will be automatically selected when this group's parent is selected, in the amount equal to constraint with min type and value greater than 0.

Links

Category Link

Category links are not visible directly, but rather as part of parent entity's properties. They reference existing category entries, thus "assigning" parents to these categories. A very important part for root entries is selecting a primary category - this will be the category in which that entry will be visible in Roster Editor

No children.

Properties:

  • Basics (uneditable)
  • Target Id - invisible, contains the ID of category entry this link references.

Entry Link

This represents a reference to another entity, either a SE or SEG that will be visible for selection in link's parent. The target must be from the shared lists contained in the same catalogue. Because of game-system level import, that also includes shared entries from game system catalogue, as they are imported on almost equal rights as catalogue-defined ones (but read-only).

Children:

Properties:

  • Basics
  • Reference
  • Hidden
  • Link Type - either Selection Entry or Selection Entry Group
  • Link Target (Link To) - the shared (a child of catalogue's shared list) SE or SEG this link references, may be selected either by directly entering referenced entity's ID, or by selecting from dropdown. For huge catalogues, copy-pasting IDs may be faster than finding the target in dropdown.

Info Link

This represents a reference to another info-entity, either a profile or rule that will be visible for selection in link's parent. The target must be from the shared lists contained in the same catalogue. Because of game-system level import, that also includes shared info-entities from game system catalogue, as they are imported on almost equal rights as catalogue-defined ones (but read-only).

Children:

Properties:

  • Basics
  • Reference
  • Link Type - either Profile or Rule
  • Link Target (Link To) - the shared (a child of catalogue's shared list) profile or rule this link references, may be selected either by directly entering referenced entity's ID, or by selecting from dropdown. For huge catalogues, copy-pasting IDs may be faster than finding the target in dropdown.

Limits, modifiers, conditions

Constraint

Constraints represent various limits applied on parent entry. They are also a common target of modifiers which may change these limits depending on various conditions.

No children.

Properties:

  • Id - same as Id in Basics.
  • Type - one of min|max, decides whether this is an (always inclusive) upper or lower bound of constrained value.
  • Value - an (inclusive) integral bound value.
  • Value is percentage? - if checked, the Value will be interpreted as percentage.
  • Query defines how the bounded value is calculated:
    • Field - selects what value of parent entry will be summed up to get the value onto which this constraint should be applied. The available values depend on the parent:
      • for selection entries and groups, it's either selections or one of defined [cost][]s
      • TODO
    • Scope - one of parent|roster|force|primary category or any type of ancestor identifier, this decides which entity should sum up all field's values of descendant selections of this constraint's parent entry.
    • switches:
      • Shared? TODO
      • And all child selections? whether constrained value is just scope's field (unchecked), or a sum of all descendant selections (checked).
      • And all child forces? whether constrained value is calculated only from parent force selections (unchecked), or all of its descendant forces too (checked).

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.

Roster entries

Following are elements of rosters.

Roster

Force

Selection

Common property groups:

Props: 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

  • 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 Number is a numeric, integral value. This value is used in [data index][], and if it's higher, the file will be updated.

Props: Hidden

  • 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: Collective

  • Collective? - that checkbox, when checked, requires all other selections of parent entry to also have this entry selected. TODO - complicated, requires more docs, links

Props: Author Details

  • Name
  • Contact
  • Website
Clone this wiki locally