Bullet Hell Patterns: Spirals, Rings and Spreads Kit
README.md
Bullet Hell Patterns: Spirals, Rings and Spreads Kit (bulletPatternsKit)
Give your enemies, bosses and turrets real bullet hell attacks in one line. bulletPatternsKit ships twelve classic danmaku patterns (spirals, rings, spread fans, walls with a dodge gap, flowers, sine waves, shotguns, crosses, staggered burst rings, sunbursts...), fires them as pooled, glowing projectiles, hit-tests them against every target you hand it (all players, not just one), and keeps every player in a multiplayer game seeing the same volley.
- 12 patterns, each a pure deterministic function with a catalog entry (title, description,
tags such as
easy,dodge-gap,boss, and defaults). - One-line volleys:
BP.fire("spiral", { from = boss, t = time }). - Emitters that keep firing, rotating each volley, for a set number of volleys or forever.
- Emitter component: drop it on any entity for a no-code turret a designer tunes in the inspector.
- Hits on many targets, with per-target radii, pierce (passes through N targets, never the same one twice) and homing (turns toward the nearest target at N deg/s).
- Multiplayer:
BP.fireSyncedsends a few numbers; every peer fires the identical volley and hit-tests only the players it owns, so the victim's peer decides the damage. - 5 enemy bullet looks: magenta orb, orange orb, cyan needle, lime orb, violet crystal.
- Smooth with hundreds of bullets: shots are plain data stepped in one loop and drawn from reused entity pools (projectileKit). 600 live shots step in a fraction of a frame (tested).
Install
zeromind_install guid=10c84280-f3da-4105-a7bf-8a350ec49a5c
or in the engine: zero zeromind installAsset --guid 10c84280-f3da-4105-a7bf-8a350ec49a5c.
It brings projectileKit 1.1.0 (pooled projectiles) with it.
Quick start
local BP = require("bulletPatternsKit.api")
-- every peer: what a hit does, and which targets this peer may hit
BP.onHit("playerDamage", function(target, info)
print("hit", target.id, "by", info.pattern, "at", info.pos.x, info.pos.z)
end)
-- one volley: a ring of 20 orange orbs from the boss
BP.fire("ring", { from = boss, count = 20, speed = 7, look = "bpOrbOrange", hit = "playerDamage" })
-- aimed spread at the player
BP.fire("spread", { from = boss, aimAt = player, count = 7, arc = math.rad(70), hit = "playerDamage" })
-- a rotating spiral that fires 10 times a second until stopped
local h = BP.emitter({ pattern = "spiral", from = boss, every = 0.1, rotate = 0.08, count = 4,
look = "bpNeedleCyan", hit = "playerDamage" })
h:stop()
By default bullets hit-test the target set "localPlayers" (this client's own player). Pass
targets = function() return { ... } end or register your own set with BP.setTargets.
Multiplayer
The peer that owns the enemy (usually the host) calls BP.fireSynced(pattern, opts) or
BP.emitterSynced(spec). It sends { pattern, origin, angle, seed, t, numeric opts, hit-handler name, target-set name, look, data } with multiplayer.send on the channel
bulletPatternsKit.fire, and fires it locally; every other peer fires the same volley from the
same numbers. Each peer hit-tests its own target set, so register on every peer:
BP.setTargets("localPlayers", function() return { myPlayerBody } end)
BP.onHit("playerDamage", function(target, info) Health.damage(target, 1) end)
Functions are never sent. data (a small table of strings and numbers) travels with the volley
and reaches handlers as info.data, e.g. { owner = shooterId } so only the right peer applies
damage.
What's inside
bulletPatternsKit.api: the API (fire, fireSynced, emitter, emitterSynced, onHit, setTargets, catalog, names, shots, stats, clear, step, looks...). See its README.bulletPatternsKit.patterns: the pure maths, usable on its own (previews, AI, tests).Emittercomponent: a no-code pattern emitter for any entity.Runnercomponent: spawned automatically; ticks emitters and delayed shots.- Guides: "How to add bullet hell patterns (spirals, rings, spreads) to enemies" and "Bullet pattern reference".
bulletPatternsKittest suite: 15 tests.
The patterns
aimed, spread, ring, spiral, doubleSpiral, flower, wave, shotgun, cross, wall, burstRing,
sunburst. BP.catalog() lists each with its options and defaults; the reference guide shows them all.
Version
1.0.0. Needs projectileKit 1.1.0 (adds the hitTest shot callback and PK.kill this kit uses).