Events

Mira API provides a powerful Events interface to simplify modding and improve compatibility between mods. It is highly recommended to use Mira Events instead of Harmony patches when applicable because Mira Events are designed for compatibility. In addition, Mira provides various built-in events for commonly patched functions to aid in compatibility. These events are detailed in the Built-in Events section below.

The Events interface is made of two parts, events and event handlers.

Events

All events are defined in a class that inherits from MiraEvent. Event classes can have an arbitrary number of members, specified by the developer's requirements. For example, the CompleteTaskEvent below, which is provided in Mira, has a property for the player who completed the task and a property for the task that was completed.

public class CompleteTaskEvent : MiraEvent
{
    public PlayerControl Player { get; }

    public PlayerTask Task { get; }

    public CompleteTaskEvent(PlayerControl player, PlayerTask task)
    {
        Player = player;
        Task = task;
    }
}

Mira itself provides two different bases for events: MiraEvent and MiraCancelableEvent. Cancelable events can be canceled by event handlers, preventing the original event from triggering. For example, the BeforeMurderEvent can be canceled to stop a murder from happening.

Developers are not limited to the events provided by Mira itself. Developers can create new events in their own mods by creating a class that inherits from MiraEvent, then triggering it with MiraEventManager.InvokeEvent, like in the example below:

var myCustomEvent = new MyCustomEvent(somePlayer, someTarget);
MiraEventManager.InvokeEvent(myCustomEvent);

If you only know the type of event at runtime, you can use InvokeEvent(MiraEvent eventInstance, Type type), like the example below:

var eventType = GetMyCustomEventType();
var @event = Activator.CreateInstance(eventType);
MiraEventManager.InvokeEvent(@event, eventType);

Event Handlers

Event handlers are delegates that are invoked when an event is triggered. Every event handler has a return type of void and a single parameter, an object that inherits from MiraEvent. Event handlers also have a priority that determines the order they are called in. Lower values are run first, and can be set during registration. Event handlers can be registered with either of the following methods:

• Call MiraEventManager.RegisterEventHandler.
• Use the RegisterEventAttribute on a method.

RegisterEventHandler and UnregisterEventHandler

The RegisterEventHandler method is more flexible because it can be called at any time and returns a MiraEventHandle that can be used to unregister the event handler later. To unregister an event with a MiraEventHandle, call MiraEventManager.UnregisterEventHandler. The priority of the event handler can be set with the priority parameter in the RegisterEventHandler method. The following example demonstrates the usage of the RegisterEventHandler and UnregisterEventHandler methods:

var handle = MiraEventManager.RegisterEventHandler<UpdateSystemEvent>(@event =>
{
    Logger<ExamplePlugin>.Info(@event.SystemType.ToString());
});

MiraEventManager.UnregisterEventHandler(handle);

You can also pass a method into the RegisterEventHandler, but it must have the correct signature. See the following example:

public static void UpdateSystemEventHandler(UpdateSystemEvent @event)
{
    Logger<ExamplePlugin>.Info(@event.SystemType.ToString());
}

MiraEventManager.RegisterEventHandler<UpdateSystemEvent>(UpdateSystemEventHandler, 5); // Priority of 5

RegisterEventAttribute

The RegisterEventAttribute is quick and efficient. To use it, you must define a static method with a return type of void and a single parameter for the MiraEvent. To set the priority with a RegisterEventAttribute, set the priority parameter. The following example demonstrates the RegisterEventAttribute:

[RegisterEvent(5)] // priority of 5
public static void UpdateSystemEventHandler(UpdateSystemEvent @event)
{
    Logger<ExamplePlugin>.Info(@event.SystemType.ToString());
}

Built-in Events

Mira API provides various built-in events under the MiraAPI.Events.Vanilla and MiraAPI.Events.Mira namespaces.

Mira Events

The following events are based on Mira API features.

• MiraButtonClickEvent: Triggered when a Mira button is clicked. This is only called locally, and triggered for every Mira button. This event can be canceled.
• MiraButtonClickEvent<T>: Triggered when a Mira button is clicked. This is only called locally, and triggered for a specific Mira button specified by the type T. This event can be canceled.
• MiraButtonCancelledEvent: Triggered when a Mira button event is canceled. This is only called locally, and triggered for every Mira button.
• MiraButtonCancelledEvent<T>: Triggered when a Mira button event is canceled. This is only called locally, and triggered for a specific Mira button specified by the type T.

Vanilla Events

The following events are based on vanilla gameplay features. It is recommended to use these events instead of Harmony patches.

Gameplay

• AfterMurderEvent: Triggered after a successful murder. Exposes the killer, target, and the dead body, if one exists.
• BeforeMurderEvent: Triggered before any murder. Exposes the killer and target. This event can be canceled.
• BeforeGameEndEvent: Triggered before GameManager.RpcEndGame. Exposes the GameOverReason. This event can be canceled.
• GameEndEvent: Triggered after EndGameManager.SetEverythingUp. Exposes the EndGameManager.
• IntroBeginEvent: Triggered when the IntroCutscene plays. Exposes the IntroCutscene.
• IntroEndEvent: Triggered at the end of the IntroCutscene. Exposes the IntroCutscene.
• RoundStartEvent: Triggered at the beginning of each round (After IntroCutscene and after ExileController). Exposes a boolean property that determines if the event was triggered by the IntroCutscene or the ExileController.
• SetRoleEvent: Triggered after a player's role is set. Exposes the player and the new role as a RoleTypes.

Map

• CloseDoorsEvent: Triggered when a door is closed. Exposes the room the door was closed in as a SystemTypes. This event can be canceled.
• PlayerOpenSabotageEvent: Triggered when a player opens the Sabotage map. Exposes the MapBehaviour instance. This event can be canceled.
• UpdateSystemEvent: Triggered when a ship system is updated. Exposes the player who updated the system, the system as a SystemTypes, and the update amount as a byte. This event can be canceled.

Meeting

More information about the Meeting events can be found in the Meetings page.

Voting Events:

• CheckForEndVotingEvent: Triggered when the game checks for the end of voting. This event can be canceled.
• HandleVoteEvent: Triggered when a player votes. This event can be canceled.
• MeetingSelectEvent: Triggered when a player selects a vote area in the meeting.
• PopulateResultsEvent: Triggered when the game populates the voting results. This event can be canceled, but it is highly recommended to not cancel it.
• ProcessVotesEvent: Triggered when Mira API processes custom votes.
• VotingCompleteEvent: Triggered when the voting is complete.

General Meeting Events:

• EjectionEvent: Triggered when a player is ejected. Exposes the ExileController.
• EndMeetingEvent: Triggered when the meeting ends. Exposes the MeetingHud.
• ReportBodyEvent: Triggered when a body is reported. Exposes the player who reported, and data related to the body that was reported. If a meeting is called via the Emergency Meeting button, the body data will be null. This event can be canceled.
• StartMeetingEvent: Triggered when a meeting starts. Exposes the MeetingHud.

Player

• CompleteTaskEvent: Triggered when a player completes a task. Exposes the player and the task that was completed.
• PlayerDeathEvent: Triggered when a player dies. Exposes the player, the death reason, and a dead body if one exists.
• PlayerJoinEvent: Triggered when a player joins the game. Exposes the ClientData of the player.
• PlayerLeaveEvent: Triggered when a player leaves the game. Exposes the ClientData and disconnect reason.

Usables

• EnterVentEvent: Triggered when a player enters a vent. Exposes the player and the vent that was entered. This event can be canceled.
• ExitVentEvent: Triggered when a player exits a vent. Exposes the player and the vent that was exited. This event can be canceled.
• PlayerUseEvent: Triggered when a player uses an IUsable. This is always run locally. Exposes the IUsable, whether it is a vent, and whether it is a "Primary Console" (this includes Consoles, MapConsoles, and SystemConsoles). This event can be canceled.
• PlayerCanUseEvent: Triggered by the HudManager to determine if an IUsable is usable by the local player. This is always run locally. Exposes the same properties as PlayerUseEvent. This event can be canceled.