Implement Skill Tree Overlay display with ASCII tree visualization and progress indicators #235

New issue

Open

opened 2026-03-16 01:40:19 +00:00 by freemo · 0 comments

freemo commented

2026-03-16 01:40:19 +00:00

Owner

Metadata

Key	Value
Parent Epic	#226 — Skill UI & Commands
Legendary	#198 — Character Progression & Skills
Branch	`feature/m4-skill-tree-overlay-display`
Commit Message	`feat(skills): implement Skill Tree Overlay display with ASCII visualization`
Points	8
Priority	Medium
MoSCoW	Must Have

Background and Context

Players need a visual way to explore the skill tree, see their current progress, and identify which skills they can unlock next. The Skill Tree Overlay renders an ASCII representation of the skill tree inside an OverlayWindow (the existing overlay system used by the MUD's windowed terminal interface).

The overlay must handle the full tree structure with up to 32 nodes across 5 disciplines, using box-drawing characters for connections, color coding for state, and progress bars for XP accumulation. Players open the overlay with a skills command and can navigate between disciplines.

Expected Behavior

SkillTreeRenderer class at lib/aethyr/core/skills/skill_tree_renderer.rb:
- render(skill_tree, player, discipline: nil) — returns an array of strings representing the ASCII tree.
- If discipline is specified, only render that discipline's sub-tree.
- If discipline is nil, render an overview showing all 5 discipline roots with their levels.
Node Display Format:
- Unlocked (has level > 0): [X] Swordplay Lv.3 [████░░░░░░] 4500/40000
- Locked but available: [ ] Finesse (requires Swordplay 3) ★
- Locked and unavailable: [—] Martial Arts (requires Kick 5, Grapple 5)
- The ★ indicator marks nodes the player can currently unlock.

Connection Lines using box-drawing characters:

[X] Combat Lv.2
 ├── [X] Swordplay Lv.3
 │    ├── [ ] Finesse (requires Swordplay 3) ★
 │    └── [ ] Power (requires Swordplay 3) ★
 ├── [ ] Shield (requires Combat 1)
 │    └── [—] Guard (requires Shield 3)
 └── [X] Unarmed Lv.1
      ├── [—] Kick (requires Unarmed 3)
      └── [—] Grapple (requires Unarmed 3)
           └── [—] Martial Arts (requires Kick 5, Grapple 5)

OverlayWindow Integration:
- The skills command opens an OverlayWindow with the rendered tree.
- skills combat opens directly to the Combat discipline sub-tree.
- skills survival opens to the Survival discipline sub-tree.
- The overlay is scrollable for large trees.
Color Coding (using ANSI escape codes):
- Green: Unlocked nodes with XP progress.
- Yellow: Available but not yet unlocked (★ nodes).
- Gray/dim: Locked and unavailable nodes.
- Cyan: Currently selected/highlighted node (for future navigation).

Acceptance Criteria

SkillTreeRenderer class exists at lib/aethyr/core/skills/skill_tree_renderer.rb.
render produces correct ASCII output for all node states (unlocked, available, locked).
Box-drawing characters correctly connect parent nodes to children.
Progress bars show XP toward next level with visual fill.
skills command opens an OverlayWindow with the tree overview.
skills <discipline> opens directly to the specified discipline sub-tree.
Color coding distinguishes unlocked, available, and locked nodes.
Overlay is scrollable when tree exceeds window height.
★ indicator marks nodes the player can currently unlock.

Subtasks

Create lib/aethyr/core/skills/skill_tree_renderer.rb with the SkillTreeRenderer class.
Implement overview mode showing all 5 discipline roots with levels.
Implement discipline sub-tree mode with full node hierarchy.
Implement node display format with state indicators ([X], [ ], [—]).
Implement XP progress bars with visual fill characters.
Implement box-drawing character connections (├──, └──, │).
Implement ANSI color coding for node states.
Implement ★ indicator for currently-unlockable nodes.
Create skills command handler that opens the OverlayWindow.
Support skills <discipline> for direct discipline navigation.
Ensure overlay scrollability for large trees.
Handle edge cases: empty skill data, brand new character, fully maxed tree.
Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable.
Tests (Cucumber): Add tests/unit/skill_tree_renderer.feature covering overview rendering, discipline sub-tree rendering, node state display (unlocked/available/locked), progress bar formatting, box-drawing connections, color coding, unlockable indicator, command handling, scrollability.
Tests (Cucumber Integration): Add integration feature in tests/integration/ for Skill tree overlay display and skills command interaction.
Tests (Profiling): Run bundle exec rake unit_profile and verify no performance regressions.
Quality: Verify coverage >=97% via bundle exec rake unit. If coverage is <97% then review the current unit test coverage report at build/tests/unit/coverage/ and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun bundle exec rake unit to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
Quality: Run bundle exec rake (default task: unit tests with coverage) and bundle exec rake integration, fix any errors if needed ensuring both pass across entire code base, do not ignore any failure even if it seems unrelated to this commit, fix it.

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata | Key | Value | |-----|-------| | **Parent Epic** | #226 — Skill UI & Commands | | **Legendary** | #198 — Character Progression & Skills | | **Branch** | `feature/m4-skill-tree-overlay-display` | | **Commit Message** | `feat(skills): implement Skill Tree Overlay display with ASCII visualization` | | **Points** | 8 | | **Priority** | Medium | | **MoSCoW** | Must Have | ## Background and Context Players need a visual way to explore the skill tree, see their current progress, and identify which skills they can unlock next. The Skill Tree Overlay renders an ASCII representation of the skill tree inside an `OverlayWindow` (the existing overlay system used by the MUD's windowed terminal interface). The overlay must handle the full tree structure with up to 32 nodes across 5 disciplines, using box-drawing characters for connections, color coding for state, and progress bars for XP accumulation. Players open the overlay with a `skills` command and can navigate between disciplines. ## Expected Behavior 1. **SkillTreeRenderer** class at `lib/aethyr/core/skills/skill_tree_renderer.rb`: - `render(skill_tree, player, discipline: nil)` — returns an array of strings representing the ASCII tree. - If `discipline` is specified, only render that discipline's sub-tree. - If `discipline` is nil, render an overview showing all 5 discipline roots with their levels. 2. **Node Display Format:** - Unlocked (has level > 0): `[X] Swordplay Lv.3 [████░░░░░░] 4500/40000` - Locked but available: `[ ] Finesse (requires Swordplay 3) ★` - Locked and unavailable: `[—] Martial Arts (requires Kick 5, Grapple 5)` - The `★` indicator marks nodes the player can currently unlock. 3. **Connection Lines** using box-drawing characters: ``` [X] Combat Lv.2 ├── [X] Swordplay Lv.3 │ ├── [ ] Finesse (requires Swordplay 3) ★ │ └── [ ] Power (requires Swordplay 3) ★ ├── [ ] Shield (requires Combat 1) │ └── [—] Guard (requires Shield 3) └── [X] Unarmed Lv.1 ├── [—] Kick (requires Unarmed 3) └── [—] Grapple (requires Unarmed 3) └── [—] Martial Arts (requires Kick 5, Grapple 5) ``` 4. **OverlayWindow Integration:** - The `skills` command opens an `OverlayWindow` with the rendered tree. - `skills combat` opens directly to the Combat discipline sub-tree. - `skills survival` opens to the Survival discipline sub-tree. - The overlay is scrollable for large trees. 5. **Color Coding** (using ANSI escape codes): - Green: Unlocked nodes with XP progress. - Yellow: Available but not yet unlocked (★ nodes). - Gray/dim: Locked and unavailable nodes. - Cyan: Currently selected/highlighted node (for future navigation). ## Acceptance Criteria - [ ] `SkillTreeRenderer` class exists at `lib/aethyr/core/skills/skill_tree_renderer.rb`. - [ ] `render` produces correct ASCII output for all node states (unlocked, available, locked). - [ ] Box-drawing characters correctly connect parent nodes to children. - [ ] Progress bars show XP toward next level with visual fill. - [ ] `skills` command opens an `OverlayWindow` with the tree overview. - [ ] `skills <discipline>` opens directly to the specified discipline sub-tree. - [ ] Color coding distinguishes unlocked, available, and locked nodes. - [ ] Overlay is scrollable when tree exceeds window height. - [ ] ★ indicator marks nodes the player can currently unlock. ## Subtasks - [ ] Create `lib/aethyr/core/skills/skill_tree_renderer.rb` with the `SkillTreeRenderer` class. - [ ] Implement overview mode showing all 5 discipline roots with levels. - [ ] Implement discipline sub-tree mode with full node hierarchy. - [ ] Implement node display format with state indicators (`[X]`, `[ ]`, `[—]`). - [ ] Implement XP progress bars with visual fill characters. - [ ] Implement box-drawing character connections (`├──`, `└──`, `│`). - [ ] Implement ANSI color coding for node states. - [ ] Implement `★` indicator for currently-unlockable nodes. - [ ] Create `skills` command handler that opens the `OverlayWindow`. - [ ] Support `skills <discipline>` for direct discipline navigation. - [ ] Ensure overlay scrollability for large trees. - [ ] Handle edge cases: empty skill data, brand new character, fully maxed tree. - [ ] Docs: Update YARD comments on affected classes and methods. Update relevant Docusaurus documentation pages if applicable. - [ ] Tests (Cucumber): Add `tests/unit/skill_tree_renderer.feature` covering overview rendering, discipline sub-tree rendering, node state display (unlocked/available/locked), progress bar formatting, box-drawing connections, color coding, unlockable indicator, command handling, scrollability. - [ ] Tests (Cucumber Integration): Add integration feature in `tests/integration/` for Skill tree overlay display and skills command interaction. - [ ] Tests (Profiling): Run `bundle exec rake unit_profile` and verify no performance regressions. - [ ] Quality: Verify coverage >=97% via `bundle exec rake unit`. If coverage is <97% then review the current unit test coverage report at `build/tests/unit/coverage/` and use it to write new Cucumber based unit tests to improve code coverage. Specifically, write Cucumber/Gherkin style unit tests that are descriptively named and specifically improve coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `bundle exec rake unit` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. - [ ] Quality: Run `bundle exec rake` (default task: unit tests with coverage) and `bundle exec rake integration`, fix any errors if needed ensuring both pass across **entire** code base, do not ignore any failure even if it seems unrelated to this commit, fix it. ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.