scene

NPCs, players, objects, ground items, and reachability.

Methods
15
Fields
None

Getting one

scene

Methods

MethodReturnsDescription
tileAt(WorldPoint)Tile?What stands on one tile: the Tile of the top-level scene.
npcs()NPCQueryA query over every NPC in the scene, whose terminals hand out NPC handles.
players()PlayerQueryA query over every other player in the scene, whose terminals hand out Player handles.
objects()ObjectQueryA query over every scene object: walls, decorations, doors, resources. Every loc in the LOADED SCENE, not a window around the player. Narro…
groundItems()GroundItemQueryA query over every item on the floor, whose terminals hand out TileItem handles (item:getTile() is where one lies).
reachability()Reachability?Reachability flood from the local player: where you can GET.
reachabilityFrom(WorldPoint)Reachability?The same flood seeded somewhere other than the local player -- "could I reach that from over there", which is what a route or a safespot ch…
hazardField(HazardFieldSpec)HazardField?Expand a set of scheduled hazards over the scene: which tiles are lethal on which ticks.
timedSearch(HazardField, TimedSearchOpts?)TimedSearch?Flood against a hazard field, asking it about the tick you ARRIVE at each tile rather than the tick the flood was built.
isWalkable(WorldPoint)booleanWhether a tile can be stood on at all -- terrain only, no flood. For whether a path reaches it, use scene:reachability().
aggressionRemainingTicks()number?Ticks left before NPCs in the area lose interest.
aggressionTolerant()booleanWhether NPCs in the area have become tolerant.
aggressionCenters(){ WorldPoint }The current NPC aggression area's safe centers, oldest first: none until the client has calibrated (a teleport or a long run), then one or…
npcMayAggro(number, WorldPoint)booleanWhether an NPC can still aggro the local player: never once the area is tolerant, and otherwise the level rule (an NPC with a combat level…
cannon()Cannon?The local player's cannon, read live from the game's vars.

Method details

tileAt

tileAt: (SceneDomain, WorldPoint) -> Tile?

What stands on one tile: the Tile of the top-level scene.

The other scene reads are queries; this is the other question. nil when the tile is outside the loaded scene, which is ordinary -- a plugin walking a path runs off the edge routinely.

tile
Which tile.

objects

objects: (SceneDomain) -> ObjectQuery

A query over every scene object: walls, decorations, doors, resources. Every loc in the LOADED SCENE, not a window around the player. Narrow it with :within(n) if you only care about what is nearby -- that filters the full answer rather than truncating the question.

The terminals hand out TileObject handles (a GameObject, WallObject, DecorativeObject or GroundObject). The alternative to walking Scene:getTiles() in Luau, which builds a handle per tile: scene:objects():ids(ids):collect() reads the whole scene once, in the host.

reachabilityFrom

reachabilityFrom: (SceneDomain, WorldPoint) -> Reachability?

The same flood seeded somewhere other than the local player -- "could I reach that from over there", which is what a route or a safespot check is actually asking.

source
The tile to flood from.
Returns
nil when the tile is outside the loaded scene.

hazardField

hazardField: (SceneDomain, HazardFieldSpec) -> HazardField?

Expand a set of scheduled hazards over the scene: which tiles are lethal on which ticks.

The hazards are DECLARED as data rather than tested by a callback, because the expansion is where the cost is -- a predicate called once per tile per tick is a hundred thousand crossings into the VM inside a native loop, with no deadline that can fire. Declared, it is one call in and one handle out whatever the scene size.

spec
The hazards, the horizon, and which tick is now.
Returns
nil when there is no scene to expand over.

timedSearch

timedSearch: (SceneDomain, HazardField, TimedSearchOpts?) -> TimedSearch?

Flood against a hazard field, asking it about the tick you ARRIVE at each tile rather than the tick the flood was built.

This is scene:reachability() for anything that moves on a schedule, plus the three things a timed route needs and an untimed one does not: shortcut edges, the grace traversing one grants, and the landed-tile departure check.

field
The field to consult.
opts
Source, run cadence, shortcuts, grace and dwell.
Returns
nil when there is no scene, or the source is off-plane.

isWalkable

isWalkable: (SceneDomain, WorldPoint) -> boolean

Whether a tile can be stood on at all -- terrain only, no flood. For whether a path reaches it, use scene:reachability().

tile
The tile to test.

aggressionCenters

aggressionCenters: (SceneDomain) -> { WorldPoint }

The current NPC aggression area's safe centers, oldest first: none until the client has calibrated (a teleport or a long run), then one or two. The area is the 21x21 square around each. The client saves the area per account and brings it back after a relog where the player logged out.

npcMayAggro

npcMayAggro: (SceneDomain, number, WorldPoint) -> boolean

Whether an NPC can still aggro the local player: never once the area is tolerant, and otherwise the level rule (an NPC with a combat level does not aggro a player more than twice its level, except in the Wilderness).

level
The NPC's combat level.
tile
The tile the NPC stands on.

cannon

cannon: (SceneDomain) -> Cannon?

The local player's cannon, read live from the game's vars.

Returns
nil when no cannon is placed.