Actor Upgrades

Mazar Farran edited this page Sep 17, 2018 · 12 revisions

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 GrantConditionOnPrerequisite trait.
    • Support powers, via the GrantExternalConditionPower power.
    • Crates, via the GrantExternalConditionCrateAction crate effect.
    • Proximity to another actor, via the ProximityExternalCondition trait on the source actor.
    • Deploying, via the GrantConditionOnDeploy trait.
  • The ConditionManager trait on each actor tracks these upgrade events and then notifies the upgrade consuming traits. There is also a GrantConditionOnPrerequisiteManager trait that must be included on the player actor if you wish to use GrantConditionOnPrerequisite sources.
  • Upgrade consumers respond to these events and activate additional functionality or apply attribute modifiers. Traits that define a RequiresCondition property (see full traits list) can consume upgrade events.

Examples

Note: These examples work with release-20180307

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:

GrantExternalConditionPower@IRONCURTAIN:
	PauseOnCondition: disabled
	Icon: invuln
	ChargeInterval: 3000
	Description: Invulnerability
	LongDesc: Makes a group of units invulnerable\nfor 20 seconds.
	Duration: 500
	SelectTargetSpeechNotification: SelectTarget
	InsufficientPowerSpeechNotification: InsufficientPower
	BeginChargeSpeechNotification: IronCurtainCharging
	EndChargeSpeechNotification: IronCurtainReady
	DisplayRadarPing: True
	Condition: invulnerability
	OnFireSound: ironcur9.aud

The invulnerability effect is implemented using an upgrade consumer defined on the ^IronCurtainable default (in mods/ra/rules/defaults.yaml).

^IronCurtainable:
	WithColoredOverlay@IRONCURTAIN:
		RequiresCondition: invulnerability
	DamageMultiplier@IRONCURTAIN:
		RequiresCondition: invulnerability
		Modifier: 0
	TimedConditionBar:
		Condition: invulnerability
	ExternalCondition@INVULNERABILITY:
		Condition: invulnerability

The WithColoredOverlay 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 palettes.yaml.

The DamageMultiplier 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 TimedConditionBar 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:

WithRangeCircle:
	Range: 12c0
	Type: cloakgenerator
ProximityExternalCondition:
	RequiresCondition: !disabled
	Condition: cloakgenerator
	Range: 12c0
	EnableSound: cloak5.aud
	DisableSound: cloak5.aud
	AffectsParent: true

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 type ^Cloakable in mods/ts/rules/defaults.yaml includes a cloak trait definition:

^Cloakable:
	Cloak@EXTERNALCLOAK:
		RequiresCondition: cloakgenerator || crate-cloak
		InitialDelay: 0
		CloakDelay: 90
		IsPlayerPalette: true
		CloakSound: cloak5.aud
		UncloakSound: cloak5.aud
		UncloakOn: Attack, Unload, Infiltrate, Demolish, Damage, Heal
	ExternalCondition@CLOAKGENERATOR:
		Condition: cloakgenerator
	ExternalCondition@CRATE-CLOAK:
		Condition: crate-cloak

All cloakable actors inherit this base type.

EMP Weapons

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

EMPulseCannon:
	ReloadDelay: 100
	Range: 40c0
	Report: plsecan2.aud
	Projectile: Bullet
		Speed: 425
		Blockable: false
		Shadow: true
		LaunchAngle: 62
		Image: pulsball
	Warhead@1Eff: CreateEffect
		Explosions: pulse_explosion
		ExplosionPalette: effect-ignore-lighting-alpha75
		VictimScanRadius: 0
	Warhead@emp: GrantExternalCondition
		Range: 4c0
		Duration: 250
		Condition: empdisable

The GrantExternalCondition warhead enables the empdisable upgrade for 250 ticks (10 seconds) on any actor within its impact range.

The ^EmpDisable: default in mods/ts/rules/defaults.yaml then defines traits that implement the disabling effect:

^EmpDisable:
	WithColoredOverlay@EMPDISABLE:
		RequiresCondition: empdisable
		Palette: disabled
	TimedConditionBar@EMPDISABLE:
		Condition: empdisable
		Color: FFFFFF
	WithIdleOverlay@EMPDISABLE:
		Sequence: emp-overlay
		Palette: effect
		RequiresCondition: empdisable
		ShowToEnemies: true
		ZOffset: 512
	PowerMultiplier@EMPDISABLE:
		RequiresCondition: empdisable
		Modifier: 0
	ExternalCondition@EMPDISABLE:
		Condition: empdisable

The WithColoredOverlay trait produces the disabled overlay effect by changing the default palette. The TimedConditionBar trait displays the remaining duration as a white bar. The empdisable condition is used to conditionally disable the Mobile and Attack* traits in various actors. For example in the ^Cyborg base trait:

Mobile:
	RequiresCondition: !empdisable

Switching Weapons / Purchasable upgrades

Note: This example is outdated and needs to be reworked.

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 GrantConditionOnPrerequisite 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.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.