voider/Scenes/Testing/TEST_MAP_GUIDE.md

Library Test Map Guide

This test map is designed to comprehensively test all movement mechanics from the EinSoftworks.Movement library.

Map Layout

Spawn Area (Center)

• Location: (0, 2, 0)
• Purpose: Starting point with clear view of all test areas
• Features: Large open floor for basic movement testing

Test Areas

1. Stairs (Right Side - Position: 10, 0, -10)

• Purpose: Test vertical movement and step climbing
• Features: 4 steps, each 0.5m high
• Tests:
  • Walking up stairs smoothly
  • Step height handling
  • Momentum preservation on steps
  • Crouch movement on stairs

2. Jump Gap (Left Side - Position: -20, 0, 0)

• Purpose: Test jump distance and height
• Features: Two platforms with 12m gap between them
• Tests:
  • Basic jump distance (should NOT be able to cross without sprint)
  • Sprint + jump distance (should be able to cross)
  • Landing mechanics
  • Edge detection

3. Speed Test Corridor (Right Side - Position: 20, 0, 0)

• Purpose: Test acceleration and max speed
• Features: 20m long corridor with walls
• Tests:
  • Acceleration from standstill
  • Time to reach max speed
  • Sprint speed comparison
  • Friction/deceleration when stopping

4. Gentle Ramp (Right Front - Position: 15, 2, 0)

• Purpose: Test slope movement
• Features: ~30° incline ramp
• Tests:
  • Walking up slopes
  • Sliding down slopes
  • Speed preservation on slopes
  • Basic surfing mechanics

5. Steep Ramp (Left Back - Position: -15, 3, 10)

• Purpose: Test steep slope handling and surfing
• Features: 45° incline ramp
• Tests:
  • Steep slope climbing
  • Advanced surfing
  • Speed gain on steep surfaces
  • Slope angle limits

6. Original Platforms (Left Back - Positions: -10, 2, -10 and -10, 4, -20)

• Purpose: Test vertical jumping and platforming
• Features: Two platforms at different heights
• Tests:
  • Single jump height (2m)
  • Double platform jumping
  • Precision landing
  • Air control

Movement Testing Checklist

Basic Movement

• Walk forward/back/left/right smoothly
• Diagonal movement works correctly
• Stopping is responsive (friction works)
• Movement speed feels appropriate

Sprint

• Sprint increases speed noticeably
• Sprint + jump covers more distance
• Can sprint in all directions
• Sprint speed cap is working

Jumping

• Jump height is consistent (~1.5-2m)
• Can jump while moving
• Landing doesn't cause stutter
• Jump cooldown works (if enabled)

Crouching

• Crouch reduces height
• Crouch reduces speed
• Can move while crouched
• Can't stand up when blocked

Air Control

• Can change direction slightly in air
• Air strafing works
• Momentum is preserved
• Gravity feels natural

Stairs

• Can walk up stairs smoothly
• No stuttering on steps
• Can jump up stairs
• Can crouch on stairs

Slopes

• Can walk up gentle slopes
• Slides down steep slopes appropriately
• Surfing mechanics work
• Speed changes on slopes feel right

Bunny Hopping (if enabled)

• Can chain jumps
• Speed increases with successful hops
• Direction control while hopping
• Speed cap is enforced

Recommended Movement Values

Based on testing, here are suggested value ranges:

Speed Settings (m/s)

MaxSpeed = 5f;          // Base walking speed
MaxSprintSpeed = 8f;    // Sprint speed (1.6x walk)
MaxWalkSpeed = 3f;      // Slow walk
MaxCrouchSpeed = 2f;    // Crouch speed (0.4x walk)

Acceleration & Friction

Acceleration = 8f;      // How fast you reach max speed
AirAcceleration = 2f;   // Air control strength
Friction = 6f;          // How fast you stop
StopSpeed = 1f;         // Speed threshold for friction

Jump & Gravity

JumpVelocity = 5f;      // Initial jump speed (gives ~1.5m height)
Gravity = 15f;          // Downward acceleration

Testing Procedures

1. Basic Movement Test (2 minutes)

1. Spawn in center
2. Walk in all 8 directions
3. Test stopping from full speed
4. Try diagonal movement
5. Expected: Smooth, responsive movement

2. Sprint Test (1 minute)

1. Sprint forward in Speed Test Corridor
2. Time how long to reach max speed
3. Try sprint jumping
4. Expected: Noticeable speed increase, ~1-2 seconds to max speed

3. Jump Test (3 minutes)

1. Jump in place 5 times
2. Jump while moving forward
3. Try to cross Jump Gap without sprint (should fail)
4. Sprint + jump across Jump Gap (should succeed)
5. Expected: Consistent jump height, gap requires sprint

4. Stairs Test (2 minutes)

1. Walk up stairs normally
2. Sprint up stairs
3. Jump up stairs
4. Crouch on stairs
5. Expected: Smooth climbing, no stuttering

5. Slope Test (3 minutes)

1. Walk up Gentle Ramp
2. Run down Gentle Ramp
3. Try to walk up Steep Ramp
4. Surf down Steep Ramp
5. Expected: Can climb gentle, slides on steep, surfing works

6. Advanced Test (5 minutes)

1. Try bunny hopping across main floor
2. Test air strafing while jumping
3. Try crouch jumping for extra height
4. Test edge cases (corners, tight spaces)
5. Expected: Advanced mechanics work as designed

Tuning Guide

Movement Feels Too Slow

• Increase MaxSpeed and MaxSprintSpeed
• Increase Acceleration
• Decrease Friction

Movement Feels Too Fast

• Decrease MaxSpeed and MaxSprintSpeed
• Decrease Acceleration
• Increase Friction

Can't Climb Stairs

• Decrease StepHeight in config
• Increase Acceleration
• Check collision shape height

Jumps Too High/Low

• Adjust JumpVelocity (higher = higher jumps)
• Adjust Gravity (higher = falls faster)
• Test with: height = (JumpVelocity²) / (2 * Gravity)

Slides Too Much

• Increase Friction
• Decrease StopSpeed
• Check surface friction values

Air Control Issues

• Adjust AirAcceleration (higher = more control)
• Adjust AirSpeedCap (limits air speed gain)
• Check AirControl value

Debug Commands

While testing, these debug outputs are helpful:

EnableDebugOutput = true;  // Shows speed and state in console

Watch for:

• Speed values (should match expected ranges)
• State transitions (idle → walking → airborne)
• OnFloor status (true when grounded)

Known Issues to Test For

1. Stuck on edges: Can player get stuck on platform edges?
2. Stair stuttering: Does movement stutter when climbing stairs?
3. Slope sliding: Does player slide uncontrollably on slopes?
4. Air control: Can player change direction reasonably in air?
5. Speed capping: Does bunny hopping break speed limits?
6. Crouch stuck: Can player get stuck in crouch state?

Performance Targets

• FPS: Maintain 60 FPS with debug output enabled
• Input Latency: Movement should feel instant (<1 frame delay)
• State Transitions: Should be smooth and immediate
• Physics: No jittering or stuttering during normal movement

Next Steps

After testing this map:

1. Document any issues found
2. Adjust movement values in TestPlayer.cs
3. Test specific mechanics that felt off
4. Create additional test scenarios if needed
5. Consider adding visual markers (distance indicators, height markers)