The interfaces OpenRA engine cares about - guidebee/OpenRA GitHub Wiki
In OpenRA, the engine recognizes a set of C# interfaces that define trait behaviors. These interfaces are used to dispatch trait logic at runtime. Here are the most important interfaces the engine knows about for traits (not an exhaustive list, but covers the main ones):
OpenRA Trait Interfaces
Interface Name | Purpose / When Called |
---|---|
ITick |
Called every game tick for logic updates |
IRender |
Called to render overlays, sprites, or debug info |
INotifyDamage |
Called when the actor takes damage |
INotifyCreated |
Called when the actor is created |
INotifyKilled |
Called when the actor is killed |
INotifyRemoved |
Called when the actor is removed from the world |
INotifyOwnerChanged |
Called when the actor's owner changes |
INotifyAttack |
Called when the actor attacks |
INotifyTargeted |
Called when the actor is targeted |
INotifyOrderIssued |
Called when the actor receives an order |
INotifyTraitAdded |
Called when a trait is added to an actor |
INotifyTraitRemoved |
Called when a trait is removed from an actor |
IActorInit |
Called during actor initialization |
IActorPreviewInit |
Called during preview actor initialization |
IResolveOrderTarget |
Used for resolving order targets |
IResolveAttackTarget |
Used for resolving attack targets |
IResolveBuildableArea |
Used for resolving buildable areas |
IResolveFootprint |
Used for resolving actor footprints |
IResolveTooltip |
Used for providing tooltips |
IResolveMapEditorData |
Used for map editor data |
This list covers the most common interfaces. Custom traits can implement any of these to hook into the engine's logic at the appropriate time.
Mobile
Trait Works in OpenRA
How the The Mobile
trait is responsible for enabling movement for actors (units) in OpenRA. It is a core trait used by vehicles, infantry, ships, and other movable entities.
Key Responsibilities
- Handles movement orders (move, stop, attack-move, etc.)
- Manages pathfinding and locomotion (e.g., wheeled, tracked, foot, naval)
- Updates the actor's position each game tick
- Responds to conditions that pause or modify movement (e.g., being captured, disabled)
How It Works
-
Trait Definition
- The
Mobile
trait is defined in the actor's YAML (e.g., under^Vehicle
,^Infantry
, etc.). - Example:
Mobile: Locomotor: wheeled TurnSpeed: 20 PauseOnCondition: being-captured
- The
-
Trait Implementation
- In C#,
Mobile
implements interfaces likeITick
(for per-tick updates) and order handling interfaces. - It contains logic for pathfinding, movement state, and responding to orders.
- In C#,
-
Order Handling
- When an actor receives a move order, the engine dispatches it to the
Mobile
trait. - The trait calculates a path and begins moving the actor toward the target.
- When an actor receives a move order, the engine dispatches it to the
-
Game Loop
- On each tick, the engine calls the
Tick
method onMobile
. - The trait updates the actor's position, checks for arrival, obstacles, or interruptions.
- On each tick, the engine calls the
-
Locomotor Types
- The
Locomotor
property determines movement rules (e.g., speed, terrain passability). - Common types:
wheeled
,tracked
,foot
,naval
.
- The
-
Pausing and Conditions
- The
PauseOnCondition
property allows movement to be paused (e.g., when captured).
- The
Example YAML
^Vehicle:
...
Mobile:
PauseOnCondition: being-captured
Locomotor: wheeled
TurnSpeed: 20
...
OpenRA Trait Interface Lifecycle & Execution Order
1. Actor Creation & Initialization
IActorInit
β Called when the actor is first created.INotifyTraitAdded
β Called for each trait as it is added to the actor.IActorPreviewInit
β Called for preview actors (e.g., build previews).
2. Game Loop (Each Tick)
ITick
β Called every game tick for logic updates (movement, state, etc.).IRender
β Called every render frame to draw overlays, sprites, etc.
3. Orders & Events
INotifyOrderIssued
β Called when the actor receives an order.INotifyAttack
β Called when the actor attacks.INotifyTargeted
β Called when the actor is targeted by something.INotifyDamage
β Called when the actor takes damage.INotifyOwnerChanged
β Called when the actorβs owner changes.
4. Actor Removal & Death
INotifyKilled
β Called when the actor is killed.INotifyRemoved
β Called when the actor is removed from the world.INotifyTraitRemoved
β Called for each trait as it is removed from the actor.
5. Data Resolution (as needed)
IResolveOrderTarget
β Used to resolve order targets.IResolveAttackTarget
β Used to resolve attack targets.IResolveBuildableArea
β Used to resolve buildable areas.IResolveFootprint
β Used to resolve actor footprints.IResolveTooltip
β Used to provide tooltips.IResolveMapEditorData
β Used for map editor data.
The most important lifecycle events are initialization, per-tick updates, event handling (orders, damage, etc.), and cleanup/removal. The engine ensures that all traits implementing a given interface are called in the order they were added to the actor.