Entity I/O

Namespace: DeadworksManaged.Api

Entities in a map talk to each other with inputs and outputs.

• An output is something an entity announces. A trigger fires OnStartTouch when something walks into it.
• An input is something you tell an entity to do. A button takes Kill to remove itself.

Your plugin can listen for both, block them, and send inputs of its own.

Find an entity's inputs and outputs

The entity database lists the inputs and outputs of every entity. See trigger_multiple for an example.

Run code when an entity fires an output

Put [EntityOutputHook] on a method, with the entity's name and the output's name.

[EntityOutputHook("trigger_multiple", "OnStartTouch")]
public HookResult OnTriggerTouched(EntityOutputEvent e)
{
    var pawn = e.Activator?.As<CCitadelPlayerPawn>();
    if (pawn == null) return HookResult.Continue;

    Console.WriteLine($"{pawn.Controller?.PlayerName} walked into a trigger");

    return HookResult.Continue;
}

e.Activator is the entity that triggered the output, usually a player's hero. e.Caller is the entity that fired the output.

Block an output

Return HookResult.Stop, and nothing connected to that output happens.

[EntityOutputHook("trigger_multiple", "OnStartTouch")]
public HookResult OnTriggerTouched(EntityOutputEvent e)
{
    return HookResult.Stop;
}

Run code when an entity receives an input

Put [EntityInputHook] on a method, with the entity's name and the input's name.

[EntityInputHook("func_button", "Kill")]
public HookResult OnButtonKilled(EntityInputEvent e)
{
    Console.WriteLine($"{e.Entity.DesignerName} was told to remove itself");

    return HookResult.Continue;
}

e.Entity is the entity receiving the input.

Block an input

Return HookResult.Stop, and the entity never receives it.

[EntityInputHook("func_button", "Kill")]
public HookResult OnButtonKilled(EntityInputEvent e)
{
    return HookResult.Stop;
}

Run code after an input or output

Add HookMode.Post and return void. Your method runs once the input or output has already happened, so it can't block it.

[EntityInputHook("func_button", "Kill", HookMode.Post)]
public void OnButtonKilled(EntityInputEvent e)
{
    Console.WriteLine("The button is gone");
}

Listen to every entity

Use "*" in place of the entity's name, the input or output's name, or both.

[EntityOutputHook("*", "OnStartTouch")]
public HookResult OnAnythingTouched(EntityOutputEvent e)
{
    Console.WriteLine($"{e.CallerClass} was touched");

    return HookResult.Continue;
}

e.CallerClass is the name of the entity that fired the output.

Read the value sent with an input or output

Some inputs and outputs carry a value. Read it from e.Value with the method for its type.

[EntityInputHook("*", "SetMessage")]
public HookResult OnSetMessage(EntityInputEvent e)
{
    string text = e.Value.AsString();

    Console.WriteLine($"{e.ClassName} was given the message: {text}");

    return HookResult.Continue;
}

e.Value also has AsInt, AsFloat, AsBool, AsVector3, AsColor and AsEntity. AsString works for any type.

warning

e.Value stops working once your method returns. Read it inside your method, and don't store it for later.

Start and stop listening from code

Use EntityIO.HookOutput or EntityIO.HookInput. Each returns a handle. The hook stays active until you call Cancel on the handle.

var hook = EntityIO.HookOutput("trigger_multiple", "OnStartTouch", e =>
{
    Console.WriteLine("Something walked into a trigger");
});

// Stop listening
hook.Cancel();

To block the input or output, return a HookResult from the handler.

Send an input to an entity

entity.AcceptInput("Kill");

To send a value with it:

entity.AcceptInput("SetMessage", value: "ROUND 2");

Run code when a player dies

Players don't fire outputs like OnDeath. Use the player_death game event for that.

[GameEventHandler("player_death")]
public HookResult OnPlayerDeath(PlayerDeathEvent args)
{
    Console.WriteLine($"{args.UseridController?.PlayerName} died");

    return HookResult.Continue;
}

See also

• Game events: events the game fires, such as player_death.
• Entities: find, create and remove entities.