PFS Tools

A collection of utilities for Pathfinder Society (PFS) organized play. Each tool lives in its own Python package with dedicated documentation.

Utilities

Utility	Description
Chronicle Extractor	Extracts chronicle sheets from scenario PDFs by season.
Scenario Renamer	Copies and renames scenario PDFs and images.
Blueprint to Layout	Converts Blueprint JSON into layout JSON via pixel detection.
Layout Generator	Generates filled chronicle PDFs from layouts and player data.
Layout Visualizer	Renders canvas overlays on chronicle PDFs for debugging.
Scenario Download Workflow	Automates end-to-end processing of newly downloaded scenario PDFs.

Setup

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Suggested Workflow

When working on blueprint layouts, run these in separate terminals:

1. Blueprint → Layout (watch mode) — regenerates layout JSON whenever a blueprint file changes:

   python -m blueprint2layout \
     --blueprints-dir Blueprints \
     --blueprint-id 'pfs2.*' \
     --watch \
     --output-dir modules/pfs-chronicle-generator/assets/layouts/

2. Layout Visualizer (watch mode) — re-renders debug PNGs whenever a layout file changes. Valid modes are fields, canvases, and data.

   python -m layout_visualizer \
     --watch \
     --mode fields \
     --layout-root modules/pfs-chronicle-generator/assets/layouts \
     --layout-id 'pfs2.*' \
     --output-dir debug_clips/layout_visualizer

3. Layout Generator — run as needed to produce the leaf layout files from chronicle PDFs and the TOML metadata:

   python -m layout_generator \
     --metadata-file chronicle_properties.toml \
     modules/pfs-chronicle-generator/assets/chronicles

Testing

python -m pytest tests/ -v

Pre-Push Checklist

1. Run the linter — no errors
2. Run the full test suite — all tests pass