Commonwealth-Online-Public/docs/phase6-quick-start.md

# Phase 6 Quick Start Checklist

## Before You Start

- [ ] All Phases 1-5 code committed to git
- [ ] F4T plugin builds without errors
- [ ] F4SE installed in Fallout 4
- [ ] Server relay running (`python server/server.py`)
- [ ] Ready to launch Fallout 4 with F4SE

## Test Execution Order

### Critical Path (30 minutes)

1. **[5 min] Test 1: Proxy Spawning**
   - Start game, load F4TTestCell01
   - Connect fake client
   - [ ] Proxy appears near player
   - [ ] No crashes
   - **Result:** PASS / FAIL

2. **[5 min] Test 2: Movement**
   - Move fake client position
   - [ ] Proxy smoothly moves to new position
   - [ ] No jittering/snapping
   - **Result:** PASS / FAIL

3. **[10 min] TEST 3 - CRITICAL: Animations**
   - Fake client: stand still → should see idle
   - Fake client: walk speed → should see walk animation
   - Fake client: run speed → should see run animation
   - Fake client: sprint speed → should see sprint animation
   - [ ] At least idle/walk/run animations visible
   - **Result:** PASS / FAIL / PARTIAL
   - **If FAIL:** Debug with console logs

4. **[5 min] Test 4: Sneak**
   - Fake client: activate sneak
   - [ ] Proxy crouches
   - **Result:** PASS / FAIL / PARTIAL

5. **[5 min] Test 5: Multiple Proxies**
   - Connect 3 fake clients (3 proxies total)
   - All moving simultaneously
   - [ ] All animate correctly
   - [ ] No crashes
   - **Result:** PASS / FAIL

### If Test 3 FAILS (Animations not playing)

**Debug Checklist (10 minutes):**
1. [ ] Check console logs for velocity being set
   - Search: `ApplyRuntimeProxyTransform`
   - Should show character controller access
   
2. [ ] Check animation graph manager available
   - Search: `animation graph manager`
   - Should NOT show "unavailable" messages
   
3. [ ] Check actor state flags
   - Search: `flags1=`
   - Should show valid hex values
   
4. [ ] Check Speed variable is changing
   - Search: `graphSpeed=`
   - Should see values > 0 when moving

5. [ ] Manual test: Set Speed directly in console
   - If manual setting works → indices correct, velocity issue
   - If manual setting doesn't work → index problem

**If still failing:** Document issue and proceed to Phase 6.3 iteration

## Key Logging Commands

### View Real-Time Logs

```powershell
# In separate terminal, tail latest logs
Get-Content "Documents\My Games\Fallout4\Logs\*.log" -Wait
```

### Search Logs for Specific Info

```powershell
# Proxy spawn
Select-String "SpawnDynamicProxyActor" (Get-ChildItem "Documents\My Games\Fallout4\Logs\*")

# Animations
Select-String "animation sync" (Get-ChildItem "Documents\My Games\Fallout4\Logs\*")

# Errors
Select-String "WARNING\|ERROR" (Get-ChildItem "Documents\My Games\Fallout4\Logs\*")
```

## Expected Console Log Patterns

### Good (Animations Working)

```
[Local Player ID: 0] SpawnDynamicProxyActor: Spawned proxy actor 0xABCD1234 for remote player 1
[Local Player ID: 0] Assigned dynamically spawned proxy 0xABCD1234 to remote player 1
[Local Player ID: 0] First smoothed runtime proxy movement for remote player 1: actor=0xABCD1234, alpha=0.15
[Local Player ID: 0] ApplyRuntimeProxyTransform: Proxy 0xABCD1234 has AIProcess: true
[Local Player ID: 0] Runtime proxy animation sync initial for remote player 1: moving=true, sprinting=false, graphSpeed=55.0
```

### Bad (Animations NOT Working)

```
[Local Player ID: 0] animation graph manager unavailable
[Local Player ID: 0] Failed to load animation variables for remote player 1
[Local Player ID: 0] Proxy 0xABCD1234 has NO AIProcess
```

## Performance Expectations

| Metric | Expected | Alert If |
|--------|----------|----------|
| Proxy spawn time | < 500ms | > 1 second |
| Per-proxy update | < 1ms | > 5ms |
| Frame rate | 60+ fps | < 30 fps with 1 proxy |
| Animation smooth | No stutter | Visible jitter |

## Results Template

Copy this after testing:

```
## Phase 6 Test Results - [DATE]

### Tests
- Test 1 (Spawning): PASS / FAIL
- Test 2 (Movement): PASS / FAIL
- Test 3 (Animations): PASS / FAIL / PARTIAL
- Test 4 (Sneak): PASS / FAIL / PARTIAL
- Test 5 (Multiple): PASS / FAIL

### Issues Found
1. <Issue>
   - Severity: Critical / Major / Minor
   - Fix: <action needed>

### Next Action
- [ ] PASS ALL → Proceed to Phase 7
- [ ] PARTIAL → Iterate Phase 6.3 (tune)
- [ ] FAIL → Debug and retest
```

## Common Fixes

### Animations not playing
- **Try:** Increase velocity scale (multiply by 1.2x)
- **Try:** Check animation variable indices in F4AnimationDescriptor
- **Try:** Enable debug logging for Speed variable

### Proxy doesn't move smoothly
- **Try:** Reduce lerp alpha (currently 0.15)
- **Try:** Increase update frequency (more network packets)
- **Try:** Check for network lag

### Multiple proxies crash
- **Try:** Reduce from 4 to 2 proxies
- **Try:** Check for memory leaks in action queue
- **Try:** Verify proxy pool cleanup on disconnect

## Success = All PASS

When you see:
1. ✅ Proxy spawns
2. ✅ Proxy moves smoothly
3. ✅ Proxy animates (idle/walk/run/sprint)
4. ✅ Multiple proxies work
5. ✅ No crashes

**Then Phase 6 is COMPLETE and Phase 7 ready!**