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.

How the Mobile Trait Works in OpenRA

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

  1. 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
      
  2. Trait Implementation

    • In C#, Mobile implements interfaces like ITick (for per-tick updates) and order handling interfaces.
    • It contains logic for pathfinding, movement state, and responding to orders.
  3. 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.
  4. Game Loop

    • On each tick, the engine calls the Tick method on Mobile.
    • The trait updates the actor's position, checks for arrival, obstacles, or interruptions.
  5. Locomotor Types

    • The Locomotor property determines movement rules (e.g., speed, terrain passability).
    • Common types: wheeled, tracked, foot, naval.
  6. Pausing and Conditions

    • The PauseOnCondition property allows movement to be paused (e.g., when captured).

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.