Pick
Find the entity under a point, a screen position, the mouse or a 3D ray, and register custom pickers.
Namespace: caffeine.pick
world#
Lua: caffeine.pick.world
world(wx, wy) -> integer
Picks the entity under a 2D world position.
| Parameters | Type | Description |
|---|---|---|
wx | number | World x. |
wy | number | World y. |
Returns: integer. Entity id, or 0 when nothing is hit.
Example
local e = caffeine.pick.world(3, 4)
screen#
Lua: caffeine.pick.screen
screen(sx, sy) -> integer
Converts a screen position to the world using the play-mode camera and picks the entity there.
| Parameters | Type | Description |
|---|---|---|
sx | number | Screen x. |
sy | number | Screen y. |
Returns: integer. Entity id, or 0 when nothing is hit.
Example
local e = caffeine.pick.screen(400, 300)
atMouse#
Lua: caffeine.pick.atMouse
atMouse() -> integer
Picks the entity under the mouse cursor; 0 without a world or input.
Returns: integer. Entity id, or 0 when nothing is hit.
Example
local e = caffeine.pick.atMouse()
screenToWorld#
Lua: caffeine.pick.screenToWorld
screenToWorld(sx, sy) -> table
Converts a screen position to a 2D world position.
| Parameters | Type | Description |
|---|---|---|
sx | number | Screen x. |
sy | number | Screen y. |
Returns: table. {x, y} in world units.
Example
local w = caffeine.pick.screenToWorld(400, 300)
register#
Lua: caffeine.pick.register
register(fn) -> integer
Registers a custom picker consulted by pick queries.
| Parameters | Type | Description |
|---|---|---|
fn | function | Called as fn(worldX, worldY); return an entity id (above 0) for a hit, or false/nil for none. |
Returns: integer. Handle for unregister.
Example
local h = caffeine.pick.register(function(x, y) return 0 end)
unregister#
Lua: caffeine.pick.unregister
unregister(handle)
Removes a custom picker.
| Parameters | Type | Description |
|---|---|---|
handle | integer | Handle from register. |
Returns: none
Example
caffeine.pick.unregister(h)
query#
Lua: caffeine.pick.query
query(wx, wy) -> table
Full pick query at a world position, including custom pickers.
| Parameters | Type | Description |
|---|---|---|
wx | number | World x. |
wy | number | World y. |
Returns: table. {kind = "entity", entityId}, {kind = "custom", customId} or {kind = "none"}; empty without a world.
Example
local hit = caffeine.pick.query(3, 4)
if hit.kind == 'entity' then caffeine.debug.log(hit.entityId) end
raycast#
Lua: caffeine.pick.raycast
raycast(origin, dir) -> integer
Casts a 3D ray and returns the entity hit.
| Parameters | Type | Description |
|---|---|---|
origin | table | {x, y, z}; missing parts are 0. |
dir | table | {x, y, z} direction; normalised for you (default z = 1). |
Returns: integer. Entity id, or 0 when nothing is hit.
Example
local e = caffeine.pick.raycast({x=0,y=1,z=0}, {x=0,y=0,z=1})