Edition Data Author

Edition Data Author

This skill guides the creation of catalog items for Shadowrun edition data files. All items live in /data/editions/{editionCode}/ JSON files.

Key Files

• Type definitions: /lib/types/edition.ts
• SR5 core data: /data/editions/sr5/core-rulebook.json
• Rating spec types: /lib/types/ratings.ts
• Quality types: /lib/types/qualities.ts

Naming Conventions

All id, category, and subcategory values must use kebab-case (lowercase letters, numbers, and hyphens).

Validation regex: /^[a-z0-9]+(-[a-z0-9]+)*$/

Run pnpm verify-naming to validate all data files.

ID Examples

combat-sense
ares-predator-v
wired-reflexes
muscle-replacement
control-thoughts
push-the-limit

Category Examples

armor-modification    (NOT armorModification)
rfid-tags             (NOT rfidTags)
nervous-system
eyeware

Subcategory Examples

throwing-weapons      (NOT throwingWeapons)
heavy-pistols
light-pistol
assault-rifles

Special Rules

For items with ratings, include the base name only (not the rating):

wired-reflexes     (NOT wired-reflexes-1, wired-reflexes-2)

For items requiring a selection (attribute, skill, limit):

improved-physical-attribute  (with requiresAttribute: true)
improved-ability             (with requiresSkill: true)

Common Patterns

Availability Format

availability: number;           // Base availability value (0-20+)
legality?: "restricted" | "forbidden";  // R or F suffix in books

Cost Patterns

// Fixed cost
cost: 5000;

// Cost with rating (use ratingSpec)
cost: 1000;
ratingSpec: {
  rating: { hasRating: true, maxRating: 6 },
  costScaling: { perRating: true }
}

Page References

page?: number;      // Page number in source book
source?: string;    // "SR5" or book abbreviation

Catalog Item Types

1. Spells

Location: modules.magic.payload.spells.{category}[]

Categories: combat, detection, health, illusion, manipulation

interface SpellCatalogItem {
  id: string; // kebab-case
  name: string; // Display name
  category: "combat" | "detection" | "health" | "illusion" | "manipulation";
  type: "mana" | "physical";
  range: "touch" | "LOS" | "LOS(A)" | "self";
  duration: "instant" | "sustained" | "permanent";
  drain: string; // "F-2", "F", "F+1", etc.
  damage?: string; // For combat spells: "(F-3)P", "(F)S", etc.
  description: string;
  page?: number;
  source?: string;
}

Example:

{
  "id": "fireball",
  "name": "Fireball",
  "category": "combat",
  "type": "physical",
  "range": "LOS(A)",
  "duration": "instant",
  "drain": "F",
  "damage": "(F)P",
  "description": "Deals Fire damage in an area."
}

2. Qualities

Location: modules.qualities.payload.qualities[]

interface Quality {
  id: string;
  name: string;
  type: "positive" | "negative";
  category: "physical" | "mental" | "social" | "magical" | "mundane" | "metatype";
  cost: number; // Karma cost (positive for positive qualities)
  maxRating?: number; // If quality has levels (1-4 typically)
  costPerRating?: boolean;
  metatypeRestrictions?: string[]; // ["human", "elf"]
  prerequisites?: QualityPrerequisites;
  incompatible?: string[]; // IDs of incompatible qualities
  description: string;
  effects?: QualityEffect[];
  source?: SourceReference;
}

Example:

{
  "id": "toughness",
  "name": "Toughness",
  "type": "positive",
  "category": "physical",
  "cost": 9,
  "description": "+1 to Physical damage resistance tests.",
  "effects": [
    {
      "type": "dicePoolModifier",
      "target": "damageResistance",
      "modifier": 1
    }
  ]
}

3. Cyberware

Location: modules.cyberware.payload.cyberware[]

Categories: headware, eyeware, earware, bodyware, cyberlimbs, nervous-system, biomonitors

interface CyberwareCatalogItem {
  id: string;
  name: string;
  category: CyberwareCategory;
  essenceCost: number; // Base essence cost
  cost: number; // Base nuyen cost
  availability: number;
  legality?: "restricted" | "forbidden";

  // For rated items, use ratingSpec (preferred)
  ratingSpec?: CatalogItemRatingSpec;

  // Or legacy properties (deprecated but still work)
  hasRating?: boolean;
  maxRating?: number;
  essencePerRating?: boolean;
  costPerRating?: boolean;

  // Capacity (for cyberlimbs that hold enhancements)
  capacity?: number; // Capacity this provides
  capacityCost?: number; // Capacity this consumes (for enhancements)

  // Bonuses
  attributeBonuses?: Record<string, number>;
  initiativeDiceBonus?: number;

  // Descriptions
  description?: string;
  wirelessBonus?: string;

  page?: number;
  source?: string;
}

Example:

{
  "id": "wired-reflexes",
  "name": "Wired Reflexes",
  "category": "nervous-system",
  "essenceCost": 2,
  "cost": 39000,
  "availability": 8,
  "legality": "restricted",
  "ratingSpec": {
    "rating": { "hasRating": true, "minRating": 1, "maxRating": 3 },
    "essenceScaling": { "perRating": true },
    "costScaling": { "values": [39000, 149000, 217000] }
  },
  "initiativeDiceBonus": 1,
  "description": "Hardwired reflexes for faster reaction time.",
  "wirelessBonus": "+1 Initiative Die while wireless enabled."
}

4. Bioware

Location: modules.bioware.payload.bioware[]

Categories: standard, cultured, cosmetic, biosculpting

interface BiowareCatalogItem {
  id: string;
  name: string;
  category: BiowareCategory;
  essenceCost: number;
  cost: number;
  availability: number;
  legality?: "restricted" | "forbidden";

  ratingSpec?: CatalogItemRatingSpec;
  hasRating?: boolean;
  maxRating?: number;

  attributeBonuses?: Record<string, number>;
  description?: string;
  wirelessBonus?: string;

  page?: number;
  source?: string;
}

5. Weapons

Location: modules.gear.payload.weapons.{subcategory}[]

Subcategories: holdout-pistols, light-pistols, heavy-pistols, machine-pistols, smgs, assault-rifles, sniper-rifles, shotguns, lmgs, hmgs, assault-cannons, blades, clubs, exotic-weapons, throwing-weapons, bows, crossbows

interface WeaponCatalogItem {
  id: string;
  name: string;
  subcategory: string;
  damage: string; // "5P", "8P(f)", "(STR+2)P"
  accuracy: number;
  ap: number; // Armor Penetration (usually negative)
  mode?: string; // "SA", "SA/BF", "SA/BF/FA"
  rc?: number; // Recoil compensation
  ammo?: string; // "12(c)", "30(c)", "belt"
  cost: number;
  availability: number;
  legality?: "restricted" | "forbidden";
  reach?: number; // For melee weapons
  concealability?: number; // Modifier for concealment
  description?: string;
  page?: number;
  source?: string;
}

Example:

{
  "id": "ares-predator-v",
  "name": "Ares Predator V",
  "subcategory": "heavy-pistols",
  "damage": "8P",
  "accuracy": 5,
  "ap": -1,
  "mode": "SA",
  "rc": 0,
  "ammo": "15(c)",
  "cost": 725,
  "availability": 5,
  "legality": "restricted",
  "description": "The iconic sidearm of shadowrunners everywhere."
}

6. Armor

Location: modules.gear.payload.armor[]

interface ArmorCatalogItem {
  id: string;
  name: string;
  armorRating: number;
  capacity: number; // For armor modifications
  cost: number;
  availability: number;
  legality?: "restricted" | "forbidden";
  encumbrance?: number; // Modifier to physical tests
  concealability?: number;
  description?: string;
  page?: number;
  source?: string;
}

7. Weapon Modifications

Location: modules.modifications.payload.weaponMods[]

interface WeaponModificationCatalogItem {
  id: string;
  name: string;
  mount?: "top" | "under" | "side" | "barrel" | "stock" | "internal";
  occupiedMounts?: WeaponMountType[]; // Additional mounts used
  isBuiltIn?: boolean;
  compatibleWeapons?: string[];
  incompatibleWeapons?: string[];
  minimumWeaponSize?: "holdout" | "light-pistol" | "heavy-pistol" | "smg" | "rifle" | "heavy";

  cost: number;
  costMultiplier?: number;
  availability: number;
  legality?: "restricted" | "forbidden";

  ratingSpec?: CatalogItemRatingSpec;
  hasRating?: boolean;
  maxRating?: number;

  recoilCompensation?: number;
  accuracyModifier?: number;
  concealabilityModifier?: number;

  description?: string;
  wirelessBonus?: string;
  page?: number;
  source?: string;
}

8. Armor Modifications

Location: modules.modifications.payload.armorMods[]

interface ArmorModificationCatalogItem {
  id: string;
  name: string;
  capacityCost: number;
  noCapacityCost?: boolean; // If true, doesn't use capacity (bracketed in book)

  ratingSpec?: CatalogItemRatingSpec;
  hasRating?: boolean;
  maxRating?: number;
  capacityPerRating?: boolean;

  cost: number;
  costPerRating?: boolean;
  costMultiplier?: number;
  availability: number;
  availabilityModifier?: number;
  legality?: "restricted" | "forbidden";

  armorBonus?: number;
  requirements?: string[]; // ["full body armor", "helmet"]

  description?: string;
  wirelessBonus?: string;
  page?: number;
  source?: string;
}

9. Adept Powers

Location: modules.adeptPowers.payload.powers[]

interface AdeptPowerCatalogItem {
  id: string;
  name: string;
  cost: number | null; // Power point cost (null if table-based)
  costType: "fixed" | "perLevel" | "table";
  maxLevel?: number;
  activation?: "free" | "simple" | "complex" | "interrupt";

  // For powers requiring selection
  requiresAttribute?: boolean;
  validAttributes?: string[];
  requiresSkill?: boolean;
  validSkills?: string[];
  requiresLimit?: boolean;
  validLimits?: string[];

  // For table-based costs (like Improved Reflexes)
  levels?: Array<{
    level: number;
    cost: number;
    bonus: string;
  }>;

  // For powers with variants (like Improved Sense)
  variants?: Array<{
    id: string;
    name: string;
    bonus?: string;
  }>;

  description: string;
  page?: number;
  source?: string;
}

10. Foci

Location: modules.foci.payload.foci[]

interface FocusCatalogItem {
  id: string;
  name: string;
  type: "enchanting" | "metamagic" | "power" | "qi" | "spell" | "spirit" | "weapon";
  costMultiplier: number; // Cost = Force × multiplier
  bondingKarmaMultiplier: number; // Karma = Force × multiplier
  availability: number;
  legality?: "restricted" | "forbidden";
  description?: string;
  page?: number;
  source?: string;
}

11. Complex Forms

Location: modules.magic.payload.complexForms[]

interface ComplexFormCatalogItem {
  id: string;
  name: string;
  target: "persona" | "device" | "file" | "sprite" | "host" | "self";
  duration: "instant" | "sustained" | "permanent";
  fading: string; // "L+1", "L-1", "L", etc.
  description: string;
  page?: number;
  source?: string;
}

Unified Ratings Tables (PREFERRED)

For items with ratings, use unified ratings tables - explicit per-rating values that match how source books print data:

interface UnifiedRatingConfig {
  hasRating: true; // Must be true to enable ratings
  minRating?: number; // Default: 1
  maxRating: number; // Maximum rating allowed
  ratings: Record<
    number,
    {
      // Explicit values for each rating
      cost?: number; // Nuyen cost at this rating
      availability?: number; // Availability at this rating
      availabilitySuffix?: "R" | "F";
      essenceCost?: number; // Essence cost (cyberware/bioware)
      capacity?: number; // Capacity provided (cyberlimbs, cybereyes)
      capacityCost?: number; // Capacity consumed (enhancements)
      karmaCost?: number; // Karma cost (qualities)
      powerPointCost?: number; // Power point cost (adept powers)
      effects?: {
        // Mechanical effects at this rating
        attributeBonuses?: Record<string, number>;
        initiativeDice?: number;
        initiativeScore?: number;
        limitBonus?: number;
        armorBonus?: number;
      };
    }
  >;
}

Example - Cybereyes (different capacity per rating):

{
  "id": "cybereyes",
  "name": "Cybereyes",
  "category": "eyeware",
  "hasRating": true,
  "minRating": 1,
  "maxRating": 4,
  "ratings": {
    "1": { "cost": 4000, "availability": 3, "essenceCost": 0.2, "capacity": 4 },
    "2": { "cost": 6000, "availability": 6, "essenceCost": 0.3, "capacity": 8 },
    "3": { "cost": 10000, "availability": 9, "essenceCost": 0.4, "capacity": 12 },
    "4": { "cost": 14000, "availability": 12, "essenceCost": 0.5, "capacity": 16 }
  },
  "description": "Replacement eyes with customizable enhancements."
}

Example - Wired Reflexes (non-linear essence/cost):

{
  "id": "wired-reflexes",
  "name": "Wired Reflexes",
  "category": "nervous-system",
  "hasRating": true,
  "minRating": 1,
  "maxRating": 3,
  "ratings": {
    "1": {
      "cost": 39000,
      "availability": 8,
      "essenceCost": 2,
      "effects": { "initiativeDice": 1, "initiativeScore": 1 }
    },
    "2": {
      "cost": 149000,
      "availability": 12,
      "essenceCost": 3,
      "effects": { "initiativeDice": 2, "initiativeScore": 2 }
    },
    "3": {
      "cost": 217000,
      "availability": 20,
      "essenceCost": 5,
      "effects": { "initiativeDice": 3, "initiativeScore": 3 }
    }
  },
  "legality": "restricted",
  "description": "Hardwired reflexes for faster reaction time.",
  "wirelessBonus": "+1 Initiative Die while wireless enabled."
}

Example - Quality with Levels (Toughness):

{
  "id": "toughness",
  "name": "Toughness",
  "type": "positive",
  "category": "physical",
  "hasRating": true,
  "minRating": 1,
  "maxRating": 4,
  "ratings": {
    "1": { "karmaCost": 9 },
    "2": { "karmaCost": 18 },
    "3": { "karmaCost": 27 },
    "4": { "karmaCost": 36 }
  },
  "summary": "+1 to Physical damage resistance tests per level."
}

Why Unified Ratings Tables?

1. Matches source books - Books print tables, not formulas
2. Non-linear scaling - Many items don't follow simple formulas
3. Easier to audit - Direct comparison with source material
4. Single code path - No special cases for different scaling types
5. Complete data - All rating-dependent values in one place

Rating Spec (LEGACY FALLBACK)

The ratingSpec format is still supported for backward compatibility, but unified ratings tables are preferred for new data:

interface CatalogItemRatingSpec {
  rating: {
    hasRating: boolean;
    minRating?: number; // Default: 1
    maxRating: number;
  };
  essenceScaling?: {
    perRating?: boolean;
    values?: number[]; // Specific essence costs per rating
  };
  costScaling?: {
    perRating?: boolean;
    values?: number[]; // Specific costs per rating
  };
  capacityCostScaling?: {
    perRating?: boolean;
    values?: number[];
  };
  attributeBonusScaling?: Record<string, number>; // Bonus per rating
}

Legacy Example - Muscle Replacement (linear scaling):

{
  "ratingSpec": {
    "rating": { "hasRating": true, "maxRating": 4 },
    "essenceScaling": { "perRating": true },
    "costScaling": { "perRating": true },
    "attributeBonusScaling": { "strength": 1, "agility": 1 }
  }
}

Validation Checklist

When creating new items, verify:

1. ID is unique within its category
2. ID follows kebab-case convention
3. Required fields are present (id, name, category/type-specific fields)
4. Availability is reasonable (typically 0-20, rarely higher)
5. Costs are positive numbers in appropriate ranges
6. Legality is only set when restricted/forbidden (omit for legal items)
7. Rating specs are consistent:
   • For rated items, prefer unified ratings tables over ratingSpec
   • If hasRating: true, must have maxRating and ratings table
   • Each rating in table should have appropriate cost/availability/essence values
8. Page references are accurate (if provided)
9. Descriptions are concise but informative
10. Unified ratings tables match source book values exactly

Adding to JSON Files

Items are added to arrays within the module payloads:

{
  "modules": {
    "magic": {
      "mergeStrategy": "merge",
      "payload": {
        "spells": {
          "combat": [
            {
              /* spell 1 */
            },
            {
              /* spell 2 */
            }
          ]
        }
      }
    }
  }
}

For sourcebooks, use appropriate merge strategy:

• merge - Combine with existing data (default)
• append - Add to arrays without replacing
• replace - Completely override module