bs-roster-parser

Python library for parsing BattleScribe/NewRecruit roster JSON into flat unit lists with costs, model counts, and weapon breakdowns.

Install

pip install git+https://git.homelab.local/kaykayyali/bs-roster-parser.git

Or clone and install locally:

git clone https://git.homelab.local/kaykayyali/bs-roster-parser.git
cd bs-roster-parser
pip install -e .

Usage

from bs_roster_parser import parse_roster_file

# Parse a roster file
summary = parse_roster_file("roster.json")

# Access units
for unit in summary.units:
    print(f"{unit.name}: {unit.pts}pts, {unit.model_count} models")
    for model in unit.breakdown:
        print(f"  {model.name} ×{model.count}")
        if model.weapons:
            print(f"    Weapons: {', '.join(model.weapons)}")

# Aggregate stats
print(f"Total: {summary.total_pts}pts, {summary.total_cp} CP")
print(f"Units: {summary.unit_count}, Models: {summary.total_models}")

# Find a specific unit
gaunt = summary.find_unit("Gaunt's Ghosts")

# Export to dict/JSON
import json
print(json.dumps(summary.to_dict(), indent=2))

What it extracts

Each unit includes:

• name — display name (custom name if set, otherwise catalogue name)
• pts — total points cost (including descendant costs for variable-model-count units)
• cp — crusade points
• model_count — total models (summed from child model nodes)
• breakdown — per-model-variant list with names, counts, and detected weapons
• type — unit or model

The roster summary includes:

• roster_name, game_system, faction (detected from first force)
• points_limit (from costLimits)
• total_pts, total_cp, unit_count, total_models

Origin

Extracted from the Nachmund Tracker project's processJSON function, ported from JavaScript to Python and generalized as a reusable library.

License

MIT