# blastKit.api
One-call explosions, called by a game's weapons, bombs, barrels and boss attacks.
- `at(pos, opts)` plays the explosion effect, then damages and knocks back everything within `radius` with distance falloff, through the health module handed to `use` (SecondWind or similar) and an optional `onHit` callback. Returns the hits nearest first.
- `query(pos, opts)` answers the same hits without hurting anyone.
- `use({ health, juice, effect })` hands in the health system, the juice module (juiceKit's `explosionLarge` by default) and any extra effect; `backends()` reports which are set.
# Blast Kit
An explosion in one call: area damage with falloff, knockback, kill credit and a big effect. For grenades, rockets, bombs, smart bombs, exploding barrels, mines and boss slams.
```luau
local Blast = require("blastKit.api")
-- once, in your game's setup: hand in the kits the blast uses (both optional)
Blast.use({ health = require("SecondWind.api"), juice = require("juiceKit.juice") })
-- any time
Blast.at(grenade.position, { radius = 6, damage = 80, by = thrower, team = "red", knockback = 12 })
```
## What one call does
1. Plays the effect: juiceKit's `explosionLarge` preset (or the `juice` you name, or `juice = false`), plus any `effect(pos, radius)` you handed to `use`.
2. Finds the targets in `radius`: the list or function in `targets`, or every target the health module knows (`health.all()`), minus `exclude` and anything `filter` rejects.
3. Damages each one: `damage` (a number, scaled by falloff from the centre down to `minFalloff` at the edge, or a function of target, distance and falloff) through the health module with `by`, `team`, `type = "explosion"`, `origin` and `knockback`, so kill credit, teams and knockback work.
4. Calls `onHit(target, amount, hit)` for each, which is all you need with your own health system.
It returns the hits, nearest first: `{ target, amount, distance, falloff, direction }`.
## Options
`radius` (5), `damage` (60), `falloff` (true), `minFalloff` (0.2), `flat` (ignore height, for top-down games), `targets`, `filter`, `exclude`, `by`, `team`, `type`, `label`, `knockback` (10), `onHit`, `apply` (false = effects only), `effects` (false = no effect), `juice` (preset name or false), `health` and `juiceModule` (per call).
## Also
- `Blast.query(pos, opts)`: who would be hit and for how much, hurting nobody (AI, previews, tests).
- `Blast.use({ health, juice, effect })`, `Blast.backends()`.
## Multiplayer
Damage once, show everywhere: send the blast's position to every peer and call `Blast.at(pos, { ..., apply = isHost })`, so every player sees the explosion and the host deals the damage. SecondWind then syncs health to everyone.
The test suite `blastKit` checks radius, falloff, filters, damage functions, the health and juice routes and effects-only mode.