Worm Commander Autopilot - Logical Overview

High-Level Flow

flowchart TD
    subgraph TRIGGER ["⏱️ Trigger (every frame)"]
        A[Game Loop] --> B{Autopilot<br/>Active?}
        B -->|No| Z[Skip]
        B -->|Yes| C{Time to<br/>Decide?}
        C -->|No| Z
        C -->|Yes| D[Proceed]
    end

    subgraph PERCEIVE ["👁️ Perceive"]
        D --> E[Gather Senses]
        E --> E1[Where am I?<br/>heading, position, length]
        E --> E2[Where is food?<br/>distance + bearing to each pellet]
        E --> E3[Where are threats?<br/>distance + bearing to each snake]
    end

    subgraph DECIDE ["🧠 Decide"]
        E1 & E2 & E3 --> F{What is<br/>my intent?}
        
        F -->|eat| G1[Target: nearest food]
        F -->|hunt| G2[Target: nearest snake]
        F -->|avoid| G3[Target: away from snake]
        F -->|survive| G4[Target: none]
        
        G1 & G2 & G3 & G4 --> H[Generate Turn Options]
        H --> I[Score Each Option]
        
        I --> I1[+ Alignment to target]
        I --> I2[+ Clearance runway]
        I --> I3[− Collision risk]
        I --> I4[− Turn magnitude]
        
        I1 & I2 & I3 & I4 --> J[Select Best Safe Option]
    end

    subgraph ACT ["🎮 Act"]
        J --> K[Apply Turn]
        K --> L[Update Heading]
        L --> M[Continue to next frame]
    end

    Z --> M

Decision Cadence

flowchart LR
    subgraph Normal ["Normal Mode"]
        N1[Check clearance ahead] --> N2{Clear > 420px?}
        N2 -->|Yes| N3[Decide every 200ms<br/>3 turn options: -30°, 0°, +30°]
    end
    
    subgraph Danger ["Danger Mode"]
        N2 -->|No| D1[Decide every 80ms<br/>7 turn options: -90° to +90°]
    end

Scoring Logic

flowchart TD
    subgraph Inputs
        T[Target Bearing]
        C[Clearance for this heading]
        D[Turn Amount]
    end
    
    T --> S1["Pursuit Score<br/>How much does this turn<br/>reduce bearing to target?"]
    C --> S2["Safety Score<br/>How much runway<br/>before collision?"]
    C --> S3["Risk Penalty<br/>Is collision imminent?"]
    D --> S4["Stability Penalty<br/>Prefer smaller turns"]
    
    S1 & S2 --> ADD[Add to Score]
    S3 & S4 --> SUB[Subtract from Score]
    
    ADD & SUB --> FINAL[Final Score]
    FINAL --> SELECT[Highest score wins]

Intent → Behavior Mapping

flowchart LR
    subgraph Intents
        I1[eat]
        I2[hunt]
        I3[avoid]
        I4[survive]
    end
    
    subgraph Targets
        I1 --> T1[🍎 Nearest pellet]
        I2 --> T2[🐍 Nearest snake head]
        I3 --> T3[🏃 Opposite of nearest snake]
        I4 --> T4[➡️ No target, go straight]
    end
    
    subgraph Priority
        T1 --> P1[Food first, avoid obstacles]
        T2 --> P2[Chase aggressively]
        T3 --> P3[Maximize distance from threat]
        T4 --> P4[Maximize clearance]
    end

Safety Zones

flowchart LR
    subgraph Clearance ["Distance to Nearest Obstacle"]
        direction TB
        Z1["🟢 SAFE<br/>> 520px<br/>No penalty"]
        Z2["🟡 CAUTION<br/>160-520px<br/>Light penalty"]
        Z3["🔴 DANGER<br/>< 160px<br/>Heavy penalty"]
    end
    
    Z1 --> A1[Pursue target freely]
    Z2 --> A2[Prefer more runway]
    Z3 --> A3[Safety overrides target]

Summary

The autopilot is fundamentally a reactive steering controller that:

1. Builds a local snapshot of the world (not a map, just nearby objects)
2. Scores candidate headings based on intent + safety
3. Picks the best option and applies it immediately
4. Repeats 5-12 times per second