-
Notifications
You must be signed in to change notification settings - Fork 458
Guidelines
We have some guidelines to standardize our catalogues. Previously there have been some suggestions that BS cats for 40k are very different in usage and one must learn every catalogue separately.
These guidelines are not "set in stone", they are developed from discussions among the data authors of what has/hasn't worked for them. As such, you may find exceptions on their application - but that's mostly due to historical reasons. Discussion is welcomed on our Discord.
Hopefully these guidelines will be applicable for most applications, (as far as possible) and the resulting catalogues will provide the finest user experience possible.
(Originally Posted in Issue #3 - that's the place for further meritorical discussion)
- gst - game system file with
.gstextension - cat(s) - catalogue file(s) with
.catextension - entry, group, profile, rule, modifier, condition etc. all refer to constructs found in cats and gst
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
- create: new guidelines MUST be added at the end
- modify: guidelines MAY be updated under an agreement of Core team members
-
remove: guidelines MUST NOT be removed unless complete document rewrite is done. If a guideline is deprecated or no longer applies, it SHOULD be formatted with
strikethroughwith a short explanation.
All choices, entries, upgrades etc. that are valid or possibly valid MUST be represented (implemented) and MUST NOT raise errors/warnings. This is the single most important rule. If there is a doubt if an option is legal, it MUST be included.
Motivation: we are not rules lawyers. Our effort targets all audiences, no matter their personal decisions, erratas or agreements.
Disclaimer:
- Our only source is Rules As Written (RAW), published by Games Workshop and their subsidiaries (Forge World etc.); that includes officially posted Erratas and FAQs (Facebook pages, emails and other unofficial channels excluded).
- If you feel we've missed a valid option (and you can provide reasonable argument supporting its legality) please raise an issue on GitHub.
- Datasheets included in physical box sets are an exception from our typical policy of inclusiveness, dictated simply by economical and practical means: we're not able to buy every single box and/or access every such datasheet by other means. If there's a request to include a specific datasheet, and the catalogue author has access to such datasheet, the catalogue maintainer can choose to include that specific box-sheet.
Gst MUST NOT contain shared wargear entries, only profiles and rules for them. Different factions have differently priced things, no reason to make errors easier while changing values in future. Shared entries in gst (for wargear) are a bad idea. Profiles and rules (inlc. abilities) are ok, but wargear has so differing point costs, usage etc. every catalogue should define them separately (again, entries - they'd link to gst profiles and rules).
Catalogues SHOULD define all profiles and rules as shared and link to them where needed.
Catalogues MAY define shared entries for wargear that's used in multiple places in the same way.
Catalogues MUST define units as shared entries to be available for other purposes like validation etc.
Catalogues SHOULD define all Selection Entry Types (unit/model/upgrade) in such a way that when building a roster, model count would reflect reality. To achieve that:
- Model MUST be applied to every entry that represents a physical in-game model;
- Unit MUST be applied to entries that may contain more than one Model (but are not themselves Models);
- Upgrade for all other entries.
Catalogues MUST link to shared entries that represent selectable choices and assign appropriate categories to these links.
Unaligned units MAY have gst shared entries and selection entry links.
Units with more than one top-faction keyword MAY have gst shared entries but MAY NOT have selection entry links [in the gst].
Non-Unaligned units MUST NOT have gst shared entries and selection entry links.
Sergeant/model choice RECOMMENDED implementation: an entry group named 'Members (min-max)' or similar with constraint on it min/max like datasheet says, commonly sergeant 0-1 and normal guys (min-1)-max. Validation is easier and roster edit view is nicer.
Units SHOULD be implemented in such a way that when adding unit to roster, it is a valid choice (no errors/warnings raised) and also resembles as close as possible the choice as presented by default in unit's datasheet.
Weapon options for Units SHOULD have an appropriate name, such as "Replace Weapon X with Weapon Y", "Weapon X options", or similar.
Psychic powers SHOULD be included as a selection group, since they are deliberately selectable by the controlling player before the battle starts.
Catalogues MUST be named according to following conventions. Faction refers to the most generic faction keyword shared by all units in catalogue, Sub-Faction is the most specific faction keyword shared by all units in catalogue. The template shown is for internal catalogue name, and should have .cat suffix for filename (don't use underscores).
-
{Faction}- use when there is no sub-faction (e.g. Tyranids, Necrons, Orks). -
{Faction} - {Sub-Faction}- use for any catalogues which contain units from Faction's subfaction (e.g. Chaos, Imperium, Aeldari, Tyranids in case of Cults). -
{Faction} - FW {Sub-Faction}- use when creating a separate catalogue for units published by Forge World.
Note that it is perfectly possible to have catalogue with just top faction and another with a subfaction within that faction, the perfect example being Tyranids who have the "main" catalogue, and a subfaction catalogue for Genestealer Cults.
Keywords SHOULD be represented as Category links for the unit entry.
Categories (Keywords) that apply to the Faction line in the data sheet SHOULD include the prefix "Faction:", e.g. "Faction: Imperium".
For example, an Ethereal should have the following categories linked: Faction: T'au Empire, Faction: <SEPT>, Character, Infantry, Ethereal.
Forge World publications SHOULD be incorporated into existing catalogues if they do not introduce a new subfaction requiring its own file.
Root selection entries SHOULD NOT be hidden by default - it obstructs discoverability and hinders UX; instead when invalid configuration occurs, a warning should be raised.
Forge World units SHOULD be considered mainline and not be tagged specifically (so no [FW] prefixes or suffixes, or similar) - instead, reference the source in unit profile's book field.
Each faction SHOULD have a local "Warlord" entry available to characters, which MUST have the gst Warlord category.
Relics SHOULD be validated against the Warlord entry, as well as any stratagems that allow for extra relics.
Warlord Traits SHOULD be available for selection by the Warlord, but MUST NOT require a minimum number to be selected.
Psychic Powers SHOULD be available for selection by psykers, but MUST NOT require a minimum number to be selected. #2316
Units published as Beta Rules by GW official channels MAY be included, but if they are, MUST be marked with (Beta) postfix. Additionally, they MUST require Use Beta Rules GST entry (by having constraint "set max to 0 when 0 'Use Beta Rules'")).
Unit abilities SHOULD be added as follows:
Abilities that DO NOT have their full text in the unit's Abilities block -> Rules
Abilities that DO have their full text in the unit's Abilities block -> Profiles with the "Abilities" type.
It is left to the author's discretion whether to add abilities that are handled by logic e.g. an ability that adds a keyword in specific circumstances, or whether to add local profileTypes to better display a particular ability.
Placeholder.
Placeholder.
Placeholder.
Placeholder.
Placeholder.
Placeholder.