range
The one interface a game uses: `local Range = require("rangeKit.range")`. It registers range sources (an aura, a coverage area, a supply range) in channels, answers deterministic queries about them (strength at a point combined by the channel's stack rule, the sources reaching a…
range (rangeKit)
The one interface a game uses: local Range = require("rangeKit.range"). It registers range sources (an aura, a coverage area, a supply range) in channels, answers deterministic queries about them (strength at a point combined by the channel's stack rule, the sources reaching a point strongest first, one source's cover, grid cells in range), defines custom shapes, falloffs, looks and channels, and draws local placement previews and channel or source overlays in eight looks through the rangeOverlay shader. Game code, the RangeSource component and UIs call it; see the package README for every call.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2nonstrict
readPos(p: any) → void
helpers
| arg | type | description |
|---|---|---|
| p | any |
mkPos(x: number, y: number, z: number) → any
| arg | type | description |
|---|---|---|
| x | number | |
| y | number | |
| z | number |
clamp01(v: number) → number
| arg | type | description |
|---|---|---|
| v | number |
copy(t: any) → any
| arg | type | description |
|---|---|---|
| t | any |
hexToLinear(s: string) → void
| arg | type | description |
|---|---|---|
| s | string |
lin(c: number) → number
| arg | type | description |
|---|---|---|
| c | number |
readColor(c: any) → void
colour: "#rrggbb" (sRGB), { r, g, b } / { r = , g = , b = } (linear), or nil
| arg | type | description |
|---|---|---|
| c | any |
W(spec: any) → number return spec
| arg | type | description |
|---|---|---|
| spec | any |
L(spec: any) → number return spec
| arg | type | description |
|---|---|---|
| spec | any |
addShape(name: string, def: any) → void
| arg | type | description |
|---|---|---|
| name | string | |
| def | any |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
pathDistance(x: number, z: number, path: { any }) → number
distance from (x, z) to a path of local points { {x, z}, ... }
| arg | type | description |
|---|---|---|
| x | number | |
| z | number | |
| path | { any } |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
fn(x: ?, z: ?, s: ?) → void
| arg | type | description |
|---|---|---|
| x | ? | |
| z | ? | |
| s | ? |
size(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
extent(s: ?) → void
| arg | type | description |
|---|---|---|
| s | ? |
defineShape(name: string, fn: (number, number, any) → void
Define a custom shape. `fn(localX, localZ, spec) -> normalisedDistance|nil`. opts.sdf names the built-in shape the overlay draws it with (default "circle"); opts.extent(spec) the farthest point (default radius); opts.size(spec) the reference size `inner` is measured against (default radius); opts.tags for UIs.
| arg | type | description |
|---|---|---|
| name | string | |
| fn | (number, number, any |
shapes( ) → void
addFalloff(name: string, def: any) → void
| arg | type | description |
|---|---|---|
| name | string | |
| def | any |
defineFalloff(name: string, fn: (number) → void
Define a custom falloff: fn(t) -> 0..1 where t is 0 at the centre (or inner edge) and 1 at the outer edge. opts.shader names the built-in falloff the overlay draws it with.
| arg | type | description |
|---|---|---|
| name | string | |
| fn | (number |
falloffs( ) → void
falloffAt(name: string, t: number) → number
falloff value at normalised distance t (for UIs and graphs)
| arg | type | description |
|---|---|---|
| name | string | |
| t | number |
addLook(name: string, def: any) → void
| arg | type | description |
|---|---|---|
| name | string | |
| def | any |
defineLook(name: string, spec: any) → void
Define a look. spec = { material = <material identity or AssetRef>, color = {r,g,b} | "#hex", tags = {...}, cellSize = number? }. The material's shader reads the same four lanes rangeOverlay reads (see rangeOverlay.shader/shader.wgsl), so a look can be a new rangeOverlay material (another `look` id, other blend) or a shader of your own.
| arg | type | description |
|---|---|---|
| name | string | |
| spec | any |
looks( ) → void
setLook(look: string) → void
| arg | type | description |
|---|---|---|
| look | string |
getLook( ) → string
defineChannel(name: string, opts: any?) → void
stack: how overlapping sources combine at a point. sum add every source's cover max the highest cover at that point strongest the cover of the source with the highest base strength (ties: lowest id) diminishing strongest cover + half the next + a quarter the next ... (opts.ratio, default 0.5) count how many sources reach the point cap clamps the combined value; color / look are the channel's overlay defaults.
| arg | type | description |
|---|---|---|
| name | string | |
| opts | any? |
getChannel(name: string) → any
| arg | type | description |
|---|---|---|
| name | string |
channels( ) → void
sortedIds( ) → void
sources
emit(kind: string, id: string, src: any) → void
| arg | type | description |
|---|---|---|
| kind | string | |
| id | string | |
| src | any |
normalize(spec: any, base: any?) → any
resolve a spec into the numbers the queries and the shader use
| arg | type | description |
|---|---|---|
| spec | any | |
| base | any? |
publicView(s: any) → any
| arg | type | description |
|---|---|---|
| s | any |
addSource(spec: any) → string
| arg | type | description |
|---|---|---|
| spec | any |
updateSource(id: string, patch: any) → void
| arg | type | description |
|---|---|---|
| id | string | |
| patch | any |
removeSource(id: string, token: any?) → boolean
`token` (optional): remove only if the source was registered with that token, so a component being replaced (a hot reload, a scene rebuild) cannot remove the source its replacement already registered under the same id.
| arg | type | description |
|---|---|---|
| id | string | |
| token | any? |
getSource(id: string) → any
| arg | type | description |
|---|---|---|
| id | string |
sources(channel: string?) → void
| arg | type | description |
|---|---|---|
| channel | string? |
clear(channel: string?) → void
| arg | type | description |
|---|---|---|
| channel | string? |
onChanged(fn: (string, string, any) → void
| arg | type | description |
|---|---|---|
| fn | (string, string, any |
toLocal(s: any, px: number, pz: number) → void
queries the shape's local frame: +z forward along the facing yaw, +x to the right
| arg | type | description |
|---|---|---|
| s | any | |
| px | number | |
| pz | number |
evalT(s: any, px: number, pz: number) → number
normalised distance after the inner hole, or nil when outside
| arg | type | description |
|---|---|---|
| s | any | |
| px | number | |
| pz | number |
coverOf(s: any, px: number, pz: number) → number
| arg | type | description |
|---|---|---|
| s | any | |
| px | number | |
| pz | number |
cover(id: string, position: any) → number
| arg | type | description |
|---|---|---|
| id | string | |
| position | any |
inRange(id: string, position: any) → boolean
| arg | type | description |
|---|---|---|
| id | string | |
| position | any |
sourcesAt(channel: string, position: any) → void
every source of `channel` that reaches `position`, strongest first (ties by id)
| arg | type | description |
|---|---|---|
| channel | string | |
| position | any |
combine(ch: any, hits: { any }) → number
| arg | type | description |
|---|---|---|
| ch | any | |
| hits | { any } |
strengthAt(channel: string, position: any) → number
| arg | type | description |
|---|---|---|
| channel | string | |
| position | any |
cellsInRange(id: string, cellSize: number, origin: any?) → void
Grid cells a source reaches. Cell (x, z) covers [origin + x*size, origin + (x+1)*size) on each axis and is tested at its centre. Sorted by z then x.
| arg | type | description |
|---|---|---|
| id | string | |
| cellSize | number | |
| origin | any? |
extent(id: string) → number
farthest reach of a source from its position (for broad-phase checks)
| arg | type | description |
|---|---|---|
| id | string |
lookMaterial(lookName: string) → any
| arg | type | description |
|---|---|---|
| lookName | string |
entityAlive(e: any) → boolean
| arg | type | description |
|---|---|---|
| e | any |
despawnOverlay(ov: any) → void
| arg | type | description |
|---|---|---|
| ov | any |
drawRoad(ov: any, s: any, lookName: string, colorIn: any, chColor: any) → void
a road draws as one rounded leg per stretch of its path; each joint is capped once
| arg | type | description |
|---|---|---|
| ov | any | |
| s | any | |
| lookName | string | |
| colorIn | any | |
| chColor | any |
world(q: any) → void
| arg | type | description |
|---|---|---|
| q | any |
drawOverlay(ov: any, s: any, lookName: string, colorIn: any, chColor: any) → void
| arg | type | description |
|---|---|---|
| ov | any | |
| s | any | |
| lookName | string | |
| colorIn | any | |
| chColor | any |
sourceOverlayWanted(id: string) → void
which look and colour a registered source's overlay uses, or nil when none is wanted
| arg | type | description |
|---|---|---|
| id | string |
_refreshSource(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
_refreshChannel(channel: string) → void
| arg | type | description |
|---|---|---|
| channel | string |
_refreshAll( ) → void
showChannel(channel: string, look: string?) → void
draw every source of a channel (and keep drawing it as sources come and go)
| arg | type | description |
|---|---|---|
| channel | string | |
| look | string? |
hideChannel(channel: string) → void
| arg | type | description |
|---|---|---|
| channel | string |
showSource(id: string, look: string?) → void
| arg | type | description |
|---|---|---|
| id | string | |
| look | string? |
hideSource(id: string) → void
| arg | type | description |
|---|---|---|
| id | string |
overlayEntity(id: string) → any
overlay entity drawing a source (for tests / tooling); nil when not shown
| arg | type | description |
|---|---|---|
| id | string |
preview(spec: any) → any
A local placement preview: shows the area a building would cover before it exists. spec = { position, shape, radius, inner, width, length, angle, facing, falloff, strength, look = "rings", color?, opacity? }
| arg | type | description |
|---|---|---|
| spec | any |
move(position: any, facingDeg: number?) → void
| arg | type | description |
|---|---|---|
| position | any | |
| facingDeg | number? |
set(patch: any) → void
| arg | type | description |
|---|---|---|
| patch | any |
cover(position: any) → number
| arg | type | description |
|---|---|---|
| position | any |
entity( ) → any
destroy( ) → void
hideAll( ) → void
remove every overlay this machine draws (sources stay registered)
sweep( ) → void
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.