launch_target(3)

💖 NAME 💖

okay so this is launch_target from the Arcan Lua API bestie — it's the one that sets up and launches an external program. that's the whole vibe. 🚀

---

✨ SYNOPSIS ✨

the returns are all of this, together:

vid:new_vid, aid:new_aid, int:cookie, int:return_code, int:elapsed

and here's every single way you can call it (yes, all of them, no skipping):

launch_target( string:target )
launch_target( string:target, string:config=default )
launch_target( string:target, int:mode=LAUNCH_INTERNAL )
launch_target( string:target, string:config=default, int:mode )
launch_target( string:target, string:config=default,
int:mode=LAUNCH_INTERNAL )
launch_target( string:target, string:config=default,
int:mode=LAUNCH_INTERNAL )
launch_target( ... function:handler(source, status) )

not me pointing out that the int:mode=LAUNCH_INTERNAL line with string:config=default shows up twice up there 🙈 that's literally how it's written, so that's how it stays. slay for consistency ig 💅

---

🦋 DESCRIPTION 🦋

so launch_target uses the database to build a whole execution environment for the specific tuple of target and config, and then launches a matching external client. the mode can be either LAUNCH_INTERNAL (that's the default babe) or LAUNCH_EXTERNAL.

🌸 if LAUNCH_INTERNAL is set

arcan sets up a frameserver container, launches the config, and just keeps executing as normal — main character energy, no blocking. the callback you pass with handler is what receives the events connected with the new frameserver, and the returned vid handle is your remote control to talk to and command that frameserver. the NOTES section down below covers the events related to this callback. 🫶

🔥 if LAUNCH_EXTERNAL is set

arcan minimizes its execution and resource footprint and waits for the specified program to finish executing. the program's return code comes back as the function return, along with the elapsed time in milliseconds. heads up though: this call is blocking — it's intended for suspend/resume and similar situations. and it only works if the binary format in the database entry has also been set explicitly to EXTERNAL. no cap. 💀

💀 when it all goes wrong

if the target:config tuple does not exist (and if config isn't specified, it gets forced to 'default'), or the config doesn't support the requested mode → you get BADID back. that's it, that's the whole error. 😭

---

🎀 the callback situation

every single argument combination takes a callback function argument at the end. if you don't set it, it should be defined through target_updatehandler — otherwise there may be a terminal state transition on the first event received from the target. so like, don't forget it bestie.

the initial states a client goes through are literally:

1. "connected" (when using target_alloc)
2. "registered" (type information available)
3. "preroll" (client waiting for initial state information)
4. "resized" (first frame and subsequent resizes)
5. [tblents below]
6. "terminated"

---

⭐ the visibility tea

do note that the returned new_vid has no guaranteed initial size, and it will be invisible regardless of resize_image / blend_image calls until the first "resized" event has been delivered through the handler. while it can be constrained, the client can always initiate resizes within a valid range — so layout, animations and so on need to be able to adapt. plan accordingly 🧚

---

🌈 the event timing tea

most of the key/values in sttatustbl depend on the kind — with a notable exception being 'frame'. (yes, sttatustbl, that's the spelling in here, don't come for me 🙈)

events are delivered in order, but their synchronisation to the stream of audio and video frames may drift. to counteract this there's a client provided clock. you can combine that with the verbose delivery mode (target_flags) in order to more tightly couple an inbound event with its visual state at the time. this should rarely matter — main exception being viewport events and custom messages as used with protocol bridges (e.g. X11) that may require a tighter timing when events are used to annotate the contents of a frame. iykyk 💅

---

👑 possible statustbl.kind values

"preroll", "resized", "ident", "coreopt", "message", "failure", "streaminfo" "frame", "streamstatus", "segment_request", "state_size", "viewport", "alert", "content_state", "registered", "clock", "cursor", "bchunkstate", "proto_update", "input_mask", "ramp_update"

yeah the missing comma between "streaminfo" and "frame" is real, i'm just the messenger 🫠

---

🌟 NOTES 🌟

1. the bridge segments have the quirk that the primary is used as an invisible segment allocation factory or to convey debugging / profiling data. the 'x11' and 'wayland' has additional expectations on interpretations of 'message' and 'viewport' events and the use of target_anchorhints to convey feedback and window management restrictions to accomodate these protocols and incorporate them. the 'allocator' one is used for complex UI toolkit constraints that need to allocate resources without a prior intent behind the primary connection. 💜

2.

that's it. note 2 is literally empty in the original. ghost note. it's giving invisible main character. i'm not adding anything to it because that would be inventing facts and we don't do that here ✨

---

🍓 EXAMPLE 🍓

function launch_target0()
      local tgts = list_targets();
      if (#tgts == 0) then
            return shutdown("no targets found, check database", -1);
      end
      return shutdown(string.format("%s returned %d0, tgts[1],
            launch_target(tgts[1], LAUNCH_EXTERNAL)));
end

---

🔥 EXAMPLE 🔥

function launch_target1()
      local tgts = list_targets();
      if (#tgts == 0) then
            return shutdown("no targets found, check database", -1);
      end
      local img = launch_target(tgts[1], LAUNCH_INTERNAL,
            function(src, stat)
                  print(src, stat);
            end
      );
      if (valid_vid(img)) then
            show_image(img);
      else
            return shutdown(string.format("internal launch of %s failed.0,
                  tgts[1]), -1);
      end
end

---

💀 MISUSE 💀

don't do this. this is the "i'm going to pass launch_target itself as a handler and a -1 for a string argument" speedrun:

function launch_target0()
      local tgts = list_targets();
      if (#tgts == 0) then
            return shutdown("no targets found, check database", -1);
      end
      launch_target("noexist", -1, launch_target);
end

that's the misuse example exactly as written — "noexist" as a target, -1 where a config string would go, and the function itself as the handler. chaotic. iconic. don't. 🙈

---

🌸 SEE ALSO 🌸

• target_accept(3)
• target_alloc(3)

---

and that's the whole page bestie!! 💖✨ this sweet thing comes to you courtesy of targetcontrol, dated October 2026 — go forth and launch things (internally, externally, responsibly) 🎀🦋💅🫶🌈