pick_items(3)

💅 pick_items(3) — Arcan Lua API, bestie edition ✨

Okay so before we even get into it: this page lives in the Arcan Lua API manual, and it's about pick_items, which is the lowkey MVP of "what did the user just click on" energy. Let's go 🫶

---

🌸 NAME 🌸

pick_items — pick a number of objects based on a screen-space coordinate. That's it. That's the whole vibe. 🎯

---

✨ SYNOPSIS ✨

vidtbl:results
pick_items( number:x, number:y )
pick_items( number:x, number:y, number:limit=8 )
pick_items( number:x, number:y, number:limit=8 )
pick_items( number:x, number:y, number:limit=8<=64, bool:reverse=false )
pick_items( number:x, number:y, number:limit=8<=64, bool:reverse=false, vid:rtgt=WORLDID )

Yes bestie, that third line is literally the same as the second one. That's how it is in the manual. We don't argue with the manual, we just vibe with it. 💀

---

💖 DESCRIPTION 💖

So pick_items is a low level function — like, foundation-level, not here to hold your hand — for building user-interface related picking tools. 🔨

It takes a screen-space or rendertarget-space coordinate, and it sweeps through the pipeline based on their render order (peep order_image for the deets on that one 👀).

If reverse is provided, it sweeps from high to low. Otherwise it goes low to high. Simple as.

And the way it's so efficient? It early outs once limit objects have been found. Iconic behavior honestly. ⚡

It will always return an integer indexed table of zero to limit number of VIDs. And limit is not allowed to exceed 64 — that's a hard no, not a suggestion. 🚫

---

🦋 NOTES 🦋

1. All VIDs start out as eligible for picking ✨ — that's the default, everyone's invited to the party. But you can control it by setting the MASK_UNPICKABLE mask (see image_mask_set). And here's the catch, bestie: this mask value is not inherited by default through linking. Which literally means you gotta set it for each new object, regardless of how link_image is being used. No shortcuts, no assumptions. 🙈
2. Clipping and alpha channel are ignored 😭 — like, fully not considered at all. You're gonna have to handle that manually by testing against any possible clipping parents. It's giving "do it yourself, girl." 💅
3. This function can be very costly depending on the complexity of the scene, so if you're expecting a high number of calls — for instance when it's tied to a touch or mouse-input device event handler — you really should be using some caching mechanism. Do not come crying to me when your frame rate dips, I warned you. 😭🔥
4. The cost progression goes roughly (low to high): normal → rotated → linked → 3d object → rotated-linked → rotated-linked-3d object. So like, the more you stack, the more expensive it gets. Plan accordingly boo. 📈
5. And this one's important — if an object is shader displayed, or manually manipulated by skewing vertices through image_tesselation or a vertex stage shader, the picking operation result is undefined. Undefined! Not "a little off", not "close enough" — undefined. You have been warned. 💀⚠️

---

👑 SEE ALSO: 👑

• image_hit(3) — your other picking bestie ✨

---

Mwah 💋 that's the whole page, no crumbs left. This one's from the image manual, dated October 2026 — go forth and pick responsibly, bestie 🎀💜🌈⭐