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
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
ProximityExternalConditiontrait on the source actor.
- Deploying, via the
- Veterancy, via the
ConditionManagertrait on each actor tracks these upgrade events and then notifies the upgrade consuming traits. There is also a
GrantConditionOnPrerequisiteManagertrait 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
RequiresConditionproperty (see full traits list) can consume upgrade events.
Note: These examples work with release-20180307
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
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
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
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 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 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
GrantExternalCondition warhead enables the
empdisable upgrade 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
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
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.
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.