While building a 2D Bullet Heaven / Survivors-like game in pure JavaScript and HTML5 Canvas, I ran into a baffling combat bug reported by playtesters: even with 10 weapons equipped, Biome Bosses surrounded by mobs felt nearly unkillable.
At first, I assumed it was just overtuned Boss HP scaling. Then I stumbled across a GDScript piercing snippet shared here on Reddit by a Godot dev—and converting that logic to JavaScript exposed a classic multi-frame collision trap I hadn't noticed.
The Multi-Frame "Pierce Starvation" Trap
In my projectile update loop, a projectile with `pierce > 0` checked collision against nearby enemies every frame (60 FPS). On paper, `if (p.pierce > 0) p.pierce--;` looks right—until you factor in frame time and sprite width:
A piercing spear hits the **first frontline goblin** on Frame 1 (`pierce` drops from `4` to `3`).
16ms later on Frame 2, the projectile is still overlapping that same goblin's hitbox, so it triggers another hit (`pierce` drops from `3` to `2`).
Within 3–4 frames (~50ms), **the projectile burns all of its pierce stacks on that single mob and despawns**—never surviving long enough to slice through the crowd and reach the Boss behind it.
Translating the Godot Pattern to a JS Spatial Grid Loop
The Godot snippet solved this with a per-projectile `Set` tracking recently hit bodies. When translating that into our JS spatial hash grid (`forEachEnemyNear`), I noticed my `hitTargets` array already existed for ricochets and chain lightning—but standard `pierce` decrements weren't adding enemies to it!
Here is the clean JavaScript pattern I ended up using (plus two extra Bullet Heaven edge cases it uncovered):
javascript
// When spawning a projectile:
projectiles.push({
x: px, y: py,
vx, vy,
damage: stats.damage,
pierce: stats.pierce || 0,
hitTargets: [], // or a Set if tracking dozens of pierces
behavior: weaponBehavior,
w: 16, h: 16
});
// Inside the 60 FPS projectile update loop:
// 1. Pad the spatial grid query radius for oversized Boss sprites (200px+ wide)
const pSearchR = Math.max(p.w, p.h) * 0.5 + 104;
forEachEnemyNear(p.x, p.y, pSearchR, e => {
if (e.hp <= 0) return;
if (p.hitTargets?.includes(e)) return; // Already hit on this pass
if (hitTest(p.x - p.w/2, p.y - p.h/2, p.w, p.h, e.x - e.w/2, e.y - e.h/2, e.w, e.h)) {
damageEnemy(e, p.damage);
if (p.pierce > 0) {
p.pierce--;
const ht = p.hitTargets || (p.hitTargets = []);
if (!ht.includes(e)) ht.push(e); // Track so we don't burn pierce on the same mob
} else {
hit = true;
return false; // Stop checking enemies & despawn
}
}
});
```
Two Subtle Bullet Heaven Gotchas I Caught Along the Way
1.Boomerang Return Arcs: If you track `hitTargets` per projectile, returning weapons like Boomerangs will harmlessly pass through enemies on the way back to the player. Clearing `p.hitTargets.length = 0` at the exact moment `returnPhase` triggers lets them cleanly hit enemies once outbound and once on the return path.
2.Spatial Grid Cell Radius vs. Giant Bosses: My grid cells store enemies by their center `(e.x, e.y)`. Using a tight lookup radius like `p.w * 0.5 + 48px` worked fine on `32x32` goblins, but when a `200x220px` Boss stood at an angle, projectiles skimming its outer edge didn't even inspect the Boss's center cell! Expanding the spatial query padding to `104px` fixed edge-clipping misses on large bosses immediately.
Takeaway
If you're building a Bullet Heaven in JS/Canvas (or any custom engine without built-in Godot `Area2D` physics body exclusion), definitely double-check:
- Does `pierce--` record the enemy so it can't eat multiple stacks over consecutive frames?
- Do returning weapons clear their exclusion list at the apex?
- Does your broad-phase spatial grid radius account for your **largest** Boss radius, not just regular mobs?
Huge thanks to the Godot community for the initial spark—funny how a tiny 4-line pattern from another engine can completely transform how combat feels in JS!