# rangeKit: area of effect, aura, coverage and supply range
Buildings and things that help everything within range: a tower that buffs nearby units, a campfire that warms survivors, a well that waters fields, a market that serves houses, a temple that makes the neighbourhood happier, a turret's firing cone. rangeKit gives every such thing a **range source**, answers "how strongly is this point covered, and by whom" with deterministic queries that agree on every machine, and draws the area as a **placement preview** or a **coverage overlay** in eight looks.
Install it and:
```lua
local Range = require("rangeKit.range")
Range.defineChannel("town.water", { stack = "max" })
Range.defineChannel("town.beauty", { stack = "sum", cap = 1 })
local well = Range.addSource({ channel = "town.water", position = { 10, 0, 4 }, radius = 8, falloff = "smooth" })
print(Range.strengthAt("town.water", { 12, 0, 5 })) -- 0..1, the same number on every machine
-- while the player is placing a building
local ghost = Range.preview({ position = cursor, shape = "circle", radius = 8, look = "rings" })
ghost:move(newCursor, facingDeg) ; ghost:destroy()
-- show every water source while the water tool is open
Range.showChannel("town.water", "heatTiles")
```
Or, with no code: add the **RangeSource** component to any entity. On a synced entity (`entity.spawnSynced`) the source is multiplayer for free: every player and every late joiner registers the same source from the entity's position and yaw, so coverage agrees everywhere.
## What is in the package
| Part | What it is |
|---|---|
| `range` module (`rangeKit.range`) | The whole API: sources, channels, queries, shapes, falloffs, looks, previews and overlays. |
| `RangeSource` component | Makes its entity a range source on every machine; follows moves, turns and property changes; optional local overlay. |
| `rangeOverlay` shader | One WGSL surface shader that evaluates the shape's signed distance and the falloff per pixel on a flat quad, in eight looks. |
| `range_<look>` materials | One material per look: `range_heatTiles`, `range_rings`, `range_chalk`, `range_glow` (additive), `range_pixel`, `range_hologram`, `range_runes`, `range_wash`. |
| `RangeDemoMover` component | Moves an entity round a circle; the showcase uses it for the moving source. |
| `rangeKitTests` test suite | Every shape, falloff and stack rule, cells, ordering, determinism, ownership, events, custom shapes, previews. |
| Guides | *How to make buildings that help everything within range (area of effect, aura, coverage)* and *Tower defense support tower and survival campfire with rangeKit*. |
The world this package lives in boots into `scenes.rangeShowcase`: a walkable gallery of all eight looks (each circle half on grass, half on cobbles), every shape × falloff as heat tiles, a moving patrol tower whose cone and aura follow it, stacking campfires and supply-range wells.
## API
**Sources**
- `Range.addSource(spec) -> id`: spec `{ id?, channel = "default", position = vec3 | {x,y,z} | {x=,y=,z=}, shape = "circle", radius = 6, inner = 0, width?, length?, angle = 90 (cone spread, degrees), facing = 0 (yaw degrees, entity convention: 0 = -Z), falloff = "none", strength = 1, owner?, tags?, entity?, token? }`. Re-adding an existing id replaces it.
- `Range.updateSource(id, patch)`, `Range.removeSource(id, token?) -> bool`, `Range.getSource(id)`, `Range.sources(channel?)`, `Range.clear(channel?)`, `Range.extent(id)`.
- `Range.onChanged(fn(kind, id, source)) -> disconnect`: kind is `added`, `updated` or `removed`.
**Queries** (pure and deterministic; sources are visited in id order)
- `Range.strengthAt(channel, position) -> number`: overlapping sources combined by the channel's stack rule.
- `Range.sourcesAt(channel, position) -> { {id, strength, source} }`: strongest first.
- `Range.cover(id, position) -> number`: 0 outside, else strength × falloff.
- `Range.inRange(id, position) -> boolean`.
- `Range.cellsInRange(id, cellSize, origin?) -> { {x, z, strength} }`: cell (x, z) spans `[origin + x·size, origin + (x+1)·size)`, tested at its centre, sorted by z then x.
**Channels**: `Range.defineChannel(name, { stack = "sum" | "max" | "diminishing" | "count" | "strongest", cap?, color?, look?, ratio? })`
- `sum` adds every cover · `max` takes the highest · `strongest` takes the cover of the source with the highest base strength · `diminishing` adds the best, then `ratio` (0.5) of the next, then a quarter… · `count` counts sources in range. `cap` clamps the result.
**Shapes**: `circle`, `square` (Chebyshev), `diamond` (Manhattan), `ring` (inner..radius, inner defaults to 60%), `cone` (facing + angle), `rectangle` (width × length centred, along facing), `line` (width × length starting at the source, along facing), `hex` (points on the forward axis). `road` (everything within `radius` of a `path`: a list of points `{ {x, z}, ... }` relative to the source and turned with its facing, so a market stall can serve a whole street, a supply line a convoy route, a lamp row a lane; the falloff runs out from the road's centre line and the overlay draws each stretch). `inner` cuts a hole in any shape. `Range.defineShape(name, fn(localX, localZ, spec) -> t|nil, { sdf = "<built-in shape the overlay draws it as>", extent?, size?, tags? })`. `Range.shapes()` lists them with tags.
**Falloffs**: `none`, `linear`, `smooth` (smoothstep), `inverseSquare`, `steps` (four bands), `exponential`. `Range.defineFalloff(name, fn(t) -> 0..1, { shader = "<built-in falloff the overlay draws it as>" })`, `Range.falloffAt(name, t)`, `Range.falloffs()`.
**Overlays** (local to the machine that asks; never synced, never saved; no colliders, so they never block raycasts or clicks)
- `Range.preview({ position, shape, radius, inner, width, length, angle, facing, falloff, strength, look = "rings", color?, opacity?, cellSize? }) -> handle` with `handle:move(position, facingDeg?)`, `handle:set(patch)`, `handle:cover(position)`, `handle:entity()`, `handle:destroy()`.
- `Range.showChannel(channel, look?)` / `Range.hideChannel(channel)`, `Range.showSource(id, look?)` / `Range.hideSource(id)`, `Range.setLook(look)` / `Range.getLook()`, `Range.hideAll()`.
- Looks: `heatTiles` (grid cells green → yellow → red by strength, or the channel colour), `rings` (clean concentric rings with a pulse), `chalk` (rough hand-drawn white chalk), `glow` (soft additive glow following the falloff), `pixel` (stepped pixel-art outline and dithered fill), `hologram` (cyan grid, radar sweep, scan band, bright edge), `runes` (rotating ring of gold glyphs over a violet field), `wash` (watercolour wash with an irregular, pigment-dark edge). `Range.defineLook(name, { material, color?, tags?, cellSize? })` adds one; `Range.looks()` lists them with tags. Colours take `"#rrggbb"` or linear `{r, g, b}`.
## RangeSource fields
`channel`, `shape`, `radius`, `inner`, `width`, `length`, `angle`, `falloff`, `strength` (replicated), and `look`, `showOverlay`, `color`, `cellSize`, `sourceId` (local). The source id defaults to `ent:<entity id>`. Methods: `:cover(position)`, `:id()`.
## Notes
- Positions and facing use the engine's conventions: Y up, yaw in degrees as in `rotation.eulerAngles.y`, 0 facing -Z.
- The registry lives in `modules.state()`, so hot reloads keep every source; a component replaced by a scene rebuild re-registers itself.
- Overlay lanes (for a custom look shader): lane0 = centre x, centre z, facing (rad), radius; lane1 = inner, width, length, half angle (rad); lane2 = colour rgb, opacity; lane3 = shape id, falloff id, flags (1 = colour given), cell size.