Merge pull request #39 from meltingscales/feature-combat

Feature: add combat

Author: meltingscales

docs/AI-INSTRUCTIONS.md .ai/instructions.mddocs/AI-INSTRUCTIONS.md renamed to .ai/instructions.md

@@ -1,12 +1,27 @@
+# AI Instructions
+
 You are allowed to run `just build` and `just install`, and also `just run-*`. This game was going to use a GUI (bevy), but I decided that `ratatui` would be faster, so we're back to using a TUI.
 
+If you're running NixOS, make sure to run `nix-shell` to get the right environment.
+
+`./docs/*.md` contains lots of useful documentation.
+
 You should use `rustup` to run `cargo` and other tools.
 
 Please avoid running `cargo clean`. It takes a long time to rebuild rust modules.
 
-Keep small copyrights inside of the main game code files. Make sure they exist if they aren't declared.
+Also never run `just client` or any other TUI because you might be in a terminal that cannot display properly as you're an AI agent. Instead, ask me to run `just client` or use unit testing to test code.
+
+## Testing
+
+Run tests with `make test` to validate game systems. Write simple unit tests for:
+- Combat mechanics (damage, death, action queues)  
+- Game logic (movement, energy, cooldowns)
+- Edge cases and bug fixes
+
+Tests help ensure systems work correctly and prevent regressions during development.
 
-Guiding principles:
+## Guiding principles
 
 - All randomly-generated choices, actions, damage, loot, worldgen, etc - should be fully deterministic and based on world seed and world tick. This means that this game should be fully TAS-able for any specific initial seed (and version of game code). Always use the seed and any permutation (when appropriate) of XYZ coordinate, biome, or other seeded randomness to generate anything "random".
 
@@ -16,9 +31,9 @@ Guiding principles:
 
 - This game renders using ASCII text.
 
-- TODO.md contains a big, unedited list of my long-term goals with this game. By no means do we need to implement all of them. I will likely cut or edit parts of the TODO. I just want to focus on the section called "MVP for steam release (2026)".
+- docs/TODO.md contains a big, unedited list of my long-term goals with this game. By no means do we need to implement all of them. I will likely cut or edit parts of the TODO. I just want to focus on the section called "MVP for steam release (2026)".
 
-- We're currently in the process of migrating from Python to Rust. Please see the migration plan for more information, called "migration-plan.md" and "TODO-RUST-MIGRATION.md".
+- We're currently in the process of migrating from Python to Rust. Please see the migration plan for more information, called "docs/migration-plan.md" and "docs/TODO-RUST-MIGRATION.md".
 
 Periodic tasks:
 

.ai/prompt_3d_voxel_editors.md

@@ -0,0 +1,26 @@
+> What would be a good choice for making custom structures or maps? I know that @crates/client/assets/structures/small_temple.lrstructure/shape_layers.txt is one way to store it but...it's not really easy to visualize. Are there any low-res voxel 3D editors that I could then make a custom exporter for? I want to make the main questline's factory that's 10 miles away [- the first quest is to travel 10 miles to the robotics factory that made you to replace your damaged fusion core and fix your limbs. you remember the location. TODO add a maps and waypoint system.] and I want to design it by hand, but not in our shape_layers.txt  format because it's pretty limited.
+
+I'd like to avoid MagicaVoxel because i primarily use linux to develop.
+
+reply from ai:
+
+  Best Options for Linux:
+
+  1. Goxel - Open source, specifically designed for voxel editing, lightweight and perfect for game assets
+  2. VoxEdit (The Sandbox) - Free voxel editor with good export options
+  3. Qubicle - Professional voxel editor with Linux support (paid)
+  4. Blender with voxel addons - Free, powerful, and you could use addons like "Voxel Tools" or "Extra Objects"
+
+  Recommended Approach:
+  Goxel would be my top recommendation - it's:
+  - Native Linux support
+  - Lightweight and fast
+  - Exports to various formats (PLY, OBJ, etc.)
+  - Simple enough for game structures but powerful enough for detail
+
+  Custom Export Strategy:
+  You could create a simple converter that:
+  1. Exports from Goxel as PLY/OBJ
+  2. Reads the mesh data
+  3. Converts to your shape_layers.txt format or a new binary format
+  4. Handles multiple layers/materials if needed

.ai/prompt_class_analysis.md

@@ -0,0 +1 @@
+Run `just analyze-modules` and `just complexity` and give me a summary of what I should do to improve the codebase, and any good patterns you see as well. You can also run `just analyze-deps` to see what dependencies we're using.

.ai/prompt_refactor_meta.md

@@ -0,0 +1,3 @@
+I'd like you to give me prompt suggestions to examine how clean/messy my state is. Things like unnecessary complexity or state tangledness. I'll be feeding these prompts to Claude CLI to help me determine how to refactor my code.
+
+oh, and run `make tokei` to see a summary of code files.

.ai/prompt_split_code_files.md

@@ -0,0 +1,3 @@
+# Modularize code
+
+I'd like you to run `make tokei` and read code files, and offer suggestions on how to make my code more modular so that AI can more easily read it.

.ai/prompt_testing.md

@@ -0,0 +1,3 @@
+# testing
+
+I'd like you to run `make test` and offer advice about code coverage and my code's structure so that we can more easily test our code.

.ai/prompts_state_mgmt.md

@@ -0,0 +1,5 @@
+Examine how game state flows through the system - identify places where state is duplicated or inconsistently managed.
+
+Find components that have too many responsibilities by analyzing the components.rs and systems.rs files.
+
+Look for global state access patterns and suggest more localized state management.

.ai/todo_combat_code_issues.md

@@ -0,0 +1,113 @@
+# Combat Code Issues - Priority List
+
+Generated: 2025-01-27
+
+## 🎯 **Recently Fixed Issues**
+- ✅ Move queuing after killing all enemies (combat state validation)
+- ✅ Duplicate queue cleanup logic (centralized cleanup function)
+- ✅ Queue cleanup not removing actions targeting dead entities
+- ✅ **Race Condition in Action Queue Processing** - Refactored to two-phase processing
+- ✅ **No Validation of Action Targets During Execution** - Added target validation checks
+
+## 🔍 **Outstanding Issues by Severity**
+
+### 🚨 **HIGH SEVERITY**
+
+*All high severity issues have been resolved! 🎉*
+
+### 🟡 **MEDIUM SEVERITY**
+
+#### 3. **Inconsistent Combat State Management** ⚡ *Medium Effort* ✅ **RESOLVED**
+- **Location**: Multiple files - combat state checked in various places
+- **Issue**: Combat state is checked/set in multiple places with different conditions
+- **Impact**: Possible states where combat UI shows but combat logic isn't active
+- **Fix**: ✅ Created centralized `CombatStateManager` system in `/home/melty/Git/LithicRivers/crates/core/src/combat_state_manager.rs`
+- **Code Changes**: ✅ Centralized all combat state transitions, replaced old `combat_trigger_system` usage in system_scheduler.rs
+
+#### 4. **Performance: O(n²) Queue Cleanup** ⚡ *Medium Effort* ✅ **RESOLVED**
+- **Location**: `cleanup_actions_targeting_dead_entity()` in `/home/melty/Git/LithicRivers/crates/core/src/systems.rs:1085`
+- **Issue**: Every entity death iterates through ALL entities with queues 
+- **Impact**: Performance degrades with many entities in large battles
+- **Fix**: ✅ Implemented `TargetTracker` resource with reverse lookup `HashMap<Entity, HashSet<Entity>>`
+- **Code Changes**: ✅ Created `/home/melty/Git/LithicRivers/crates/core/src/target_tracker.rs`, optimized cleanup function reduces from O(n²) to O(1) + O(k) where k = entities targeting dead one
+
+#### 5. **Memory Leak: Dead Entities with Components** ⚡ *Low Effort*
+- **Location**: Entity cleanup throughout codebase
+- **Issue**: Dead entities keep their ActionQueue and other components until manually cleaned
+- **Impact**: Memory usage grows during long combat sessions  
+- **Fix**: Add periodic cleanup system or immediate component removal on death
+- **Code Changes**: Extend cleanup functions to remove all unnecessary components
+
+#### 6. **No Action Priority System** ⚡ *High Effort*
+- **Location**: `ActionQueue` system in `/home/melty/Git/LithicRivers/crates/core/src/moves.rs:278`
+- **Issue**: All actions execute in timing order only, no tactical priority
+- **Impact**: Unrealistic combat where healing can't interrupt attacks
+- **Fix**: Add priority levels to actions and priority-based queue sorting
+- **Code Changes**: Major refactor of action queue to support priority levels
+
+### 🟢 **LOW SEVERITY**
+
+#### 7. **UI Shows Entity IDs Instead of Names** ⚡ *Low Effort*
+- **Location**: Combat UI in `/home/melty/Git/LithicRivers/crates/client/src/ui/panels/combat.rs:222`
+- **Issue**: Target display shows "Enemy 42" instead of "Goblin" or similar
+- **Impact**: Poor user experience, harder to track specific enemies
+- **Fix**: Add name component lookup in UI target display logic
+- **Code Changes**: Add Name component and lookup in UI rendering
+
+#### 8. **No Action Animation/Feedback Delay** ⚡ *Medium Effort*  
+- **Location**: Action execution system
+- **Issue**: Actions complete instantly with no visual feedback period
+- **Impact**: Combat feels disconnected, hard to follow action flow
+- **Fix**: Add animation/feedback phase to action execution
+- **Code Changes**: Add animation states and timing to action system
+
+#### 9. **Hard-coded Move Validation** ⚡ *Medium Effort*
+- **Location**: Input handler `/home/melty/Git/LithicRivers/crates/client/src/app/input_handler.rs:677`
+- **Issue**: Move #3 is hard-coded as "Escape" in input handler
+- **Impact**: Fragile code, breaks if move list changes
+- **Fix**: Add move metadata for target requirements
+- **Code Changes**: Add `requires_target` field to Move struct
+
+#### 10. **Limited Error Recovery** ⚡ *Low Effort*
+- **Location**: Various action execution paths
+- **Issue**: Failed actions don't provide recovery mechanisms
+- **Impact**: Players can get stuck in invalid states
+- **Fix**: Add action validation and error state recovery
+- **Code Changes**: Add validation checks and fallback behaviors
+
+## 📊 **Summary Statistics**
+
+### By Severity:
+- **High**: 0 issues ✅ (All resolved!)
+- **Medium**: 2 issues (performance/UX problems) - 2 resolved ✅  
+- **Low**: 4 issues (polish/maintainability)
+
+### By Effort:
+- **Low Effort**: 4 issues (quick fixes)
+- **Medium Effort**: 5 issues (moderate refactoring)
+- **High Effort**: 1 issue (major feature addition)
+
+## 🎯 **Recommended Fix Order**
+
+### Phase 1 - Critical Fixes (High Impact, Lower Effort)
+1. **Action target validation** (High Severity, Low Effort) - Prevents crashes
+2. **Memory leak cleanup** (Medium Severity, Low Effort) - Performance improvement
+3. **UI entity names** (Low Severity, Low Effort) - Quick UX win
+
+### Phase 2 - Performance & Stability (Medium Effort)
+4. **Race condition fix** (High Severity, Medium Effort) - System stability
+5. **Queue cleanup performance** (Medium Severity, Medium Effort) - Scalability
+6. **Combat state centralization** (Medium Severity, Medium Effort) - Maintainability
+
+### Phase 3 - Polish & Features (Higher Effort)
+7. **Hard-coded move validation** (Low Severity, Medium Effort) - Code quality
+8. **Animation system** (Low Severity, Medium Effort) - UX improvement
+9. **Error recovery** (Low Severity, Low Effort) - Robustness
+10. **Priority system** (Medium Severity, High Effort) - Major feature
+
+## 🔧 **Technical Notes**
+
+- All high severity issues should be addressed before major feature additions
+- The race condition fix (#1) is the most critical as it affects system stability
+- Performance issues (#4) will become more apparent with larger battles
+- Priority system (#6) would be a good candidate for a major refactor milestone

.ai/todo_world_sim_tests.md

@@ -0,0 +1,4 @@
+I'd like you to add a unit test that simulates a game world running to catch this in the future - combat working, debugInstantKill actually killing, combat joining working, etc.
+
+also, how hard would it be to make unit tests that simulate the world BTW? Just tell me.
+we can do things like, walking 10,000 steps, death due to waiting in combat, stress testing things, etc.

.claude/settings.local.json

@@ -0,0 +1,34 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(make:*)",
+      "Bash(grep:*)",
+      "Bash(mkdir:*)",
+      "Bash(sed:*)",
+      "Bash(cargo check:*)",
+      "Bash(find:*)",
+      "Bash(rustup run nightly cargo clippy:*)",
+      "Bash(just clippy:*)",
+      "Bash(rustup run stable cargo check)",
+      "Bash(just build)",
+      "Bash(rustc:*)",
+      "Bash(rustup run nightly cargo build:*)",
+      "Bash(/dev/null)",
+      "Bash(cargo:*)",
+      "Bash(timeout 2s cargo run --bin lithicrivers-client)",
+      "Bash(timeout 3s cargo run --bin lithicrivers-client)",
+      "Bash(timeout 10s make build)",
+      "Bash(timeout 3s make build)",
+      "Bash(just test:*)",
+      "Bash(RUSTFLAGS='-Z unstable-options' RUSTDOCFLAGS='-Z unstable-options' RUSTC_BOOTSTRAP=1 rustup run nightly cargo test -p lithicrivers-core --lib systems::tests::test_combat_system_enemy_death)",
+      "Bash(timeout 10s cargo run --bin lithicrivers-client)",
+      "Bash(timeout:*)",
+      "Bash(cat:*)",
+      "Bash(rustup:*)",
+      "Bash(RUSTFLAGS=* rustup:*)",
+      "Bash(RUST_BACKTRACE=* RUSTFLAGS=* rustup:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}