Custom Events

Built-in authoring reference for Mercury 1.1.2. All events.

Custom Event

Runs when another action or script triggers the selected named custom event.

Reference key: customEvent.

Editor category: Custom Events > Project Events.

Example: Create a docsPulse receiver, then send docsPulse with Trigger Custom Event.

Object inputs: self, other.

Filter (Custom event): Choose the name to receive, and match it exactly in the sending Action, including capitalization.

Event context is a read-only snapshot for this invocation. It is available in the Event’s Action fields; store a required value in a declared Variable before using it in another Event.

Base Event Context

The table lists the base participant fields used in this 2D example.

Field	Type	Description
otherName	thing:object	Object resource of the other participant. This identifies the reusable definition; use the Event Object input to target the live participant.
otherInstance	instance	Live instance supplied by this Event. Use this typed handle to target the participant or store it in an Instance Variable; an Object resource name identifies its reusable definition instead. The handle can be empty when no participant is supplied.
otherId	text	Placement ID of the other participant, when supplied. Several live instances can share the same Placement ID when they are runtime copies of one placement. It can be blank. Use Other Instance to target a live participant.

Add a Named Receiver

First build the diagnostic handler on World Marker. This comparison also uses a second active, placed Object named Window UI Marker.

In a 2D Logic Component named Custom Route Receiver, open Action List > Events > Custom Events > Project Events, then choose Add Custom Event…. Enter docsPulse in Event Name and choose OK.

Select the receiver’s Mode, then check that the toolbar says On custom event docsPulse before adding its Actions. Add a Print Debugger Message with Message set to Matched docsPulse. Connect the Action to End.

Attach Custom Route Receiver once to each Object, and enable both attachments. Save the project.

The Event name must match exactly. To check capitalization, add another Custom Event named docspulse in the same Logic. Select its own Mode, then connect a Print Debugger Message with Message set to Negative docspulse through End.

Send the Matching Event

In the sender’s Create Event, select Mode 1 and add Trigger Custom Event after the diagnostic Actions. Set Custom Event to docsPulse. Keep the sender Logic attached to World Marker only.

Save, then start a fresh Debug Play. With both Objects active, one broadcast produces two Matched docsPulse messages. The docspulse receiver stays silent. Choose Stop before editing again.

To send to one owner, replace that sender Action with Trigger Custom Event on Object. Set Custom Event to docsPulse. In Applies To, choose Attached Object > Self for the sender’s owner.

Save and start a fresh Debug Play again. With both receiver attachments still enabled, this send produces one Matched docsPulse message. The second receiver does not run. Choose Stop afterward.

Identify the Sender

On Window UI Marker, Self is the receiver running the handler. Other Object identifies World Marker, the sender’s reusable Object definition. Other Instance is its live handle.

Other Placement ID can be blank even when Other Instance is present. Use the live handle to target the sender.

Sent Values and Model Filters

Custom Events can also declare Sent Values. These add typed message fields beyond the base participant context listed above.

When the Logic has an eligible Model, Using can restrict the receiving Model. That restriction is separate from the Event name.

The End Trial example sends a named Event to one Object in Weighted Maze.