picking

Mouse/pointer picking helpers. Wraps the engine-provided getPointerHitTable() and getLookHitTable() globals into decoded Lua tables and exposes small extractors for the entity id / name fields callers reach for most often.

Exports

• M.getHit() -> Hit? — current pointer hit, or nil when none.
• M.getLook() -> Hit? — current look-at (camera-center) hit, or nil.
• M.hoveredEntityId(hit: Hit?) -> string? — extract entity_id from a hit.
• M.lookedEntityId(hit: Hit?) -> string? — same shape, semantic mirror of hoveredEntityId.
• M.hoveredName(hit: Hit?) -> string? — extract name from a hit.

Types:

• Hit = { entity_id: string?, name: string?, [string]: any } — the engine-emitted hit table; carries additional fields beyond those typed here.

Usage

local Picking = require("@builtin::modules.picking")

local hit = Picking.getHit()
local id  = Picking.hoveredEntityId(hit)
if id then
    print("hovering over", id)
end

Notes

• Returns nil (not false) when the engine globals are absent — call sites can branch on if hit then ....
• The extractors accept nil so callers can chain Picking.hoveredEntityId(Picking.getHit()) without a manual guard.
• Pure read-side helpers — no state, no side effects.