Objects & Modules

Object Improvements

Upgrade Cameos

Added support for UpgradeCameo6-9 slots. These need to be defined in the controlbar .wnd files to work.

WeaponSet

Added new parameters to an object's WeaponSet definition

• WeaponReloadSharedAcrossSets = No - If a unit switched between weaponset, it's reload time and ammo count (in percent) will be kept. For instance Migs will not reload in air when they get BlackNapalm.
• ShareWeaponClip = No - (If Yes, all weapon slots in this WeaponSet draw from one shared ammo clip instead of reloading independently: firing any slot also ticks down the clip of every other slot in the set.)

AutoChooseSources

Added new types for AutoChooseSources

• SYNC_TO_PRIMARY - This weapon slot cannot fire on its own, but will be fired whenever PRIMARY is fired.
• SYNC_TO_SECONDARY - This weapon slot cannot fire on its own, but will be fired whenever SECONDARY is fired.
• SYNC_TO_TERTIARY - This weapon slot cannot fire on its own, but will be fired whenever TERTIARY is fired.

Syncs a weapon slot to another. The weapon slot cannot be used except when it's parent weapon is fired. This ignores all conditions and checks of the synced weapon.

Example:

Weapon = PRIMARY MainWeapon
Weapon = SECONDARY SyncedWeapon
AutoChooseSources = SECONDARY SYNC_TO_PRIMARY

In this example, the secondary weapon SyncedWeapon will not be used on its own. Whenever the unit attacks with its primary MainWeapon, the secondary weapon will be fired as well. This can be used for Aircraft to reliably fire multiple weapons on each attack.

AmmoPips style

Added options to customize Ammo Pips, e.g. for Aircraft with a very large clip size.

Added a new parameter for object definitions:

• AmmoPipsStyle = DEFAULT - (Change the unit's display style for ammo pips to one of these:)
  • DEFAULT - default ZH style; 1 yellow pip symbol for each shot.
  • PERCENTAGE_BAR - display a yellow bar similar to the health bar, showing the ammo count in percent.
  • SINGLE - default ZH pip visuals, but only show a single symbol regardless of clip size. Ammo count is displayed via fading yellow color.

Note: This parameter might be moved to individual weapons in the future, to allow displaying ammo pips for multiple weapon slots at once.

Object Modules

AIUpdateInterface (And all other AIUpdate types)

New experimental parameter:

• PreferredAttackAngle = <angle> [MIRRORED] - (mirrored keyword is optional) When a unit turns to attack, it will attempt to turn to this angle. If mirrored is enable it can also use the same angle +180°. Possibly useful for battleship setups with multiple turrets. Only works for locomotors that can turn in place (minTurnSpeed = 0) Note: this is NOT needed for limited turret angles (See below). Units will follow the actual turret angles when trying to attack.

Minimum range handling (reversing)

New parameters for vehicles with a weapon MinimumAttackRange, mainly slow-turning units without a turret (e.g. artillery). They use the locomotor's reverse movement, so the locomotor needs CanMoveBackwards = Yes (see Locomotor).

• MinRangeRetreatStraight = No - (When the unit is inside its weapon's minimum range, it backs off straight away from the target, just far enough to get back into range (min range + one pathfind cell). Without it the pathfinder picks the nearest valid cell, often to the side, which is a long arc for slow-turning vehicles and leaves them facing the wrong way. Falls back to normal attack pathfinding if the straight spot is blocked. Ground units only.)
• AimByReversing = No - (Units without a turret that have to turn to aim: if the target is in front and a forward turn would carry the unit into its minimum range, it turns by backing up instead. Once it started reversing it keeps reversing until aligned. Not used if turning would take the unit out of its maximum range.)
• AimByReversingMaxAngle = 90 - (Only reverse to aim if the target is at most this many degrees off the nose.)
• AimByReversingMargin = 10.0 - (Safety margin, in world units, added to the minimum range in the "would a forward turn get too close" test.)
• AimByReversingTurnFactor = 1.0 - (Scales the estimate of how much closer a forward turn brings the unit (turn radius × sin(angle)). Raise it if units still drive into their minimum range while turning, lower it if they reverse too eagerly.)

Behavior = AIUpdateInterface ModuleTag_AI
  ...
  MinRangeRetreatStraight = Yes
  AimByReversing = Yes
  AimByReversingMaxAngle = 90
End

Turret

New paramters for Turret or AltTurret entries

• MinTurretAngle = 0 - Minimum angle the turret is allowed to turn
• MaxTurretAngle = 0 - Maximum angle the turret is allowed to turn Notes:

• for backwards facing configurations, MaxTurretAngle can be > MinTurretAngle; Currently this is not working 100% reliably
• Remove the angle limit lines to use unlimited angle. A value of 0 will use 0 as limit.
• If the turret cannot turn to the front (e.g. side mounted gun on a helicopter), the unit will attempt to turn to the turret's firing arc
  • this feature only works for locomotors that can turn in place (minTurnSpeed = 0)

WeaponSetUpgrade

Added new parameters for WeaponSetUpgrade

• WeaponSetFlag = <WeaponSetFlag> - define which Weaponset to enable (default = PLAYER_UPGRADE)
• WeaponSetFlagsToClear = <WeaponSetFlag1> <WeaponSetFlag2> .. - define which Weaponsets to disable
• NeedsParkedAircraft = No - Units with JetAIUpdate need to be parked in hangar to research this upgrade

Notes: WeaponSetFlagsToClear can be used to switch between WeaponSets using multiple upgrades. example:

  Behavior = WeaponSetUpgrade ModuleTag_04a
    WeaponSetFlag = PLAYER_UPGRADE
    WeaponSetFlagsToClear = PLAYER_UPGRADE2 PLAYER_UPGRADE3
    TriggeredBy = Upgrade_GLAWorkerFakeCommandSet
    RemovesUpgrades = Upgrade_GLAWorkerRealCommandSet Upgrade_GLAWorkerFakeCommandSet Test_Upgrade_DummyToggle
  End
  
  Behavior = WeaponSetUpgrade ModuleTag_04b
    WeaponSetFlag = PLAYER_UPGRADE2
    WeaponSetFlagsToClear = PLAYER_UPGRADE PLAYER_UPGRADE3
    TriggeredBy = Upgrade_GLAWorkerRealCommandSet
    RemovesUpgrades = Upgrade_GLAWorkerRealCommandSet Upgrade_GLAWorkerFakeCommandSet Test_Upgrade_DummyToggle
  End
  
  Behavior = WeaponSetUpgrade ModuleTag_04c
    WeaponSetFlag = PLAYER_UPGRADE3
    WeaponSetFlagsToClear = PLAYER_UPGRADE PLAYER_UPGRADE2
    TriggeredBy = Test_Upgrade_DummyToggle
    RemovesUpgrades = Upgrade_GLAWorkerRealCommandSet Upgrade_GLAWorkerFakeCommandSet Test_Upgrade_DummyToggle
  End

You can combine this with NeedsParkedAircraft to allow Jets to switch their ammo type when parked using multiple object upgrades.

ArmorUpgrade

Added new parameters for ArmorUpgrade

• ArmorSetFlag = <ArmorSetFlag> - define which Armorset to enable (default = PLAYER_UPGRADE)
• ArmorSetFlagsToClear = <ArmorSetFlag1> <ArmorSetFlag2> .. - define which ArmorSets to disable

Notes: ArmorSetFlagsToClear can be used to switch between ArmorSets using multiple upgrades (see WeaponSetUpgrade).

LocomotorSetUpgrade

Added new parameters for LocomotorSetUpgrade

• EnableUpgrade = No - (if 'Yes' (default), locomotor is switched to SET_NORMAL_UPGRADED; if 'No' locomotor is switched back to SET_NORMAL)
• ExplicitLocomotorType = SET_SUPERSONIC - Optional; explicitly switch to the defined locomotor set (This is not persistant, unlike EnableUpgrade)

Notes: EnableUpgrade only allows for a single locomotor upgrade, but it can be toggled on/off with multiple upgrades. With ExplicitLocomotorType, Locomotor sets can be set freely, but they will not persist if the unit changes its locomotor through other means (e.g. Aircraft taking off, or combat bike switching rider)

MaxHealthUpgrade

Added new parameter for MaxHealthUpgrade

• MultiplyMaxHealth = 1.0 - (multiplier on the unit's current HP; default = 1.0 -> no change.)

Notes:

• It is recommended to change all health upgrades to multiplicative as they will not be affected by other HP changes like veterancy, and can be freely stacked (and even reversed).
• You can still use AddMaxHealth for additive boni, and could even combine it with MultiplyMaxHealth. The formula is NewHP = (CurrentHP * MultiplyMaxHealth) + AddMaxHealth.

ArmorDamageScalarUpdate (New)

This module was designed for a temporary armor buff ability. The module will apply a damage/armor scale value to every unit in the area for the given amount of time. In addition, various visual effects can be added.

example:

Behavior = ArmorDamageScalarUpdate ModuleTag_01
    AllowedAffectKindOf = VEHICLE STRUCTURE  ; (required; any object matching *any* of these KindOfs is a valid target)
    ForbiddenAffectKindOf = INFANTRY  ; (optional; any object matching *any* of these KindOfs is an invalid target)
    AffectsTargets = ALLIES NEUTRALS  ; (required; any combination of ALLIES, NEUTRALS, ENEMIES)
    AffectAirborne = Yes   ; (default = Yes; Should this affect units currently in the air) 
    BonusDuration = 10000     ; (required; How long effect lasts, in ms)
    BonusRange = 100     ; (required; Radius of the effect)
    ArmorDamageScalar = 0.9;   ; (default = 1.0; damage scalar to apply; 1.0 = no effect; 0.5 = takes half damage; 2.0 = takes double damage; min = 0.01)
    EffectParticleSystem = <entry from particlesystem.ini>  ; (optional; apply particlesystem to affected objects. SystemLifeTime is scaled automatically. If VolumeType = BOX, the size will be changed to the object's geometry.)
    OverrideDamageFX = <entry from damageFX.ini> ; (optional; change the object's DamageFX to this entry over the duration)
    ScaleParticleSystem = Yes  ; (default = No; If enabled, the particle system's spawn rate will be adjusted for the object's size)
    ApplyColorTint = Yes  ; (default = No; Apply a dark red color tint to the objects for the duration)
End

Notes:

• This module is designed to be put on a dummy object marker, like for EmergencyRepair or Frenzy.
• To correctly track the objects over the duration, the marker object needs to stay alive for the duration. Lifetime is tracked in the module itself. You do not need to add a lifetimeupdate as well. If the object is killed earlier, the effect will be removed from all units.
• The effect is applied once at the beginning. Objects leaving or entering the radius later will not get the effect.
• The module can be used to apply a damage increase to enemy units (i.e. lower their armor)

CostModiferUpgrade

New Parameters added. Example:

Behavior = CostModiferUpgrade ModuleTag_123
  TriggeredBy = Upgrade_CostReduction  ; entry from upgrade.ini
  EffectKindOf = VEHICLE  ; Units with this KindOf will be affected
  Percentage = -20%  ; amount that cost will be reduced
  IsOneShotUpgrade = No  ; (NEW) Is this a one time global upgrade, or should it be removed when the object dies or changes owner?
  BonusStacksWith = DIFFERENT_VALUE  ; (NEW) Stacking behavior when multiple bonus sources exist
End

** BonusStacksWith types **

• DIFFERENT_VALUE - Default behavior: Does not stack with other bonus with the same value. Does stack with bonus with different value.
• OTHER_TYPE - Does stack with bonus from other type of unit with the same value. Does not stack with bonus from the same type of unit. I.e. Multiple OilRefineries would not stack, but a Refinery would stack with an IndustrialPlant if it had the same value.
• SAME_TYPE - Bonus from multiple sources of the same type will stack. I.e. Owning multiple Refineries grants additional bonus.

Notes:

• Bonus stacking is additive, not multiplicative

ProductionTimeModiferUpgrade (New)

This works just like CostModiferUpgrade (Oil Refinery) to apply a global production time reduction for the given KindOf example:

Behavior = ProductionTimeModifierUpgrade ModuleTag_123
  TriggeredBy = Upgrade_CostReduction  ; entry from upgrade.ini
  EffectKindOf = VEHICLE  ; Units with this KindOf will be affected
  Percentage = -20%  ; amount that build time will be reduced
  IsOneShotUpgrade = No  ; Is this a one time global upgrade, or should it be removed when the object dies or changes owner?
  BonusStacksWith = DIFFERENT_VALUE  ; Stacking behavior when multiple bonus sources exist
End

ExperienceScalarUpgrade

Added parameter to make module active by default (useful for negativ scalars):

• StartsActive = False

Update: removed this, because it didn't work. You will need to grant a dummy upgrade instead.

Added new parameter to modify XP value of a unit (i.e. XP that is gained for the enemy when the unit is killed)

• AddXPValueScalar = 0.0 - Additive modifier for XP value scalar. I.e.: XPValueNew = XPValueOld * (1.0 + AddXPValueScalar).

• SetMaxVeterancyLevel = <VeterancyLevel> - (Raises the unit's maximum veterancy level (e.g. to LEVEL_FOUR or LEVEL_FIVE) when this upgrade is active. Lets you unlock the extra veterancy levels via an upgrade. See Veterancy Object Parameters.)

Laser Improvements

LaserUpdate

New parameters are added to allow the laser to grow/shrink or fade in/out

• BeamFadeInDuration = 0 - (time in ms. Alpha scalar is linear interpolated from 0 to 1 over the given time at the start.)
• BeamFadeOutDuration = 0 - (time in ms. Alpha scalar is linear interpolated from 1 to 0 at the end of the beam's lifetime. Requires LifetimeUpdate)
• BeamGrowDuration = 0 - (time in ms. Beam width is linear interpolated from 0 to 1 over the given time at the start.)
• BeamShrinkDuration = 0 - (time in ms. Beam width is linear interpolated from 1 to 0 at the end of the beam's lifetime. Requires LifetimeUpdate)
• UseMultiLaserDraw = No - (This flag is needed, if a Laser object has multiple LaserDraw modules, to correctly update all of them)
• UseHouseColoredParticles = No - (Apply house colored tint to the laser's muzzle and target particle systems)

W3DLaserDraw

Added parameters to specify grid animation. Currently only a 1xn grid is allowed (i.e. multiple columns) to work together with scrollRate.

• TextureGridTotalColumns = 1 - (total number of columns in the texture)
• TextureGridColumns = 1 - (actual number of columns used for the animation)
• UseHouseColorOuter = No - (apply house color to the laser's outer color)
• UseHouseColorOuter = No - (apply house color to the laser's inner color)

Note: Usually both TextureGridColumns and TextureGridTotalColumns numbers would be the same. But having separate numbers allows to use an odd number of frames and still keep proper DDS texture sizes. E.g. you have a texture width of 512, with 8 frames of 64. But you only want 7 frames, so you can set TextureGridTotalColumns=8 and TextureGridColumns=7.

MissileAIUpdate

Added new parameters to MissileAIUpdate module:

• RandomPathOffset = 0.0 - distance in meters. Missile projectils will spread out randomly to fly a random arc pattern for more interesting visuals.

• ZCorrectionFactor = 2.0 - Missiles attacking air units will have their direction shifted upwards by this factor. (2.0 is vZH default)

• ApplyLauncherBonus = No - Any extra weapon that is fired from the projectile (On death, fireweaponupdate, etc.) will inherit the shooter's weapon bonus values

Notes:

• ZCorrectionFactor is what causes AA missiles in vZH to be never aligned to the launcher. For units with actual fire pitch (e.g. Patriot), it is recommended to set this value to 0. For units that cannot pitch (e.g. Missile Defender) a value between 1 and 2 is recommended.

DumbProjectileBehavior

New parameters:

• ApplyLauncherBonus = No - Any extra weapon that is fired from the projectile (On death, fireweaponupdate, etc.) will inherit the shooter's weapon bonus values

• DynamicHeightMinScale = 1.0 - (Scales the projectile's arc height based on the distance to the target. At maximum weapon range the full arc height is used; the closer the target, the more the height is scaled down towards this value. 1.0 = no scaling (default). Useful so short-range shots don't arc as high, e.g. for torpedoes/arcing guns.)

• DynamicHeightMinRange = 1.0 - (The target distance at/below which DynamicHeightMinScale is fully reached. The height scale interpolates between this range and the weapon's max range.)

• LinearFlightPath = No - (If Yes, the projectile flies a straight line from launch point to target at constant speed instead of the Bezier arc. The arc parameters (FirstHeight, SecondHeight, FirstPercentIndent, ...) are ignored.)

• KillSelfDelay = 0 - (Time in ms the projectile lingers at the impact point after detonating before it dies. During that time it is hidden, frozen in place and has no collisions, but its exhaust and model-condition particle systems keep emitting, so trails can catch up instead of being cut off. The detonation weapon still fires immediately; only the death (and its die modules) is delayed. 0 = die immediately (old behavior).)

Notes:

• Lingering projectiles are ignored by PointDefenseLaserUpdate and no longer trigger ScatterShotUpdate.

FreeFallProjectileBehavior

New type of projectile module that mimics the behavior of Bombs dropped by genpowers. Projectiles will move based on physics, making it suitable for carpet bomb or strafing run aircraft weapons. On collision, the weapon's damage and detonation effects are applied.

Example:

Behavior = FreeFallProjectileBehavior ModuleTag_009
   MaxLifespan = 10000  ; Maximum lifetime of the object
   TumbleRandomly = No  ; Adds random rotation, same as for DumbProjectileBehavior
   CourseCorrectionScalar = 1.0   ; guide the bomb towards the intended target. 1=no homing, 0=snapto; 0.99=smooth, 0.95=too-fast
   UseWeaponSpeed = No   ; apply additional speed from the unit's weapon
   ExitPitchRate = 0 ; Angle tilt per second to apply (respects centerOfMassOffset in the projectile's physics)
   ApplyLauncherBonus = Yes  ; Apply weapon bonus from launcher for any secondary weapon effects
   DetonateOnGround = Yes   ; Will the projectile detonate when hitting the ground or live on (to bounce or rest on ground)?
   DetonateOnCollide = Yes    ; Same as above, when hitting another object (See Weapon for collission settings)
   GarrisonHitKillRequiredKindOf = <Kindof list>  ; Same as MissileAI/DumbProjectile
   GarrisonHitKillForbiddenKindOf= <Kindof list>  ; Same as MissileAI/DumbProjectile
   GarrisonHitKillCount = 0  ; Same as MissileAI/DumbProjectile
   GarrisonHitKillFX = <FXList>  ; Same as MissileAI/DumbProjectile
End

Notes:

• This module's behavior depends a lot on the projectile's physics settings, such as mass, friction, etc. It takes some finetuning to get the exact behavior you want.
• For basic carpet bombing, you can copy the settings from existing genpowers.

ScatterShotUpdate (New)

New module intended for weapon projectiles, to allow scattering in mid air and fire multiple shots to targets within range.

Parameters:

• Weapon = - (The weapon to be fired at targets.)
• NumShots = - (default = 0; number of shots to fire)
• TargetSearchRadius = - (default = 0; range around the weapon's target location or object that we look for targets)
• TargetMinRadius = - (default = 0; minimum range targets need to be away from the original target)
• MaxShotsPerTarget = - (default = 0; How many shots to fire at each target. 0 = randomly attack ground only; 1 = attack each target once; >1 when each target was attacked once, start from the beginning)
• PreferSimilarTargets = - (default = No; Choose air or ground targets similar to the main target object. I.e. if we attack an air unit, all targets will be picked from air units first)
• PreferNearestTargets = - (default = No; Prefer targets closest to the original target; Otherwise choose randomly)
• NoTargetsScatterRadius = - (default = 0; If not targets were found/picked, use this random scatter radius to attack the ground)
• NoTargetsScatterMinRadius = - (default = 0; Minimum scatter radius when no target is found)
• NoTargetsScatterMaxAngle = - (default = 0; Acceptable aim delta angle for scatter targets)
• AttackGroundWhenNoTargets = - (default = yes; If Yes, when we run out of targets, fire randomly at the ground; If No, do not fire.)
• AvoidOriginalTargetObject = - (default = no; If Yes, we never try to hit the original target of the attack)
• AvoidPreviousTargetWhenChain = - (default = no; When the attack was fired from another ScatterShot module, avoid that modules original target)
• TriggerDistanceToTarget = - (default = 0; How close the projectile needs to be to the target to trigger the scatter shot.)
• TriggerLifetime = - (default = 0; How long after the projectile was created to trigger the scatter shot. 0 = no limit.)
• TriggerOnImpact = - (default = No; Trigger scatter shot on projectile impact.)
• TriggerInstantly = - (default = No; Trigger scatter shot instantly after the projectile was created)
• StayAliveAfterTrigger = - (default = No; The original weapon's projectile will stay alive after the scatter shot was triggered.)
• TriggeredDeathType = - (default = NORMAL; The death type to use for the projectile object when the scatter shot is triggered.)
• ScatterFX = - (default = None; entry from FXList.ini to play when scatter shot is triggered.)

Notes:

• The weapon used for the scatter shot needs to have a clip size large enough to fire all shots.
• When picking targets for the scatter shots, they need to be viable targets for the weapon's damage type.
• When the original weapon targets an object, that original target will always be picked to fire a scatter weapon at.
• This module can be used on non-projectile objects as well (using lifetime or instant triggers), e.g. to create an object that fires at multiple units in range simultaneously

Examples:

  Behavior = ScatterShotUpdate ModuleTag_Scatter
    Weapon = TomahawkMissileScatterWeapon    ; simple guided rocket weapon
    NumShots = 5
    TargetSearchRadius = 120.0    ; Pick targets in 120 range
    NoTargetsScatterRadius = 60.0   ; If no targets, scatter randomly in 60 radius
    MaxShotsPerTarget = 1       ; Fire at each targets once. If we have more than 5 targets, hit the ground randomly
    TriggerDistanceToTarget = 150.0   ; Trigger at this distance to target
  End

Contain Modules

Added new features for all contain modules. WeaponBonus types that are passed to passengers can now be configured.

• PassengerWeaponBonusList = <BONUS1> <BONUS2> - (provide a list of WeaponBonus types that will be applied to the contained objects)

Default values:

• GarrisonContain: GARRISONED
• TransportContain: CONTAINED

Setting PassengerWeaponBonusList = None will override the default value.

Note: HelixContain grants GARRISONED to its passengers in vanilla ZH. This is changed to CONTAINED. To restore vanilla behaviour you will need to manually set the bonus here.

StickyBombUpdate#

Added new parameters to customize the 2D anim visuals:

• Animation2DBase = <entry from Animation2D.ini> - 2D anim for background bomb visuals (default = BombRemote)
• Animation2DTimed = <entry from Animation2D.ini> 2D anim for foreground/timer visuals; This is used when the bomb object has a LifeTimeUpdate (default = BombTimed)
• ShowTimer = Yes - Flag to disable Animation2DTimed for timed bombs - Only use base animation.

Note: Setting Animation2DBase or Timed to "None" will hide them.

CrateCollide

Added new parameters for all CrateCollide modules:

• AllowNeutralPlayer = No - Crate can be picked up by the neutral player
• AllowPickAboveTerrain = No - Crate can be picked up when it is above ground.

StickyBombCrateCollide

CrateCollide module to apply sticky bombs to objects. Can be used with pickup crates or projectiles.

Example:

Behavior = StickyBombCrateCollide ModuleTag_419
   NeedsTarget = No ; Needs an intended target object (e.g. from a projectile) cannot be picked up by regular collission
   StickyBombObject = <Object with StickyBombUpdate>  ; The object to create
   AllowMultiCollide = No ; If used as a crate, can the effect be applied to multiple objects at once?
   ShowInfiltrationEvent = No  ; If enabled, shows a radar event for the target player
   ChanceToTriggerPercent = 100%; Chance to create the StickyBombObject.
End

Example to use on a Missile or DumbProjectile to apply a sticksBomb to the target:

Behavior = StickyBombCrateCollide ModuleTag_419
  RequiredKindOf = STRUCTURE
  ForbiddenKindOf = VEHICLE INFANTRY
  BuildingPickup = Yes
  ExecuteFX = FX_SniperDroneTargetTracerPingFX
  AllowNeutralPlayer = Yes
  AllowPickAboveTerrain = Yes
  NeedsTarget = Yes
  StickyBombObject = Lazr_SniperDroneTargetTracerStickyBomb
End

; Needs separate modules for Building/Unit collissions
Behavior = StickyBombCrateCollide ModuleTag_420
  ;RequiredKindOf = VEHICLE INFANTRY
  ForbiddenKindOf = STRUCTURE
  BuildingPickup = No
  ExecuteFX = FX_SniperDroneTargetTracerPingFX
  AllowNeutralPlayer = Yes
  AllowPickAboveTerrain = Yes
  NeedsTarget = Yes
  StickyBombObject = Lazr_SniperDroneTargetTracerStickyBomb
End

AdvancedCollide (New)

A collide module with more versatile parameters

• CollideWeapon = <weapon entry> - Weapon to fire on collide
• OCL = <OCL entry> - OCL to create on collide
• FX = <FXList entry> - FX to create on collide
• FireOnce = No - trigger once or for every collission
• CollideWithGround = No - trigger collision when hitting the ground
• CollideWithObjects = Yes - trigger collission when hitting objects.
• RequiredStatus = <status entry> - required status for this object
• ForbiddenStatus = <status entry> - forbidden status for this object
• TargetRequiredStatus = <status entry> - required status for the object we collide with
• TargetForbiddenStatus = <status entry> - forbidden status for the object we collide with
• RequiredKindOf = <KindOf entry> - required KindOf for the object we collide with
• ForbiddenKindOf = <KindOf entry> - forbidden KindOf for the object we collide with
• ChanceToTriggerPercent = 100% - Chance to trigger effects on collide
• RollOnceForTrigger = No - Roll for trigger chance every time we collide, or only the first time (and then keep the result)

Note: This module allows to trigger effects when objects collides with the ground, e.g. when a projectile misses it's target.

LifeTimeUpdate

Add new parameter: *ShowProgressBar = No Enables progress bar above unit health to visualize lifetime. Requires SHOW_PROGRESS_BAR KindOf.

RadiusDecalBehavior (New)

New module to create a radius decal that follows a unit. Can be triggered via upgrade.

Example:

Behavior = RadiusDecalBehavior ModuleTag_decal1
    TriggeredBy = <Upgrade entry>  ; Optional
    ; < All other basic upgrade entries (ConflictsWith, RemovesUpgrades, FXListUpgrade, RequiresAllTriggers) >
    StartsActive = No  ; Set to yes, to enable initially
    Radius = 100.0 ; (radius in meters)
    RadiusDecal   ; Decal Template, Same parameters as DeliveryDecal in OCL ini
      Texture           = SCCFuelAirBomb_USA   ; Texture name
      Style             = SHADOW_ALPHA_DECAL   ; SHADOW_DECAL, SHADOW_ALPHA_DECAL or SHADOW_ADDITIVE_DECAL
      OpacityMin        = 25%    ; default = 100%, Opacity will move between min and max
      OpacityMax        = 50%    ; default = 100%
      OpacityThrobTime  = 500    ; default = 1000
      Color             = R:255 G:0 B:0 A:255 
      OnlyVisibleToOwningPlayer = Yes     ; Disable to make the decal visible to all players
      End
  End

Note: This module reacts to the upgrade being removed (by a different upgrade). This means you can make the decal toggle on/off.

Added parameters:

• DecalRadius = 0.0 - (Overrides the decal radius separately from the Radius field; if 0, Radius is used.)
• WorksWhileContained = No - (If Yes, the decal stays visible/active while the object is contained inside a transport or structure.)

ParkingPlaceBehavior

Added new features and parameters to ParkingPlaceBehavior (Airfield)

• ParkedUnitsDamageScalar = 1.0 - scalar for damage taken applied to all parked aircraft (0.9 = only take 90% of damage)
• ParkedUnitsDamageScalarUpgraded = 1.0 - same as above, after upgrade
• DamageScalarUpgradedTriggeredBy = <upgrade name> - upgrade to trigger the upgraded scalar value
• RequiredKindOf = <KindOf list> - if set, only aircraft that has these KindOfs is allowed to dock here
• ForbiddenKindOf = <KindOf list> - if set, aircraft that has these KindOfs is not allowed to dock here.

Notes:

• ParkedUnitsDamageScalar can be used to apply an upgrade that grants damage protection to parked aircraft
• Required/Forbidden KindOf can be used to allow only specific kinds of aircraft to land (i.e. to use different sizes, or differ between VTOL/Regular jets)

UnitProductionBonusUpgrade (New)

This upgrade module allows to set a cost and/or build time modifier for individual types of units. This affects the whole player and not just individual factories.

Parameters:

• <All common upgrade params; e.g. TriggeredBy>
• CostModifierPercentage = 0 - Percentage amount that the unit's costs are modified
• BuildTimeModifierPercentage = 0 - Percentage amount that the unit's build time is modified
• UnitTemplateName = <Name of an Object> - The unit to apply this bonus to. (multiple lines are allowed)
• IsOneShotUpgrade = No - (If Yes, the bonus is applied once and is not tracked/removed - matches the old, pre-stacking behavior. If No (default), the bonus is now correctly removed if the upgrade module is deleted, and transferred to the new owner if the object is captured.)
• BonusStacksWith = NO_STACKING - (Controls stacking when the same unit type receives this bonus from multiple sources. Options: NO_STACKING (default; a second source does not add further bonus), SAME_TYPE (stacks with bonuses from any source, including the same upgrade/object type), OTHER_TYPE (stacks only with bonuses coming from a different source object type).)

Example

Behavior = UnitProductionBonusUpgrade ModuleTag_01
  TriggeredBy = Upgrade_CostReduction   ; The upgrade trigger
  CostModifierPercentage = -40%    ; Cost is reduced by 40%
  BuildTimeModifierPercentage = -80%    ; Build time is reduced by 80%
  UnitTemplateName = Tank_ChinaInfantryRedguard    ; The units this bonus applies to
  UnitTemplateName = Tank_ChinaTankBattleMaster
  BonusStacksWith = SAME_TYPE
End

Notes

• This upgrade is now removable and capture-aware (as long as IsOneShotUpgrade = No): the bonus goes away with the granting module and follows the object if it's captured by another player, similar to the CostModifierUpgrade module for Tech OilRefinery.

PropagateUpgradeToContainedUpgrade (New)

An upgrade module that, when triggered, forwards one or more player upgrades onto every object currently contained (garrisoned/loaded) inside this object - so passengers with a matching UpgradeModule react as if they had been upgraded directly, without needing the upgrade to be player-wide.

• UpgradeToPropagate = <Upgrade name> ... - (One or more upgrade template names to grant to each currently-contained object. Multiple names can be listed.)

Example

Behavior = PropagateUpgradeToContainedUpgrade ModuleTag_01
  TriggeredBy = Upgrade_NationalismReactorBonus
  UpgradeToPropagate = Upgrade_Nationalism
End

StealthUpgrade

Added new parameters

• EnableStealth = Yes - If set to No, this will disable the object's stealth instead of enabling it. Can be used for a toggleable upgrade.

• OverrideStealthForbiddenConditions = <StealthForbiddenConditionFlags> - Override StealthForbiddenConditions in StealthUpdate for this unit.

Note: if OverrideStealthForbiddenConditions is set, EnableStealth is ignored as there is no reason to use both functionalities at the same time.

BattlePlanBonusBehavior (New)

New module that can be used to customize the effects of BattlePlans for individual units. This module needs to go to the unit that receives the battle plan bonus effects, not the StrategyCenter.

Parameters:

Behavior = BattlePlanBonusBehavior ModuleTag_BPB
  ; Generic Upgrade parameters:  
  TriggeredBy = <Upgrade entry>
  ; ---
  StartsActive = No  ; Active immediately or requires upgrade?
  OverrideGlobalBonus = No  ; Enable to skip default BattlePlan bonus effects (i.e. values from BattlePlanUpdate, or WeaponBonus effects) for this unit
  ShouldParalyzeOnPlanChange = Yes  ; Should this unit be paralyzed/disabled while switching battle plans?
  ; -- Bonus entries -- Valid <BATTLE_PLAN_NAME> are BOMBARDMENT, SEARCH_AND_DESTROY and HOLD_THE_LINE
  WeaponSet = <BATTLE_PLAN_NAME> <WEAPON_SET_FLAG>  ; Set this weaponset flag while this battleplan is active
  ArmorSet = <BATTLE_PLAN_NAME> <WEAPON_SET_FLAG>  ; Set this armorset flag while this battleplan is active
  WeaponBonus = <BATTLE_PLAN_NAME> <WEAPON_BONUS_NAME>  ; Grant this weaponbonus while this battleplan is active
  ArmorDamageScalar = <BATTLE_PLAN_NAME> 1.0   ; Set damage reduction while this battleplan is active
  SightRangeScalar = <BATTLE_PLAN_NAME> 1.0  ; Set a sight range bonus while this battleplan is active
  MovementSpeedScalar = <BATTLE_PLAN_NAME> 1.0  ; Multiply movement speed while this battleplan is active (kept across locomotor set changes)
  StatusToSet = <BATTLE_PLAN_NAME> <STATUS_TYPE>   ; Set this status when enabling this battle plan. Clear it on battle plan removal
  StatusToClear = <BATTLE_PLAN_NAME> <STATUS_TYPE>  ; Clear this status when enabling this battle plan. Set it on battle plan removal
End

Examples

Example 1 - Give extra effects to Battle plans

Behavior = BattlePlanBonusBehavior ModuleTag_BP1
  TriggeredBy = Upgrade_BattlePlanBonusExample
  OverrideGlobalBonus = No
  ShouldParalyzeOnPlanChange = Yes
  WeaponSet = BOMBARDMENT PLAYER_UPGRADE
  WeaponBonus = SEARCH_AND_DESTROY FRENZY_THREE
  StatusToClear = HOLD_THE_LINE CAN_STEALTH
  ArmorDamageScalar = HOLD_THE_LINE 0.9
End

This unit gains the regular battlePlan bonus effects with additional effects:

• With BOMBARDMENT we switch to the upgraded WeaponSet
• With SEARCH_AND_DESTROY we gain an extra weapon bonus
• With HoldTheLine we gain additional damage reduction, but lose the ability to stealth.

Example 2 - Allow units to gain battle plans

Behavior = BattlePlanBonusBehavior ModuleTag_BP0
  StartsActive = Yes
  OverrideGlobalBonus = Yes
  ConflictsWith = Upgrade_GrantBattlePlans
  ShouldParalyzeOnPlanChange = No
End
  
Behavior = BattlePlanBonusBehavior ModuleTag_BP1
  TriggeredBy = Upgrade_GrantBattlePlans
  OverrideGlobalBonus = No
  ShouldParalyzeOnPlanChange = Yes
End

This adds no additional effects, but makes the unit skip default BattlePlan effects (and paralyze) initially, and applies them only after the upgrade. Note: For this to work, the unit needs to be inlcuded in the BattlePlan's valid KindOfs, even though the intention is to not give them the battlePlan effects by default.

AllBattlePlansUpdate (New)

Grants the controlling player the army bonuses of all three battle plans (Bombardment, Hold the Line, Search & Destroy) while its object exists. It counts as an additional battle plan source next to the Strategy Centers, so the plan a Strategy Center runs, plan switching and the building-only plan effects are not touched. When the object is deleted the bonuses are removed again; if it is captured they move to the new owner.

Behavior = AllBattlePlansUpdate ModuleTag_AllPlans
  StrategyCenterTemplate = AmericaStrategyCenter   ; object whose BattlePlanUpdate provides the bonus values and member KindOfs
End

The bonus values (Hold the Line armor scalar, Search & Destroy sight scalar) and the valid/invalid member KindOfs are read from the BattlePlanUpdate of StrategyCenterTemplate, so they match the permanent plans exactly. Units with a BattlePlanBonusBehavior get their custom effects as usual.

Intended use: an OCLSpecialPower spawns an invisible marker object with this module and a DeletionUpdate for the duration. The special power enum SPECIAL_ALL_BATTLE_PLANS (behaves like the no-target CIA Intelligence power) is meant for the power. The marker can carry a second, never-fired power with SPECIAL_ALL_BATTLE_PLANS_ACTIVE that only shows the owner the remaining time (PublicTimer + OwnerOnlyTimer + FlashingTimer, see SpecialPowers).

Example marker object (the power that creates it is a normal OCLSpecialPower with Enum = SPECIAL_ALL_BATTLE_PLANS):

Object SupW_StrategicEscalationMarker
  ; no Draw module, invisible
  EditorSorting = SYSTEM
  KindOf = IMMOBILE NO_COLLIDE UNATTACKABLE NO_SELECT INERT
  Body = InactiveBody ModuleTag_01
  End
  Behavior = AllBattlePlansUpdate ModuleTag_02
    StrategyCenterTemplate = SupW_AmericaStrategyCenter
  End
  Behavior = DeletionUpdate ModuleTag_03     ; power duration
    MinLifetime = 60000
    MaxLifetime = 60000
  End
  Behavior = OCLSpecialPower ModuleTag_04    ; never fired, only shows the remaining duration to the owner
    SpecialPowerTemplate = SupW_SpecialPowerStrategicEscalationActive
  End
End

SpecialPower SupW_SpecialPowerStrategicEscalationActive
  Enum = SPECIAL_ALL_BATTLE_PLANS_ACTIVE
  ReloadTime = 60000      ; = marker lifetime
  PublicTimer = Yes
  OwnerOnlyTimer = Yes
  FlashingTimer = Yes
  ShortcutPower = No
End

PointDefenseLaserUpdate

Can now be switched on by an upgrade. Without TriggeredBy it is always active, as before.

Behavior = PointDefenseLaserUpdate ModuleTag_PDL
  ; ... existing parameters ...
  ; Generic Upgrade parameters:
  TriggeredBy = <Upgrade entry>
  ConflictsWith = <Upgrade entry>
  RequiresAllTriggers = No
  ; ---
  StartsActive = No   ; active from the start even with TriggeredBy
End

Removing the trigger upgrade switches the laser off again.

StealthDetectorUpdate

Can now be switched on by an upgrade, and limited to playable owners. Without TriggeredBy it is always active, as before.

Behavior = StealthDetectorUpdate ModuleTag_SD
  ; ... existing parameters ...
  ; Generic Upgrade parameters:
  TriggeredBy = <Upgrade entry>
  ConflictsWith = <Upgrade entry>
  RequiresAllTriggers = No
  ; ---
  StartsActive = No          ; active from the start even with TriggeredBy
  RequiresPlayerOwner = No   ; if Yes, inactive while owned by a non-playable side (neutral, civilian), e.g. a tech building that only detects once captured
End

Removing the trigger upgrade switches the detector off again. InitiallyDisabled and the battle plan switch still work on top of this.

WeaponBonusUpdate

Added Parameters:

• AffectsTargets = [ALLIES/ENEMIES/NEUTRALS] ; Allows applying a bonus to enemies
• AffectsAirborne = Yes ; allow/disallow the bonus be applied to currently airborne units
• TintStatusType = [TINT_STATUS type] ; which color tint to apply
• BonusConditionType = [WeaponBonus type] ; The WeaponBonus condition flag that is granted to affected units (default = the module's own bonus). Lets you pick which WeaponBonus the module applies.

DelayedUpgradeBehavior (New)

Applies or Removes Upgrade(s) after a set time. Initially triggered by an upgrade. This can be used to make temporary upgrades.

Example:

Behavior = DelayedUpgradeBehavior ModuleTag_DelUp
  TriggeredBy = <Upgrade entry>   ; Initial Trigger
  ; additional generic Upgrade params (ConflictsWith, RemovesUpgrades, FXListUpgrade, RequiresAllTriggers)
  UpgradesToTrigger = <Upgrade1, Upgrade2, ...>   ; Upgrades that will be triggered after the delay
  UpgradesToRemove = <Upgrade1, Upgrade2, ...>    ; Upgrades that will be removed after the delay
  TriggerAfterTime = <time in msec>    ; Time delay
End

UpgradeSpecialPower (New)

Trigger an upgrade via a special power. This can be used to (e.g. in combination with DelayedUpgradeBehavior) to create a temporary upgrade with a cooldown.

Example:

Behavior = UpgradeSpecialPower ModuleTag_SpecUp01
  SpecialPowerTemplate = <SpecialPower Entry>
  ; Other params from SpecialPower module (UpdateModuleStartsAttack, StartsPaused, InitiateSound, ScriptedSpecialPowerOnly)
  UpgradeToGrant = <Upgrade Entry>
End

OCLSpecialPower

Added new parameter: *SelectCreatedObject = No The (first) created object will be automatically selected by the player

• MinDistToSimilarRadius = 0.0 - (If > 0, the special power cannot be targeted within this radius of another object created by the same OCL special power. Useful to prevent stacking multiple deployments on top of each other. Default = 0 = no limit)

OCLUpdate

Added parameters for directional payload delivery (e.g. for OCLs that spawn a delivery aircraft, to make it approach from a consistent direction):

• DirectionalDelivery = No - (If Yes, the delivered payload/aircraft is aligned to the source object's direction instead of a fixed/default direction.)
• DirectionalDeliveryFurthestEdge = No - (If Yes, always pick the map edge furthest along the delivery angle as the spawn/approach point.)

TeleporterAIUpdate (New - EXPERIMENTAL)

** Warning: This module is experimental, i.e. it is not fully tested and might undergo revisions**

AIUpdate module designed to work like a Chrono Legionnaire in RA2. I.e. The unit teleports instead of moving normally, and needs to recharge depending on the distance it teleported. ** Note: Currently this module is only working properly for infantry units. It currently does not work properly for vehicles and it is not certain it ever will.**

Example:

Behavior = TeleporterAIUpdate ModuleTag_123
   TeleportStartFX = [FXList entry] ; FX to play at the unit's previous position when it teleports
   TeleportTargetFX = [FXList entry] ; FX to play at the unit's target position when it teleports
   TeleportRecoverEndFX = [FXList entry] ; FX to play on the unit, when it has finished recovering
   MinDistanceForTeleport = 20.0  ; distance in which the unit moves normally instead of teleporting
   DisabledDurationPerDistance = 10.0 ; How long the unit will need to recover, linear to the distance (in MS per distance). Recommended values = 5-10. 
   TeleportRecoverSoundAmbient = [AudioEvent entry] ; Ambient sound played on the unit while it recovers from a teleport.
   TeleportRecoverOpacityStart = 10%  ; Unit maximum transparency when it starts to recover.
   TeleportRecoverOpacityEnd = 80%  ; Unit minimum transparency when it has finished recovering.
   TeleportRecoverTint = TELEPORT_RECOVER  ; Color tint status to apply while recovering
   [entries from AIUpdate]
End

When a unit is recovering from a teleport, the conditionstate TELEPORT_RECOVER is set. Note: In most cases, the unit will also be MOVING after a teleport, so it's recommended to define both states.

ChronoDeathBehavior (New)

Death Module for "Chrono" death. This makes the unit fade out and shrink.

Example:

Behavior = ChronoDeathBehavior ModuleTag_ChronoDeath
  DeathTypes = NONE +CHRONO  ; Death types to use
  ; Additional DieModule params (VeterancyLevels, ExemptStatus, RequiredStatus)
  StartFX = <FXList entry> ; FX to play at the start
  EndFX = <FXList entry> ; FX to play at the end
  ; Note: The following params are meant to be used (instead of StartFX/EndFX) when used in Default/Object.ini:
  StartFXInfantry = <FXList entry> ; played if the object is INFANTRY
  StartFXVehicle = <FXList entry> ; VEHICLE
  StartFXStructure = <FXList entry>  ; STRUCTURE
  EndFXInfantry = <FXList entry> ; played if the object is INFANTRY
  EndFXVehicle = <FXList entry> ; VEHICLE
  EndFXStructure = <FXList entry>  ; STRUCTURE

  OCL = <OCL entry> ; OCL to create at the start
  OCLDynamicGeometryScaleFactor = 0.0;  Used in combination with DynamicGeometryClientUpdate. If this is set, the created object will be scaled to the parent object's radius. The value here should be set to the model's default size (e.g. a value of 10.0 corresponds to a sphere with radius 10.0)

  StartScale = 1.0  ; Unit scale at the start
  EndScale = 0.1    ; Unit scale at the end
  StartOpacity = 25%  ; Opacity at the start
  EndOpacity = 0%    ; Opacity at the end
  DestructionDelay = 500   ; Duration of the sequence in ms
End

DynamicGeometryClientUpdate (New)

Client module for simple animations on a drawable's opacity and scale. Can be useful for effects like EMP bubbles.

Example:

ClientUpdate = DynamicGeometryClientUpdate ModuleTag_02
  Opacity = INITIAL 0.0      ; value when object is created
  Opacity = MIDPOINT 1.0     ; value at midpoint duration
  Opacity = FINAL 0.0        ; value at end of duration
  Scale = INITIAL 0.0
  Scale = MIDPOINT 1.0
  Scale = FINAL 0.0
  Interpolation = SMOOTH   ; How values in between are interpolated - SMOOTH (sinus curve) or LINEAR
  TotalDuration = 666   ; in ms
  MidpointDuration = 200    ; in ms
End

ResetSpecialPowerTimerWhileAliveUpdate (New)

Update Module to reset a player global (shared synch timer) superweapon while a unit is alive, this allows super unit deploys to start the cooldown when the unit is dead

Example:

  Behavior = ResetSpecialPowerTimerWhileAliveUpdate ModuleTag_x
    SpecialPowerTemplate = Tank_SuperweaponUniqueUnit  ; a superweapon template with shared synch timer ( like genpowers)
  End

W3DModelDraw

Added parameters (To the main Draw module block, not the individual ConditionStates):

• IgnoreAnimationSpeedScaling = No - ignore animation scaling (e.g. for PreAttackDelay) for a draw module. Useful for having Looping animations (e.g. rotor blades or flags) along with a pre_attack anim in another draw module.

• IgnoreRotation = No - This model will always stay aligned to the world (i.e. Z up), ignoring rotation via movement. Do not use this on modules with Firebones or Turrets.

• OnlyVisibleToOwningPlayer = No - This model will only be visible to the owning player. Do not use it on modules with Firebones or Turrets.

Energy Shields

Added a Body and Behavior module for rechargable energy shields. This adds another health bar on top and absorbs damage until it's depleted.

ShieldBody

This Body is required for shields to work.

Body = ShieldBody ModuleTag_ES1
  ;<ActiveBody paramters>
  StartsActive = No  ; Enable Shields by default; Otherwise an upgrade is required (defined in EnergyShieldBehavior)
  ShieldMaxHealth = 100  ; Health points of the shield (only needed if ShieldMaxHealthPercent is not set)
  ShieldMaxHealthPercent = 30%  ; Health points relative to MaxHealth (overrides ShieldMaxHealth)
  ShieldArmorSetFlag = PLAYER_UPGRADE  ; (Optional) ArmorSetFlag to use while the shield is up
  ShieldPassThroughDamageTypes = <Damage Types> ; List of damage types that will go through the shield and damage the Health. NONE +X, ALL -Y notation.
  DefaultShieldPassThroughDamageTypes = <Damage Types> ; This has the same functionalty as above, but is predefined with all utility damage types that should always be passed through. This should not be defined in most cases, but can be overriden
End

NOTE: DefaultShieldPassThroughDamageTypes default values: NONE +STATUS +DEPLOY +UNRESISTABLE +HEALING +PENALTY +DISARM +HAZARD_CLEANUP +TOPPLING +SUBDUAL_UNRESISTABLE +CHRONO_UNRESISTABLE

EnergyShieldBehavior

The second required module for shield logic

Behavior = EnergyShieldBehavior ModuleTag_ES2
    StartsActive = No  ; Enabled by default (no upgrade required)
    TriggeredBy = <Upgrade Name>
    ShieldRechargeDelay = 5000  ; Time (ms) of no damage taken, until shield starts recharging.
    ShieldRechargeRate = 100  ; Delay (ms) between shield recharge ticks
    ShieldRechargeAmount = 0  ; How much shield to recharge per tick (Absolute. Use only one)
    ShieldRechargeAmountPercent = 2%  ; How much shield to recharge per tick (Percentage. Use only one)
    ShieldHealthBarColor = R:128 G:255 B:255 A:255  ; RGBA color for the shield health bar
    ShieldHealthBarBackgroundColor = R:0 G:0 B:0 A:255  ; RGBA color for the shield health bar outline
    ShowHealthBarBackgroundWhenEmpty = No   ; Show empty frame when shield is depleted
    ShowHealthBarWhenUnselected = No ; Show shield health bar when the unit is not selected or mousover
    ShieldModelCondition = <ConditionStateName>  ; Optional: Conditionstate to set when shield is active
    ShieldSubObjectName = <SubObjName> ; Optional: Model subobject to show when the shield is active
    ShieldHitModelCondition = <ConditionStateName> ; Optional: Conditionstate to set when shield was hit
    ShieldHitSubObjectName = <SubObjName> ; Optional: Model subobject to show when the shield was hit
    ShieldHitConditionDuration = 500  ; Optional: How long to show conditionstate when shield was hit
    ShieldDownFX = <FXList> ; Optional: FX to play when shield is depleted
    ShieldUpFX = <FXList> ; Optional: FX to play when a depleted shield starts recharging
End

** Note: for the shield health bar to work, the KindOf "SHOW_PROGRESS_BAR" is required on the object**

** Note2: When using both ShieldHitModelCondition and ShieldModelCondition parameters: When the shield is hit, both conditionstates are active at the same time. So a setup like this is required:

Draw = W3DModelDraw ModuleTag_ES0
  ; Inactive Shield
  DefaultConditionState
    Model = None
  End
		
  ; Active Energy Shield
  ConditionState = USER_1
    Model = ShieldActive
  End
	
  ; Energy Shield Hit
  ConditionState = USER_1 USER_2
    Model = ShieldHit
  End
End

MultiAddOnContain (New)

New contain module to replicate MARV turret functionality from Kane's Wrath: The object (Can be used on a structure or vehicle) has a container for multiple infantry units. Each contained infantry, will spawn a portable structure on the unit, that will move and attack along with it. Each type of infantry has it's own portable structure defined. Only units defined in the list can enter. There is no limit on how many addOns can be defined.

Example:

Behavior = MultiAddOnContain ModuleTag_123
  ; Params from TransportContain:  
  Slots = 4
  EnterSound = GarrisonEnter
  ExitSound = GarrisonExit
  ImmuneToClearBuildingAttacks = Yes
  DamagePercentToUnits = 100%
  IsEnclosingContainer = No
  ; New Params
  PayloadTemplateName = <Name of Infantry object to be contained by default> ; can have multiple PayloadTemplateName entries
  AddOnBoneName = STATION  ;Name of bone to place the addOns (uses numbering from 00-99 for available slots)
  AddOnEntry = <Name of contained Infantry object 1> <Name of Portable Structure object 1>
  AddOnEntry = <Name of contained Infantry object 2> <Name of Portable Structure object 2>
  AddOnEntry = <Name of contained Infantry object 3> <Name of Portable Structure object 3>
  ...
  EmptySlotSubObjectName = COVER_EMPTY   ;Name of any subobject (numbered) that should be visible when a slot is empty
  OccupiedSlotSubObjectName = COVER_OCCUPIED   ;Name of any subobject (numbered) that should be visible when a slot is filled (hide this in art code by default)
End

Container Draw Module Requirements

Like with OverlordContain, the container object needs to have one of

• W3DOverlordTankDraw
• W3DOverlordTruckDraw
• W3DOverlordAircraftDraw - Note: Contary to the name, this is the default module to use (e.g for Structures) when no extra behavior is required

A new parameter was added to these modules that needs to be set when used with MultiAddOnContain:

• HasMultiAddOns = Yes

AddOn Draw Module Requirements

Like with Overlord addOns, the contained portable structure object needs to have W3DDependencyModelDraw

AttachToBoneInContainer should now be set to the same numbered bone used for AddOnBoneName in MultiAddonContain. E.g. "STATION" if using STATION01-XX

Drone Carrier system

Added modules to support a simplified mobile aircraft carrier.

DoneCarrierContain

  Behavior = DroneCarrierContain ModuleTag_Contain
    ;<TransportContain parameters>
    Slots = 123
    HealthRegen%PerSec = 3.0
    ExitBone = STATION
    ExitDelay = 300
    HealthRegen%PerSec = 3.0
    ...
    ;
    LaunchVelocityBoost = 2.5
    LaunchBone = STATION
    NumLaunchBones = 1
    EnterPositionOffset = X:0 Y:0 Z:0
    EnterPositionOffset = X:0 Y:0 Z:0  ;Multiple entries allowed
    ...
    ContainedUnitsDeathType = TOPPLED
    KeepSlotAssignment = Yes
  End

DroneCarrierAIUpdate

  Behavior = DroneCarrierAIUpdate ModuleTag_AI
    ;<AIUpdate parameters>
    Slots = 8
    RespawnTime = 3000
    DroneTemplateName = Lazr_AmericaVehicleCarrierDrone
    DronesEnterMainDoor = Yes
  End

DroneCarrierSlavedUpdate

  Behavior = DroneCarrierSlavedUpdate ModuleTag_123
    <SlavedUpdate params>
    LeashRange = 400.0
  End

CarrierDroneAIUpdate

  Behavior = CarrierDroneAIUpdate ModuleTag_312
    DockingDistance = 70.0
    DockingLocomotorType = SET_SLUGGISH
    LaunchingLocomotorType = SET_TAXIING
    LaunchTime = 750
  End

TODO: In-depth description

BuffUpdate

Works similar to WeaponBonusUpdate (Frenzy module) to apply buffs to objects in an area

• RequiredAffectKindOf = <List of KindOfs>
• RequiresAllKindOfs = Yes/No ; Require all listed KindOfs, or just one of them
• ForbiddenAffectKindOf = <List of KindOfs>
• AffectsTargets = <combination of ALLIES | ENEMIES | NEUTRALS>
• AffectAirborne = Yes/No
• BuffDuration = duration in msec ; how long to apply the buff
• BuffDelay = duration in msec ; how often to apply the buff
• BuffRange = 0.0 ; area radius
• BuffTemplateName = <BuffTemplate.ini entry> ; the template to apply

Naval / Water Modules

PhysicsBehavior

Added parameters to support objects floating/impacting on water (used together with the ship death behavior and water effects).

• DoWaterPhysics = No - (If Yes, the object reacts to the water surface, e.g. floating and slowing down in water instead of falling through. Default = No)
• WaterExtraFriction = 0.0 - (Additional friction applied while the object is in/on water. Default = 0.0)
• WaterImpactFX = <FXList> - (FXList played once when the object first impacts the water surface. Default = None)

ShipSlowDeathBehavior (New)

A death behavior for ships and other large naval objects. It plays a multi-stage sinking sequence: an initial delay, an optional toppling motion, and finally sinking below the water surface, each with their own FX/OCL and model condition states.

The module has a lot of parameters, grouped by stage below. All durations are in milliseconds, all angles in degrees.

Behavior = ShipSlowDeathBehavior ModuleTag_ShipDeath
  ; --- common DieModule params (DeathTypes, VeterancyLevels, ExemptStatus, ...) ---

  ; --- Initial delay before the death sequence starts ---
  InitialDelay = 0
  InitialDelayVariance = 0
  InitialConditionFlag = <ModelCondition>   ; condition flag set when the death starts (default = RUBBLE)

  ; --- Wobble (gentle rocking while sinking) ---
  WobbleMaxAnglePitch = 0
  WobbleMaxAngleYaw = 0
  WobbleMaxAngleRoll = 0
  WobbleInterval = 0

  ; --- Topple stage (ship tips over) ---
  ToppleStyle = TOPPLE_FRONT   ; TOPPLE_FRONT, TOPPLE_BACK, TOPPLE_SIDE_LEFT, TOPPLE_SIDE_RIGHT (random if omitted)
  ToppleFrontMinPitch = 0
  ToppleFrontMaxPitch = 0
  ToppleBackMinPitch = 0
  ToppleBackMaxPitch = 0
  ToppleSideMinRoll = 0
  ToppleSideMaxRoll = 0
  ToppleMinHeightOffset = 0
  ToppleMaxHeightOffset = 0
  ToppleDuration = 0
  ToppleDurationVariance = 0
  ToppleMinPushForce = 0
  ToppleMaxPushForce = 0
  ToppleMinPushForceSide = 0
  ToppleMaxPushForceSide = 0
  ToppleAngleCorrectionRate = 0   ; angular velocity used to settle the topple angle
  ToppleConditionFlag = <ModelCondition>   ; condition flag set when toppling starts (default = RUBBLE)
  FXStartTopple = <FXList>
  OCLStartTopple = <OCL>

  ; --- Sink stage (ship goes below water) ---
  SinkHowFast = 100%       ; sink speed as a percentage
  SinkConditionFlag = <ModelCondition>   ; condition flag set when sinking starts (default = RUBBLE)
  FXStartSink = <FXList>
  OCLStartSink = <OCL>
  SinkAttachParticle = <ParticleSystem>   ; particle system attached while sinking (e.g. bubbles)
  SinkAttachParticleBones = <Bone1> <Bone2> ...   ; bones to attach the particle to
  SoundSinkLoop = <AudioEvent>            ; looping sound while sinking

  ; --- Pilot / ground impact ---
  OCLEjectPilot = <OCL>     ; OCL created to eject a pilot/crew
  FXHitGround = <FXList>    ; FX when the wreck reaches the sea/ground floor
  OCLHitGround = <OCL>      ; OCL when the wreck reaches the sea/ground floor
End

Notes:

• The three condition flags (InitialConditionFlag, ToppleConditionFlag, SinkConditionFlag) all default to RUBBLE. Set them to distinct states if you want different models/animations per stage.
• ToppleStyle accepts the topple direction names; if omitted, a random direction is chosen.

HeightDieUpdate

Added parameter:

• TargetHeightIncludesWater = No - (If Yes, the target height check used to trigger the death also takes the water surface height into account, so the object dies relative to the water level rather than the terrain below it. Useful for projectiles/objects over water. Default = No)

Die Modules - Water Depth Conditions

All Die modules (the shared DieMux conditions) now support restricting the death to a water depth range. This lets you trigger different death effects depending on how deep the water is (e.g. a normal death on land/shallow water, a sinking death in deep water).

• MinWaterDepth = 0.0 - (Minimum water depth required for this death module to trigger. Default = 0)
• MaxWaterDepth = 0.0 - (Maximum water depth allowed for this death module to trigger; 0 = no upper limit. Default = 0)

BunkerBusterBehavior

Added parameter:

• WorksOverWater = Yes - (If Yes (default), the bunker buster triggers its behavior even when it hits the water surface. Set to No to make it ignore targets over water.)

Bridges

Bridge.ini / TerrainRoad (Bridge type)

• BridgeHoleAreaPercentage = 100% - (Percentage of the bridge span that is removed/becomes impassable when the bridge is destroyed. Lets you tune how much of the bridge collapses.)

Destroyable road bridges

Road bridges (the procedural bridges placed with the bridge tool in WorldBuilder, drawn from BridgeModelName) can now be destroyed and rebuilt like landmark bridges. Before, they were always indestructible and had no towers.

• Destroyable = No - (If Yes, the bridge can be damaged and destroyed. It is owned by the neutral player and gets the 4 targetable towers from TowerObjectNameFromLeft/FromRight/ToLeft/ToRight, which a Dozer/Worker can use to rebuild it (if the span object's BridgeBehavior has Restoreable = Yes). The deck model switches to BridgeModelNameDamaged / ReallyDamaged / Broken with the span object's damage state.)
• BridgeObjectName = GenericBridge - (Object template that represents the bridge span in the logic. For a destroyable bridge this object needs a body, armor and BridgeBehavior, and KindOf should include BRIDGE. Its geometry is a placeholder: at runtime the box is resized to the bridge (half span length × half bridge width) so area weapons aimed at the deck hit it, and it collapses to nothing while the bridge is destroyed. Leave out to use GenericBridge as before.)
• BridgeDeckHeight = 0.0 - (Thickness of the deck (and girders/arches) below the driving surface. It is subtracted from the clearance under the bridge, so units that need clearance (see RequiredBridgeHeight below) have to fit below the bottom of the deck, not the road surface. Applies to all bridge types.)

The sectional deck has no skeleton, so it cannot play a model animation. These parameters drive a procedural collapse instead: span sections fold toward the middle and drop. All default to 0, which keeps the old instant model swap.

• BridgeCollapseDuration = 0 - (Time in ms the collapse animation runs. The broken model is swapped in when it ends. 0 = no animation.)
• BridgeCollapseDrop = 0.0 - (World units a fully collapsed section falls.)
• BridgeCollapseTilt = 0 - (Degrees a fully collapsed section folds by. The two halves fold toward each other, hinging at the end nearest their bank.)
• BridgeCollapseStagger = 0% - (Part of the duration spent rippling out from mid span: sections in the middle start falling immediately, those near the banks start up to this much later. Capped at 90%.)
• BridgeRebuildDuration = 0 - (Time in ms of the rebuild animation, the collapse played backwards when the bridge goes from rubble back to healthy. 0 = no animation.)
• BridgeCollapseSingleSpanRoll = 0 - (A bridge short enough to be a single span section has nothing to fold against, so it banks sideways by this many degrees instead. The sign picks the side.)
• BridgeCollapseSingleSpanDrop = 0.0 - (World units a single-span deck sinks. 0 = use BridgeCollapseDrop.)

Notes:

• A Bridge block that leaves out RadarColor or BridgeHoleAreaPercentage, or any of the new fields, now takes them from DefaultBridge, like the other fields.

Example (Roads.ini):

Bridge IndustrialDestroyable
  BridgeScale                    = 0.85
  BridgeModelName                = CBBridgeIn
  Texture                        = CBBridgeIn.tga
  BridgeModelNameDamaged         = CBBridgeIn_d
  TextureDamaged                 = CBBridgeIn_d.tga
  BridgeModelNameReallyDamaged   = CBBridgeIn_e
  TextureReallyDamaged           = CBBridgeIn_e.tga
  BridgeModelNameBroken          = CBBridgeIn_r
  TextureBroken                  = CBBridgeIn_r.tga
  TowerObjectNameFromLeft        = DestructibleBridgeTowerConcreteLeft01
  TowerObjectNameFromRight       = DestructibleBridgeTowerConcreteLeft02
  TowerObjectNameToLeft          = DestructibleBridgeTowerConcreteRight01
  TowerObjectNameToRight         = DestructibleBridgeTowerConcreteRight02
  ScaffoldObjectName             = BridgeScaffold01
  ScaffoldSupportObjectName      = BridgeScaffoldSupport01
  Destroyable                    = Yes
  BridgeObjectName               = GenericBridgeDestructible
  BridgeDeckHeight               = 5.0
  BridgeCollapseDuration         = 1200
  BridgeCollapseDrop             = 22
  BridgeCollapseTilt             = 25
  BridgeCollapseStagger          = 60%
  BridgeCollapseSingleSpanRoll   = 20
  BridgeRebuildDuration          = 1500
End

Span object for it:

Object GenericBridgeDestructible
  Draw = W3DDefaultDraw ModuleTag_Draw
    ; nothing -- the bridge system draws the span
  End
  EditorSorting = SYSTEM
  ArmorSet
    Conditions = None
    Armor = StructureArmor
    DamageFX = StructureDamageFXNoShake
  End
  RadarPriority = NOT_ON_RADAR
  KindOf = STRUCTURE IMMOBILE BRIDGE
  Body = StructureBody ModuleTag_Body
    MaxHealth = 4000.0
    InitialHealth = 4000.0
  End
  Behavior = BridgeBehavior ModuleTag_Bridge
    LateralScaffoldSpeed = 100.0
    VerticalScaffoldSpeed = 70.0
    BridgeDieFX = FX:FX_RailroadBridgeCollapse Delay:0   SpanFraction:0.5
    BridgeDieFX = FX:FX_RailroadBridgeCollapse Delay:250 SpanFraction:0.3
    BridgeDieFX = FX:FX_RailroadBridgeCollapse Delay:250 SpanFraction:0.7
    Restoreable = Yes
    RepairPushDuration = 1500
    RepairPushForce = 150
  End
  Geometry = BOX
  GeometryMajorRadius = 1.0   ; overwritten at runtime (half span length)
  GeometryMinorRadius = 1.0   ; overwritten at runtime (half bridge width)
  GeometryHeight = 12.0
  GeometryIsSmall = No
  Shadow = NONE
End

ThingTemplate

• RequiredBridgeHeight = 0 - (Minimum bridge-layer height this object's pathfinding requires to be allowed to cross a bridge. Lets tall units/ships be blocked from bridges that aren't high enough for them, while shorter units can still cross.)
  • Clearance is stored in steps of 10 world units; the requirement is rounded up to the next step (e.g. 12 needs 20), so an object is never let through a gap it does not fit under. The clearance is measured to the bottom of the deck (BridgeDeckHeight).

BridgeBehavior

Added parameters to push objects on a bridge when it is repaired:

• RepairPushDuration = 0 - (Duration in ms over which objects standing on the bridge are pushed up when the bridge is repaired/restored.)
• RepairPushForce = 0 - (Acceleration applied to objects on the bridge while it is being repaired.)

BridgeDieFX / BridgeDieOCL accept a new optional location label:

• BridgeDieFX = FX:<FXList> Delay:<ms> [Bone:<bone>] [SpanFraction:<0..1>]
• SpanFraction places the effect along the bridge centreline: 0 = the 'from' bank, 1 = the 'to' bank. FX are oriented along the span. Meant for road bridges, whose span object has no model and so no bones. Bone takes priority if both are given; with neither, a random spot on the deck is used as before.

DrawBridgeUpdate (New) / DrawBridgeTowerUpdate (New)

New modules implementing an openable "draw bridge" that can be raised and lowered, triggered via a special power.

DrawBridgeUpdate (on the bridge object):

Behavior = DrawBridgeUpdate ModuleTag_DrawBridge
  OpeningDuration = 0       ; time in ms to open (raise) the bridge
  ClosingDuration = 0       ; time in ms to close (lower) the bridge
  OpeningPushForce = 0      ; acceleration applied to objects when the bridge opens (pushes them off)
  ClosingDamageTime = 0     ; time in ms during closing when objects underneath take damage
End

DrawBridgeTowerUpdate (on the bridge tower/control object):

Behavior = DrawBridgeTowerUpdate ModuleTag_DrawBridgeTower
  SpecialPowerTemplate = <SpecialPower entry>   ; special power that triggers opening/closing
End

Jumpjet / Special Ability Modules

SpecialAbilityUpdate

Added parameters to control turning before an ability is used:

• RequiresMoveToTurn = No - (If Yes, the unit must use its movement/locomotor to turn towards the target before the ability can fire, instead of snapping its facing.)
• FacingAngleTolerance = 0 - (Allowed facing angle error (in degrees) towards the target before the ability is considered "facing" the target.)

JumpjetContain (New)

A contain module for a "jumpjet"-style carrier that launches and lands riders which fly using jumpjet missiles. Handles the flying/landing animation states and landing safety checks.

Behavior = JumpjetContain ModuleTag_Jumpjet
  ;<TransportContain parameters>
  FlyingConditionFlag = <ModelCondition>    ; condition flag set while flying
  LandingConditionFlag = <ModelCondition>   ; condition flag set while landing
  LandingDistance = 0.0                     ; distance from the ground at which landing begins
  KillWhenLandingInWater = No               ; kill the unit if it tries to land in water
  KillWhenLandingInWaterSlop = 0.0          ; extra water-depth tolerance before the water kill triggers
  KillWhenLandingOnCliff = No               ; kill the unit if it tries to land on an (impassable) cliff
  KillWhenLandingOnImpassable = No          ; kill the unit if it tries to land on impassable terrain
End

JumpjetMissileAIUpdate (New)

AI update for the projectiles/riders launched by a jumpjet carrier.

Behavior = JumpjetMissileAIUpdate ModuleTag_JumpjetMissile
  ScatterRadius = 0.0        ; random scatter radius around the target (default = 0)
  MaxSearchRadius = 100.0    ; radius to search for targets (default = 100)
  InitialPitchAngle = 0.0    ; initial launch pitch angle in degrees (default = 0)
End

Animation Blending

A set of features to smoothly blend between animations and trigger frame-accurate effects. (PRs #85, #86, #91, #93)

W3DModelDraw (module level)

• KeepRecoilAcrossStates = No - (If Yes, weapon recoil offset is kept when the model switches condition states, instead of being reset. Avoids the gun "snapping back" when the firing state changes. Default = No)

ConditionState parameters

• AnimationBlendTime = 0 - (Per ConditionState; number of animation frames to blend from the previous state's animation into this state's animation, for a smooth transition. Default = 0 = no blending)

• AutoConditionState = <ConditionFlag1> <ConditionFlag2> ... - (Shorthand that auto-generates a combined condition state from the previously defined ConditionState by OR-ing in the listed condition flags. It copies the previous state's model/animation/overrides and creates a new state for each of the previous state's condition sets combined with the auto flags. It has no body.)

  Requirements/notes:

  • Must come after a regular ConditionState (it refers to the last defined one).
  • Requires at least one condition flag.
  • It is an asset error if it would produce a condition state that already exists.
  • Useful for animation blending, e.g. to duplicate a state for an additional flag without retyping the whole block.

• FXEvent = <frame> <boneName> <FXList> - (Per ConditionState; plays the given FXList at the given bone when the animation playback crosses the given frame number. Can be added multiple times. Lets you trigger effects at exact animation frames, e.g. footstep dust or muzzle smoke.)

AnimationSteeringUpdate

Existing (retail) behavior module that plays steering animations from the unit's turning, as used by the GLA Combat Cycle. When the unit starts turning it sets CENTER_TO_LEFT / CENTER_TO_RIGHT; when it stops, it switches to LEFT_TO_CENTER / RIGHT_TO_CENTER and clears that once the unit drives straight. New parameters were added to the retail MinTransitionTime.

Behavior = AnimationSteeringUpdate ModuleTag_AnimSteer
  MinTransitionTime = 0     ; (retail) minimum time in ms between two steering state changes
  MinAngle = 0              ; (new) degrees; don't start a turn animation while the AI's goal is less than this far off the nose
  SkipCenteringAnims = No   ; (new) if Yes, only CENTER_TO_LEFT / CENTER_TO_RIGHT are used; they are cleared directly when the turn ends, without LEFT_TO_CENTER / RIGHT_TO_CENTER
  BackwardsCondition = No   ; (new) if Yes, set the MOVING_BACKWARDS condition state while the unit drives in reverse
  BackwardsTurnAnims = No   ; (new) if Yes, keep playing the turn animations while reversing (otherwise they are suppressed)
End

Notes:

• MinAngle uses the AI's current goal object or goal position. It only prevents a turn animation from starting; a running one finishes as usual. 0 = off (retail behavior).

Notes on reversing (BackwardsCondition = Yes):

• MOVING_BACKWARDS follows the actual movement (the unit's speed is backwards), with a little hysteresis so it doesn't flicker on small nudges.
• Without BackwardsTurnAnims, the turn conditions (CENTER_TO_LEFT, CENTER_TO_RIGHT, LEFT_TO_CENTER, RIGHT_TO_CENTER) are cleared while reversing. With it, MinAngle is measured against the unit's rear.

W3DDecalDraw (New)

A draw module that renders a single ground decal for its object. Mainly used together with the Decal FX nugget to create temporary decals (e.g. scorch marks, footprints) via FXLists.

Draw = W3DDecalDraw ModuleTag_Decal
  Texture = <texture name>
  Style = SHADOW_ALPHA_DECAL   ; SHADOW_ALPHA_DECAL or SHADOW_ADDITIVE_DECAL only - see note below
  Color = R:255 G:255 B:255 A:255
  Opacity = 100%
  SizeX = 1.0       ; world-space size in X
  SizeY = 1.0       ; world-space size in Y
  FadeInTime = 0    ; ms to fade in
  FadeOutTime = 0   ; ms to fade out (use with LifetimeUpdate)
  RenderAboveWater = DEFAULT   ; DEFAULT, ABOVE or BELOW - see note below
End

• RenderAboveWater = DEFAULT - (Per-decal override of whether this decal draws above or below the water surface. DEFAULT follows the global RadiusDecalsAboveWater GameData flag; ABOVE/BELOW force it regardless of the global setting.)

Note: Style = SHADOW_DECAL is not supported here (it's a real object-shadow type, not a standalone FX decal, and will crash/get coerced to SHADOW_ALPHA_DECAL). Only SHADOW_ALPHA_DECAL and SHADOW_ADDITIVE_DECAL are valid.

Target Designator

SpecialPowerDesignatorUpdate (New)

Update module that lets a unit "designate" an area, enabling special powers that require a designator (see NeedsTargetDesignator on the SpecialPower). While active, it can show a radius decal and optionally apply a temporary status to objects in the area.

Behavior = SpecialPowerDesignatorUpdate ModuleTag_Designator
  SpecialPowerTemplate = <SpecialPower entry>   ; the power that this designator enables
  DesignatorRadius = 0.0       ; radius of the designated area
  AlwaysShowDecal = No         ; always show the radius decal, even when the power is not ready
  TriggerStatusType = <ObjectStatus>   ; status applied to objects in the designated area
  TriggerStatusTime = 0        ; how long (ms) the status stays on after leaving the area
  TriggerFX = <FXList>         ; FX played when the designator triggers
End

Crate / Salvage Upgrades

AutoHealBehavior

Added parameters so that auto-healing can also grant salvage upgrades / promotions (e.g. a repair bay that "salvages" or veterans up units while healing them):

• GrantSalvageUpgrade = No - (If Yes, apply a salvage crate upgrade to the unit while it is being healed.)
• GrantPromotion = No - (If Yes, give the unit a veterancy level-up while it is being healed.)

CrateApplyUpgrade (New)

An upgrade module that applies "crate"-style effects (salvage weapon/armor upgrades or a veterancy level-up) when triggered, reusing the salvage-crate logic.

• SalvageCrate = No - (If Yes, apply a salvage weapon/armor upgrade. Only affects units that are KINDOF_WEAPON_SALVAGER / KINDOF_ARMOR_SALVAGER and not already at the highest salvage tier.)
• LevelUp = No - (If Yes, grant a veterancy level-up, up to HEROIC, if the unit is trainable.)

Crate.ini (CrateData)

• AllowWater = No - (If Yes, this salvage/pickup crate may be created on water. By default crates are only created on land. Default = No)

Multiple Portable Structures (Overlord contain)

OverlordContain (and Overlord-style contain redirection) now allows holding multiple add-ons at once, as long as they are KINDOF_PORTABLE_STRUCTURE. Objects with this KindOf are always added directly to the Overlord's own contain list (rather than being redirected to a single passenger), so several portable structures can be mounted on the same carrier. See also MultiAddOnContain.

New OverlordContain parameter:

• AddOnBoneName = FIREPOINT - (Bone prefix the riders sit on. Rider N (in contain order) is placed at <AddOnBoneName><NN> (e.g. FIREPOINT01, FIREPOINT02), falling back to the bone without number, then to the container's own position. Must match the riders' AttachToBoneInContainer, so the logic position (turret aiming, projectile launch) matches where the rider is drawn. With PassengersInTurret = Yes the bones are looked up on the main turret.)

Water Genpower Support

Improvements to make existing generals-power superweapons work correctly over water. (PR #97)

SpectreGunshipUpdate

• HitWaterSurface = No - (If Yes, the gunship's strafing shots detonate at the water surface instead of passing through / hitting the sea floor.)
• GattlingStrafeFXParticleSystemWater = <ParticleSystem> - (Particle system used for strafe impacts that land on water, instead of the regular land FX.)

ParticleUplinkCannonUpdate

• HitWaterSurface = No - (If Yes, the uplink cannon beam detonates at the water surface over water.)

See also OrbitalBeamUpdate HitWaterSurface and the DeliverPayload StrafingWeaponTargetsWater flag.

Veterancy

Veterancy Object Parameters

With the two extra veterancy levels (LEVEL_FOUR, LEVEL_FIVE; see New Enum Definitions), the per-object veterancy parameters now support up to 6 levels:

• MaxVeterancyLevel = HEROIC - (The highest veterancy level this object may ever reach. Default = HEROIC (vanilla behavior). Set to LEVEL_FOUR / LEVEL_FIVE to allow the extra levels.)
• ExperienceRequired = <lvl0> <lvl1> ... <lvl5> - (XP required to reach each level. Accepts up to 6 values now.)
• ExperienceValue = <lvl0> <lvl1> ... <lvl5> - (XP granted to the killer when this object is destroyed, per level. Up to 6 values.)
• SkillPointValue = <lvl0> <lvl1> ... <lvl5> - (Skill points granted per level. Up to 6 values.)

Notes:

• Health bonuses for the new levels are set in GameData via HealthBonus_Four / HealthBonus_Five.
• The maximum level can also be raised at runtime via the SetMaxVeterancyLevel upgrade.

RiderChangeContain

Extended from 8 to 16 rider slots. Additional slots Rider9 through Rider16 can now be defined, using the same syntax as Rider1-Rider8. Corresponding RIDER9-RIDER16 enums were added for ArmorSet/WeaponSet/ModelCondition/ObjectStatus (see New Enum Definitions).

On-Kill Modules

Two new behavior modules that trigger an effect when the object kills another object. Both share a common set of "kill condition" parameters (KillMux) that filter which kills count.

Shared Kill Conditions (KillMux)

These parameters are available on both On-Kill modules below:

• KilledKindOf = <KindOf list> - (Only trigger when the killed victim matches these KindOfs.)
• ForbiddenKilledKindOf = <KindOf list> - (Do not trigger if the victim matches any of these KindOfs.)
• RequiresAllKindOfs = No - (If Yes, the victim must match all KilledKindOf entries instead of any.)
• RequiredKilledStatus = <ObjectStatus list> - (Victim must have these status flags.)
• ForbiddenKilledStatus = <ObjectStatus list> - (Victim must not have these status flags.)
• KilledRelationship = <ALLIES | ENEMIES | NEUTRALS> - (Only count kills of victims with this relationship to the killer.)
• DamageTypes = <DamageType flags> - (Only trigger if the killing blow used one of these damage types. NONE/ALL +X -Y notation.)
• DeathTypes = <DeathType flags> - (Only trigger for these death types.)
• TriggerChance = 100% - (Chance to trigger on a qualifying kill.)
• CooldownTime = 0 - (Minimum time (ms) between triggers.)

CreateObjectOnKillBehavior (New)

Spawns an OCL when the object kills a qualifying victim.

Behavior = CreateObjectOnKillBehavior ModuleTag_CreateOnKill
  StartsActive = Yes
  ; --- shared KillMux conditions (see above) ---
  KilledKindOf = INFANTRY
  ; --- module params ---
  CreationList = <OCL entry>          ; OCL spawned at the victim's location
  CreateAtKillerLocation = No         ; if Yes, spawn at the killer's position instead of the victim's
  CreateObjectForVictim = No          ; if Yes, the created object is owned by the victim's player instead of the killer's
End

FireWeaponOnKillBehavior (New)

Fires a weapon at the victim when the object kills a qualifying target.

Behavior = FireWeaponOnKillBehavior ModuleTag_FireOnKill
  StartsActive = Yes
  ; --- shared KillMux conditions (see above) ---
  KilledKindOf = VEHICLE
  ; --- module params ---
  KillWeapon = <Weapon entry>         ; weapon fired at the victim on kill
End

Superweapon / Special Power Update Modules

OrbitalBeamUpdate (New)

A special power update module for an "orbital beam" style superweapon that charges up several beams and then fires a final beam/weapon. (PR #99)

Behavior = OrbitalBeamUpdate ModuleTag_OrbitalBeam
  SpecialPowerTemplate = <SpecialPower entry>   ; (via SpecialPowerModule params)
  InitialDelay = 0             ; ms before the sequence starts
  InitialSound = <AudioEvent>
  InitialFX = <FXList>          ; FX played right at the start of the sequence
  InitialOCL = <OCL>            ; OCL created right at the start of the sequence

  ; --- Charge beams (multiple beams that converge before the final shot) ---
  NumChargeBeams = 1
  ChargeBeamName = <LaserName>            ; laser template used for charge beams
  ChargeBeamRadius = 0.0                  ; radius the charge beams spread over
  ChargeBeamHeight = 0.0
  ChargeBeamRotation = 0                  ; rotation angle (degrees)
  ChargeBeamsStartCenter = No             ; start beams from the center
  ChargeBeamInterpolation = <InterpolationType>   ; how the beams move in
  RandomizeChargeBeamOrder = No
  ChargeBeamStartFX = <FXList>
  ChargeStartFX = <FXList>      ; FX played when the charge phase begins
  ChargeStartOCL = <OCL>        ; OCL created when the charge phase begins
  ChargeSound = <AudioEvent>
  ChargeWeapon = <Weapon entry>           ; weapon(s) fired per charge beam (can repeat)
  ChargeBeamParticleSystem = <ParticleSystem> ...       ; particle systems for the charge beam
  ChargeBeamParticleSystemLand  = <ParticleSystem> ...  ; used over land
  ChargeBeamParticleSystemWater = <ParticleSystem> ...  ; used over water
  DelayBetweenChargeBeams = 0
  DelayChargeToAnim = 0
  BeamAnimationDuration = 0
  DelayAnimationToFinal = 0

  ; --- Final beam / weapon ---
  FinalBeamName = <LaserName>
  FinalBeamDuration = 0
  FinalWeapon = <Weapon entry>
  FinalFX = <FXList>            ; FX played when the final beam appears
  FinalOCL = <OCL>              ; OCL created when the final beam appears

  HitWaterSurface = No          ; if Yes, beam/effects detonate at the water surface over water
End

Note: many fields have a matching ...Frames internal name; all Delay/Duration values are in milliseconds. Refer to the field list for the full set.

ChronoSphereUpdate (New)

Special power update module implementing a Chronosphere-style teleport superweapon: teleports units from a source area to a target area after a delay. (PR #100)

Behavior = ChronoSphereUpdate ModuleTag_Chrono
  SpecialPowerTemplate = <SpecialPower entry>
  Radius = 0.0                 ; radius of the source/target area
  RequiredKindOf = <KindOf list>     ; only these units are teleported
  ForbiddenKindOf = <KindOf list>    ; these units are never teleported
  TeleportDelay = 0            ; ms between activation and the teleport happening
  SourceFX = <FXList>          ; FX at the source area
  SourceOCL = <OCL>            ; OCL at the source area
  TargetFX = <FXList>          ; FX at the target area
  TargetOCL = <OCL>            ; OCL at the target area
  UnitSourceFX = <FXList>      ; FX on each teleported unit at the source
  UnitTargetFX = <FXList>      ; FX on each teleported unit at the target
End

MultiLocationSpecialPowerUpdate (New)

Special power update that can create objects/OCLs at multiple resolved map locations (e.g. edges relative to the source/target). Used together with the multi-target CommandButton fields.

Behavior = MultiLocationSpecialPowerUpdate ModuleTag_MultiLoc
  SpecialPowerTemplate = <SpecialPower entry>
  CreateLocation = CREATE_AT_EDGE_NEAR_SOURCE   ; where the OCL/object is created
  ; valid values:
  ;   CREATE_AT_EDGE_NEAR_SOURCE (default)
  ;   CREATE_AT_EDGE_NEAR_TARGET
  ;   CREATE_AT_EDGE_FARTHEST_FROM_TARGET
  ;   CREATE_AT_LOCATION
  InitialDelay = 0        ; ms before the first creation
  Delay = 0               ; ms between creations at each location
  OCL = <OCL entry>       ; default OCL created at each location
  UpgradeOCL = <Upgrade> <OCL>   ; optional per-upgrade OCL override (can repeat)
End

RiftSlowDeathBehavior (New)

A slow death behavior that turns its object into a gravity well ("rift" / black hole). Put it on a helper object (e.g. created by an OCL) and let it die right away (e.g. LifetimeUpdate with a 1 ms lifetime): when the slow death starts, the rift locks in its position LiftHeight above the ground and runs through its phases. Everything pullable within Radius is lifted, spun and sucked toward the center; things reaching EventHorizonRadius are consumed. At the end the rift collapses with an outward blast.

Phases: charge (InitialDelay, FX only, nothing is pulled), ramp-up (RampupTime, strength 0 → 1), main (MainDuration, full strength), fade-out (FadeOutTime, strength 1 → 0), then collapse. Strength scales suction and damage. Suction also falls off linearly from the center to Radius.

It extends SlowDeathBehavior, so all its parameters (DestructionDelay, DeathTypes, FX/OCL phases, ...) work too. DestructionDelay must be at least the sum of the four phase times, or the rift is cut off.

Behavior = RiftSlowDeathBehavior ModuleTag_Rift
  DestructionDelay = 16050      ; >= sum of the phases below

  ; --- Phases (ms) ---
  InitialDelay = 0              ; charge phase, FXCharge only
  RampupTime = 0                ; strength climbs 0 -> 1
  MainDuration = 0              ; full strength
  FadeOutTime = 0               ; strength falls 1 -> 0, then the rift collapses

  ; --- Shape ---
  Radius = 0.0                  ; 2D radius of the effect (the circle on the ground)
  EventHorizonRadius = 0.0      ; victims closer than this (3D) are killed with ConsumeDeathType; 0 = off
  LiftHeight = 100.0            ; height of the rift center above the ground

  ; --- Suction ---
  PullAcceleration = 0.0        ; inward acceleration, dist/sec^2
  SwirlFactor = 0.0             ; bends the pull sideways: 0 = falls straight in, ~1 = orbits
  PullDamping = 12%             ; velocity bled off per frame; terminal speed is about PullAcceleration / PullDamping
  LiftAcceleration = 0.0        ; vertical acceleration toward the rift plane, dist/sec^2
  MaxPullSpeed = 0.0            ; speed cap for held victims, dist/sec; 0 = no cap
  InitialLiftVelocity = 0.0     ; upward kick on capture, dist/sec
  CancelGravity = Yes           ; cancel world gravity while a victim is held
  SpinRate = 0                  ; tumble, deg/sec
  HugeVehiclePullScalar = 1.0   ; suction multiplier for KINDOF_HUGE_VEHICLE

  ; --- Damage (everything within Radius, pullable or not) ---
  DamagePerSecond = 0.0         ; at full strength (inside MaximumDamageRadius)
  MaximumDamageRadius = 0.0     ; 2D distance within which the full DamagePerSecond applies
  OuterDamagePerSecond = -1     ; damage per second at Radius, linear falloff from MaximumDamageRadius; negative = no falloff
  DamageInterval = 1000         ; ms between damage ticks
  DamageType = EXPLOSION
  DeathType = NORMAL            ; death type of the continuous damage
  ConsumeDeathType = EXPLODED   ; death type at the event horizon, and for damage kills within ConsumeDeathRadius
  ConsumeDeathRadius = 0.0      ; victims killed within this distance keep falling in until they are destroyed

  ; --- Collapse ---
  FinalPushForce = 0.0          ; shockwave over the whole Radius at the collapse; 0 = none
  FinalPushSpeed = 0.0          ; outward throw for victims still held, dist/sec
  FinalPushDeathType = SPLATTED

  ; --- Filters ---
  PullKindOf = <KindOf list>    ; if set, only these kinds are pulled
  NoPullKindOf = PROJECTILE SMALL_MISSILE BALLISTIC_MISSILE INERT DRAWABLE_ONLY OPTIMIZED_TREE MINE  ; (default) never pulled

  ; --- Effects ---
  FXCharge = <FXList>           ; at activation
  FXMain = <FXList>             ; at the start of the ramp-up
  FXFinal = <FXList>            ; at the collapse
  FXConsume = <FXList>          ; on each victim crossing the event horizon
  OCLConsume = <OCL>            ; on each victim crossing the event horizon

  ; --- Structure debris ---
  StructureDebrisOCL = <OCL>    ; fired at a random spot on a damaged structure; the created object is pulled in
  StructureDebrisChance = 100%  ; per damaged structure per damage tick
  StructureDebrisCount = 1      ; how often the OCL fires per spawn, each at its own spot
End

Notes:

• Never pulled (they only take damage): IMMOBILE, STRUCTURE, BRIDGE, BRIDGE_TOWER, the new IMMUNE_TO_PULL KindOf, contained passengers, invulnerable objects and objects with ImmortalBody / HighlanderBody.
• Aircraft whose locomotor has LocomotorWorksWhenDisabled are steered through their own locomotor; everything else is taken over by physics (disabled as in freefall while held).
• Only the first object a StructureDebrisOCL creates can be grabbed, so use Count = 1 in that OCL and StructureDebrisCount for more pieces. Debris is destroyed at the event horizon. Structures that can't be destroyed (indestructible, ImmortalBody, HighlanderBody) never spawn debris.
• Victims consumed at the event horizon stay held until they are destroyed, so a death that plays out over time (e.g. a shrinking ChronoDeathBehavior) happens inside the singularity instead of dropping to the ground.
• A new DamageType and DeathType BLACK_HOLE are available for DamageType / ConsumeDeathType and matching armor and die modules.
• Rift generator superweapons can use the special power enum SPECIAL_RIFT_GENERATOR, the radius cursor RIFT_GENERATOR and the *_RIFT_GENERATOR EVA events (see SpecialPowers).

Misc Improvements

ObjectExtend

Allows to use inheritence in the parser. ObjectExtend is similar to ObjectReskin but inherit all modules and allow modifications. The parent object must be defined before the ObjectExtend.

Syntax: ObjectExtend NewObject ObjectToInheritFrom

Use RemoveModule ModuleTag_xx to remove a module inherited from the parent.
WeaponSet and ArmorSet are inherited, but if you define another one in the child, the inherited sets are removed.
If the parent has multiple WeaponSets all will be removed from the child if the child defines one. Prerequisites work the same way: they are inherited, but a Prerequisites block in the child replaces the inherited ones instead of adding to them.

Examples:

ObjectExtend ZExtendedTank Chem_GLAVehicleRadarVan  
  ; *** ART Parameters ***  
  SelectPortrait = SNHacker2_L ;define other icons  
  ButtonImage = SNHacker2  
    
  RemoveModule ModuleTag_01 ; Remove the parent's draw  
  
  Draw = W3DTankDraw ModuleTag_1337 ; add a new draw  
    OkToChangeModelColor = Yes  
    DefaultConditionState  
      Model = NVInferno  
      Turret = Turret  
      TurretPitch = TurretEL01  
      WeaponFireFXBone = PRIMARY Muzzle  
      WeaponRecoilBone = PRIMARY Barrel  
      WeaponLaunchBone = PRIMARY Muzzle  
      HideSubObject = PARTSUP TurretEl02  
      ShowSubObject = TurretEL01 TURRETPARTS  
    End  
    ConditionState = RUBBLE REALLYDAMAGED  
      Model = NVInferno_D  
    End  
    TrackMarks = EXTnkTrack.tga  
    TreadAnimationRate = 2.0  
  End  
  Draw = W3DModelDraw ModuleTag_0123 ; add a second draw (tree on top)  
    DefaultConditionState  
      Model = PTOak01  
    End  
  End  
  Prerequisites ; change the prerequisites  
    Object = Tank_ChinaCommandCenter TEST_MODE  
  End  
  WeaponSet ; define new weaponset, all parent inherited weapons are cleared  
    Conditions = None  
    Weapon = PRIMARY Tank_InfernoCannonGun  
  End  
  RemoveModule ModuleTag_Stealth ; Remove the stealth update inherited from the parent  
End  
ObjectExtend ZExtendedTank2 ZExtendedTank  ; inherit again
  RemoveModule ModuleTag_0123  ; remove the tree draw
  WeaponSet  ; replaces all weaponset
    Conditions = None  
    Weapon = PRIMARY MarauderTankGun  
  End  
  ArmorSet  ; replaces all armor sets
    Conditions = None  
    Armor = TruckArmorExtended  
    DamageFX = TankDamageFX  
  End  
End