Caffeine

Pick

Reference Input Last updated: Lua 8 · Dryad 0

Find the entity under a point, a screen position, the mouse or a 3D ray, and register custom pickers.

All namespaces

Namespace: caffeine.pick

world#

Lua: caffeine.pick.world

text
world(wx, wy) -> integer

Picks the entity under a 2D world position.

ParametersTypeDescription
wxnumberWorld x.
wynumberWorld y.

Returns: integer. Entity id, or 0 when nothing is hit.

Example

lua
local e = caffeine.pick.world(3, 4)

screen#

Lua: caffeine.pick.screen

text
screen(sx, sy) -> integer

Converts a screen position to the world using the play-mode camera and picks the entity there.

ParametersTypeDescription
sxnumberScreen x.
synumberScreen y.

Returns: integer. Entity id, or 0 when nothing is hit.

Example

lua
local e = caffeine.pick.screen(400, 300)

atMouse#

Lua: caffeine.pick.atMouse

text
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

lua
local e = caffeine.pick.atMouse()

screenToWorld#

Lua: caffeine.pick.screenToWorld

text
screenToWorld(sx, sy) -> table

Converts a screen position to a 2D world position.

ParametersTypeDescription
sxnumberScreen x.
synumberScreen y.

Returns: table. {x, y} in world units.

Example

lua
local w = caffeine.pick.screenToWorld(400, 300)

register#

Lua: caffeine.pick.register

text
register(fn) -> integer

Registers a custom picker consulted by pick queries.

ParametersTypeDescription
fnfunctionCalled as fn(worldX, worldY); return an entity id (above 0) for a hit, or false/nil for none.

Returns: integer. Handle for unregister.

Example

lua
local h = caffeine.pick.register(function(x, y) return 0 end)

unregister#

Lua: caffeine.pick.unregister

text
unregister(handle)

Removes a custom picker.

ParametersTypeDescription
handleintegerHandle from register.

Returns: none

Example

lua
caffeine.pick.unregister(h)

query#

Lua: caffeine.pick.query

text
query(wx, wy) -> table

Full pick query at a world position, including custom pickers.

ParametersTypeDescription
wxnumberWorld x.
wynumberWorld y.

Returns: table. {kind = "entity", entityId}, {kind = "custom", customId} or {kind = "none"}; empty without a world.

Example

lua
local hit = caffeine.pick.query(3, 4)
if hit.kind == 'entity' then caffeine.debug.log(hit.entityId) end

raycast#

Lua: caffeine.pick.raycast

text
raycast(origin, dir) -> integer

Casts a 3D ray and returns the entity hit.

ParametersTypeDescription
origintable{x, y, z}; missing parts are 0.
dirtable{x, y, z} direction; normalised for you (default z = 1).

Returns: integer. Entity id, or 0 when nothing is hit.

Example

lua
local e = caffeine.pick.raycast({x=0,y=1,z=0}, {x=0,y=0,z=1})