|
| 1 | +# Homegrown Game Data Visualization Plan |
| 2 | + |
| 3 | +## 1. Objective |
| 4 | +Replace the current Mermaid-based visualization with a homegrown, zero-dependency node-based and hierarchical representation of the game's data structure. This will improve flexibility, control, and alignment with the project's "Lattice" and "Graph" metaphors. |
| 5 | + |
| 6 | +## 2. Removal of Mermaid |
| 7 | +The following Mermaid-specific artifacts will be removed: |
| 8 | +- `scripts/export_graph_mermaid.py` |
| 9 | +- `scripts/visualize_graph.py` (to be replaced) |
| 10 | +- `scripts/check_mermaid_integrity.py` |
| 11 | +- `scripts/generate_html_only.py` |
| 12 | +- `temp_graph.mmd` |
| 13 | +- References in `docs/content_web.md` |
| 14 | +- Any Mermaid CDN links or selectors in `scripts/test_render.js` |
| 15 | + |
| 16 | +## 3. Data Source |
| 17 | +The definitive source of truth remains `Mythril.Blazor/wwwroot/data/content_graph.json`. This file is generated by `scripts/migrate_to_graph.py` from the individual JSON data files. |
| 18 | + |
| 19 | +## 4. Visualization Architecture |
| 20 | + |
| 21 | +### A. The Visualizer Engine (`scripts/visualize_v2.py`) |
| 22 | +A new Python script will: |
| 23 | +1. Load `content_graph.json`. |
| 24 | +2. Generate a single-file interactive HTML dashboard (`output/visual_dashboard.html`). |
| 25 | +3. Embed all necessary CSS and JavaScript (Vanilla) directly into the HTML to ensure portability. |
| 26 | + |
| 27 | +### B. View Modes |
| 28 | +The dashboard will provide two distinct view modes: |
| 29 | + |
| 30 | +#### 1. Node-Link Lattice View |
| 31 | +- **Technology**: SVG-based rendering. |
| 32 | +- **Layout**: A lightweight, custom Force-Directed Layout algorithm implemented in JavaScript. |
| 33 | +- **Interactions**: |
| 34 | + - **Draggable Nodes**: Move nodes to refine the layout. |
| 35 | + - **Zoom/Pan**: Standard SVG viewport manipulation. |
| 36 | + - **Hover Details**: Show metadata (description, requirements, rewards) in a sidebar or tooltip. |
| 37 | + - **Highlighting**: Hovering over a node highlights its immediate neighbors (dependencies and dependents). |
| 38 | +- **Styling**: Distinct colors and icons for different node types (Quest, Item, Ability, Cadence, Stat, Refinement). |
| 39 | + |
| 40 | +#### 2. Hierarchical Progression View |
| 41 | +- **Technology**: HTML/CSS Grid-based "Indented Tree" or "Tiered Columns". |
| 42 | +- **Layout**: |
| 43 | + - Nodes are grouped by their "Depth" or "Tier" in the progression lattice. |
| 44 | + - Tier 0: Starting Quests/Items. |
| 45 | + - Tier N: Content unlocked by Tier N-1. |
| 46 | +- **Structure**: |
| 47 | + - Columns represent progression stages. |
| 48 | + - Rows represent categories (e.g., Combat, Crafting, Exploration). |
| 49 | +- **Functionality**: Clearly shows "what leads to what" without the visual clutter of a full graph. |
| 50 | + |
| 51 | +## 5. Implementation Details |
| 52 | + |
| 53 | +### Custom Layout Algorithm (Lattice-Link) |
| 54 | +A simple spring-embedder algorithm will be used: |
| 55 | +1. **Repulsion**: Nodes push away from each other. |
| 56 | +2. **Attraction**: Connected nodes pull toward each other (spring force). |
| 57 | +3. **Gravity**: All nodes are slightly pulled toward the center. |
| 58 | +4. **Iteration**: Run for ~300 frames on load to settle the graph, then allow manual adjustments. |
| 59 | + |
| 60 | +### Hierarchical Sorting Logic |
| 61 | +1. Perform a Breadth-First Search (BFS) starting from "Root" nodes (e.g., `quest_prologue`). |
| 62 | +2. Assign a `depth` property to each node. |
| 63 | +3. Group nodes by `depth` and `type` for the Tiered View. |
| 64 | + |
| 65 | +## 6. Styling & Aesthetics |
| 66 | +- **Theme**: Dark mode by default, matching the project's UI. |
| 67 | +- **Node Aesthetics**: |
| 68 | + - Quests: Hexagons |
| 69 | + - Items: Circles |
| 70 | + - Abilities: Rhombus |
| 71 | + - Cadences: Squares |
| 72 | +- **Edge Aesthetics**: |
| 73 | + - Directional arrows. |
| 74 | + - Color-coded edges: "Requires" (Red), "Unlocks" (Green), "Consumes" (Orange). |
| 75 | + |
| 76 | +## 7. Timeline & Tasks |
| 77 | +1. **Scrub**: Remove all Mermaid code (scripts and docs). |
| 78 | +2. **Scaffold**: Create `scripts/visualize_v2.py` and the HTML template. |
| 79 | +3. **Engine**: Implement the JS force-directed layout and SVG renderer. |
| 80 | +4. **Hierarchy**: Implement the CSS-grid hierarchy generator. |
| 81 | +5. **Finalize**: Update `scripts/check_health.py` to use the new visualizer if applicable. |
| 82 | + |
| 83 | +## 8. Verification |
| 84 | +- Validate that the generated HTML loads without console errors. |
| 85 | +- Confirm that all 130+ nodes from `content_graph.json` are present and correctly linked. |
| 86 | +- Ensure the visualization correctly reflects circular dependencies (if any) in the node-link view. |
0 commit comments