Run a race

1. Choose the season year in the header.
2. Championship → Enter race result.
3. Play the round in PCSX2 (menus and spectator setup are manual).
4. Drag drivers into finish order → Lock in race.
5. Check Standings or continue on Championship.

Optional: on the race page, open Verify grid in PCSX2 to compare your start order with the reference grid.

Pages

Home

Season list and how many races you have finished.

Championship

Active round, grid mode, live top-eight standings, PCSX2 connection panel, and Season controls.

Calendar

Every Grand Prix, date, and whether a result is saved.

Standings

Driver and constructor points — switch tabs at the top.

Rules & points

Official vs reversed grid

Set on Championship before you lock in. Official matches real qualifying order; Reversed matches a reversed start. Pit-lane and non-starters are flagged on the race page.

Points

2001–2002: top six — 10-6-4-3-2-1. 2003–2006: top eight — 10-8-6-5-4-3-2-1.

When standings update

Only after Lock in race. Drag order, staged imports, or historical reference grids do not change points until then.

Driver labels

Full name plus three-letter code (e.g. MSC). Internal slugs appear in tooltips and automation JSON only.

Fix mistakes

Wrong result for one round

Championship or the race page → Season controls → Reset race.

Start the year over

Start new championship — clears all saved results for that year (confirmation required). A DB backup is created first.

Restore a backup

Stop the dashboard, copy data/approved/backups/championship-*.db over data/approved/championship.db, restart.

Install & run

Workspace (recommended)

npm run f1cm:install once · npm run f1cm:launch for dashboard + supervisor when capture is enabled · npm run f1cm:autostart:install for login start · npm run f1cm:autostart:status to check.

Project venv

Python 3.12+, pip install -e ".[dev]", then uvicorn f1cm.app.main:app --host --port 8787.

Restart after code changes

npm run f1cm -- dashboard restart — reloads Python and templates.

Default autostart year

2001 unless you reinstall autostart with F1CM_CHAMPIONSHIP_YEAR=2002 (etc.).

First-time calendar data

f1cm init-db · python scripts/build_historical_from_ergast.py (network) · f1cm import-historical

Database & states

Production DB

data/approved/championship.db — your locked-in championship. Backups: data/approved/backups/ before approved writes.

Data states

unverified — imported history (not official grid until approved) · staged — proposed results · approved — committed and counted in standings · test — pytest only.

Test isolation

pytest sets F1CM_ENV=test and F1CM_DB_PATH to a temp file so tests cannot open production.

Ops page (advanced)

/reliability — DB path, backup list, emulator status (not in main nav).

PAL roster (advanced)

/pal-roster/{year} — verify in-game driver codes against imported IDs for automation.

PCSX2 & PINE

What the UI does today

Read-only PINE identity on Championship — confirms PCSX2 is running and which ISO/disc looks loaded. It does not drive menus or read the classification screen yet.

CLI checks

f1cm pcsx2 diagnose --year 2001 · f1cm pcsx2 game-info --year 2001 · f1cm championship status --year 2001

Automation (optional)

With emulator capture enabled, f1cm championship supervise can run in the background. Default workflow is manual Lock in race — no polling CLI required.

Portfolio deploy

Regenerate the portfolio snapshot with npm run f1cm:portfolio:live-pack, then npm run ship -- portfolio. Run the live dashboard with npm run f1cm:launch.

2004–2006

Calendars and serial hints are in-repo; verify menus, rosters, and grids on your PCSX2 setup before trusting automation.

Live integration tests

F1CM_PCSX2_LIVE=1 pytest tests/test_pcsx2_live_integration.py (real emulator required).

CLI & JSON

Everyday path

Browser Lock in race — no separate preview step in the web UI.

Race results JSON

{"results": [{"driver_id": "michael_schumacher", "position": 1, "status": "classified"}]} — driver_id slugs match the historical import (shown on the race page).

Stage / approve

JSON paste and API staging still supported for automation; approved rows land in the same SQLite DB as the dashboard.

CLI entry

npm run f1cm -- … or bash scripts/local/f1cm.sh from the MSR workspace root.

Dev & troubleshooting

Wrong Python (e.g. 3.9)

eval "$(bash scripts/local/agent-shell-path.sh)" from workspace root, or use mise/nvm per .nvmrc.

Empty home season list

Run historical build + f1cm import-historical.

Ergast build 429

Re-run python scripts/build_historical_from_ergast.py (retries with backoff).

Race form submit fails

Install deps: pip install -e ".[dev]" (needs python-multipart).

Tests

pytest in projects/game/formula-one. Optional: F1CM_PLAYWRIGHT=1 pytest tests/test_browser.py after playwright install chromium.