order_image(3)

📦
version 0.7.1 · 2 versions
, in nixos 26.05

💅 order_image 💅

okay bestie, welcome to the Arcan Lua API manual page for order_image(3) — yes, the one that changes up when your image gets drawn. let's get into it, no cap.

🌸 NAME 🌸

order_image — alter the drawing order of the specified image. it's giving "move over, i'm the main character now" energy. 👑

✨ SYNOPSIS ✨

nil
order_image( vid or tblvid, newzv )

so yeah, it returns nil, and you feed it either a vid or a tblvid, plus your newzv. simple, iconic. 💫

🦋 DESCRIPTION 🦋

okay so literally every object has an order property, and that property decides when it should be drawn in respect to other ones. think of it as the object's place in the drawing line. 🎀

you can change that value by calling the order_image function on a video object, or on a table of video objects. group makeover, we love to see it. 💖

the newzv should be within the range 0 <= n < 65535 and will be clamped — so if you try to push it outside, it gets pulled back into line. the exception to this is objects that are linked to others and have their order being relative to its parent. for those, negative values are permitted, but they will be resolved to a value within the specified range. so yes, negatives can happen, but they still get resolved into that range. periodt. 🔥

👑 NOTES 👑

  1. this only applies to the active owner of an image. for images attached to multiple rendertarget, such changes won't take place until you forcibly attach/detach for each specified rendertarget. so don't expect it to just magically update everywhere, bestie. 💀
  2. order can also be relative to the world-order of the resolved parent, see image_inherit_order. iykyk. 🌈

🧚 EXAMPLE 🧚

function order_image0()
      a = color_surface(32, 32, 255, 0, 0);
      b = color_surface(32, 32, 0, 255, 0);
      move_image(b, 16, 16);
      show_image({a, b});
      order_image(a, 2);
end

look at a getting its order set to 2 — little main character move. slay. 💅

🙈 MISUSE 🙈

function order_image0()
      a = color_surface(32, 32, 255, 0, 0);
      order_image(a, -1);
end

this is the MISUSE example, bestie. it is right there in the name. do not treat it like a cute little hack without knowing what you're doing. 😭

⭐ SEE ALSO ⭐

that's the whole vibe 💖 this page comes from the image source/version and is dated October 2026, so you know it's official. stay slay, bestie — and may your draw order always be correct. 🫶✨

📦 where this page comes from