- Added a new system to prevent NPCs from clipping through walls and tables during collisions.
- Introduced functions for position validation and safe movement: `isPositionSafe()`, `boundsOverlap()`, and `findSafeCollisionPosition()`.
- Updated `handleNPCCollision()` and `handleNPCPlayerCollision()` to utilize the new safe position logic, allowing NPCs to find alternative paths when blocked.
- Created comprehensive documentation detailing the implementation, testing procedures, and performance analysis.
- Ensured minimal performance impact with efficient collision checks and pathfinding.
- Added automatic collision avoidance for NPCs when colliding with each other and the player.
- Updated `setupNPCToNPCCollisions()` to include collision callbacks for NPC-to-NPC interactions.
- Created `handleNPCCollision()` to manage NPC-to-NPC collision responses, moving NPCs 5px northeast and recalculating paths.
- Implemented `handleNPCPlayerCollision()` for NPC-to-Player collisions, ensuring consistent behavior with NPC-to-NPC avoidance.
- Modified `updatePatrol()` to check for path recalculation after collisions.
- Enhanced console logging for collision events and path recalculations.
- Created comprehensive documentation covering implementation details, quick reference, and testing procedures.
- Ensured minimal performance impact with efficient pathfinding and collision detection.
- Created comprehensive documentation for two new NPC patrol features: Waypoint Patrol and Cross-Room Navigation.
- Added `QUICK_START_NPC_FEATURES.md` detailing configuration, implementation phases, and testing guidelines.
- Introduced `README_NPC_FEATURES.md` as an index for navigating the documentation package.
- Implemented `update_tileset.py` script to update Tiled map with all objects from the assets directory, ensuring proper GIDs.
- Updated test scenarios for NPC patrol behaviors, including waypoint patrol tests in `test-npc-waypoints.json`.
- Adjusted positions in existing test scenarios for better alignment with new patrol features.
✅ Phase 4: Personal Space Behavior COMPLETE
Test scenario with 10 NPCs, comprehensive documentation (1000+ lines),
and Ink toggle testing for personal space behavior.
Includes:
- 10 test NPCs with varied configurations
- Distance tests (32px to 128px bubbles)
- Backing speed tests (3px to 10px increments)
- Wall collision detection tests
- Personal space + patrol integration
- Ink toggle for runtime distance control
- Complete test guide with debugging tools
Key features tested:
- Gradual backing away (5px increments)
- Face player while backing
- Wall collision detection
- Priority system integration
- Idle animations (not walk)
- Distance-based activation
✅ Phase 2: Face Player Behavior COMPLETE
This phase focuses on testing and verifying the face player behavior
implemented in Phase 1. Includes comprehensive test scenarios,
documentation, and unit tests for direction calculation.
## New Files Created
### Test Scenario
**scenarios/test-npc-face-player.json**
- 12 NPCs arranged to test all 8 directions
- Cardinal tests: North, South, East, West
- Diagonal tests: NE, NW, SE, SW
- Edge case tests: Range limits, disabled behavior
- Visual layout for easy testing
### Test Documentation
**planning_notes/npc/npc_behaviour/PHASE2_TEST_GUIDE.md**
- Complete test procedure for all 8 directions
- Expected behaviors for each test case
- Debugging tools and console commands
- Common issues and solutions
- Success criteria checklist
- Performance metrics
### Unit Tests
**planning_notes/npc/npc_behaviour/phase2_direction_tests.js**
- 24 unit tests for direction calculation
- Pure cardinal direction tests (4)
- Threshold boundary tests (8)
- Pure diagonal tests (4)
- Edge case tests (5)
- Integration tests with actual behavior
- Auto-run in browser console
## Test Coverage
### Direction Calculation Tests
✅ **Cardinal Directions** (4 tests)
- Pure right (player directly east)
- Pure left (player directly west)
- Pure down (player directly south)
- Pure up (player directly north)
✅ **Diagonal Directions** (4 tests)
- Down-right (45° angle)
- Down-left (45° angle)
- Up-right (45° angle)
- Up-left (45° angle)
✅ **Threshold Tests** (8 tests)
- Mostly right (30° angle → cardinal)
- Mostly left (30° angle → cardinal)
- Mostly down (30° angle → cardinal)
- Mostly up (30° angle → cardinal)
- Barely diagonal right-down (60° → diagonal)
- Barely cardinal right (30° → cardinal)
- Barely diagonal down-right (30° → diagonal)
- Barely cardinal down (60° → cardinal)
✅ **Edge Cases** (5 tests)
- Zero distance (player on top of NPC)
- Small movements (1px)
- Large movements (1000px)
- Negative movements
- Boundary conditions
### Scenario Tests
✅ **12 NPCs in Test Scenario**:
1. `npc_center` - Default behavior, all 8 directions
2. `npc_north` - Cardinal north position
3. `npc_south` - Cardinal south position
4. `npc_east` - Cardinal east position
5. `npc_west` - Cardinal west position
6. `npc_northeast` - Diagonal NE position
7. `npc_northwest` - Diagonal NW position
8. `npc_southeast` - Diagonal SE position
9. `npc_southwest` - Diagonal SW position
10. `npc_far` - Short range test (64px)
11. `npc_disabled` - Face player disabled
12. (Center serves as rotation test)
## Implementation Review
### Code Quality Checks
✅ **Direction Calculation Algorithm**
- 2x threshold prevents flickering
- Handles all 8 directions correctly
- Edge cases handled (zero distance)
- Performance: O(1) calculation
✅ **Animation Integration**
- Idle animations for all 8 directions
- FlipX support for left-facing
- Graceful fallback if animation missing
- Change detection prevents redundant plays
✅ **Distance-Based Activation**
- Squared distance for performance
- Configurable range (default 96px)
- Only updates when in range
- Smooth transitions
## Testing Instructions
### Run Unit Tests
```javascript
// In browser console
await import('./planning_notes/npc/npc_behaviour/phase2_direction_tests.js?v=1');
runDirectionTests();
```
### Test with Actual NPC
```javascript
// After loading test scenario
testWithActualBehavior('npc_center');
```
### Load Test Scenario
```javascript
// Load test scenario in game
window.gameScenario = await fetch('scenarios/test-npc-face-player.json').then(r => r.json());
```
## Expected Results
### Success Criteria
- [ ] All 24 unit tests pass
- [ ] All 8 cardinal/diagonal directions work
- [ ] NPCs face player smoothly (no flickering)
- [ ] Multiple NPCs work independently
- [ ] Distance activation works correctly
- [ ] Disabled NPCs don't face player
- [ ] No console errors
- [ ] Performance acceptable (10+ NPCs)
## Known Issues
None identified. Implementation appears solid.
## Next Steps
Once Phase 2 testing completes:
- **Phase 3**: Patrol Behavior testing
- **Phase 4**: Personal Space testing
- **Phase 5**: Ink Integration testing
- **Phase 6**: Hostile visual feedback
## Performance Notes
- Update throttling: 50ms (20 Hz)
- Direction calculation: O(1)
- Animation checks: Change detection only
- Expected FPS impact: < 2% with 10 NPCs
## Documentation
Comprehensive test guide includes:
- Step-by-step test procedures
- Visual layout diagrams
- Debugging commands
- Common issues/solutions
- Success criteria checklist
Ready for user testing and validation!
- Updated IMPLEMENTATION_PLAN.md to reflect new architecture and simplified lifecycle management due to rooms never unloading.
- Added critical prerequisites in Phase -1 for walk animations, player position checks, and phone NPC filtering.
- Revised QUICK_REFERENCE.md and README.md for clarity on implementation status and next steps.
- Introduced QUICK_TAKEAWAYS.md summarizing key changes from the code review.
- Created UPDATE_SUMMARY.md detailing updates applied based on maintainer clarifications.
- Adjusted review README.md to streamline navigation and highlight important documents for developers and stakeholders.
- Added PHASE_MINUS_ONE_ACTION_PLAN.md detailing critical fixes needed before Phase 1 implementation.
- Updated README.md to include new action plan and review status.
- Created README_REVIEWS.md as a navigation guide for review documents.
- Addressed critical issues including walk animations, player position tracking, phone NPC filtering, and environment collisions.
- Established a checklist for testing and verification of fixes.
- Revised estimated timelines for implementation phases.
- Created CHANGES_SUMMARY.md to summarize updates and fixes post-review.
- Added PLAN_REVIEW_AND_RECOMMENDATIONS.md detailing critical issues and recommendations for NPC behavior implementation.
- Fixed critical issues regarding animation creation timing, integration points, and validation for patrol bounds and sprite references.
- Updated implementation plan to include a new Phase 0 for animation prerequisites.
- Clarified NPC collision configuration and ensured roomId is stored in NPC data.
- Enhanced documentation across multiple files to reflect changes and provide troubleshooting guidance.
- Created CHANGES_APPLIED.md to document critical clarifications and updates based on code review findings.
- Established a new review and improvements document (REVIEW_AND_IMPROVEMENTS.md) outlining 9 critical improvements and 12 enhancement opportunities for NPC behavior.
- Updated TECHNICAL_SPEC.md, IMPLEMENTATION_PLAN.md, QUICK_REFERENCE.md, and example_scenario.json with necessary changes regarding roomId tracking, sprite storage, wall collision setup, animation creation timing, and personal space behavior.
- Clarified async import patterns and depth update requirements in the implementation plan.
- Enhanced personal space behavior design to ensure NPCs back away slowly while maintaining eye contact with players.
- Documented all changes and improvements to ensure better integration with existing systems and reduce complexity in NPC behavior implementation.
- Introduced a data-driven global variable system to manage narrative state across NPC interactions.
- Added support for global variables in scenario JSON, allowing for easy extension and management.
- Implemented synchronization of global variables between Ink stories and the game state, ensuring real-time updates across conversations.
- Enhanced state persistence, allowing global variables to survive page reloads and be restored during conversations.
- Created comprehensive documentation and testing guides to facilitate usage and verification of the new system.
- Introduced new NPC inventory system allowing NPCs to hold and give items to players.
- Updated ContainerMinigame to support NPC mode, displaying NPC avatars and available items.
- Enhanced chat and conversation systems to sync NPC item states with Ink variables, improving narrative interactions.
- Added event listeners for item changes, ensuring dynamic updates during conversations.
- Implemented new methods in NPCGameBridge for item giving and inventory display, streamlining item interactions.
- Consolidated async function updates for NPC loading in the `create()` function to streamline the process.
- Improved error handling during NPC loading for the starting room, ensuring room creation continues even if NPC loading fails.
- Updated documentation to reflect changes in the implementation checklist for better clarity on migration steps.
- Updated various planning documents to include additional details and clarity on the NPC migration process.
- Added new sections to CLIENT_SERVER_SEPARATION_PLAN.md, NPC_MIGRATION_OPTIONS.md, RAILS_ENGINE_MIGRATION_PLAN.md, and README.md to improve overall documentation and ensure comprehensive coverage of migration strategies.
- Ensured all documents reflect the latest architectural decisions and implementation plans for better guidance during the migration process.
- Create README.md outlining the entire migration plan, including executive summary, technical details, migration guide, API specification, and testing checklist.
- Introduce START_HERE.md as a quick start guide for implementation, detailing initial steps and phase breakdown.
- Develop VISUAL_GUIDE.md with diagrams and visual references for current vs. target architecture, NPC types, implementation phases, and memory usage comparisons.
- Created a new JSON scenario file for testing NPC sprite functionality.
- Implemented a simple HTTP server with caching headers for development purposes.
- Added an HTML page for testing NPC interactions, including system checks and game controls.
- Introduced a separate HTML page for testing item delivery through person chat interactions.
- Created SoundManager class for centralized audio management using Phaser's audio system.
- Integrated 34 sound assets, including UI interactions, item collection, and lock attempts.
- Developed UI sound helpers for seamless attachment to DOM elements.
- Updated game.js to preload and initialize sound manager, ensuring global access.
- Modified interactions.js, unlock-system.js, and panels.js to incorporate sound feedback.
- Provided extensive documentation, including implementation summary and usage examples.
- Ensured backward compatibility and optimized performance for audio playback.
- Added event emissions for NPC interactions in core game systems:
- Unlock System: door_unlocked, item_unlocked, door_unlock_attempt
- Interactions System: object_interacted
- Inventory System: item_picked_up:*
- Minigame Framework: minigame_completed, minigame_failed
- Created event-triggered reactions for the helper NPC:
- Added knots for lockpick pickup, success, failure, door unlock, and object interaction.
- Implemented state tracking and context-aware responses.
- Updated event mappings in scenario JSON for the helper NPC to respond to various events.
- Fixed global variable references in event emission code to ensure proper event dispatching.
- Added debug logging to verify event emissions and NPC reactions.
- Documented implementation details and testing instructions for new features.
- Added NPCGameBridge class to facilitate interactions between NPCs and game state.
- Implemented methods for unlocking doors, giving items, setting objectives, revealing secrets, adding notes, triggering events, and discovering rooms.
- Introduced a helper NPC that can assist players by unlocking the CEO's office and providing items based on trust levels.
- Created comprehensive documentation for the NPC Game Bridge implementation.
- Updated scenario JSON to include the new helper NPC and its interactions.
- Added Ink story for the helper NPC demonstrating its capabilities.
- Deleted `phone-messages-minigame.js` and archived related CSS.
- Updated `interactions.js` to exclusively use phone-chat with runtime conversion.
- Enhanced error handling for phone interactions.
- Marked completion of old phone minigame removal in implementation log.
- Added detailed cleanup summary documentation.
- Added support for voice messages prefixed with "voice:" in Ink files.
- Updated UI rendering to display voice message UI with play button and transcript.
- Implemented automatic conversion for scenario JSON with voice properties.
- Created test examples for pure voice messages and mixed content.
- Fixed issues with NPC registration and message duplication in test scenarios.
- Documented feature details, use cases, and testing procedures.
Update interactions.js to reference new version of constants
Improve NPCBarkSystem to dynamically import phone-chat minigame and handle fallback UI more gracefully
Modify constants.js to conditionally export GAME_CONFIG based on Phaser availability
Update implementation log for Phone Chat Minigame, detailing completed modules and next steps
Create detailed implementation plan for Phone Chat Minigame, outlining structure, features, and integration points
Add test HTML page for Phone Chat Minigame, including setup, chat tests, and history management functionalities
- Created a generic NPC script with conversation handling.
- Developed an Alice NPC script demonstrating branching dialogue and state tracking.
- Implemented a test NPC script for development purposes.
- Added JSON representations for the NPC scripts.
- Created an HTML test interface for NPC integration testing.
- Included event handling and bark systems for NPC interactions.
- Created `05_EXAMPLE_SCENARIO.md` with a complete Ink script for the Biometric Breach scenario featuring NPCs Alice and Bob.
- Added `QUICK_REFERENCE.md` as a cheat sheet for NPC system components, event types, and common patterns.
- Introduced `README.md` as an index for NPC integration planning, outlining document structure and key concepts.
