---
type: reference
title: "Pokémon TCG — Normalized Replay Data Model"
description: "Relational replay state, event lineage and external official visualizer contract."
tags: [pokemon-tcg, replay, visualizer, event-sourcing, schema]
timestamp: "2026-07-27T23:00:00-03:00"
---

# Pokémon TCG — Normalized Replay Data Model

## Canonical path

`env.render(mode='json')` is an extraction source only. The database stores no replay JSON, serialized action arrays, blobs or HTML. The parser writes relational steps, options, actions, events, snapshots and zone membership.

The current implementation in `scripts/tournament.py` persists local replay
JSON into `matches`, `match_steps`, `step_options`, `step_events`,
`board_snapshots`, and `pokemon_on_field`. This is partial progress toward the
target model. Complete zone snapshots, card movements, serial-scoped effects,
and a verified official visualizer reconstruction path remain open.

## Required relations

- `match_steps` preserves ordered decisions, turns, phases, active player, context, status and reward.
- `step_options` stores every available option and selection result as rows.
- `step_actions` stores action type and normalized parameters.
- `step_events` stores actor, source, target, quantities and effects.
- `board_snapshots`, `zone_snapshots` and `zone_cards` preserve player state, ownership, serial identity, position and visibility.
- `pokemon_on_field`, `card_state_effects` and `card_movements` preserve HP, energies, tools, statuses, evolution and zone transitions.

Each child has a parent FK and a natural sequence/serial uniqueness key. A replay can be reconstructed without the original JSON file.

## Official visualizer

The dashboard lists local arena replays and opens the official visualizer in a separate window. It does not embed or persist HTML. An adapter reconstructs the visualizer's required JSON payload from normalized rows at launch and supports selecting Player 1 or Player 2. The exact request contract remains an integration test to verify before implementation.

## Scope boundary

Remote Kaggle replay data may feed aggregate statistics and competitive context; the local dashboard is a viewer for local arena replays.

## Related

[[pokemon_tcg_physical_schema]] · [[pokemon_tcg_schema_evolution]] · [[pokemon_tcg_implementation_specification]] · [[pokemon_tcg_local_overhaul]] · [[pokemon_tcg_local_platform_status]] · [[pokemon_tcg_arena_future_architecture]] · [[pokemon_tcg_dashboard_and_tournament]]