pyxen.world.pick()

Pick entities at a screen-space point or rectangle.

world.pick(x, y, w=1, h=1, *components, without=None)

Returns an iterator over entities whose sprite overlaps the rectangle, topmost first (highest layer, then highest depth).

The default rectangle size is 1×1, so calling world.pick(x, y) performs a point pick.

Basic Usage

def update():
    if input.mouse.left.pressed:
        for hit in world.pick(input.mouse.pos.x, input.mouse.pos.y):
            hit.health.value -= 10
            break

The for ... break pattern takes the topmost entity (or skips the body entirely if nothing was hit). Pyxen’s MicroPython doesn’t ship the 2-arg next(it, default) form, so don’t use it here.

Rectangle Pick

Pass w and h to query a rectangle. Useful for drag-box selection or area-of-effect logic.

for e in world.pick(rx, ry, w=64, h=64, "selectable"):
    e.selected = True

The rectangle is in screen-space pixels — top-left is (x, y), bottom-right is (x + w, y + h).

Component Filter

Positional component names restrict the result to entities that have all of them.

for e in world.pick(mx, my, "clickable"):
    e.on_click()

Same semantics as world.all(): a component is identified by its name as a string. Builtin components ("sprite", "body", "camera", etc.) and custom schema components are both supported.

Excluding Components

Use without= to filter out entities that have specific components.

for e in world.pick(mx, my, "enemy", without=("dead",)):
    attack(e)

without must be a tuple, just like in world.all().

Coordinate System

Coordinates are screen-space pixels matching input.mouse.pos.x and input.mouse.pos.y. The Y axis points down (row 0 is the top of the screen).

If a Camera component is in the scene, pick() accounts for it automatically — pass mouse coordinates as-is.

Ordering

Hits are returned topmost first — highest layer, then highest depth, then most-recently-spawned. This matches the painter’s order in reverse: the entity drawn on top is the first one returned.

Pickable Entities

Only entities with a sprite are pickable. Entities without a sprite (e.g. logical containers, parents, cameras) are skipped, just like in rendering.

The pickable area of an entity is its sprite quad, computed from tw, th, and the sprite’s pivot. Rotated and scaled sprites are accounted for via the entity’s world transform.

Edge Cases

• w <= 0 or h <= 0 returns an empty iterator (the rectangle is invalid).
• Picking before the first frame has rendered yields no hits — sprite world transforms are computed during rendering. Call pick() from update(), not from the module top-level.

Example: Click to Select

selected = None

def update():
    global selected
    if input.mouse.left.pressed:
        selected = None
        for hit in world.pick(input.mouse.pos.x, input.mouse.pos.y, "selectable"):
            selected = hit
            break

Example: Drag-Box Selection

def update():
    if input.mouse.left.released:
        x0, y0 = drag_start
        x1, y1 = input.mouse.pos.x, input.mouse.pos.y
        rx, ry = min(x0, x1), min(y0, y1)
        rw, rh = abs(x1 - x0), abs(y1 - y0)
        for e in world.pick(rx, ry, w=rw, h=rh, "selectable"):
            e.selected = True

Mini samples

Open from Samples & Tutorials inside Pyxen:

• world.pick() — Pick the entity under the cursor on click.