Within Reach: Area of Effect and Building Range Kit
- ..
- .metadata128 B
- README.md7.6 KB
- RangeDemoMover.component
- RangeSource.component
- how-to-make-buildings-that-help-everything-within-range.guide
- package.yaml743 B
- range.module
- rangeKitTests.testSuite
- rangeOverlay.shader
- range_chalk.material
- range_glow.material
- range_heatTiles.material
- range_hologram.material
- range_pixel.material
- range_rings.material
- range_runes.material
- range_wash.material
- tower-defense-support-tower-and-survival-campfire-with-rangekit.guide
README.md
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:
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 isadded,updatedorremoved.
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? })
sumadds every cover ·maxtakes the highest ·strongesttakes the cover of the source with the highest base strength ·diminishingadds the best, thenratio(0.5) of the next, then a quarter… ·countcounts sources in range.capclamps 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? }) -> handlewithhandle: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.