ActorIO

About

Actor I/O is a level scripting tool for Unreal Engine, featuring an input/output system similar to the Source Engine by Valve™ Software. At its heart, the plugin is an event binding system where actions are executed in reaction to an event being triggered. Using the C++ reflection system of Unreal Engine, the system can react to any dynamic delegate be it C++ or blueprint, and essentially call any function by name with parameters.

The plugin is also available on FAB: Actor IO Level Scripting

Usage

In order to use the I/O system you need to add ActorIOActions to actors. Actions are the driving force behind the whole system. Each action represents an event binding, which calls the designated function when that event is triggered. Actions exist in the game world as objects, with their lifetime tied to the actor - more specifically the ActorIOComponent of the actor.

Go to Windows → Actor I/O to open the action editor tab. The editor is broken up into two tabs: Outputs and Inputs. The Outputs tab is your main editing environment, it shows all actions that are tied to this actor. You can add new actions to the actor with the "New Action" button.

The Inputs tab shows all actions that are targeting this actor. This tab is purely for debugging and overview purposes. You cannot edit or change actions from here, only from the calling actor.

The I/O system was designed in a way to be easily extensible. You can register custom events and functions with the I/O system for any of your actors using the ActorIOInterface. Here is a quick rundown on how you can expose custom events and functions:

1. Add the ActorIOInterface to your actor.
2. Override the RegisterIOEvents and RegisterIOFunctions of the I/O interface.
3. Use RegisterIOEvent to expose a C++ dynamic delegate, or blueprint event dispatcher.
4. Use RegisterIOFunction to expose a C++ UFUNCTION, blueprint function, or blueprint custom event.
5. After compiling and saving, your custom events and functions should now appear in the I/O editor for the actor.

Logic Actors

Logic Actors are small "script-like" actors that help you create more complex level scripting logic. They usually only serve one specific purpose, so they can be used in any combination when working on levels. The plugin comes with a collection of logic actors such as Branch, Relay, Counter, Spawner, etc. All logic actors can be found in Window → Place Actors.

You can also create custom logic actors by subclassing the LogicActorBase class. The idea is that you create your own logic actors that interact with different parts of your game, such as adding/removing items from the player's inventory, updating the current objective, or starting an ambush that spawns enemies.

For more information visit: Logic Actors

Introduction Video

Check out this introduction video showcasing the plugin in action, as well as some of the key concepts.

Sample Project

A top-down shooter game is also available, showcasing how Actor I/O can be used for level scripting in Unreal Engine. See: Actor I/O Shooter Sample

<img width="378" height="241" alt="screenshot_1" src="https://github.com/user-attachments/assets/7e7a87dc-8909-449d-924c-7b21bfec1ec2" /> <img width="378" height="241" alt="screenshot_2" src="https://github.com/user-attachments/assets/9db8ce28-7099-4ad2-ad81-f65bc2a272f4" />

Why Use This?

You may be wondering why use this over blueprint interfaces? Aren't these the same thing?

While the system may look similar to regular interfaces, behind the scenes they are completely different. In fact, this is much closer to event bindings rather than interfaces. There is nothing wrong with using interfaces for hooking up game logic together, but it requires you to have a fairly robust system to be flexible enough. Again, not an issue just a different approach.

The biggest advantage of this approach is reduced memory usage, since you can avoid blueprint Casting with the I/O system. This can significantly lower memory usage, as the Cast node in Unreal causes the selected class to be loaded into memory with the blueprint. In larger projects, this can quickly spiral out of control if not managed properly. The I/O system can help you cut down on a lot of Cast nodes as the system uses the C++ reflection system to access members of a class, without casting to it.

Debugging

The plugin is integrated with the Map Check feature of Unreal in Build → Map Check. Use this to find build time errors, such as actions with invalid targets or function names.

All error messages and issues are logged to the Output Log in Window → Output Log. Use the -log launch parameter to see logs when you are not playing in the editor (e.g. in Standalone Game play mode, or packaged builds).

Useful console commands to use:

• ActorIO.DebugActions <bool>: Enable I/O action execution messages. Enabled by default.
• ActorIO.WarnAboutInvalidTarget <bool>: Warn about missing or invalid target actor when executing I/O action.
• ActorIO.LogNamedArgs <bool>: Log named arguments to console when executing I/O action.
• ActorIO.LogFinalCommand <bool>: Log the final command sent to the target actor after executing I/O action.

Help

• Documentation: https://horizongames.gitbook.io/actorio
• Discord: Horizon Games
• Email: horizongames.contact@gmail.com