Unit Data Schema — Topic 02: Equipment & Variants — Omega War
Stage 2 · per-topic review · topic 02 of 6 · cycle unit-data-schema · page created 2026-06-14
This page reviews topic 02 only — the
EquipmentItem entity and the
Variant (upgrade) entity, resolving topic 01's open question "equipment as entity vs
attribute" — compiled from the working doc
research/_working/unit-data-schema/02-equipment-and-variants.md. The cycle was decomposed
(at the user's direction) into six per-topic docs reviewed one by one; the canonical
artifact research/unit-data-schema.md is the later synthesis of all six topics,
not this page. This page authors no canonical artifact and no glossary
output, and it stays review.
Boundary (UD-A1): this topic defines shape, not values — entities, fields, enums, relationships, and a few clearly-marked illustrative rows. It assigns no equipment stats (penetration, rate of fire, range, weight), ammo loadouts, upgrade/variant costs, availability trade-offs, or balance. Static-vs-runtime discipline (topic 01) holds: everything here is authored static catalogue data on the
card; storage medium is deferred to the tactical vertical-slice spec.
review) authored the card entity and left three relationship slots for this
topic: equipment: ref<EquipmentItem>[] ("separate-entity vs attribute decision lives in
topic 02"), variants: ref<Variant>[] ("separate-card variants / upgrade packages —
modeled in topic 02"), and transport_options: ref<Card>[] (the config-pattern transport
selection). Topic-01 open question "equipment as entity vs attribute" is resolved here.
1. Purpose & scope of this topic
Define the EquipmentItem entity and the Variant
(upgrade) entity, and fix how each attaches to the card. Arsenal §4A.1 already names the three
upgrade-mechanic patterns the genre uses; this topic turns those patterns into schema shape — entities, fields,
enums, relationships — without authoring any specific kit values, costs, or magnitudes (UD-A1).
Same static-vs-runtime discipline as topic 01. Everything here is authored
static catalogue data referenced by the card; no runtime/instance state, and the
storage medium (content files vs DB) is deferred to the tactical vertical-slice spec under UD-A1. This topic
fixes which kit and upgrades exist and how they attach, not how well they perform.
2. The three §4A.1 upgrade-mechanic patterns
Arsenal §4A.1 (ACCEPTED) models variants/upgrades three ways. The schema must be able to express each — the
Variant entity (§4) carries a kind discriminator with one member per pattern.
| # | Pattern (§4A.1) | Genre example | Schema home |
|---|---|---|---|
| 1 | Separate-card variant — major kit is its own card beside the base | SD2: Firefly is its own card beside Sherman V | a sibling card + a Variant link of kind separate_card |
| 2 | Per-squad munitions upgrade — ammo/weapon package toggled on a card | CoH3: BAR package, then a 2nd BAR | a Variant of kind munitions_upgrade attached to one card |
| 3 | Configuration trade-off — veterancy / transport / phase chosen per card | SD2/WARNO: veterancy buys quality vs availability; nested transport; phase slotting | a Variant of kind configuration, or an existing config field on the card |
§4A.1 recommendation (design intent, not values): major kit = separate cards; ammo/weapon packages = munitions upgrades; veterancy/transport/phase = configuration.
3. The EquipmentItem entity — equipment-as-entity
Proposed decision: equipment is a first-class entity referenced by the card — not a
free-form per-card attribute. Rationale: arsenal §3's per-faction equipment is shared and reused across many
cards (the same MG, gun, or ammo type recurs), carries its own provenance (zone /
plausibility_tier / source_ref — the same source-quality fields topic 01 fixed), and
is the natural anchor for munitions-upgrade variants. A shared catalogue entity de-duplicates that; a per-card
string attribute would not.
| Field | Type | Req? | Source | Notes |
|---|---|---|---|---|
id | string (stable key) | required | schema | Stable internal identifier; never a display name. |
display_name | string | required | §3 cells | Historical name (e.g. "M1919A4 .30 cal"). |
equip_class | enum EquipClass | required | §3 | Coarse kit class. Value set in §5.1. |
mount | enum Mount | optional | §3/§4A.1 | How it is fielded: infantry-carried / towed / vehicle-mounted. Value set in §5.2. |
zone | enum Zone | required | §4B | Same provenance dial as the card (baseline / stretch / what_if). Reused from topic 01 §3.4. |
plausibility_tier | enum Tier | optional | §2/§3 | T1–T4 evidence tier; reused from topic 01 §3.5. |
framing_note | string | optional | §4B | Provenance/what-if framing (e.g. "captured-Panzerfaust"). |
source_ref | string | optional | §3 | Citation/claim anchor (e.g. "Claim 1.9"). |
No stats. Penetration, rate of fire, range, weight, ammo counts — all deferred
(UD-A1). This entity fixes which kit exists and how it is fielded, not how well it performs. On the
card: equipment: ref<EquipmentItem>[] (optional, per-faction) — the slot topic
01 left open.
Gate — equipment-entity-vs-attribute required · resolves topic-01 OQ
This resolves topic 01's open question. Model equipment as a first-class shared entity referenced by the card (the proposal above), or as a free-form per-card attribute?
Gate — equipment-model required
Approve the EquipmentItem field shape and required set (§3), with all stats deferred (UD-A1)?
4. The Variant entity — the upgrade/variant link
A Variant is the authored upgrade option offered on a card. It is the single shape that
expresses all three §4A.1 patterns via a kind discriminator.
| Field | Type | Req? | Source | Notes |
|---|---|---|---|---|
id | string (stable key) | required | schema | Stable identifier. |
display_name | string | required | §4A.1 | Shown on the card/upgrade UI (e.g. "HVAP rounds"). |
kind | enum VariantKind | required | §4A.1 | separate_card / munitions_upgrade / configuration. Value set in §5.3. |
base_card | ref<Card> | required | §4A.1 | The card this variant is offered on / derived from. |
target_card | ref<Card> | optional | §4A.1 | For separate_card: the sibling card this variant resolves to (else null). |
grants_equipment | ref<EquipmentItem>[] | optional | §3/§4A.1 | For munitions_upgrade: the kit the package adds. |
config_axis | enum ConfigAxis | optional | §4A.1 | For configuration: which trade-off axis (veterancy / transport / phase). Value set in §5.4. |
exclusivity | enum Exclusivity | optional | §4A.1 | Whether variants on a card are mutually exclusive or stackable. Value set in §5.5. |
zone | enum Zone | optional | §4B | Provenance of the variant where it differs from the base card. |
effect | deferred | — | UD-A1 | Magnitudes, costs, availability trade-offs — deferred (no numbers this cycle). |
The effect slot is intentionally a deferred placeholder: §4A.1's "veterancy buys
quality at the cost of availability (4/8/16 rookie vs 2/4/6 elite)" is exactly the kind of magnitude this
cycle does not author. On the card:
variants: ref<Variant>[] (optional, per-faction) — the slot topic 01 left open.
Gate — variant-model required
Approve the single Variant entity with a kind discriminator covering all three
§4A.1 patterns (§4), with effect magnitudes deferred (UD-A1)?
5. Enum value sets (shape, not values)
Enumerating allowed members is schema shape, not balance. Five enum sets follow; two
(Zone, Tier) are reused from topic 01 and not redefined here.
| Enum | Members | Meaning |
|---|---|---|
EquipClass (required on EquipmentItem) | small_arms, mg, at_weapon, gun, ammo, flame, engineering, optics_ir, air_loadout | Coarse kit class (shape; final set confirmed at synthesis against §3). gun = towed gun/artillery piece; ammo = ammo/munitions package. Grounded in §3 tables + §4A.1 named upgrade types (HVAP/APDS ammo, IR optics, air HVAR/napalm loadouts). |
Mount (optional) | infantry_carried, towed, vehicle_mounted | How the kit is fielded; distinguishes a carried MG from a tripod-towed or hull-mounted one without duplicating the topic-01 card_class split. |
VariantKind (required on Variant) | separate_card, munitions_upgrade, configuration | One member per §4A.1 pattern (§2). The core discriminator of the topic. |
ConfigAxis (optional) | veterancy, transport, phase | Only meaningful when kind = configuration. veterancy/phase reference topic 01 / topic 03 fields; transport references the topic-01 transport_options slot. |
Exclusivity (optional) | exclusive, stackable | Whether picking one variant on a card locks out the others (exclusive) or combines (stackable). Shape only — slot counts deferred. |
6. Relationship diagram
| Entity | Relationship to card | Where modeled |
|---|---|---|
| EquipmentItem | equipment (optional ref list; shared catalogue) | Resolved here — topic 02 §3 |
| Variant | variants (optional ref list) | Resolved here — topic 02 §4 |
| Variant → base_card | base_card (required ref back to a card) | Topic 02 §4 |
| Variant → target_card | target_card (separate-card only) | Topic 02 §4 |
| Variant → EquipmentItem | grants_equipment (munitions only) | Topic 02 §4 |
| faction | faction (required ref) | Topic 04 / synthesis |
7. Illustrative filled rows (shape demonstration only — NO values)
One row per §4A.1 pattern, marked illustrative. They show field population, not balance — no costs, no stats.
Variant.id | display_name | kind | base_card | target_card | grants_equipment | config_axis |
|---|---|---|---|---|---|---|
uk_sherman_firefly | Firefly (17-pdr) | separate_card | uk_sherman_v | uk_firefly_vc | — | — |
us_bar_package | 2nd BAR package | munitions_upgrade | us_rifle_squad_45 | — | [us_bar_m1918] | — |
ussr_tankriders | Tank-rider (desant) | configuration | ussr_t34_85 | — | — | transport |
Row 1 is the separate-card pattern (Firefly beside Sherman V, §4A.1 UK). Row 2 is the munitions-upgrade pattern (CoH3-style BAR package, §4A.1 US). Row 3 is the configuration pattern (desant tank-riders on any T-34/IS card, §4A.1 USSR).
8. Open questions carried to synthesis
- open
EquipClassfinal set (§5.1) — confirm the coarse kit-class list against §3 per-faction tables at synthesis. - open Variant ↔ separate-card duplication — when a
separate_cardvariant points at atarget_card, synthesis must confirm there is no double-counting in the To&E/deck topics (05/04). - open Where transport config lives — whether
transport_options(topic 01) stays a card field, becomes aconfigurationVariant, or both, is a synthesis reconciliation across topics 01–04. - open Air loadout granularity — whether air HVAR/napalm loadouts are
munitions_upgradeVariants orEquipClass = air_loadoutEquipmentItems (or both) — a synthesis refinement.
The disposition of these open questions is carried by the route gate below.
Gate — route required
How should the cycle proceed? This also disposes the §8 open questions (they carry to synthesis unless you direct otherwise in notes).
9. Deferred-values register (this topic)
| Deferred | Why | Where it lands |
|---|---|---|
| Equipment stats (pen / RoF / range / weight) | UD-A1 shape-not-values | later balance pass |
| Variant effect magnitudes & availability trade-offs (4/8/16 vs 2/4/6) | UD-A1 | prototype balance pass |
| Upgrade/variant costs & slot counts | UD-A1 | prototype balance pass |
| Per-faction full equipment catalogue contents | arsenal §3 (values) | balance/content pass |
10. Source log (topic 02)
This is a design-synthesis topic over already-approved internal sources — "evidence" here is the source-section → schema mapping below, not external research.
arsenal-1945§4A.1 — variants/upgrades catalog; the three upgrade-mechanic patterns (separate-card / munitions / configuration) + the per-faction variant lists (calibration; named types only, no stats).arsenal-1945§3 — per-faction equipment tables (theEquipmentItemcatalogue source; category/faction/tier attributes; counts/stats deferred).arsenal-1945§4B — three-zone dial + provenance discipline (reused forEquipmentItem/Variantzone).game-genre-map§3 — deck × base conventions; trait-tag Prototype framing (variants are not trait tags — kept distinct).01-core-unit-card-entity.md— topic-01 hand-off: theequipment,variants, andtransport_optionsslots this doc resolves.
11. Compile Responses
Answer the required gates above, add optional section feedback, then compile and copy the YAML into the next execution message. You may compile partial responses.