novafarma/docs/PHASE1_PLAYER_CONTROLS.md

🎮 PHASE 1: PLAYER CONTROLS - Implementation Summary

Date: 2025-12-14 15:02
Status: Analysis Complete - Ready to Implement

---

📊 CURRENT STATE ANALYSIS

Existing Player System:

• ✅ Grid-based movement (tile by tile)
• ✅ WASD + Arrow keys
• ✅ Gamepad support (basic)
• ✅ Virtual joystick (mobile)
• ✅ Animation system (4 directions)
• ❌ NO smooth movement
• ❌ NO sprint system
• ❌ NO acceleration/deceleration
• ❌ NO diagonal movement

Issues Found:

1. Grid-locked movement - Player jumps from tile to tile
2. No momentum - Instant start/stop
3. Basic animations - Simple 4-direction only
4. No sprint - Single speed only

---

🎯 IMPLEMENTATION PLAN

PHASE 1A: Smooth Movement System ⭐ PRIORITY

Goal: Replace grid-based with smooth pixel-based movement

Changes:

// BEFORE (Grid-based):
moveToGrid(targetX, targetY) {
    // Tween to grid position
    this.scene.tweens.add({...});
}

// AFTER (Smooth velocity):
update(delta) {
    // Apply velocity
    this.sprite.x += this.velocity.x * delta;
    this.sprite.y += this.velocity.y * delta;
    
    // Acceleration
    this.velocity.x = Phaser.Math.Linear(
        this.velocity.x,
        this.targetVelocity.x,
        this.acceleration
    );
}

Implementation:

1. Add velocity properties
2. Replace grid movement with pixel movement
3. Add acceleration/deceleration
4. Smooth turning

Files to modify:

• src/entities/Player.js (major refactor)

---

PHASE 1B: Sprint System 🏃

Goal: Add sprint with Shift key

Features:

• Normal speed: 100 px/s
• Sprint speed: 200 px/s
• Energy drain (optional)
• Visual indicator

Implementation:

// In update()
this.sprinting = this.keys.shift.isDown;
const maxSpeed = this.sprinting ? 200 : 100;

// Energy system (optional)
if (this.sprinting && this.moving) {
    this.energy -= 0.1 * delta;
    if (this.energy <= 0) this.sprinting = false;
}

---

PHASE 1C: Animation Polish 🎨

Goal: Smooth animations with transitions

Enhancements:

1. Walking animations - 4 directions (already exists)
2. Idle animations - Breathing effect
3. Sprint animations - Faster frame rate
4. Transition smoothing - Blend between anims

Implementation:

updateAnimation() {
    const speed = Math.sqrt(
        this.velocity.x ** 2 + 
        this.velocity.y ** 2
    );
    
    if (speed < 5) {
        // Idle
        this.sprite.play('protagonist_idle_' + this.direction, true);
    } else if (this.sprinting) {
        // Sprint (faster)
        this.sprite.play('protagonist_walk_' + this.direction, true);
        this.sprite.anims.msPerFrame = 80; // Faster
    } else {
        // Walk (normal)
        this.sprite.play('protagonist_walk_' + this.direction, true);
        this.sprite.anims.msPerFrame = 120; // Normal
    }
}

---

PHASE 1D: Enhanced Input 🎮

Goal: Better input handling

Features:

1. Diagonal movement - Combine inputs
2. Input buffering - Queue actions
3. Deadzone - Gamepad precision
4. Key rebinding - Custom controls (future)

Implementation:

handleInput() {
    let inputX = 0;
    let inputY = 0;
    
    // Collect all inputs
    if (this.keys.up.isDown) inputY -= 1;
    if (this.keys.down.isDown) inputY += 1;
    if (this.keys.left.isDown) inputX -= 1;
    if (this.keys.right.isDown) inputX += 1;
    
    // Normalize diagonal
    const length = Math.sqrt(inputX ** 2 + inputY ** 2);
    if (length > 0) {
        inputX /= length;
        inputY /= length;
    }
    
    // Set target velocity
    const maxSpeed = this.sprinting ? 200 : 100;
    this.targetVelocity.x = inputX * maxSpeed;
    this.targetVelocity.y = inputY * maxSpeed;
}

---

⚠️ IMPORTANT CONSIDERATIONS

Grid vs Smooth Movement:

Problem: Current game uses grid-based terrain system!

• Terrain tiles are on grid
• Collision is grid-based
• Farming is grid-based

Solutions:

Option A: Full Smooth Movement

• Move player smoothly
• Keep terrain on grid
• Convert player position to grid for interactions
• Pros: Best feel
• Cons: More complex collision

Option B: Hybrid System

• Smooth movement between grid points
• Snap to grid for actions
• Pros: Simpler collision
• Cons: Less freedom

Option C: Enhanced Grid Movement

• Keep grid movement
• Add smooth tweens
• Improve animations
• Pros: Simple, works with terrain
• Cons: Not as smooth

---

🎯 RECOMMENDED APPROACH

I recommend Option B: Hybrid System

Why:

1. ✅ Maintains grid-based farming mechanics
2. ✅ Smooth player movement
3. ✅ Simple collision detection
4. ✅ Easy to implement
5. ✅ Best of both worlds

How it works:

// Player moves smoothly in pixels
update() {
    this.sprite.x += this.velocity.x * delta;
    this.sprite.y += this.velocity.y * delta;
}

// Convert to grid for interactions
interact() {
    const gridX = Math.floor(this.sprite.x / TILE_SIZE);
    const gridY = Math.floor(this.sprite.y / TILE_SIZE);
    this.terrainSystem.interactAt(gridX, gridY);
}

---

📋 IMPLEMENTATION CHECKLIST

Step 1: Backup Current Code ✅

• File already in git

Step 2: Refactor Movement System

• Add velocity properties
• Remove grid tweens
• Implement smooth movement
• Add acceleration

Step 3: Add Sprint

• Shift key detection
• Speed multiplier
• Energy system (optional)
• Visual feedback

Step 4: Polish Animations

• Idle animations
• Sprint animation speed
• Smooth transitions
• Direction detection

Step 5: Enhance Input

• Diagonal movement
• Input normalization
• Gamepad deadzone
• Input buffering

Step 6: Testing

• Test all directions
• Test sprint
• Test gamepad
• Test farming (grid snapping)
• Performance check

---

🚀 READY TO IMPLEMENT?

Next Steps:

1. Confirm approach (Hybrid System recommended)
2. Start implementation
3. Test incrementally
4. Polish and refine

Estimated Time: 2-3 hours

Shall we begin? 🎮✨

---

Waiting for confirmation to proceed...