mirror of
https://github.com/cliffe/BreakEscape.git
synced 2026-02-21 11:18:08 +00:00
adc5f3baa4
- 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.
490 lines
12 KiB
Markdown
490 lines
12 KiB
Markdown
# NPC Patrol Features - Complete Summary
|
|
|
|
## What Was Requested
|
|
|
|
> "Can we add a list of co-ordinates to include in the patrol? Range of 3-8 for x and y in a room"
|
|
>
|
|
> "And can an NPC navigate between rooms, once more rooms are loaded?"
|
|
|
|
## What Was Designed
|
|
|
|
Two complementary features, documented in three comprehensive guides:
|
|
|
|
---
|
|
|
|
## Feature 1: Waypoint Patrol 📍
|
|
|
|
**Location:** Single-room NPC patrol between predefined waypoints
|
|
|
|
### Configuration
|
|
```json
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 100,
|
|
"waypoints": [
|
|
{"x": 3, "y": 3},
|
|
{"x": 6, "y": 3},
|
|
{"x": 6, "y": 6},
|
|
{"x": 3, "y": 6}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Modes
|
|
- **Sequential** (default): Follow waypoints 1→2→3→4→1→...
|
|
- **Random**: Pick any waypoint every `changeDirectionInterval`
|
|
|
|
### Advanced
|
|
```json
|
|
{
|
|
"x": 4,
|
|
"y": 4,
|
|
"dwellTime": 2000 // Stand here for 2 seconds
|
|
}
|
|
```
|
|
|
|
### How It Works
|
|
```
|
|
Tile Coords (3-8) → World Coords → Pathfinding Grid
|
|
(4, 4) + Room Offset → Uses EasyStar.js
|
|
↓
|
|
Valid Waypoint?
|
|
↓
|
|
NPC follows path
|
|
```
|
|
|
|
---
|
|
|
|
## Feature 2: Cross-Room Navigation 🚪
|
|
|
|
**Location:** Multi-room patrol route spanning connected rooms
|
|
|
|
### Configuration
|
|
```json
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 80,
|
|
"multiRoom": true,
|
|
"startRoom": "lobby",
|
|
"route": [
|
|
{
|
|
"room": "lobby",
|
|
"waypoints": [{"x": 4, "y": 3}, {"x": 6, "y": 5}]
|
|
},
|
|
{
|
|
"room": "hallway",
|
|
"waypoints": [{"x": 3, "y": 4}, {"x": 3, "y": 6}]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### How It Works
|
|
```
|
|
Start: NPC in lobby at (4,3)
|
|
↓
|
|
Patrol lobby waypoints: (4,3) → (6,5)
|
|
↓
|
|
Lobby segment complete → Find door to hallway
|
|
↓
|
|
Transition to hallway, spawn at entry
|
|
↓
|
|
Patrol hallway waypoints: (3,4) → (3,6)
|
|
↓
|
|
Hallway segment complete → Find door to lobby
|
|
↓
|
|
Loop back to start
|
|
↓
|
|
Repeat infinitely
|
|
```
|
|
|
|
---
|
|
|
|
## Feature Comparison Matrix
|
|
|
|
```
|
|
┌─────────────────────┬──────────────┬──────────────┬────────────────┐
|
|
│ Aspect │ Random Patrol│ Waypoint │ Cross-Room │
|
|
├─────────────────────┼──────────────┼──────────────┼────────────────┤
|
|
│ Patrol Type │ Random tiles │ Specific │ Multi-room │
|
|
│ │ │ waypoints │ waypoint route │
|
|
├─────────────────────┼──────────────┼──────────────┼────────────────┤
|
|
│ Predictable Route │ ❌ │ ✅ │ ✅ │
|
|
│ Configuration │ bounds │ waypoints │ route │
|
|
│ Coordinate Range │ Configurable │ 3-8 (or any)│ 3-8 (or any) │
|
|
├─────────────────────┼──────────────┼──────────────┼────────────────┤
|
|
│ Single Room │ ✅ │ ✅ │ ❌ │
|
|
│ Multiple Rooms │ ❌ │ ❌ │ ✅ │
|
|
├─────────────────────┼──────────────┼──────────────┼────────────────┤
|
|
│ Status │ ✅ Works │ 🔄 Ready │ 🔄 Ready │
|
|
│ Implementation │ Current │ Phase 1 │ Phase 2 │
|
|
├─────────────────────┼──────────────┼──────────────┼────────────────┤
|
|
│ Complexity │ Simple │ Medium │ Medium-High │
|
|
│ Memory Impact │ Minimal │ Minimal │ Load all rooms │
|
|
│ Dev Time Estimate │ Done │ 2-4 hrs │ 4-8 hrs │
|
|
└─────────────────────┴──────────────┴──────────────┴────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
### System Interactions
|
|
|
|
```
|
|
Scenario JSON
|
|
├─ waypoints: [...], ← Feature 1 config
|
|
├─ multiRoom: true, ← Feature 2 config
|
|
└─ route: [...] ← Feature 2 config
|
|
│
|
|
↓
|
|
npc-behavior.js (MODIFIED)
|
|
├─ parseConfig() ← Add waypoint/route parsing
|
|
├─ chooseNewPatrolTarget() ← Add waypoint selection
|
|
└─ updatePatrol() ← Add room transition logic
|
|
│
|
|
↓
|
|
npc-pathfinding.js (ENHANCED Phase 2)
|
|
├─ findPathAcrossRooms() ← Multi-room pathfinding
|
|
└─ getRoomConnectionDoor() ← Room door detection
|
|
│
|
|
↓
|
|
npc-sprites.js (ENHANCED Phase 2)
|
|
├─ relocateNPCSprite() ← Sprite room transitions
|
|
└─ updateNPCDepth() ← Depth sorting after moves
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Single-Room Waypoints ⭐ Recommended First
|
|
|
|
**Changes:**
|
|
```
|
|
npc-behavior.js
|
|
├─ parseConfig() → Add patrol.waypoints, patrol.waypointMode
|
|
├─ validateWaypoints() → Check walkable, within bounds
|
|
├─ chooseNewPatrolTarget() → Select waypoint vs random
|
|
└─ dwell timer → Pause at waypoints
|
|
```
|
|
|
|
**Test Case:**
|
|
```json
|
|
{
|
|
"id": "test_guard",
|
|
"behavior": {
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 100,
|
|
"waypoints": [
|
|
{"x": 3, "y": 3},
|
|
{"x": 6, "y": 3},
|
|
{"x": 6, "y": 6}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Effort:** 2-4 hours
|
|
**Risk:** Low (isolated to npc-behavior.js)
|
|
|
|
---
|
|
|
|
### Phase 2: Multi-Room Routes 🚀 After Phase 1
|
|
|
|
**Changes:**
|
|
```
|
|
npc-behavior.js
|
|
├─ multiRoom config handling
|
|
├─ transitionToNextRoom()
|
|
└─ room switching logic
|
|
|
|
npc-pathfinding.js
|
|
├─ findPathAcrossRooms()
|
|
└─ door detection
|
|
|
|
npc-sprites.js
|
|
└─ relocateNPCSprite()
|
|
|
|
rooms.js
|
|
└─ Pre-load all route rooms
|
|
```
|
|
|
|
**Test Case:**
|
|
```json
|
|
{
|
|
"id": "security",
|
|
"multiRoom": true,
|
|
"route": [
|
|
{"room": "lobby", "waypoints": [...]},
|
|
{"room": "hallway", "waypoints": [...]}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Effort:** 4-8 hours
|
|
**Risk:** Medium (coordination across systems)
|
|
|
|
---
|
|
|
|
## Documentation Created
|
|
|
|
| Document | Purpose |
|
|
|----------|---------|
|
|
| `NPC_PATROL_WAYPOINTS.md` | **Complete Feature 1 Guide** - Configuration, validation, code changes, examples |
|
|
| `NPC_CROSS_ROOM_NAVIGATION.md` | **Complete Feature 2 Guide** - Architecture, phases, validation, error handling |
|
|
| `NPC_WAYPOINTS_AND_CROSSROOM_QUICK_REFERENCE.md` | **Quick Start Guide** - Both features, comparison, examples, troubleshooting |
|
|
| `PATROL_CONFIGURATION_GUIDE.md` | **Updated** - Existing random patrol configuration (still relevant) |
|
|
|
|
---
|
|
|
|
## Configuration Examples
|
|
|
|
### Example 1: Rectangle Patrol (Feature 1)
|
|
|
|
```json
|
|
{
|
|
"id": "perimeter_guard",
|
|
"position": {"x": 4, "y": 4},
|
|
"behavior": {
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 100,
|
|
"waypoints": [
|
|
{"x": 3, "y": 3},
|
|
{"x": 7, "y": 3},
|
|
{"x": 7, "y": 7},
|
|
{"x": 3, "y": 7}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Result:** Guard walks perimeter of room (3,3)→(7,3)→(7,7)→(3,7)→repeat
|
|
|
|
---
|
|
|
|
### Example 2: Checkpoint Guard with Dwell (Feature 1)
|
|
|
|
```json
|
|
{
|
|
"id": "checkpoint_guard",
|
|
"position": {"x": 4, "y": 4},
|
|
"behavior": {
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 60,
|
|
"waypoints": [
|
|
{"x": 4, "y": 3, "dwellTime": 3000},
|
|
{"x": 4, "y": 7, "dwellTime": 3000}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Result:** Guard moves to checkpoint (4,3), stands 3s, moves to (4,7), stands 3s, repeats
|
|
|
|
---
|
|
|
|
### Example 3: Multi-Room Security Patrol (Feature 2)
|
|
|
|
```json
|
|
{
|
|
"id": "security_patrol",
|
|
"startRoom": "lobby",
|
|
"position": {"x": 4, "y": 4},
|
|
"behavior": {
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 80,
|
|
"multiRoom": true,
|
|
"route": [
|
|
{
|
|
"room": "lobby",
|
|
"waypoints": [
|
|
{"x": 4, "y": 3},
|
|
{"x": 6, "y": 5}
|
|
]
|
|
},
|
|
{
|
|
"room": "hallway_east",
|
|
"waypoints": [
|
|
{"x": 3, "y": 4},
|
|
{"x": 3, "y": 6}
|
|
]
|
|
},
|
|
{
|
|
"room": "office",
|
|
"waypoints": [
|
|
{"x": 5, "y": 5}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Result:** Guard patrols: lobby (4,3)→(6,5) → hallway (3,4)→(3,6) → office (5,5) → repeat
|
|
|
|
---
|
|
|
|
## Validation Rules
|
|
|
|
### Phase 1: Waypoint Validation
|
|
|
|
```javascript
|
|
// Each waypoint must pass:
|
|
✅ x, y in range (configurable, e.g., 3-8)
|
|
✅ Position within room bounds
|
|
✅ Position is walkable (not in wall)
|
|
✅ At least 1 valid waypoint exists
|
|
|
|
// If validation fails:
|
|
→ Log warning
|
|
→ Fall back to random patrol
|
|
→ Continue normally (graceful degradation)
|
|
```
|
|
|
|
### Phase 2: Multi-Room Route Validation
|
|
|
|
```javascript
|
|
// Route must pass:
|
|
✅ startRoom exists in scenario
|
|
✅ All rooms in route exist
|
|
✅ Consecutive rooms connected via doors
|
|
✅ All waypoints in all rooms valid
|
|
✅ Route contains at least 1 room
|
|
|
|
// If validation fails:
|
|
→ Log error
|
|
→ Disable multiRoom
|
|
→ Use single-room patrol in startRoom
|
|
```
|
|
|
|
---
|
|
|
|
## Performance Impact
|
|
|
|
### Phase 1 (Waypoints Only)
|
|
- **Memory:** ~1KB per NPC (waypoint list storage)
|
|
- **CPU:** No additional cost (uses same pathfinding)
|
|
- **Result:** ✅ Negligible impact
|
|
|
|
### Phase 2 (Multi-Room Routes)
|
|
- **Memory:** ~160KB per loaded room
|
|
- Tilemap: ~100KB
|
|
- Pathfinding grid: ~10KB
|
|
- Sprite data: ~50KB
|
|
- **CPU:** ~50ms per room for pathfinder initialization
|
|
- **Example:** 3-room route = ~480KB, ~150ms one-time cost
|
|
- **Result:** 🟡 Acceptable for most scenarios
|
|
|
|
---
|
|
|
|
## Backward Compatibility
|
|
|
|
✅ **Both features are fully backward compatible:**
|
|
|
|
```json
|
|
// Old configuration still works:
|
|
{
|
|
"patrol": {
|
|
"enabled": true,
|
|
"speed": 100,
|
|
"bounds": {"x": 64, "y": 64, "width": 192, "height": 192}
|
|
}
|
|
}
|
|
|
|
// New features are opt-in:
|
|
{
|
|
"patrol": {
|
|
"enabled": true,
|
|
"waypoints": [...] // Optional
|
|
}
|
|
}
|
|
|
|
// No breaking changes
|
|
// Existing scenarios work unchanged
|
|
// Features can be mixed and matched
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
### Immediate (You)
|
|
1. Review the three documentation files:
|
|
- `NPC_PATROL_WAYPOINTS.md`
|
|
- `NPC_CROSS_ROOM_NAVIGATION.md`
|
|
- `NPC_WAYPOINTS_AND_CROSSROOM_QUICK_REFERENCE.md`
|
|
|
|
2. Decide implementation priority:
|
|
- **Recommended:** Phase 1 first (waypoints), then Phase 2 (multi-room)
|
|
- **Or:** Combine both at once (riskier but faster)
|
|
|
|
### Then (Implementation)
|
|
1. **Start Phase 1:**
|
|
- Modify `npc-behavior.js` `parseConfig()`
|
|
- Add waypoint validation
|
|
- Update `chooseNewPatrolTarget()`
|
|
- Test with scenario
|
|
|
|
2. **Then Phase 2:**
|
|
- Extend patrol config for routes
|
|
- Implement room transition logic
|
|
- Test cross-room movement
|
|
|
|
### Finally (Deployment)
|
|
1. Create test scenarios demonstrating both features
|
|
2. Update documentation in scenario design guide
|
|
3. Add waypoints to JSON schema validation
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
| Aspect | Status |
|
|
|--------|--------|
|
|
| **Feature 1: Waypoints** | ✅ Documented, ready to implement |
|
|
| **Feature 2: Cross-Room** | ✅ Documented, architecture designed |
|
|
| **Documentation** | ✅ 4 comprehensive guides created |
|
|
| **Backward Compat** | ✅ Full compatibility maintained |
|
|
| **Examples** | ✅ Multiple examples provided |
|
|
| **Testing Guide** | ✅ Validation rules documented |
|
|
| **Performance** | ✅ Impact analyzed |
|
|
| **Risk Assessment** | ✅ Phase-based approach reduces risk |
|
|
|
|
---
|
|
|
|
## Files Modified/Created
|
|
|
|
```
|
|
Created:
|
|
├─ NPC_PATROL_WAYPOINTS.md (2,000+ words)
|
|
├─ NPC_CROSS_ROOM_NAVIGATION.md (2,500+ words)
|
|
└─ NPC_WAYPOINTS_AND_CROSSROOM_QUICK_REFERENCE.md (1,500+ words)
|
|
|
|
Updated:
|
|
└─ PATROL_CONFIGURATION_GUIDE.md (existing, still relevant)
|
|
```
|
|
|
|
---
|
|
|
|
## Support & Questions
|
|
|
|
For detailed information on:
|
|
- **Waypoint configuration** → See `NPC_PATROL_WAYPOINTS.md`
|
|
- **Multi-room routes** → See `NPC_CROSS_ROOM_NAVIGATION.md`
|
|
- **Quick start** → See `NPC_WAYPOINTS_AND_CROSSROOM_QUICK_REFERENCE.md`
|
|
- **Current patrol system** → See `PATROL_CONFIGURATION_GUIDE.md`
|
|
|
|
---
|
|
|
|
**Ready to implement Phase 1? Let me know when you're ready to start coding! 🚀**
|
|
|