link_image(3)

💖 link_image — bestie, let's re-parent some objects 💖

okay so real talk, this is link_image(3) from the Arcan Lua API and it's literally the glow-up your object hierarchy has been waiting for. it's giving "found family" but for property spaces 🫶

---

✨ NAME ✨

link_image — reassign the property-space so it's relative to another object. yes, that means your baby object gets a new parent and everything. slay.

---

🌸 SYNOPSIS 🌸

nil
link_image( vid:id, vid:newparent )
link_image( vid:id, vid:newparent, int:panchor )
link_image( vid:id, vid:newparent, int:panchor, int:anchor_opt )

four whole flavors, pick your fighter ✨

---

🦋 DESCRIPTION 🦋

so by default, every single object out here defines its properties relative to an invisible WORLDID object — that's the default parent, the main character of the universe, whatever. but with this function you can swap that parent out dynamically and build the most complex hierarchies your heart desires. no cap, hierarchies are the vibe.

the default properties that get to be relative to another object in this way are opacity, position, orientation and lifetime — iconic set honestly. BUT 💅 that set can be changed with image_mask_set, image_mask_clear, image_mask_clearall, and image_mask_toggle. so you have range.

the vid argument refers to the object that shall be reassigned (the one getting adopted, basically 🥺) and the newparent argument specifies the object that it should be made relative to. found family, periodt.

---

🎀 the panchor era 🎀

if the panchor argument is specified, it defines the positional anchoring space in the parent, based on one of these values:

• ANCHOR_UL : upper-left
• ANCHOR_CR : upper-center
• ANCHOR_UR : upper-right
• ANCHOR_CL : center-left
• ANCHOR_C : center
• ANCHOR_CR : center-right
• ANCHOR_LL : lower-left
• ANCHOR_LC : lower-center
• ANCHOR_LR : lower-right

(and yep, ANCHOR_CR really does show up twice in the manual — we report, we don't editorialize 💀 copy it exactly as the manpage says, bestie.)

this is relative to the anchor origo of id — which defaults to ANCHOR_UL — and that origo can be changed with image_origo_offset. adorable.

---

💜 the anchor_opt era 💜

if the anchor_opt argument is specified, further anchor behavior can be controlled 👑. the valid values for anchor_opt right now are:

• ANCHOR_SCALE_NONE — the default, lowkey the chill option
• ANCHOR_SCALE_W
• ANCHOR_SCALE_H
• ANCHOR_SCALE_WH

with these, the object size is now defined relative to that of the width and/or height of the parent. the relative delta is calculated based on the current scale versus the initial (surface without a texture backing) or the current storage size. math but make it fashion ⭐

---

⚠️ NOTES ⚠️ (read these, i'm serious) ⚠️

1. changing link ownership resets all scheduled transformations except for blending. all of them. gone. blending gets to stay, because blending is the favorite child apparently 😭
2. rotation transforms do not take the positional anchor point into account — only its mask and origo offset. so don't come for rotation expecting anchor behavior, it simply will not do that 🙈
3. link to self is equivalent to linking back to WORLDID. so linking to yourself is just... going home. mood.
4. linked scale means 1px will be subtracted from id in each desired dimension when calculating final size, since no object can go below 1x1 px size — which would otherwise make it impossible to describe the case where parent and child should have identical size for the shared dimension. hare dimensions 💀 (the manpage says this, we're just the messenger)

ok but seriously note 1 is the one that bites people. transformations get yeeted on re-link. you've been warned, bestie.

---

🔥 EXAMPLE 🔥

function link_image0()
      a = fill_surface(64, 64, 255, 0, 0);
      b = fill_surface(32, 32, 0, 255, 0);
      link_image(b, a);
      show_image(b);
      blend_image(a, 1.0, 50);
      move_image(a, VRESW, VRESH, 100);
      rotate_image(a, 100, 100);
      expire_image(a, 100);
end

look at b getting adopted by a and then a goes off and does a whole move/rotate/expire arc — main character energy fr fr 🌈

---

and that's the whole page, bestie, you ate that 💅

cute lil sign-off: this came from the image manual, dated October 2026, and it's link_image(3) — go forth and re-parent responsibly 🎀✨