Inside BeeLadybug: Visual Logic & Collision Debugging (CodePen Challenge)

🐞 BeeLadybug (v2.4.0) — Visual Debugging & System Monitoring

Following up on my previous post about BeeLadybug, I wanted to map out its internal architecture for this week's CodePen Challenge using a clean Mermaid flowchart!

BeeLadybug serves as the primary visual inspector for BeeEngine JS. It lives isolated in src/debug/ and executes its render pass immediately after the game world, overlaying AABB/OBB hitboxes in camera space and system metrics in screen space.

⌨️ Input Architecture & Control

• F12 Avoidance: Left untouched to preserve standard browser DevTools workflows.
• Tilde Key (~) Alternative: Avoided due to non-standard layouts on non-US keyboards (such as Italian layouts).
• F2 Toggle: Selected as the clean, standard toggle key for desktop and indie game engine debug panels.

📊 Screen Overlay Features

• AABB & OBB Hitbox Tracking: Traverses active scene entities, groups, and child nodes. If an entity contains a BeeTransform, BeeLadybug calculates and draws oriented bounding boxes (OBB) in real-time.
  • 🟢 Green: Active entity, no collision detected.
  • 🔴 Red: Overlapping/colliding with another bounding box.
  • ⚪ Gray: Disabled or inactive entity.
• Engine Metrics: Displays current frame rate (BeeTime.fps), active entity count vs. total allocation, frame execution time (unscaledDt in ms), timeScale, and simulation state (RUN/FREEZE).

🕹️ Quick Controls

💡 Technical Note: The GUI buttons on the screen overlay trigger the exact same methods as physical keyboard shortcuts. Freezing the loop stops delta time (dt) calculations while maintaining the render loop, allowing pixel-perfect inspection of overlapping hitboxes.

🛠️ Quick Implementation

const game = new BeeEngine('gameCanvas', 800, 600); 
game.enableLadybug(); // Enabled on boot; press F2 to hide 
game.start();

📐 Logical Collision & Debug Flowchart

Here is the exact decision workflow executed when BeeLadybug inspects entity bounds during high-throughput canvas operations:

flowchart TD
    A[🐞 BeeLadybug Detects Bug] --> B{Is SpatialHash Enabled?}
    B -- Yes --> C[🎯 Locate Colliding Entity ID]
    B -- No --> D[⚠️ Fallback: Full Canvas Scan]
    C --> E[📊 Log to BeeLadybug Console]
    D --> E
    E --> F[🔧 Apply Fix & Resume 60 FPS]

    %% Custom Cyberpunk Styling %%
    classDef bugStyle fill:#ff4757,stroke:#ff6b81,stroke-width:2px,color:#fff;
    classDef hashStyle fill:#2ed573,stroke:#2bcbba,stroke-width:2px,color:#fff;
    classDef warnStyle fill:#ffa502,stroke:#ff7f50,stroke-width:2px,color:#000;
    classDef fixStyle fill:#1e90ff,stroke:#70a1ff,stroke-width:2px,color:#fff;

    class A bugStyle;
    class C hashStyle;
    class D warnStyle;
    class F fixStyle;