Actor Upgrades

Introduction

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.

Examples

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:

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 ^Vehicle, ^Tank, and ^Building defaults (in mods/ra/rules/defaults.yaml).

UpgradeOverlay@IRONCURTAIN:
	UpgradeTypes: invulnerability
	UpgradeMinEnabledLevel: 1
InvulnerabilityUpgrade@IRONCURTAIN:
	UpgradeTypes: invulnerability
	UpgradeMinEnabledLevel: 1
TimedUpgradeBar:
	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:

UpgradeActorsNear:
	Upgrades: cloakgenerator
	Range: 12c0
	EnableSound: cloak5.aud
	DisableSound: cloak5.aud
	AffectsParent: true
WithRangeCircle:
	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:

Cloak@CLOAKGENERATOR:
	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:

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

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:

UpgradeOverlay@EMPDISABLE:
	UpgradeTypes: empdisable
	UpgradeMinEnabledLevel: 1
	Palette: disabled
DisableUpgrade@EMPDISABLE:
	UpgradeTypes: empdisable
	UpgradeMinEnabledLevel: 1
TimedUpgradeBar@EMPDISABLE:
	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:

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

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.