Skip to main content

Game events

Namespace: DeadworksManaged.Api

A game event is a notice the game fires when something happens: a player dies, picks a hero, or uses an ability. Plugins can listen for any of them.

Find an event​

The event database lists every event in the game. Each event has its own page, such as player_death, that shows its fields.

Commonly used events:

  • player_death: fires when a hero dies.
  • player_respawned: fires when a player respawns.
  • player_hero_changed: fires when a player picks or changes hero.
  • player_used_ability: fires when a player uses an ability, shoots or melees.
  • ability_added: fires when a player gets an ability or an item.

Run code when an event happens​

Put [GameEventHandler] on a method, with the event's name. Every event has a matching class.

[GameEventHandler("player_hero_changed")]
public HookResult OnPlayerHeroChanged(PlayerHeroChangedEvent args)
{
    var pawn = args.Userid?.As<CCitadelPlayerPawn>();
    if (pawn == null) return HookResult.Continue;

    // The player has a hero now

    return HookResult.Continue;
}

Run code when a player dies​

[GameEventHandler("player_death")]
public HookResult OnPlayerDeath(PlayerDeathEvent args)
{
    var victim = args.UseridController;
    var killer = args.AttackerController;

    // killer is null when they weren't killed by a player
    if (victim == null || killer == null) return HookResult.Continue;

    Console.WriteLine($"{killer.PlayerName} killed {victim.PlayerName}");

    if (args.Headshot)
        Console.WriteLine("It was a headshot.");

    return HookResult.Continue;
}

args.UseridPawn is the victim's hero. args.AttackerPawn is the killer's hero.

Run code when a player spawns​

Listen for player_respawned. It fires each time a player comes back to life.

[GameEventHandler("player_respawned")]
public HookResult OnPlayerRespawned(PlayerRespawnedEvent args)
{
    var pawn = args.Userid?.As<CCitadelPlayerPawn>();
    if (pawn == null) return HookResult.Continue;

    pawn.Teleport(position: new Vector3(100, 200, 300));

    return HookResult.Continue;
}
warning

The first time a player joins, player_spawn fires before their hero is ready. Use player_respawned instead.

Run code when a player uses an ability​

[GameEventHandler("player_used_ability")]
public HookResult OnPlayerUsedAbility(PlayerUsedAbilityEvent args)
{
    var pawn = args.Player?.As<CCitadelPlayerPawn>();
    if (pawn == null) return HookResult.Continue;

    Console.WriteLine($"{pawn.Controller?.PlayerName} used {args.Abilityname}");

    return HookResult.Continue;
}

The abilities database lists every ability name.

Run code when a player attacks​

player_used_ability also fires for gunshots and melee hits.

[GameEventHandler("player_used_ability")]
public HookResult OnPlayerAttacked(PlayerUsedAbilityEvent args)
{
    if (args.Abilityname.StartsWith("citadel_weapon_"))
    {
        // They fired their gun
    }

    if (args.Annotation == "heavy_melee")
    {
        // They did a heavy melee
    }

    if (args.Annotation == "light_melee")
    {
        // They did a light melee
    }

    return HookResult.Continue;
}

Run code when a player gets an item​

ability_added fires for abilities and items. Item names start with upgrade_.

[GameEventHandler("ability_added")]
public HookResult OnAbilityAdded(AbilityAddedEvent args)
{
    var pawn = args.Userid?.As<CCitadelPlayerPawn>();
    var name = args.Ability?.SubclassVData?.Name;
    if (pawn == null || name == null) return HookResult.Continue;

    if (name == "upgrade_unstoppable")
        Console.WriteLine($"{pawn.Controller?.PlayerName} got Unstoppable!");

    return HookResult.Continue;
}

Read an event's fields by name​

Each event's class already has a property for each field. Read fields by name only when an event has no class, or its class has a field typed wrong.

Take a GameEvent and read each field by its name. The names are on the event's database page. They're case-sensitive.

[GameEventHandler("player_used_ability")]
public HookResult OnAbility(GameEvent ev)
{
    var name = ev.GetString("abilityname", "");

    Console.WriteLine($"Someone used {name}");

    return HookResult.Continue;
}

GameEvent also has GetInt, GetFloat, GetBool, GetPlayerPawn, GetPlayerController and GetEHandle.

Fire an event yourself​

Create one of the game's events, fill in its fields, and fire it.

var ev = GameEvents.Create("player_hintmessage");
if (ev != null)
{
    ev.SetString("hintmessage", "Hello");
    ev.Fire();
}

Create returns null when the game has no event with that name. You can't create new event types.

Don't use ev again after Fire().