DEV Community

Antonio
Antonio

Posted on

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

#codepenchallenge #gamedev #javascript #webdev

🐞 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

Key Action Performed
F2 Toggle visual debugger panel
F3 Toggle instant slow-motion (0.25x / 1.0x)
F4 Freeze / Unfreeze simulation loop (BeeTime.pause)

💡 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();
Enter fullscreen mode Exit fullscreen mode

📐 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;

Top comments (1)

Collapse
 
raknaos profile image
Raknaos •

Isolating the inspector in src/debug/ so it doesn't touch the game world's render path is the right instinct — a debug overlay that slows the thing it's debugging is worse than none. I hit the same problem on a completely different stack: driving headless browser agents where you can't see anything, and the "debug view" ends up as an overlay of actions and state on top of the page being driven, always kept as a separate layer that can be disabled without touching the main path.

The F12-avoidance detail is thoughtful too. On my side the equivalent is never hijacking input a human might need mid-run. Small choices like that are what make debugging tools usable in production rather than just in demos.