message_target(3)

💖 message_target(3) — a.k.a. the "send a lil text note to a frameserver" era 💖

okay so real talk, this is a page out of the Library Functions Manual and it's all about message_target, which sends a utf-8 coded text message to a frameserver. yes bestie, that's the whole NAME section, we're starting strong ✨

---

🌸 SYNOPSIS 🌸

int:bytes_left
message_target( vid:tgtvid, string:msg )

so it gives you back an int:bytes_left, and it takes a vid:tgtvid plus a string:msg. that's the whole vibe check 🫶

---

🦋 DESCRIPTION 🦋

okay so picture this: rare occasions. we're talking custom applications, and clipboard situations that are not using the bchunk-method of transfer. in those specific cases it genuinely makes sense to send short custom text messages to a target frameserver 💅

so what this function does is: it takes a string, validates it as utf-8, breaks it down into event-sized chunks, and adds them to the target frameserver's incoming eventqueue. iconic behavior, no notes 👑

and the return value? lemme break it down because it's giving three-whole-personalities:

• 0 — slay, the entire message was sent, we love a clean finish 💖
• a negative value — the string failed to validate, so like... it did not pass the vibe check 😭
• a positive number — this one tells you the number of bytes left 👀 and heads up, this case only occurs if the target event queue is full, so it's not a random thing, it's specifically the queue-is-full situation

---

✨ NOTES ✨

1. in cases where an arcan appl was spawned by another arcan instance, WORLDID is a valid vid for message_target to the parent. and you can test this:

-- via ref:valid_vid(WORLDID, TYPE_FRAMESERVER).

literally that's the test, iykyk 🧚

---

🎀 EXAMPLE 🎀

here's the whole thing, bestie, copy it exactly:

-- @group: targetcontrol
-- @cfunction: targetmessage
-- @related: target_input
function message_target0()
      target_alloc("test", function(source, status)
            if (status.kind == "connected") then
                  message_target(source, "welcome");
                  return shutdown();
            end
      end);
end

the way this just allocates a target, waits for status.kind == "connected", fires off "welcome" into the world, and then immediately shutdown()s — main character energy, honestly 🔥

---

and that's the whole page, no cap. every flag-free, option-free, detail-preserved bit of it 💀 (yes there are no OPTIONS here, don't come for me, that's just the page 🙈)

mwah 💋 this lil drop comes to you courtesy of the Arcan Lua API and is dated October 2026 — take care of her, she's iconic 🌈⭐👑