Actor Upgrades

Paul Chote edited this page Jun 11, 2016 · 11 revisions
Clone this wiki locally


The actor upgrades system is a collection of traits and other objects that can be used to apply leveled modifiers to individual actors. There are three parts to the upgrade system:

  • Upgrade sources that can send messages to an actor in order to activate or deactivate upgrades. Upgrade levels can be permanent, timed, or added/removed based on a specific event. Existing upgrade sources include:
    • Veterancy, via the GainsExperience trait.
    • Global prerequisites, via the GlobalUpgradable trait.
    • Support powers, via the GrantUpgradePower power.
    • Crates, via the GrantUpgradeCrateEffect crate effect.
    • Proximity to another actor, via the UpgradeActorsNear trait on the source actor.
    • Deploying, via the DeployToUpgrade trait.
  • The UpgradeManager trait on each actor tracks these upgrade events and then notifies the upgrade consuming traits. There is also a GlobalUpgradeManager trait that must be included on the player actor if you wish to use GlobalUpgradable sources.
  • Upgrade consumers respond to these events and activate additional functionality or apply attribute modifiers. Traits that define a UpgradeTypes property (see full traits list) can consume upgrade events. The UpgradeMinEnabledLevel defines the minimum aggregate upgrade level of the upgrades in the UpgradeTypes property for the trait to be enabled. The UpgradeMaxEnabledLevel defines the maximum aggregate upgrade level of the upgrades in the UpgradeTypes property that enables the trait with higher levels disabling it if they are accepted. The UpgradeMaxAcceptedLevel defines the maximum aggregate upgrade level of the upgrades in the UpgradeTypes property accepted by the trait with higher levels ignored.


Note: These examples are outdated and do not work with release-20160508.

Iron Curtain

The Iron Curtain in the Red Alert mod is now implemented using upgrades.

The Iron Curtain structure (IRON in mods/ra/rules/structures.yaml) defines an upgrade source that activates the invulnerability upgrade on targeted actors:

    Icon: invuln
    ChargeTime: 120
    Description: Invulnerability
    LongDesc: Makes a group of units invulnerable\nfor 20 seconds.
    Duration: 500
    SelectTargetSound: slcttgt1.aud
    InsufficientPowerSound: nopowr1.aud
    BeginChargeSound: ironchg1.aud
    EndChargeSound: ironrdy1.aud
    DisplayRadarPing: True
    Upgrades: invulnerability

The invulnerability effect is implemented using three upgrade consumers defined on the ^Vehicle, ^Tank, and ^Building defaults (in mods/ra/rules/defaults.yaml).

    UpgradeTypes: invulnerability
    UpgradeMinEnabledLevel: 1
    UpgradeTypes: invulnerability
    UpgradeMinEnabledLevel: 1
    Upgrade: invulnerability

The UpgradeOverlay trait produces the red overlay color for invulnerable units. A different overlay color can be used by adding a Palette: mypalettename propery and defining a new palette type in world.yaml.

The InvulnerabilityUpgrade trait grants the actual invulnerability effect. This trait is also used in the Red Alert shellmap to prevent the Allied base from being destroyed.

The TimedUpgradeBar trait displays the bar that shows the remaining effect time. The color of the bar can be changed by defining a Color property.

Stealth Generator

The Stealth Generator in the Tiberian Sun mod (NASTLH in mods/ts/rules/structures.yaml) defines a proximity upgrade source that activates the cloakgenerator upgrade on actors within a range of 12 cells:

    Upgrades: cloakgenerator
    Range: 12c0
    EnableSound: cloak5.aud
    DisableSound: cloak5.aud
    AffectsParent: true
    Range: 12c0
    Type: cloakgenerator

The AffectsParent property allows the upgrade to be granted to the stealth generator actor itself. The WithRangeCircle trait draws the range circle around the actor.

Each of the base default types in mods/ts/rules/defaults.yaml includes a cloak trait definition:

    UpgradeTypes: cloakgenerator
    UpgradeMinEnabledLevel: 1
    InitialDelay: 0
    CloakDelay: 90

EMP Weapons

The EMP weapons in the Tiberian Sun mod are implemented using a warhead upgrade source. The EMPulseCannon weapon in mods/ts/weapons.yaml defines:

    ReloadDelay: 100
    Range: 10c0
    Report: PLSECAN2.AUD
    Projectile: Bullet
        Speed: 425
        High: yes
        Shadow: true
        Angle: 62
        Image: pulsball
    Warhead@2Eff: CreateEffect
        Explosion: pulse_explosion
# Dummy warhead to allow targeting
    Warhead@target: SpreadDamage
        Spread: 0
        Damage: 0
        ValidTargets: Vehicle
    Warhead@emp: GrantUpgrade
        Range: 3c0
        Duration: 250
        Upgrades: empdisable
        ValidTargets: Vehicle

The GrantUpgrade warhead enables the empdisable upgrade for 250 ticks (10 seconds) on any actor that defines the Vehicle target type within its impact range. The SpreadDamage warhead is currently required for targeting purposes, but does no damage of its own.

The ^Vehicle and ^Tank defaults in mods/ts/rules/defaults.yaml then define traits that implement the disabling effect:

    UpgradeTypes: empdisable
    UpgradeMinEnabledLevel: 1
    Palette: disabled
    UpgradeTypes: empdisable
    UpgradeMinEnabledLevel: 1
    Upgrade: empdisable
    Color: 255,255,255

The UpgradeOverlay trait produces the disabled overlay effect by changing the default palette. The DisableUpgrade trait prevents the actor from being able to move or attack. The TimedUpgradeBar trait displays the remaining duration as a white bar.

Switching Weapons / Purchasable upgrades

The ability to purchase upgrades and switch weapons is illustrated by adding an upgrade to the Tiberian Dawn mod that replaces the Light Tank's gun with the Obelisk laser. This is not likely to be implemented in the default mod.

First check that the Player actor (mods/cnc/rules/player.yaml) defines the GlobalUpgradeManager trait. The Tiberian Dawn mod already includes this, so we can move to the next step.

Next, we define a system actor that allows the upgrade to be purchased. In mods/cnc/rules/misc.yaml we add:

        Name: Light Tank Lasers
        Description: Upgrade Light Tanks with a laser turret
        BuildPaletteOrder: 50
        Prerequisites: tmpl, ~techlevel.high
        Queue: Defence.Nod
        BuildLimit: 1
        Cost: 1000
        Image: ltnk
        Prerequisite: ltnklaser

We must now tweak the construction yard rules so that it can produce the upgrade actor. Change the FACT definition in mods/cnc/rules/structures.yaml to specify:

        Produces: Building.GDI, Buildings.Nod, Defence.GDI, Defence.Nod
        MoveIntoWorld: false

The combination of MoveIntoWorld: false and the empty Exit trait allows the construction to complete, spawning the system actor outside the world.

Finally, we can modify the ltnk definition (in mods/cnc/rules/vehicles.yaml) to enable the upgrade. Replace the existing armament definition with:

    Upgrades: ltnklaser
    Prerequisites: ltnklaser
    Weapon: 70mm
    UpgradeTypes: ltnklaser
    UpgradeMaxEnabledLevel: 0
    Recoil: 85
    RecoilRecovery: 17
    LocalOffset: 720,0,90
    MuzzleSequence: muzzle
    Weapon: Laser
    UpgradeTypes: ltnklaser
    UpgradeMinEnabledLevel: 1
    Recoil: 85
    RecoilRecovery: 17
    LocalOffset: 720,0,90

The GlobalUpgradable trait acts to bridge the (global) prerequisite provided by the ProvidesPrerequisite trait to a (local) upgrade on the actor.

Because we are now specifying multiple Armaments we must distinguish them by adding different suffixes after the @. These have the sole purpose of making the definitions unique (like the ModuleTag strings in the C&C Generals rules), but the game attributes no other meaning to them.

The UpgradeTypes: ltnklaser with UpgradeMaxEnabledLevel: 0 on the original Armament will cause the gun to be disabled when the ltnklaser upgrade is activated. This is paired with our new laser Armament that becomes enabled with the upgrade. This has the effect of switching the weapons.