Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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
- Global prerequisites, via the
- Support powers, via the
- Crates, via the
- Proximity to another actor, via the
ProximityExternalConditiontrait on the source actor.
- Deploying, via the
- Veterancy, via the
ConditionManagertrait on each actor tracks these events and then notifies the traits consuming conditions. There is also a
GrantConditionOnPrerequisiteManagertrait that must be included on the player actor if you wish to use
- Consumers respond to these events and activate additional functionality or apply attribute modifiers. Traits that define a
RequiresConditionproperty (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
Note: These examples work with release-20180307
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
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.
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.
TimedConditionBar trait displays the bar that shows the remaining effect time. The color of the bar can be changed by defining a
Conditions accepted from external sources (e.g. map scripts, warheads, or other actors) need an
ExternalCondition on the consuming actor.
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
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),
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.
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
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.
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
GrantExternalCondition warhead enables the
empdisable condition for 250 ticks (10 seconds) on any actor within its impact range.
^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
WithColoredOverlay trait produces the disabled overlay effect by changing the default palette.
TimedConditionBar trait displays the remaining duration as a white bar.
empdisable condition is used to conditionally disable the
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
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.
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.