Hey folks, this is just a little overview of some new Circuits tech called Messages that makes it easier for objects to talk to each other, especially when using Inventions. The easiest way to think about Messages is “What if Events didn’t need Definitions?”
What are Messages?
Similar to Events, Messages are a way to send messages around the room or between objects. However, Messages are a lot more flexible and efficient, and hopefully easier to use! I’ll unpack the various differences in this post:
- Messages match using their names only - if I import two Inventions that are both using a Message called On Enemy Died, they’ll automatically merge
- Different Senders and Receivers can pass around different parameters, but they’re still all the same Message
- Messages don’t use Definitions, so including them in Inventions is much less error-prone
- Messages can target an object directly, or be sent to the whole room, and they are not inherently restricted to certain scopes based on where they’re defined
Messages are available in both R1 and R2, though we expect them to be more useful in R2 due to hierarchical objects.
How to use Messages
You’ll find two new chips in your palette for the Message Sender and Receiver. These will start off using a Message named “Default”.
You can configure either one of them and use the Message dropdown to choose which Message to use. The list of available Messages is based on all the Message chips that currently exist in your room.
From this dropdown, you can add a new message or switch this Message chip to use another of the room’s existing Messages.
You can also click the Edit button next to the Message dropdown to edit the name of the current Message. This will change it everywhere it’s referenced in the room without breaking any existing circuits.
Any sender and receiver with the same name have the potential to connect, depending on…
Target Scope and Players
Message Senders can be set to send to the entire room, or to send to a specific object. In both cases, all children of the target scope will also hear it. So if you send a Message to the room, it will be available everywhere, and if you send it to a specific object, all children of that object will also receive it.
If you’re using a Message to pass damage to an enemy, you can send it either to every enemy in the room, or one in particular. Setting a Sender to target a specific object will add a Target port so you’re able to specify which.
This setting is available in the “Receivers” dropdown.
You also have access to the same networking options as Events, where you may choose for which players the Messages receivers will execute. By default, it will be received only by the local player, or the same player who executes the Sender.
Flexible Parameters and Default Values
Messages can send parameters along for the ride. One of the big improvements over Events is that not all of the chips have to match - different Senders and Receivers can have different sets of parameters, and yet they can all still work together.
You can add parameters using the Add Parameter button. They’ll need a name, a type, and a default value. The default value is the value that will be received by any Message Receiver that’s using this parameter if the Sender does not specify a value.
Whenever you configure a Message Sender or Receiver, you’ll see all the available parameters in this foldout. This list contains every parameter that is associated with this Message anywhere in the room. Importing a new Invention may add to this list, if the Invention is using a Message that has the same name but new parameters.
Any parameters that are not used anywhere will stick around until you save the room, and then will be “cleaned up.”
You can toggle these parameters on and off for each individual chip. On a Sender, these toggles will change which input ports it has, while on a Receiver, they will toggle which output ports it has. If a Receiver is being triggered by a Sender with mismatched parameters, it resolves in this way:
- Any parameters that exist on the Sender, but not the Receiver, are ignored by the Receiver
- Any parameters that exist on the Receiver, but not the Sender, fall back to their Default Value
- Any parameters that exist on both are passed from Sender to Receiver
This has some major advantages, but it’s a little tough to think about if you’re used to Events. Keep reading and I’ll go through an example!
Messages In Action
Here’s how this advantage comes into play. Let’s say you’ve got a bunch of stuff in your room that will damage enemies: swords, spike traps, and lava. All of these things do some amount of damage. But you want the spike traps to slow an enemy down, the lava to set them on fire, and the swords to make them bleed.
No problem. We can use one Message for all of that.
Here we’ve got a Message called Enemy Request Damage. All of our enemies have a Message Receivers with all of these parameters, and internal logic that knows what to do if they get hit.
While our weapons have Message Senders with only the parameters relevant to that type.
If an enemy is hit by a sword, they’ll get a value for Damage and a value for Bleed, but SetsOnFire and Slows will both fall back to their Default Values, which is false.
If they step into Lava, they’ll get a value for Damage and a bool for SetsOnFire, but Bleed will fall back to its default value of 0, and Slows to False.
In both of these examples, the sword or the lava is sending a message only to the enemy that got hit. But let’s say I want to add acid rain that will damage all enemies at once. In this case I can make a Message Sender that targets the room and sends a small amount of damage to all enemies at once.
And let’s say I also want to make a stun grenade that can slow, but doesn’t actually do any damage. I can do that, too, by only sending Slows.
There are more complicated ways to do a lot of this, but using Messages can make things a lot simpler and more flexible. Not only that, but they lend themselves to Inventions that are more likely to be compatible with the rooms they’re spawned into.
If you hit any bugs with Messages or have questions let us know in this thread!
Cheers
~ The RR Team
