Conditions - OpenRA/OpenRA GitHub Wiki

Introduction

Trait conditions were first implemented in playtest-20170303 as a replacement for the older actor upgrades system. It provides a way for certain traits to activate or deactivate other traits in order to build more complicated actor behaviours.

There are three parts to the condition system:

  • Sources that can activate or deactivate conditions on actors. Conditions 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.
  • Each actor tracks these events and then notifies the traits consuming conditions. There is also a GrantConditionOnPrerequisiteManager trait that must be included on the player actor if you wish to use GrantConditionOnPrerequisite sources.
  • Consumers respond to these events and activate additional functionality or apply attribute modifiers. Traits that define a RequiresCondition property (see our Trait Documentation) can can be enabled or disabled using a condition expression. The simplest condition expressions are boolean equations that combine condition variables with && (and) or || (or).

Examples

Note: These examples work with release-20180307

Iron Curtain

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

The Iron Curtain structure (IRON in mods/ra/rules/structures.yaml) defines a condition source that activates the invulnerability condition 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 consumers 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.

Conditions accepted from external sources (e.g. map scripts, warheads, or other actors) need an ExternalCondition on the consuming actor.

Thumpers

Another example of this is the Thumper infantry in Dune 2000, which includes the following yaml (in mods/d2k/rules/infantry.yaml):

	GrantConditionOnDeploy:
		DeployedCondition: deployed
		Facing: 128
		AllowedTerrainTypes: Sand, Spice, Dune, SpiceSand
	Mobile:
		Speed: 43
		RequiresCondition: !deployed
	WithInfantryBody:
		RequiresCondition: !deployed
	WithSpriteBody@DEPLOYED:
		Sequence: thump
		RequiresCondition: deployed
	WithIdleOverlay@DEPLOYED:
		Sequence: thump-sand
		RequiresCondition: deployed
	AmbientSound:
		SoundFile: THUMPER1.WAV
		Interval: 60
		RequiresCondition: deployed
	AttractsWorms:
		Intensity: 1000
		Falloff: 0, 0, 0, 100, 100, 100, 25, 11, 6, 4, 3, 2, 1, 0
		RequiresCondition: deployed

The GrantConditionOnDeploy trait grants a condition named deployed when the player clicks or uses a hotkey to deploy the actor. This condition is then used to disable Mobile (to stop the actor from moving), WithInfantryBody, WithSpriteBody, and WithIdleOverlay to switch the normal infantry artwork with the stationary thumping artwork, AmbientSound to enable the "thumping" sound, and finally AttractsWorms to attract worms to the area.

Stealth Generator

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

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.

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 as 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 condition 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

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
	Buildable:
		BuildPaletteOrder: 50
		Prerequisites: tmpl, ~techlevel.high
		Queue: Defence.Nod
		BuildLimit: 1
		Description: Upgrade Light Tanks with a laser turret
	Valued:
		Cost: 1000
	RenderSprites:
		Image: ltnk
	ProvidesPrerequisite:
		Prerequisite: ltnklaser
	Interactable:
	AlwaysVisible:

(RenderSprites is needed to get the icon of ltnk to display for our upgrade.)

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:

	GrantConditionOnPrerequisite:
		Condition: ltnklaser
		Prerequisites: ltnklaser
	Armament@gun:
		Weapon: 70mm
		RequiresCondition: !ltnklaser
		Recoil: 85
		RecoilRecovery: 17
		LocalOffset: 720,0,90
		MuzzleSequence: muzzle
	Armament@laser:
		Weapon: Laser
		RequiresCondition: ltnklaser
		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 RequiresCondition: !ltnklaser on the original Armament will cause the gun to be disabled when the ltnklaser condition is activated. This is paired with our new laser Armament that becomes enabled with the condition. This has the effect of switching the weapons.