Games Leaderboard

Key Concepts

• Status values: "Completed" | "Playing" | "Dropped" | "Backlog" — "In Progress" no longer exists
• played_day field: optional integer on GameData; used by formatDate() and computeGapDays() for precision
• formatDate(month, year, day?): helper that renders "Jan 5, 2024" (with day) or "Jan 2024" (without); used everywhere dates appear
• Score display: .toFixed(2) on both raw score and percentage (was integer)
• humanDays(days): formats gap as Nd / Nw / Nmo / Ny; toggled by "show days" button to show raw d count
• Score computation (computeGame): sum subcriteria scores (or use score field if no subcriteria), divide by totalMax, multiply by 100 → weighted_percentage
• puzzles is special: uses a flat score field (not subcriteria), supports enabled: false to exclude from total
• Grade brackets: defined in schema.json → grade_brackets (sorted descending), S+ (≥97%) to F (≥0%)
• Visual tiers — card border: driven by letter grade; rainbow border when weighted_percentage > 98.5
• Visual tiers — category block: gold-shiny >95%, gold >90%, silver-shiny >85%, silver >80%, silver-dull >75%, bronze >65%
• Card dim class: game-card-outer--playing dims playing-status cards
• price_paid / hours_played: optional fields on GameData; computeGame derives price_per_hour (stored in _computed) when both are present and hours_played > 0
• Financial helpers: formatPrice(n) → "$N.NN"; formatHours(n) → "N.NNh"

Visualizations (GameVisualizations)

• Stat callout row: avg gap, shortest gap (named), longest gap (named); humanDays() by default, toggle to raw days
• Chart 1 — Grade Distribution: bar chart; custom tooltip shows grade extremes (best/worst game per grade); "show empty" toggle includes zero-count grades
• Chart 2 — Category Averages: radar chart; custom tooltip shows best/worst game per category
• Chart 3 — Score Over Time: scatter; toggle between release date timeline (default) and played-date timeline; "today" reference line shown; filters out "Playing" games for release timeline
• Chart 4 — Category Heatmap: pure CSS grid; heatColor() maps pct → background
• Chart 5 — Days After Release: horizontal bar chart; sorted ascending by gap
• Chart 6 — Score vs. Gap: scatter of score % vs days after release
• Chart 7 — Release Year Distribution: bar chart of games-played by release year
• TOOLTIP_STYLE constant defines shared dark-theme tooltip styling

Financials Section (GameFinancials)

• Rendered below GameVisualizations when any game has price_paid or hours_played
• Stat callout row: Total Spent, Total Hours Logged, Avg Cost per Hour, Best Value (lowest $/hr), Most Expensive/hr
• Chart A — Value Map: scatter of $/hr vs Score %; uses buildPphScoreData(); requires ≥2 data points
• Chart B — Hours Played: horizontal bar chart sorted descending by hours; uses buildHoursData(); bars colored by grade
• Chart C — Spending by Platform: horizontal bar chart by platform total; uses buildSpendByPlatformData()
• Chart D — Price Paid vs Score %: scatter of price paid vs score %; uses buildCostScoreData(); requires ≥2 data points
• Chart E — Hours by Grade: vertical bar chart; uses buildHoursPerGradeData(); bars colored by grade
• CSS classes: .game-financials-inline (collapsed card row), .game-financials-row (expanded card row), .game-fin-block, .game-fin-stat, .game-fin-stat--pph (blue tint), .game-fin-sep

Sort Options

• Sort dropdown includes a "Financials" group with: hours_played, price_paid, price_per_hour
• Games missing a field sort last (value treated as -1)

Backlog Section

• Loaded from public/games/backlog.json (flat array, not a directory)
• BacklogEntry type: { title: string; icon: string | null; release_month?: string | null; release_year: number | null }
• BacklogCard shows rank (array index + 1), icon/placeholder, title, and release year (or "TBD")
• BacklogStats shows total count, oldest/newest by release year, unknown-year count, per-year breakdown pills
• Display order = array order in backlog.json (no priority field)

Critical Rules

• Never edit index.json manually — regenerated on next start/build.
• Backlog entries go in public/games/backlog.json as array elements, NOT in public/games/ as individual files.
• Status field must be exactly "Completed", "Playing", "Dropped", or "Backlog".
• Adding subcriteria to schema: every existing game JSON must also get that subcriteria key or scoring silently breaks.
• Modifying computeGame affects all grades retroactively — verify against existing games before changing.
• buildRadarData skips puzzles (cat.key !== "puzzles") — update this filter if adding other opt-out categories.

References

• Patterns: .claude/guidelines/games-leaderboard/patterns.md

Last Updated: 2026-04-11