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

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

Search Logs for Specific Info

# 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!