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
- Global prerequisites, via the
- Support powers, via the
- Crates, via the
- Proximity to another actor, via the
UpgradeActorsNeartrait on the source actor.
- Deploying, via the
- Veterancy, via the
UpgradeManagertrait on each actor tracks these upgrade events and then notifies the upgrade consuming traits. There is also a
GlobalUpgradeManagertrait that must be included on the player actor if you wish to use
- Upgrade consumers respond to these events and activate additional functionality or apply attribute modifiers. Traits that define a
UpgradeTypesproperty (see full traits list) can consume upgrade events. The
UpgradeMinEnabledLeveldefines the minimum aggregate upgrade level of the upgrades in the
UpgradeTypesproperty for the trait to be enabled. The
UpgradeMaxEnabledLeveldefines the maximum aggregate upgrade level of the upgrades in the
UpgradeTypesproperty that enables the trait with higher levels disabling it if they are accepted. The
UpgradeMaxAcceptedLeveldefines the maximum aggregate upgrade level of the upgrades in the
UpgradeTypesproperty accepted by the trait with higher levels ignored.
Note: These examples are outdated and do not work with release-20160508.
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:
GrantUpgradePower@IRONCURTAIN: 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
^Building defaults (in mods/ra/rules/defaults.yaml).
UpgradeOverlay@IRONCURTAIN: UpgradeTypes: invulnerability UpgradeMinEnabledLevel: 1 InvulnerabilityUpgrade@IRONCURTAIN: UpgradeTypes: invulnerability UpgradeMinEnabledLevel: 1 TimedUpgradeBar: Upgrade: invulnerability
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.
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.
TimedUpgradeBar trait displays the bar that shows the remaining effect time. The color of the bar can be changed by defining a
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:
UpgradeActorsNear: Upgrades: cloakgenerator Range: 12c0 EnableSound: cloak5.aud DisableSound: cloak5.aud AffectsParent: true WithRangeCircle: Range: 12c0 Type: cloakgenerator
AffectsParent property allows the upgrade to be granted to the stealth generator actor itself.
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:
Cloak@CLOAKGENERATOR: UpgradeTypes: cloakgenerator UpgradeMinEnabledLevel: 1 InitialDelay: 0 CloakDelay: 90
The EMP weapons in the Tiberian Sun mod are implemented using a warhead upgrade source. The
EMPulseCannon weapon in mods/ts/weapons.yaml defines:
EMPulseCannon: 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
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.
^Tank defaults in mods/ts/rules/defaults.yaml then define traits that implement the disabling effect:
UpgradeOverlay@EMPDISABLE: UpgradeTypes: empdisable UpgradeMinEnabledLevel: 1 Palette: disabled DisableUpgrade@EMPDISABLE: UpgradeTypes: empdisable UpgradeMinEnabledLevel: 1 TimedUpgradeBar@EMPDISABLE: Upgrade: empdisable Color: 255,255,255
UpgradeOverlay trait produces the disabled overlay effect by changing the default palette.
DisableUpgrade trait prevents the actor from being able to move or attack.
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:
upgrade.lasertanks: Tooltip: Name: Light Tank Lasers Description: Upgrade Light Tanks with a laser turret Buildable: BuildPaletteOrder: 50 Prerequisites: tmpl, ~techlevel.high Queue: Defence.Nod BuildLimit: 1 Valued: Cost: 1000 RenderSprites: Image: ltnk ProvidesPrerequisite: 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:
Production: Produces: Building.GDI, Buildings.Nod, Defence.GDI, Defence.Nod MoveIntoWorld: false Exit:
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:
GlobalUpgradable: Upgrades: ltnklaser Prerequisites: ltnklaser Armament@gun: Weapon: 70mm UpgradeTypes: ltnklaser UpgradeMaxEnabledLevel: 0 Recoil: 85 RecoilRecovery: 17 LocalOffset: 720,0,90 MuzzleSequence: muzzle Armament@laser: Weapon: Laser UpgradeTypes: ltnklaser UpgradeMinEnabledLevel: 1 Recoil: 85 RecoilRecovery: 17 LocalOffset: 720,0,90
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.
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.