# bulletPatternsKit.api
The public API of bulletPatternsKit: fires bullet hell patterns through projectileKit, hit-tests
them against any set of targets (with pierce, homing and per-target radii), runs emitters, and
syncs volleys across peers. Gameplay code (enemies, bosses, turrets, the player's own weapons)
calls it: `local BP = require("bulletPatternsKit.api")`.
## Fields
- `VERSION`: `"1.0.0"` (matches package.yaml).
- `CHANNEL`: `"bulletPatternsKit.fire"`, the multiplayer channel synced volleys use.
- `LOOKS`, `DEFAULT_LOOK` (`"bpOrbMagenta"`), `patterns` (the pure maths module).
## Firing
- `fire(pattern, opts) -> number`: one volley here only; returns the shot count (delayed ones included).
- `fireSynced(pattern, opts) -> number`: one volley on every peer (sender included).
- `encodeVolley(pattern, opts) -> event`, `fireEvent(event, source?) -> number`: the synced event by hand.
- `shots(pattern, opts)`, `catalog()`, `names()`: the pure pattern data.
opts:
- `from`: `{x,y,z}`, `{1,2,3}`, vector, entity or id (entity origins get `height`, default 1 m).
- `angle` (radians in XZ, 0 = +X, pi/2 = +Z) or `aimAt` (position or entity).
- `count`, `arc`, `speed`, plus any pattern option (see the reference guide).
- `look` (projectileKit look; default `bpOrbMagenta`), `size`, `range` (m, 40), `draw`, `impact`.
- `radius` (shot hit radius, 0.22), `targetRadius` (default target radius, 0.5).
- `seed`, `t`: the deterministic inputs (spirals turn with `t`, shotguns and wall gaps use `seed`).
- `hit`: name of a handler registered with `onHit`; `onHit`: a function (local fire only).
- `targets`: function returning entities, ids or `{ entity = e, radius = r }`; or `targetSet`: a
registered name (default `"localPlayers"`).
- `pierce` (extra targets passed through, 0), `homing` (deg/s, 0), `homeOn` (set name or function the
homing steers toward; default the hit targets).
- `logic = false`: drawn only, never hits. `data`: small table of strings/numbers, reaches handlers.
## Hits and targets
- `onHit(name, fn(targetEntity, info))`: register on every peer. info = `{ pattern, pos = {x,y,z},
angle, speed, data, shotId, volley, synced, source, pierceLeft }`.
- `setTargets(name, fn)`, `targetsOf(name)`: named target sets; `"localPlayers"` defaults to this
client's player body.
- `position(v)`: `{x,y,z}` of any position-like value.
## Emitters
- `emitter(spec) -> handle`: spec = `{ pattern, from, aim?, every, volleys?, rotate, delay, synced, ...fire opts }`.
`handle:stop()`, `handle.alive`, `handle.fired`.
- `emitterSynced(spec)`: every volley via `fireSynced`; run on the authority only.
- `step(dt, alsoProjectiles?)`: the Runner calls it each frame; tests call it by hand.
## Readouts
- `stats()`: `{ shots, pending, emitters, volleys, fired, hits, syncedSent, syncedReceived }`.
- `clear()`: stop emitters, drop delayed shots, end BP shots in flight. `resetStats()`. `looks()`.
# bulletPatternsKit.Emitter
A no-code bullet hell turret. Put it on any entity (a boss, a turret prop, an empty marker) and,
while the game runs, it fires a catalog pattern from the entity every `every` seconds, turning the
aim by `rotate` radians each volley. It needs no sibling components.
```luau
entity(id).component.add("Emitter", { pattern = "spiral", every = 0.08, rotate = 0.12, look = "bpNeedleCyan" })
```
## Fields
- `pattern`: aimed, spread, ring, spiral, doubleSpiral, flower, wave, shotgun, cross, wall, burstRing, sunburst.
- `every` (s), `volleys` (0 = forever), `speed` and `count` (0 = the pattern's default), `rotate` (rad/volley).
- `angleDeg` (base aim, 0 = +X, 90 = +Z) or `aimAtPlayer` (nearest entity of `targetSet`).
- `look`, `size`, `range` (m), `height` (m above the entity's origin).
- `hit` (handler name registered with `BP.onHit`), `targetSet` (default `localPlayers`).
- `synced`: fire with `BP.fireSynced` so every peer sees the same volley; only the host runs it then.
- `active`: pause/resume.
Changing a field while it runs restarts it with the new settings.
## Methods
- `restart()`: start again from the first volley. `fired()`: volleys since it last started.
# 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.fireSynced` sends 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
```luau
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:
```luau
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).
- `Emitter` component: a no-code pattern emitter for any entity.
- `Runner` component: spawned automatically; ticks emitters and delayed shots.
- Guides: "How to add bullet hell patterns (spirals, rings, spreads) to enemies" and
"Bullet pattern reference".
- `bulletPatternsKit` test 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).