Pigeon - easy and safe messaging for Defold

Daremo · May 13, 2024, 12:24pm

I copy and edited and everything works great,
Thanks a lot for the help!

Pawel · October 14, 2024, 11:03pm

Pigeon has been updated to 1.2

Added possibility to use another logger - Defold-Log by Insality
Updated example to Defold 1.9.3

Release is added on Github, current link to add to game.project dependency:

https://github.com/paweljarosz/pigeon/archive/refs/tags/v1.2.zip

Quick Reference:

local insality_log = require "log.log"
pigeon.set_dependency_module_log(insality_log.get_logger("pigeon"))

Insality · October 14, 2024, 11:14pm

Well done!

Pawel · November 2, 2024, 12:54am

Pigeon has been updated to 1.3

Added possibility to define multiple types in message definition using | as separator, e.g. string|number|nil. Example script extended with this usage. Change is not breaking and all legacy tests are passing. Quick Reference:

pigeon.define("test", { test_value = "string|number|nil" }) -- define message with one test_value being string, number or nil
pigeon.send("test", {test_value = 1 }) -- we can then send a message with number
pigeon.send("test", {test_value = "test" }) -- or string
pigeon.send("test", {test_value = nil }) -- or nil
pigeon.send("test". {}) -- and because the only defined key here can be nil, so we as well can pass empty table
pigeon.send("test") -- or nothing at all

Added Lua annotations to all functions in Pigeon!
Improved documentation.
Working with Defold 1.9.4 (library is pretty much version agnostic though unless msg API changes)

Release is added on Github as 1.3, current link to add to game.project dependency:

https://github.com/paweljarosz/pigeon/archive/refs/tags/v1.3.zip

Pawel · March 1, 2026, 10:36am

Pigeon has been updated to 1.4

This release is pretty huge, but it maintains a backward compatibility with 1.3. If anything is broken in your project after updating to 1.4, please let me know or write an issue on github repository. I closed the issues and updated it basing on the feedback from users, special thanks for @Bomborant for reporting. Code has been refactored and modularized and everything has proper Lua annotations.

Changelog:

NEW: Added optional context support for hooks in pigeon.subscribe().

The context is the subscriber’s data (e.g. self) passed at subscribe-time and stored with the subscription. When any script calls pigeon.send(), the hook fires immediately with the subscriber’s context — not the sender’s. This allows safe access to instance-specific data inside hooks.


-- Script B subscribes with its own self as context:
local function my_hook(message_id, message, ctx)
    go.set_position(ctx.my_id, message.new_pos)
end

pigeon.subscribe("move", my_hook, nil, self)

-- Script A sends a message and script B's hook fires immediately with B's self as context:
pigeon.send("move", { new_pos = vmath.vector3(100, 200, 0) } )

NEW: Added pigeon.extend_subscription(id, messages) — add new message ids to an existing subscription without creating a new one.
NEW: Added pigeon.reduce_subscription(id, messages) — remove specific message ids from an existing subscription. If all messages are removed, the subscription is automatically unsubscribed.
NEW: Added pigeon.new(handlers, tag?) — create a convenience handler instance that auto-subscribes to all message ids from the handlers table and dispatches them via on_message. Call handler:final() to clean up.
NEW: Added pigeon.define_batch(letters_table, is_overwriting?) — define multiple message schemas at once from a table of letter definitions.
NEW: pigeon.unsubscribe() now accepts a table of subscriber ids to unsubscribe multiple subscriptions at once.
FIX: Built-in Defold message ids (for example load, unload, enable) are protected from accidental redefinition (always blocked). This fixes issues, when users could accidentally overwrite internally used message_ids.
DEPRECATED: pigeon.set_dependency_module_hashed() is now a deprecated and if you call it it’s no-op. Pigeon always uses the internal hashed module.
UPDATE: Refactored internals (separate implementation pigeon_impl.lua, new separate module for checking types: pigeon.typer).
UPDATE: Added or expanded Lua annotations directly in pigeon/pigeon.lua and added pigeon/typer.lua as a dedicated runtime type checking module.
UPDATE: Added tests to cover new functionalities.
Version 1.4 should be backward compatible with 1.3, as all API functions remained unchanged, only new, safer behaviour is added via using trailing optional parameters in calls, while keeping default as in the previou version. Deprecated function (set_dependency_module_hashed) is still kept for backward compatibility.

Pawel · April 20, 2026, 6:24pm

Pigeon has been updated to 1.5

This brings a really small, but confusing bug fix, or a lack-of-consitency fix for the pigeon.send_to (equivalent of msg.post()). Letters could have been designed to work with urls in forms of Defold url, hash, string or id for ease of use, but it was missing in the direct message sending. Now you can send messages using ids, meaning, e.g.: if you create an object using a local id = factory.create(), you can use this id directly, no need to wrap them in additional msg.url() calls.

Changelog:

NEW: Added possibility to send messages directly using ids.

It’s backward compatible with the previous version.

Pawel · April 28, 2026, 5:50pm

A little teaser of what I created for Pigeon.

So, I always had an idea of making a graph of messages - what is sent to who, who receives what, who handles what. I’m a visual guy, who likes to literally see the connections and usually draws graphs on paper or in draw_io and this helps me to mentally maintain huge projects I’m working on, so it’s natural I wanted something like this for messaging system in Defold. I had it always in my mind, especially when working on Pigeon, as it simplifies sending messages to any subscribers, but there’s no quick way of verifying then, where are those sent (who are the subsrcibed currently subscribers) and most importantly who handles it and who’s not (yet). So sometimes I swear on my own tool, because simplyfing one thing it makes other stuff more complex. So a graph of dependencies like this would be a nice helper for the development.

I had some attempts e.g. ImNodes, and some projects also made in Defold, but coding it to be useful, handy and having nice UX is an ambitious task, so I never actually made something like this. I know I’m justifying now myself, when truth is, I’m too lazy and I just don’t want to spend time on it! So I took my chances with LLMs then, because why not. I spent a few minutes, maybe an hour, on preparing the research and gathering the backend knowledge, I am not actually familiar with, but that would solve my problem and veryfing it on several different levels, and then preparing the implementation with Codex and v’oila:

It doesn’t have to be perfectly coded (it isn’t), but it does the job! I’ll release it on a separate branch, as it injects some code into Pigeon itself, that I must verify, but maybe for someone, dived deep in a huge project that uses Pigeon - it might be as worthy as I think so!

It analyzes the code using Editor Script, this part I was already working on in the past, but the LLM also touched this part and added more dependencies checking, verification, errors and warnings for loose or unhandled messages etc and then produces a graph and visualizes it on a local website that is opened from Editor: