Log inGet started
Package

rangeKit.package

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

PartWhat it is
range module (rangeKit.range)The whole API: sources, channels, queries, shapes, falloffs, looks, previews and overlays.
RangeSource componentMakes its entity a range source on every machine; follows moves, turns and property changes; optional local overlay.
rangeOverlay shaderOne WGSL surface shader that evaluates the shape's signed distance and the falloff per pixel on a flat quad, in eight looks.
range_<look> materialsOne material per look: range_heatTiles, range_rings, range_chalk, range_glow (additive), range_pixel, range_hologram, range_runes, range_wash.
RangeDemoMover componentMoves an entity round a circle; the showcase uses it for the moving source.
rangeKitTests test suiteEvery shape, falloff and stack rule, cells, ordering, determinism, ownership, events, custom shapes, previews.
GuidesHow 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.