Skip to content

Data structure overview

Jump to bottom
Amadeusz Sadowski edited this page Jan 24, 2020 · 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. index.bsi is just a zip file that contains a single index.xml file.
  • 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

TODO

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 costs
      • 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? if checked, the constrained value is a sum of all selections of this shared entry in roster in total; if unchecked, the sum is calculated for a given entry link instance.
      • 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 its parent or the Value of its parent's Constraints. If the parent is a Link, it may instead change the properties of the link's target or the Value of the link's Constraints.

A modifier that is the ancestor of one or more Conditions may be referred to as a "Conditional Modifier".
A modifier that is the ancestor of one or more Repeats may be referred to as a "Repeating Modifier".

Children:

Properties:

  • Modifier
    • Type
      • Increment - Field must be numerical. Increases Field by Value.
      • Decrement - Field must be numerical. Decreases Field by Value.
      • Set - Sets Field to Value.
      • Append - Field must not be numerical or boolean. Appends Field with Value. A space is implicitly added between Field and Value.
    • Field - selects the property or Constraint that will be modified.
    • Value - the amount to modify Field by.

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.

No children.

Properties:

  • Condition - The test that is made to determine the outcome.
    • Type - one of less than|greater than|equal to|at least|at most|instance of|not instance of. Determines how to compare Value and Query. Where Scope is Ancestor, only instance of|not instance of are valid.
    • Value - the number to be compared with Query. Has no effect where Type is instance of|not instance of.
    • Value is percentage? - if checked, Value will be interpreted as percentage. Has no effect where Type is instance of|not instance of.
  • Query - how much is counted to be compared with Condition.
    • Field - what to count. Either selections or Cost Type. Has no effect where Type is instance of|not instance of.
    • Scope - one of parent|ancestor|roster|force|primary category, any ancestor, any Category, or any Force. Determines where to look in order to sum the Field.
    • And all child selections? - whether constrained value is just Scope's Field (unchecked), or a sum of all descendant selections (checked). Has no effect where Type is instance of|not instance of.
    • And all child forces? - whether constrained value is calculated only from parent force selections (unchecked), or all of its descendant forces too (checked). Has no effect where Type is instance of|not instance of.
  • Filter By - The filter to apply to determine the tested value. of|(select)|(enter id) will adjust themselves to match each other when a valid selection or Unique ID is given.
    • (select) - drop-down list of available selections. May be anything|unit|model|upgrade, any Category, any Force, or any SSE.
    • (enter id) - textbox to enter the filter. May be any|unit|model|upgrade or the UID of any Category, any Force, or any SSE.
    • Shared?

Condition Group

A condition group allows logic to be applied to a group of Conditions. Condition groups may also be nested in order to provide more complex logic.

Children:

Properties:

  • Type
    • And|(and) - is true iff all of its children are true.
    • Or|(or) - is true iff any of its children are true.

Repeat

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

No children.

Properties:

  • Repeat - The test that is made to determine the outcome.
    • Repeats - the number of times the parent modifier should apply each time the Query is met.
    • Value - the number to be compared with Query.
    • Value is percentage? - if checked, Value will be interpreted as percentage.
  • Query - how much is counted to be compared with Repeat.
    • Field - what to count. Either selections or Cost Type.
    • Scope - one of parent|roster|force|primary category, any ancestor, any Category, or any Force. Determines where to look in order to sum the Field.
    • 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).
  • Filter By - The filter to apply to determine the tested value. of|(select)|(enter id) will adjust themselves to match each other when a valid selection or Unique ID is given.
    • (select) - drop-down list of available selections. May be anything|unit|model|upgrade, any Category, any Force, or any SSE.
    • (enter id) - textbox to enter the filter. May be any|unit|model|upgrade or the UID of any Category, any Force, or any SSE.
    • Shared?

Roster entries

Following are elements of rosters.

Roster

TODO

Force

TODO

Selection

TODO

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.

TODO update to publication

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: Author Details

  • Name TODO
  • Contact TODO
  • Website TODO

Unicorns

Shared?

A checkbox on Constraint, Condition and Repeat elements (part of query).

An explanation of the behavior was initially provided by the BattleScribe developer, for an instance see https://github.com/BSData/wh40k-7th-edition/issues/2880

Collective?

That checkbox, when checked, requires all other selections of parent entry to also have this entry selected. A whole-page explanation with examples: Help:-Collective-Entries

TODO: Update to 2.02 (libraries, Publications, new Groups etc)

Clone this wiki locally