diff --git a/Docs/INI/Object/Enums/DamageType.md b/Docs/INI/Object/Enums/DamageType.md new file mode 100644 index 0000000000..53b788b1c7 --- /dev/null +++ b/Docs/INI/Object/Enums/DamageType.md @@ -0,0 +1,180 @@ +# DamageType + +Status: AI-generated, 0/2 reviews + +## Overview + +`DamageType` is an enum that defines the different types of damage that can be dealt to objects in the game. Damage types are used to determine how damage interacts with armor, what visual and audio effects are played, and what special behaviors are triggered. Different damage types can have different effectiveness against different armor types, and some damage types have special mechanics (e.g., surrender damage, status damage). + +Damage types are used throughout the game for: +- **Weapon damage**: Weapons specify their damage type to determine how they interact with targets +- **Armor resistance**: Armor types can have different resistances to different damage types +- **Visual effects**: Different damage types trigger different visual and audio effects +- **Special mechanics**: Some damage types have special behaviors (e.g., surrender damage causes units to surrender, status damage applies status conditions) + +**For modders**: In INI files, you specify the damage type for weapons using the `DamageType` property. Damage types interact with armor types defined in [Armor](../Armor.md) templates to determine final damage amounts. Some damage types have special mechanics that affect how they interact with objects. + +Available in: *(v1.04)* + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) +- [Enum Value Lists](#enum-value-lists) + - [Standard Damage Types](#standard-damage-types) + - [Special Damage Types](#special-damage-types) +- [Examples](#examples) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +**Limitations**: +- Damage types are assigned to weapons in the [Weapon](../Weapon.md) template using the `DamageType` property. +- Damage types interact with armor types to determine final damage amounts through damage multipliers. +- Some damage types have special mechanics that bypass normal health damage (e.g., status damage). +- Damage types are used by visual effect systems to determine which effects to play when damage is dealt. + +**Conditions**: +- Damage types are specified in weapon templates to define how weapons deal damage. +- Armor templates define resistance multipliers for each damage type. +- Some damage types have special behaviors that trigger when they are dealt (e.g., `DAMAGE_SURRENDER` causes units to surrender instead of die). +- Damage types can be combined in damage type flags for systems that need to check for multiple damage types. + +**Dependencies**: +- Damage types are used by [Weapon](../Weapon.md) templates to define weapon damage characteristics. +- Damage types interact with [Armor](../Armor.md) templates to determine damage multipliers. +- Some damage types require specific body modules or behaviors to function (e.g., surrender damage requires units with the `CAN_SURRENDER` KindOf flag). + +## Enum Value Lists + +### DamageType Values + +Available in: *(v1.04)* + +### Standard Damage Types + +- **`DAMAGE_EXPLOSION`** *(v1.04)* - Explosive damage. Standard explosive damage type used by most explosive weapons like grenades, rockets, and bombs. Used for weapons that deal damage through explosive force. Typically effective against structures and vehicles. + +- **`DAMAGE_CRUSH`** *(v1.04)* - Crush damage. Damage type used when objects are crushed by heavier units or objects. Used for vehicles running over lighter units or objects. Typically very effective against infantry and light vehicles. + +- **`DAMAGE_ARMOR_PIERCING`** *(v1.04)* - Armor-piercing damage. Damage type designed to penetrate armor. Used by anti-tank weapons and armor-piercing rounds. Typically very effective against heavily armored targets. + +- **`DAMAGE_SMALL_ARMS`** *(v1.04)* - Small arms damage. Damage type used by small firearms like pistols and rifles. Used for infantry weapons and light firearms. Typically effective against infantry and light targets. + +- **`DAMAGE_GATTLING`** *(v1.04)* - Gatling gun damage. Damage type used by rapid-fire weapons like gatling guns and miniguns. Used for high-rate-of-fire weapons. Typically effective against infantry and light vehicles. + +- **`DAMAGE_RADIATION`** *(v1.04)* - Radiation damage. Damage type used by radiation-based weapons. Used for weapons that deal damage through radiation exposure. May have special effects on certain unit types. + +- **`DAMAGE_FLAME`** *(v1.04)* - Flame damage. Damage type used by flamethrowers and fire-based weapons. Used for weapons that deal damage through fire. Can set objects on fire and cause burning effects. + +- **`DAMAGE_LASER`** *(v1.04)* - Laser damage. Damage type used by laser weapons. Used for precision energy weapons. Typically very accurate and effective against various targets. + +- **`DAMAGE_SNIPER`** *(v1.04)* - Sniper damage. Damage type used by sniper rifles. Used for long-range precision weapons. Typically very effective against infantry and can kill pilots in vehicles. + +- **`DAMAGE_POISON`** *(v1.04)* - Poison damage. Damage type used by poison-based weapons. Used for weapons that deal damage through toxic effects. May have special effects on biological targets. + +- **`DAMAGE_HEALING`** *(v1.04)* - Healing damage (negative damage). Special damage type that heals instead of damages. Used by healing systems to restore health. Negative damage values heal the target. + +- **`DAMAGE_UNRESISTABLE`** *(v1.04)* - Unresistable damage. Damage type that bypasses all armor resistances. Used for scripting to cause 'armorproof' damage. This damage type ignores all armor multipliers and deals full damage. + +- **`DAMAGE_WATER`** *(v1.04)* - Water damage. Damage type used by water-based attacks. Used for weapons that deal damage through water or flooding. May have special effects on certain unit types. + +- **`DAMAGE_DEPLOY`** *(v1.04)* - Deploy damage. Special damage type for transports to deploy units and order them to all attack. Used by transport systems to deploy passengers. Does not deal actual damage but triggers deployment behavior. + +- **`DAMAGE_SURRENDER`** *(v1.04)* - Surrender damage. If something "dies" to surrender damage, they surrender instead of being destroyed. Used by surrender systems to force units to surrender. Units with the `CAN_SURRENDER` KindOf flag will surrender instead of die when killed by this damage type. + +- **`DAMAGE_HACK`** *(v1.04)* - Hack damage. Damage type used by hacking attacks. Used for weapons that hack or disable electronic systems. May have special effects on electronic targets. + +- **`DAMAGE_KILLPILOT`** *(v1.04)* - Kill pilot damage. Special snipe attack that kills the pilot and renders a vehicle unmanned. Used by sniper weapons to kill vehicle pilots. Vehicles affected by this damage type become unmanned and can be hijacked. + +- **`DAMAGE_PENALTY`** *(v1.04)* - Penalty damage. Damage from game penalty (you won't receive radar warnings BTW). Used by penalty systems to deal damage as a penalty. Does not trigger radar warnings. + +- **`DAMAGE_FALLING`** *(v1.04)* - Falling damage. Damage type used when objects fall from heights. Used by physics systems when objects take fall damage. Typically results in `DEATH_SPLATTED` death type. + +- **`DAMAGE_MELEE`** *(v1.04)* - Melee damage. Blades, clubs, and other melee weapons. Used for close-combat weapons. Typically effective against infantry. + +- **`DAMAGE_DISARM`** *(v1.04)* - Disarm damage. "Special" damage type used for disarming mines, bombs, etc. (NOT for "disarming" an opponent!). Used by mine clearing systems to disarm explosive devices. Does not deal health damage but disarms explosive objects. + +- **`DAMAGE_HAZARD_CLEANUP`** *(v1.04)* - Hazard cleanup damage. Special damage type for cleaning up hazards like radiation or bio-poison. Used by cleanup systems to remove environmental hazards. Does not deal health damage but removes hazard effects. + +- **`DAMAGE_PARTICLE_BEAM`** *(v1.04)* - Particle beam damage. Incinerates virtually everything (insanely powerful orbital beam). Used by superweapon systems. Extremely powerful damage type that can destroy almost anything. + +- **`DAMAGE_TOPPLING`** *(v1.04)* - Toppling damage. Damage from getting toppled. Used by topple systems when structures fall over. Results in toppled state rather than destruction. + +- **`DAMAGE_INFANTRY_MISSILE`** *(v1.04)* - Infantry missile damage. Damage type used by infantry-carried missile weapons. Used for portable missile launchers. Typically effective against vehicles and structures. + +- **`DAMAGE_AURORA_BOMB`** *(v1.04)* - Aurora bomb damage. Damage type used by Aurora bomber weapons. Used for specialized bomber weapons. Typically very effective against structures. + +- **`DAMAGE_LAND_MINE`** *(v1.04)* - Land mine damage. Damage type used by land mines. Used for explosive traps. Typically very effective against vehicles and infantry. + +- **`DAMAGE_JET_MISSILES`** *(v1.04)* - Jet missile damage. Damage type used by jet aircraft missiles. Used for air-to-ground and air-to-air missiles from jet aircraft. Typically effective against various targets. + +- **`DAMAGE_STEALTHJET_MISSILES`** *(v1.04)* - Stealth jet missile damage. Damage type used by stealth jet aircraft missiles. Used for specialized stealth aircraft weapons. Typically effective against various targets. + +- **`DAMAGE_MOLOTOV_COCKTAIL`** *(v1.04)* - Molotov cocktail damage. Damage type used by molotov cocktail weapons. Used for incendiary thrown weapons. Sets targets on fire. + +- **`DAMAGE_COMANCHE_VULCAN`** *(v1.04)* - Comanche Vulcan damage. Damage type used by Comanche helicopter Vulcan cannon. Used for specialized helicopter weapons. Typically very effective against infantry and light vehicles. + +- **`DAMAGE_FLESHY_SNIPER`** *(v1.04, Zero Hour only)* - Fleshy sniper damage. Like `DAMAGE_SNIPER`, but generally does no damage to vehicles. Used by sniper weapons that are specifically designed to target infantry. Only effective against infantry, vehicles are immune. + +## Examples + +### Basic Damage Type Usage + +```ini +Weapon = TankCannon WeaponSlot_PRIMARY + DamageType = ARMOR_PIERCING + Damage = 150 + Range = 200 +End +``` + +In this example, the weapon uses `ARMOR_PIERCING` damage type, which is effective against armored targets. + +## Notes + +- **Damage Type and Armor Interaction**: Damage types interact with armor types through damage multipliers defined in [Armor](../Armor.md) templates. The final damage is calculated as: `finalDamage = baseDamage * armorMultiplier[damageType]`. + +- **Special Damage Types**: Some damage types have special mechanics that bypass normal health damage: + - **Deploy damage** (`DAMAGE_DEPLOY`): Does not deal damage but triggers deployment behavior + - **Disarm damage** (`DAMAGE_DISARM`): Does not deal health damage but disarms explosive devices + - **Hazard cleanup damage** (`DAMAGE_HAZARD_CLEANUP`): Does not deal health damage but removes hazard effects + +- **Damage Type Flags**: Damage types can be combined in `DamageTypeFlags` (bit flags) for systems that need to check for multiple damage types simultaneously. + +## Source Files + +**Header (Generals):** [Damage.h](../../../../Generals/Code/GameEngine/Include/GameLogic/Damage.h) *(if retail Generals codebase exists)* +- `DamageType` enum definition (lines 43-97): Defines all available damage types for Retail Generals + +**Header (Zero Hour):** [Damage.h](../../Code/GameEngine/Include/GameLogic/Damage.h) +- `DamageType` enum definition (lines 43-97): Defines all available damage types for Retail Zero Hour + +**Source (Generals):** [Damage.cpp](../../../../Generals/Code/GameEngine/Source/GameLogic/Damage.cpp) *(if retail Generals codebase exists)* +- Damage type name mapping: Maps damage type names to their values for INI file parsing + +**Source (Zero Hour):** [Damage.cpp](../../Code/GameEngine/Source/GameLogic/Damage.cpp) +- Damage type name mapping: Maps damage type names to their values for INI file parsing + +## Changes History + +- In Retail Zero Hour, 1 new damage type was added: `DAMAGE_FLESHY_SNIPER` (like `DAMAGE_SNIPER`, but generally does no damage to vehicles). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +AI-generated, 0/2 reviews + +## Reviewers + +- [ ] Reviewer 1 +- [ ] Reviewer 2 + diff --git a/Docs/INI/Object/Enums/KindOf.md b/Docs/INI/Object/Enums/KindOf.md new file mode 100644 index 0000000000..bbc11afc82 --- /dev/null +++ b/Docs/INI/Object/Enums/KindOf.md @@ -0,0 +1,419 @@ +# KindOf + +Status: AI-generated, 0/2 reviews + +## Overview + +KindOf is a system used to categorize and filter objects in the game. Each KindOf flag represents a specific category or property that an object can have. Objects can have multiple KindOf flags at the same time, which allows flexible classification and filtering. + +For example, a tank might have `KindOf = VEHICLE CAN_ATTACK SELECTABLE`, meaning it's categorized as a vehicle, can attack, and can be selected by the player. + +KindOf flags are used throughout the game for many purposes: +- **Weapon targeting**: Weapons can prefer certain types of targets (e.g., anti-infantry weapons prefer infantry) +- **AI behavior**: AI systems use KindOf to filter and prioritize targets +- **Special abilities**: Special powers and abilities can affect specific object types +- **Gameplay mechanics**: Systems like garrisoning, pathfinding, and victory conditions use KindOf flags + +**For modders**: In INI files, you simply list the KindOf flags you want an object to have. The game automatically combines them into a collection of flags. You don't need to worry about the technical details - just list the flags that describe your object. + +Available in: *(v1.04)* + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) +- [Enum Value Lists](#enum-value-lists) + - [Basic Object Types](#basic-object-types) + - [Prison/Surrender System](#prison-surrender-system) + - [Building and Structure Types](#building-and-structure-types) + - [Unit Role Types](#unit-role-types) + - [Naval Categories](#naval-categories) + - [Projectile and Special Objects](#projectile-and-special-objects) + - [Faction Structure Types (FS)](#faction-structure-types-fs) + - [Building and Structure Behaviors](#building-and-structure-behaviors) + - [Visibility and Interaction](#visibility-and-interaction) + - [Movement and Pathfinding](#movement-and-pathfinding) + - [Garrison and Containment](#garrison-and-containment) + - [Special Abilities](#special-abilities) + - [Supply and Resources](#supply-and-resources) + - [Gameplay and Scoring](#gameplay-and-scoring) + - [Special Object States](#special-object-states) + - [Special Behaviors](#special-behaviors) + - [Water and Terrain](#water-and-terrain) + - [Custom/Extra Flags](#customextra-flags) +- [Examples](#examples) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +**Limitations**: +- Multiple KindOf flags can be set on a single object by listing them in the `KindOf` property. +- KindOf flags are defined in the object's `KindOf` property in INI files. The property accepts a space-separated list of KindOf flag names. +- Some KindOf flags may have dependencies or interactions with other flags (e.g., `STICK_TO_TERRAIN_SLOPE` requires `IMMOBILE` to be set). +- KindOf flags are case-sensitive and must match exactly as defined in the value list below. + +**Conditions**: +- KindOf flags are set in the object's `KindOf` property in INI files (e.g., `KindOf = INFANTRY VEHICLE`). +- Multiple KindOf flags can be combined by listing them space-separated in the `KindOf` property. +- Systems throughout the game use KindOf flags to filter objects (e.g., weapons can target specific KindOf types, AI systems can filter by KindOf, special abilities can affect specific KindOf types). +- Game systems can check for multiple flags at once, allowing complex filtering rules. + +**Dependencies**: +- KindOf flags are defined at the object template level and apply to all instances of that object. +- Various game systems reference KindOf flags for filtering and targeting (e.g., [Weapon](../Weapon.md) targeting, AI behavior, special powers). + +## Enum Value Lists + +### KindOf Flag Values + +The following KindOf flags are available for use in INI files. Each flag represents a specific category or property that objects can have. You can combine multiple flags by listing them in the `KindOf` property. + +**Source (Generals):** [KindOf.h](../../../Generals/Code/GameEngine/Include/Common/KindOf.h) - KindOf flag definitions (lines 41-254) *(if retail Generals codebase exists)* + +**Source (Zero Hour):** [KindOf.h](../../Code/GameEngine/Include/Common/KindOf.h) - KindOf flag definitions (lines 41-254) + +**Parsing (Generals):** [KindOf.cpp](../../../Generals/Code/GameEngine/Source/Common/System/KindOf.cpp) - Flag name mapping (line 35) - Maps flag names to their values for INI file parsing. *(if retail Generals codebase exists)* + +**Parsing (Zero Hour):** [KindOf.cpp](../../Code/GameEngine/Source/Common/System/KindOf.cpp) - Flag name mapping (line 35) - Maps flag names to their values for INI file parsing. + +The following KindOf flags are available and can be combined: + +### Basic Object Types +- **`OBSTACLE`** *(v1.04)* - Objects that block land-based pathfinders. Pathfinding systems use this flag to identify objects that units cannot move through or must navigate around. Objects with this flag are treated as obstacles by the pathfinding system, affecting unit movement and AI path planning. + +- **`SELECTABLE`** *(v1.04)* - Actually means MOUSE-INTERACTABLE (doesn't mean you can select it!). This flag determines whether an object can be interacted with via mouse clicks. Objects with this flag can be clicked, hovered over, and interacted with through the UI. The default selectability state is determined by this flag, though it can be overridden per-object instance. Note: This flag does NOT guarantee the object is selectable - it only enables mouse interaction. + +- **`IMMOBILE`** *(v1.04)* - Fixed in location. Objects with this flag cannot move and are permanently positioned at their spawn location. Used by structures and static objects. Objects with this flag do not receive AI update interfaces (AIUpdate) unless they also have other specific requirements. Immobile objects with weapons have special range checking behavior - they must be within weapon range to attack targets, as they cannot move to close distance. This flag is also used by weapon systems to determine if an object can adjust its position to attack targets. + +- **`CAN_ATTACK`** *(v1.04)* - Indicates the object can attack other objects. Objects with this flag can use weapons to attack targets. This flag is used by weapon targeting systems to identify objects that are capable of offensive actions. Typically combined with other flags like `INFANTRY`, `VEHICLE`, `STRUCTURE`, or `AIRCRAFT` to define what type of object can attack. + +- **`STICK_TO_TERRAIN_SLOPE`** *(v1.04)* - Object should be stuck at ground level and aligned to terrain slope. When set, the object automatically aligns itself to the terrain slope at its location. **Requires that `IMMOBILE` flag is also set** - this flag only works on immobile objects. Objects with this flag are positioned at ground level and rotate to match the terrain angle. + +- **`CAN_CAST_REFLECTIONS`** *(v1.04)* - Object can cast reflections in water. When set, the object will create reflection effects when positioned over water surfaces. Used for visual rendering effects to create realistic water reflections. Objects with this flag or the `FLAG_DRAWS_IN_MIRROR` flag are rendered with mirror effects. + +- **`SHRUBBERY`** *(v1.04)* - Tree, bush, or other vegetation objects. Objects with this flag are treated as vegetation by the game systems. Shrubbery can only be damaged by flame weapons (`DEATH_BURNED` damage type) - all other damage types return 0.0 damage. Shrubbery objects are filtered out of map loading when trees are disabled in graphics settings. Used for decorative terrain objects that can be destroyed by fire. + +- **`STRUCTURE`** *(v1.04)* - Building structure of some sort (buildable or not). Objects with this flag are identified as structures by game systems. Used extensively for weapon targeting (weapons can prefer structures as targets), AI behavior (AI can target structures for attacks), script actions (scripts can filter for structures), and victory conditions. Structures are typically combined with `IMMOBILE` to indicate they cannot move. Structures with sniper damage types check if they have garrisoned units before allowing damage. Structures are used in multiplayer victory calculations and scoring systems. + +- **`INFANTRY`** *(v1.04)* - Infantry unit (soldier, etc.). Objects with this flag are identified as infantry units. Used extensively for weapon targeting (weapons can prefer infantry as targets), AI behavior (AI can target infantry units), garrison systems (infantry can garrison buildings unless `NO_GARRISON` is set), weapon accuracy (infantry-specific inaccuracy modifiers), and script actions. Infantry units can typically garrison buildings and are affected by anti-infantry weapons. Used for airborne infantry targeting calculations. + +- **`VEHICLE`** *(v1.04)* - Vehicle unit (tank, jeep, plane, helicopter, etc.). Objects with this flag are identified as vehicles by game systems. Used extensively for weapon targeting (weapons can prefer vehicles as targets), AI behavior (AI can target vehicles), airborne vehicle targeting, and script actions. Vehicles are typically mobile units that can move around the map. + +- **`AIRCRAFT`** *(v1.04)* - Aircraft unit (plane, helicopter, etc.) that is predominantly a flyer. Objects with this flag are identified as aircraft units. **Important: Hovercraft are NOT aircraft** - they are vehicles. Aircraft units are affected by aircraft pathfinding (they path around tall objects with `AIRCRAFT_PATH_AROUND` flag). Used for weapon targeting, AI behavior, and categorization. + +- **`HUGE_VEHICLE`** *(v1.04)* - Unit that is technically a vehicle, but WAY larger than normal (e.g., Overlord). Objects with this flag are identified as exceptionally large vehicles. Used for special handling of oversized vehicle units. Typically combined with `VEHICLE` to indicate a large vehicle. + +- **`DOZER`** *(v1.04)* - Construction unit (dozer). Objects with this flag are identified as construction units that can build structures. Used extensively by construction systems, AI behavior (AI uses dozers for building), production systems (production checks if builder is a dozer), pathfinding (dozers can move through obstacles that other units cannot), and script actions. Dozers are excluded from certain AI calculations and can enter unmanned vehicles (unless `REJECT_UNMANNED` is set). Dozers are used by the build assistant system and can be commanded to construct buildings. AI systems filter dozers separately from other units for construction tasks. + +- **`HARVESTER`** *(v1.04)* - Resource gathering unit (harvester). Objects with this flag are identified as resource gathering units. Used extensively by AI behavior (AI uses harvesters for resource gathering), resource systems (harvesters collect supplies), pathfinding (harvesters can use special pathfinding rules), and script actions. Harvesters are typically supply trucks or specialized resource gathering vehicles. AI systems filter harvesters separately for resource management tasks. Harvesters are excluded from certain combat calculations. + +- **`COMMANDCENTER`** *(v1.04)* - Command center building. Objects with this flag are identified as command centers. Used by game systems to identify the primary command structure. Script actions can check for command centers to determine player base status. Command centers are typically important structures that serve as the primary base building. + +### Prison/Surrender System *(v1.04 - conditional compilation)* +- **`PRISON`** *(v1.04 - conditional compilation)* - A prison detention center kind of thing +- **`COLLECTS_PRISON_BOUNTY`** *(v1.04 - conditional compilation)* - When prisoners are delivered to these, the player gets money +- **`POW_TRUCK`** *(v1.04 - conditional compilation)* - A pow truck can pick up and return prisoners +- **`CAN_SURRENDER`** *(v1.04 - conditional compilation)* - Object that can surrender + +### Building and Structure Types +- **`LINEBUILD`** *(v1.04)* - Wall-type structure that is built in a line. Objects with this flag are identified as structures that are constructed in a continuous line, like walls. Used by construction systems to handle line-based building mechanics. Line-build structures are typically walls or barriers that can be placed in a continuous line. + +- **`BRIDGE`** *(v1.04)* - Bridge structure (special structure). Objects with this flag are identified as bridges. Used extensively by game systems for special bridge handling: weapon systems check for bridges to prevent targeting (bridges cannot be force-attacked), wave guide systems check bridge height for water effects, pathfinding systems use bridges for unit movement, and weapon systems check bridges for collision behavior. Bridges are special structures that connect terrain across water or gaps. + +- **`LANDMARK_BRIDGE`** *(v1.04)* - Landmark bridge (special bridge that isn't resizable). Objects with this flag are identified as landmark bridges that have fixed sizes and cannot be resized. Used for special bridges that are part of the map terrain rather than buildable structures. Landmark bridges are typically pre-placed on maps and cannot be modified. + +- **`BRIDGE_TOWER`** *(v1.04)* - Bridge tower that can be targeted for bridge destruction. Objects with this flag are identified as bridge towers that support bridges. Used by weapon systems (bridge towers cannot be force-attacked, similar to bridges), wave guide systems to check bridge structure, and worker AI systems to identify bridge repair targets. Destroying bridge towers can cause bridges to collapse. Bridge towers are typically used to support bridge structures. + +- **`REBUILD_HOLE`** *(v1.04)* - GLA rebuild hole. Objects with this flag are identified as rebuild holes used by the GLA faction. Rebuild holes are special structures that allow destroyed buildings to be rebuilt. Used for GLA-specific rebuilding mechanics. + +- **`DEFENSIVE_WALL`** *(v1.04)* - Wall can't be driven through, even if crusher, so pathfinder must path around it. Objects with this flag are identified as defensive walls that cannot be destroyed by crusher units. Used by pathfinding systems to ensure units path around these walls rather than attempting to drive through them. Defensive walls are typically indestructible barriers that block unit movement. + +- **`PORTABLE_STRUCTURE`** *(v1.04)* - Flag to identify building-like subobjects an Overlord is allowed to Contain. Objects with this flag are identified as structures that can be contained by units like the Overlord. Used by contain systems to determine which structures can be carried by transport units. Portable structures are typically small buildings or sub-objects that can be moved. + +- **`WALK_ON_TOP_OF_WALL`** *(v1.04)* - Units can walk on top of a wall made of these kind of objects. Objects with this flag allow units to walk on top of them. Used by pathfinding systems to enable units to traverse walls. Used by game logic systems to check if units can walk on wall objects. Used for wall structures that units can climb and walk across. + +### Unit Role Types +- **`SALVAGER`** *(v1.04)* - Units that can create and use Salvage Crates. Objects with this flag can pick up salvage crates and receive benefits from them. Used by the salvage crate collision system to filter which units can interact with salvage crates. Only units with this flag can pick up salvage crates when they collide with them. Used extensively by AI systems and script actions to identify salvage-capable units. Salvage crates search for nearby units with this flag when determining valid targets. + +- **`WEAPON_SALVAGER`** *(v1.04)* - Subset of salvager that can get weapon upgrades from salvage. Objects with this flag are salvagers that specifically receive weapon upgrades when picking up salvage crates. This is a specialized flag that combines with `SALVAGER` to indicate the type of upgrade received from salvage. Used by salvage systems to determine upgrade type distribution. + +- **`ARMOR_SALVAGER`** *(v1.04, Zero Hour only)* - Subset of salvager that can get armor upgrades from salvage. Objects with this flag are salvagers that specifically receive armor upgrades when picking up salvage crates. This is a specialized flag that combines with `SALVAGER` to indicate the type of upgrade received from salvage. Used by salvage systems to determine upgrade type distribution. + +- **`TRANSPORT`** *(v1.04)* - A true transport unit (has TransportContain module). Objects with this flag are identified as transport units that can carry other units. Used by script actions to identify transport units and by transport systems to determine if a unit can carry passengers. Transport units must have a TransportContain module to function properly. Script actions check for this flag when determining if a unit can transport other units. + +- **`HERO`** *(v1.04)* - Hero units (any of the single-instance infantry: JarmenKell, BlackLotus, ColonelBurton). Objects with this flag are identified as hero units. Used by weapon systems for special hero-specific behavior (e.g., `DAMAGE_KILLPILOT` damage type works differently on heroes with primary weapons). Hero units are typically unique, single-instance units with special abilities. Used for filtering and special gameplay mechanics. + +### Naval Categories +- **`BOAT`** *(v1.04)* - Naval vessel unit. Objects with this flag are identified as boats or naval units. Used by disguise systems to prevent units from disguising as boats (boats cannot be disguised as). Used by action manager systems to filter boat targets. Used for categorization of naval units that operate on water surfaces. + +### Projectile and Special Objects +- **`PROJECTILE`** *(v1.04)* - Projectile object (instead of being a ground or air unit, this object is special). Objects with this flag are identified as projectiles launched by weapons. Used by weapon systems for collision detection (weapons can collide with projectiles), projectile targeting, and weapon targeting. All projectiles should have this flag. Projectiles are typically temporary objects that exist only during weapon firing. + +- **`SMALL_MISSILE`** *(v1.04)* - Small missile object: **ONLY USED FOR ANTI-MISSILE TARGETING PURPOSES!** Keep using `PROJECTILE` for general projectiles! Objects with this flag are identified as small missiles that can be targeted by anti-missile systems. Used by anti-missile targeting systems and countermeasure systems. All missiles are also projectiles, so this flag should be combined with `PROJECTILE`. This flag is specifically for anti-missile weapon targeting - do not use it for general projectile identification. + +- **`BALLISTIC_MISSILE`** *(v1.04)* - Large ballistic missiles that are specifically large enough to be targeted by base defenses. Objects with this flag are identified as large ballistic missiles. Used by base defense targeting systems. Ballistic missiles are typically large strategic weapons that can be intercepted by base defenses. Used by weapon systems to determine if a weapon can target ballistic missiles. + +- **`CRATE`** *(v1.04)* - Bonus crate object. Objects with this flag are identified as bonus crates that can be picked up by units. Used by crate collision systems to identify pickup objects. Bonus crates typically provide temporary bonuses or upgrades when collected by units. + +- **`MINE`** *(v1.04)* - Landmine object (possibly also extends to Col. Burton timed charges). Objects with this flag are identified as landmines. Used by weapon systems for special mine targeting (mines can be targeted by disarm weapons and anti-mine weapons) and weapon collision detection. Mines can be disarmed by weapons with `DAMAGE_DISARM` damage type. Mines have special rendering and selection behavior. Used for explosive traps that activate when units step on them. + +- **`DEMOTRAP`** *(v1.04, Zero Hour only)* - Demo trap object added strictly only for disarming purposes. Objects with this flag are identified as demo traps. Used by weapon systems for special trap targeting (traps can be targeted by disarm weapons) and weapon collision detection. **Important: They don't act like mines which have rendering and selection implications!** Demo traps are used for disarming gameplay mechanics but don't have the same visual/selection behavior as mines. Used for Col. Burton timed charges and similar objects. + +- **`BOOBY_TRAP`** *(v1.04, Zero Hour only)* - Sticky bomb that gets set off by 5 random and unrelated events. Objects with this flag are identified as booby traps. Used by weapon systems for special trap targeting (booby traps can be targeted by disarm weapons) and weapon collision detection. Booby traps are activated by specific game events rather than direct unit contact. Used for explosive traps with complex activation triggers. + +- **`HULK`** *(v1.04)* - Hulk object types for special handling via scripts or other systems. Objects with this flag are identified as hulks (destroyed unit remains). Used for special handling of destroyed unit remains. Scripts can use this flag to identify hulk objects for special processing or cleanup. Hulks are typically the remains of destroyed vehicles or structures. + +- **`PARACHUTE`** *(v1.04)* - Parachute object. Objects with this flag are identified as parachutes. Used for weapons that can target parachuting units. Parachutes are typically temporary objects used during unit airdrops. Used for airborne unit delivery systems. + +- **`PROP`** *(v1.04, Zero Hour only)* - Prop object (visual only, doesn't interact with other objects). Objects with this flag are identified as decorative props. Props are visual-only objects that don't interact with other game objects (e.g., rocks, street signs, inert fire hydrants). Props are filtered out of certain game systems since they don't affect gameplay. Used for decorative map elements that don't need game logic interaction. + +- **`OPTIMIZED_TREE`** *(v1.04, Zero Hour only)* - Optimized, client-side only tree. Objects with this flag are identified as optimized trees that exist only on the client side. Used for performance optimization - these trees are rendered but don't have full game object logic. Optimized trees are filtered out of map loading when trees are disabled in graphics settings. Used for decorative vegetation that doesn't need full game object functionality. + +### Faction Structure Types (FS) +- **`FS_POWER`** *(v1.04)* - Faction structure power building. Objects with this flag are identified as power-generating structures. Used by `ThingTemplate` to generate unit type strings (e.g., "UNITTYPE:FS_POWER"). Typically combined with `STRUCTURE` to indicate power plant buildings. Used for categorization of structures that generate power for the faction. Power buildings are essential for powering other structures that require electricity. + +- **`FS_FACTORY`** *(v1.04)* - Faction structure factory building. Objects with this flag are identified as factory structures for unit production. Used by `ThingTemplate` to generate unit type strings. Typically combined with `STRUCTURE` to indicate factory buildings. Used for categorization of structures that produce units. Factory buildings include war factories, barracks, and other production facilities. + +- **`FS_BASE_DEFENSE`** *(v1.04)* - Faction structure base defense. Objects with this flag are identified as defensive structures for base protection. Used by `ThingTemplate` to generate unit type strings (e.g., "UNITTYPE:FS_BASE_DEFENSE"). Typically combined with `STRUCTURE` to indicate defensive buildings. Used for categorization of structures designed for base defense, such as guard towers, bunkers, and defensive emplacements. + +- **`FS_TECHNOLOGY`** *(v1.04)* - Faction structure technology building. Objects with this flag are identified as technology research structures. Used by `ThingTemplate` to generate unit type strings. Typically combined with `STRUCTURE` to indicate technology buildings. Used for categorization of structures that provide technology research and upgrades. Technology buildings unlock new units, abilities, and upgrades for the faction. + +- **`FS_SUPPLY_DROPZONE`** *(v1.04, Zero Hour only)* - Supply dropzone structure. Objects with this flag are identified as supply dropzone structures where supplies can be airdropped. Used for categorization of structures that serve as supply delivery points. Supply dropzones allow players to receive supply deliveries via airdrop, providing resources without requiring ground transport. + +- **`FS_SUPERWEAPON`** *(v1.04, Zero Hour only)* - Superweapon structure. Objects with this flag are identified as superweapon structures like nuclear missile silos, particle uplink cannons, and scud storms. Used for categorization of structures that house powerful superweapons. Superweapon structures provide devastating area-of-effect attacks but typically have long cooldown periods and high resource costs. + +- **`FS_BLACK_MARKET`** *(v1.04, Zero Hour only)* - Black market structure. Objects with this flag are identified as black market structures. Used for categorization of structures that provide black market services. Black market structures typically offer unique units, upgrades, or abilities that are not available through standard production facilities. + +- **`FS_SUPPLY_CENTER`** *(v1.04, Zero Hour only)* - Supply center structure. Objects with this flag are identified as supply center structures that generate or manage supplies. Used by `ThingTemplate` to generate unit type strings (e.g., "UNITTYPE:SUPPLY_CENTER"). Typically combined with `STRUCTURE` to indicate supply center buildings. Used for categorization of structures that provide supply generation or management capabilities. + +- **`FS_STRATEGY_CENTER`** *(v1.04, Zero Hour only)* - Strategy center structure. Objects with this flag are identified as strategy center structures. Used for categorization of structures that provide strategic capabilities. Strategy centers typically offer strategic upgrades, abilities, or command functions that affect overall faction strategy. + +- **`FS_FAKE`** *(v1.04, Zero Hour only)* - Fake structure. Objects with this flag are identified as fake structures that appear as real buildings but are actually decoys. Used by `Drawable` to determine terrain decal rendering - fake structures show shadows for allies/neutrals but no terrain decal for enemies. Used by `ThingTemplate` to generate unit type strings (e.g., "UNITTYPE:FS_FAKE"). Typically combined with `STRUCTURE` to indicate fake building structures. Used for categorization of decoy structures that appear as real buildings to deceive enemies. + +- **`FS_INTERNET_CENTER`** *(v1.04, Zero Hour only)* - Internet center structure. Objects with this flag are identified as internet center structures that provide hacking and cyber warfare capabilities. Used by `ActiveBody` to check if units inside internet centers should resume hacking when recovered from subdual. Used by script actions to identify internet center structures. Used for categorization of structures that provide hacking abilities and cyber warfare capabilities. Units garrisoned in internet centers can perform hacking attacks. + +- **`FS_ADVANCED_TECH`** *(v1.04, Zero Hour only)* - Advanced technology structure. Objects with this flag are identified as advanced technology buildings that represent each faction's advanced tech tree structure (strategy center, propaganda center, and palace). Used for categorization of the highest-tier technology structures for each faction. Advanced tech structures typically provide the most powerful upgrades and abilities available to a faction. + +- **`FS_BARRACKS`** *(v1.04, Zero Hour only)* - Barracks structure. Objects with this flag are identified as barracks structures for infantry production. Used for categorization of structures that produce infantry units. Barracks structures are production facilities specifically designed for training and deploying infantry units. + +- **`FS_WARFACTORY`** *(v1.04, Zero Hour only)* - War factory or arms dealer structure. Objects with this flag are identified as war factory structures for vehicle production. Used for categorization of structures that produce vehicles and armored units. War factory structures are production facilities specifically designed for manufacturing and deploying vehicles and combat units. + +- **`FS_AIRFIELD`** *(v1.04, Zero Hour only)* - Airfield structure. Objects with this flag are identified as airfield structures that serve as landing and takeoff points for aircraft. Used by `JetAIUpdate` and `ChinookAIUpdate` to identify valid airfield structures for aircraft operations. Used by `Weapon` to prevent projectiles from colliding with airfields when targeting aircraft parked on them. Used by `AIPathfind` to check for airfield obstacles during pathfinding. Used for categorization of structures that function as airfields for aircraft operations. Aircraft can land, take off, and be parked at airfield structures. + +### Building and Structure Behaviors +- **`TECH_BUILDING`** *(v1.04)* - Neutral tech building (Oil derrick, Hospital, Radio Station, Refinery). Objects with this flag are identified as neutral tech buildings that can be captured. Used by game systems to identify capturable neutral structures. Tech buildings are typically neutral structures that provide benefits when captured by players. + +- **`TECH_BASE_DEFENSE`** *(v1.04, Zero Hour only)* - Tech Building that acts as base defense when captured. Objects with this flag are tech buildings that function as base defenses after being captured. Used to identify tech buildings that provide defensive capabilities when captured. Combines with `TECH_BUILDING` to indicate defensive tech structures. + +- **`POWERED`** *(v1.04)* - This object gets the Underpowered disabled condition when its owning player has power consumption exceed supply. Objects with this flag are affected by power shortages. When the owning player's power consumption exceeds power supply, objects with this flag receive the `DISABLED_UNDERPOWERED` condition, which disables their functionality. Used by power systems to determine which structures are affected by power shortages. Used for buildings that require power to function. + +- **`CASH_GENERATOR`** *(v1.04)* - Used to check if the unit generates cash. Checked by cash hackers and other systems. Objects with this flag are identified as structures that generate income. Used by cash hacking systems to identify valid targets for cash generation abilities. Used by AI systems to identify income-generating structures (excluding them from certain calculations). Used by script actions to identify cash-generating buildings. Used by academy stats to track cash generation sources. + +- **`MONEY_HACKER`** *(v1.04, Zero Hour only)* - Unit that generates money from air. Needed for things that directly power them up. Objects with this flag are identified as units that generate money passively. Used by script actions to identify money-generating units. Used by academy stats to track money-generating units. Used by open contain systems to identify money-generating riders. Used for units that generate income without requiring a structure. + +- **`REPAIR_PAD`** *(v1.04)* - Is a repair pad object that can repair other machines. Objects with this flag are identified as repair pads that can repair vehicles and structures. Used by action manager systems to identify valid repair destinations. Units can be ordered to move to repair pads for automatic repair. Repair pads automatically repair nearby damaged units. + +- **`HEAL_PAD`** *(v1.04)* - Is a heal pad object that can heal flesh and bone units. Objects with this flag are identified as heal pads that can heal infantry units. Used by auto-find healing update systems to identify valid healing destinations. Used by command systems to identify heal pad targets. Units can be ordered to move to heal pads for automatic healing. Heal pads automatically heal nearby damaged infantry units. + +- **`CONSERVATIVE_BUILDING`** *(v1.04, Zero Hour only)* - Conservative structures aren't considered part of your base for sneak attack boundary calculations. Objects with this flag are excluded from base boundary calculations for sneak attack detection. Used by AI systems to determine base boundaries for sneak attack mechanics. Conservative buildings don't count as part of the base perimeter, allowing for more flexible base defense calculations. + +### Visibility and Interaction +- **`ALWAYS_VISIBLE`** *(v1.04)* - Is never obscured by fog of war or shroud. Mostly for UI feedback objects. Objects with this flag are always visible to all players, regardless of fog of war or shroud state. Used for UI feedback objects that need to remain visible for gameplay purposes. Objects with this flag bypass normal visibility checks and are rendered even when they should be hidden. + +- **`ALWAYS_SELECTABLE`** *(v1.04)* - Is never unselectable (even if effectively dead). Mostly for UI feedback objects. Objects with this flag can always be selected, even when they would normally be unselectable (e.g., when effectively dead). Used by selection systems to override normal selectability restrictions. Used for UI feedback objects that need to remain selectable. Selection checks verify this flag to allow selection of effectively dead objects. Used by AI group systems to allow non-AI units with this flag. + +- **`NO_SELECT`** *(v1.04, Zero Hour only)* - Can't select it but you can mouse over it to see its health (drones!). Objects with this flag cannot be selected by the player, but can still be hovered over to view their health status. Used by selection systems to prevent selection while allowing mouse interaction. Typically used for drones and other units that should be visible but not directly controllable. Selection systems check this flag and exclude objects with it from selection lists. + +- **`CLICK_THROUGH`** *(v1.04)* - Objects with this will never be picked by mouse interactions! Objects with this flag are completely ignored by mouse interaction systems. These objects cannot be clicked, selected, or interacted with through the mouse. Used for objects that should be completely transparent to mouse interactions. Mouse interaction systems check this flag and skip objects with it. + +- **`UNATTACKABLE`** *(v1.04)* - You cannot target this thing, it probably doesn't really exist. Objects with this flag cannot be targeted by weapons or attacks. Used by weapon systems to prevent targeting of special objects that don't represent real game entities. Weapon attack checks verify this flag and return `ATTACKRESULT_NOT_POSSIBLE` if the target has this flag. Used for objects that have "life" for lifetime updates and vision but aren't real game objects that can be attacked. + +- **`CANNOT_RETALIATE`** *(v1.04, Zero Hour only)* - Unit will not retaliate if asked. Objects with this flag will not automatically retaliate when attacked. Used by AI and combat systems to prevent automatic retaliation behavior. Units with this flag must be manually commanded to attack enemies. + +- **`REVEAL_TO_ALL`** *(v1.04)* - This object reveals shroud for all players. Objects with this flag reveal the fog of war/shroud for all players, not just the owner. Used by visibility systems to create shared visibility objects. Used for objects that should provide shared intelligence to all players. + +- **`REVEALS_ENEMY_PATHS`** *(v1.04, Zero Hour only)* - Like the listening outpost... when selected, any enemy drawable will show paths when moused over. Objects with this flag reveal enemy unit paths when selected. When the player selects an object with this flag, enemy units will display their movement paths when moused over. Used for intelligence gathering objects that provide tactical information. + +- **`CAN_SEE_THROUGH_STRUCTURE`** *(v1.04)* - Structure does not block line of sight. Objects with this flag do not block line of sight for weapons or vision systems. Used by pathfinding and weapon systems to allow units to see through these structures. Used for transparent or open structures that don't obstruct vision. + +- **`DISGUISER`** *(v1.04)* - This object has the ability to disguise. Objects with this flag can disguise themselves as other units. Used by weapon systems for special disguise behavior - force attacks can target disguised units, and disguised units that are stealthed and undetected can be attacked if they're disguised as enemies. Used by stealth systems to determine if an object can be disguised. Used for units like bomb trucks that can disguise as enemy vehicles. + +- **`IGNORED_IN_GUI`** *(v1.04)* - Object that is a member of a mob (i.e. GLAInfantryAngryMob). Objects with this flag are ignored by GUI systems. Used for objects that are part of a mob or group that should not be individually displayed in the UI. Used for mob member units that are controlled by a mob nexus object. + +- **`IGNORES_SELECT_ALL`** *(v1.04)* - Too late to figure out intelligently if something should respond to a Select All command. Objects with this flag do not respond to "Select All" commands. Used by selection systems to exclude specific units from group selection. Used for units that should not be selected as part of a group. + +- **`SHOW_PORTRAIT_WHEN_CONTROLLED`** *(v1.04)* - Only shows portraits when controlled. Objects with this flag only display their portrait in the UI when they are being directly controlled by the player. Used by UI systems to conditionally display unit portraits. Used for units that should only show portraits under specific conditions. + +### Movement and Pathfinding +- **`NO_COLLIDE`** *(v1.04)* - Object never collides with other objects or is collided with. Objects with this flag are completely ignored by collision detection systems. Used by AI update systems to skip collision avoidance logic - units with this flag do not need to tell other units to get out of the way. Used for objects that should pass through other objects without physical interaction. Used for projectiles, effects, or other objects that should not participate in collision detection. + +- **`AIRCRAFT_PATH_AROUND`** *(v1.04)* - Structure is tall enough that aircraft must path around it. Objects with this flag are identified as tall obstacles that aircraft cannot fly over. Used by aircraft pathfinding systems to create paths that navigate around tall buildings and structures. Used by `AIPathfind` to identify obstacles that aircraft must avoid during pathfinding. Aircraft pathfinding algorithms check for this flag to determine if a structure blocks aircraft movement. Used for tall buildings, towers, and other structures that extend high enough to interfere with aircraft flight paths. + +- **`LOW_OVERLAPPABLE`** *(v1.04)* - When objects overlap with this object, they overlap at a low height rather than using the object's geometry height. Objects with this flag are treated as flat or low-profile objects for overlap calculations. Used by `Drawable` systems to determine overlap height - when objects overlap with objects having this flag, they use `FLATTENED_OBJECT_HEIGHT` instead of the object's actual geometry height. Used for flattened objects, crushed vehicles, infantry, or other low-profile objects that should allow other objects to overlap at ground level. + +- **`WALK_ON_TOP_OF_WALL`** *(v1.04)* - Units can walk on top of walls made of these objects. Objects with this flag allow units to traverse and walk across their top surface. Used by pathfinding systems to enable units to walk on wall structures. Used by game logic systems to check if units can walk on wall objects. Used for wall structures that units can climb and traverse, allowing infantry to move across walls. + +- **`CLIFF_JUMPER`** *(v1.04, Zero Hour only)* - Unit cannot climb cliffs but can jump off of them. Objects with this flag are identified as units that can jump from cliffs but cannot climb up them. Used by transport contain systems for special cliff jumping behavior with hero units. Used by AI group systems to exclude cliff jumpers from certain group behaviors. Used by disguise systems to prevent units from disguising as cliff jumpers. Used by neutron blast behavior for special handling. Used for units like Colonel Burton that can jump from elevated positions but cannot climb cliffs. + +- **`CAN_BE_REPULSED`** *(v1.04)* - Object runs away from repulsor objects when damaged. Objects with this flag are affected by repulsor mechanics - when damaged, they become repulsors themselves and cause other repulsable objects to flee. Used by `ActiveBody` to set the `OBJECT_STATUS_REPULSOR` status when damaged objects with this flag are hit. Used by AI systems to check for nearby repulsors and move units away from them. Used by `AIStates` to interrupt movement and pathfinding when repulsors are detected nearby. Used for civilian units and other objects that should flee when damaged or when near damaged objects. + +### Garrison and Containment +- **`NO_GARRISON`** *(v1.04)* - Unit may not garrison buildings, even if infantry bit is set. Objects with this flag are prevented from garrisoning buildings, regardless of whether they have the `INFANTRY` flag. Used by garrison systems to explicitly exclude units from garrisoning behavior. Garrison checks first verify that the unit does not have this flag before allowing garrisoning. Script actions check for this flag when determining if infantry can garrison. Used to prevent specific infantry units from garrisoning buildings. + +- **`STEALTH_GARRISON`** *(v1.04)* - Enemy teams can't tell that unit is in building, and if they garrison that building, the stealth unit will eject. Objects with this flag are identified as stealth garrison units. When garrisoned, enemy teams cannot detect that the unit is inside the building. If an enemy team attempts to garrison the same building, the stealth garrisoned unit will be automatically ejected. Used by garrison systems for special stealth behavior. Used by open contain systems to check for stealth garrison behavior. Used by mob nexus systems to expose stealthed units when needed. + +- **`GARRISONABLE_UNTIL_DESTROYED`** *(v1.04)* - Object is capable of garrisoning troops until completely destroyed. Objects with this flag (typically buildings) can continue to accept garrisoned units even when severely damaged. Normally, buildings in the `BODY_REALLYDAMAGED` state cannot accept new garrisoned units, but buildings with this flag can. Used by garrison systems to override the normal damage state restrictions on garrisoning. Allows buildings to continue functioning as garrisons even when heavily damaged. + +- **`REJECT_UNMANNED`** *(v1.04, Zero Hour only)* - Unit cannot enter an unmanned vehicle. Objects with this flag are prevented from entering unmanned vehicles. Used by transport and contain systems to prevent specific units from entering vehicles that don't have a driver. Some units (like drones) can enter unmanned vehicles, but units with this flag cannot. Used to prevent specific unit types from using unmanned vehicles. + +### Special Abilities +- **`CAN_RAPPEL`** *(v1.04)* - Unit can rappel down from aircraft or elevated positions. Objects with this flag are identified as units that can perform rappelling actions. Used by `ChinookAIUpdate` to identify units that can rappel from transport helicopters during combat drops. Used by `AIStates` to check if units can enter rappelling state. Used by control bar command systems to enable rappelling commands. When units with this flag are in transport helicopters, they can be deployed via rappelling instead of landing. Used for special forces infantry units that can rappel from helicopters. + +- **`PARACHUTABLE`** *(v1.04)* - Object can be transported and deployed via parachute. Objects with this flag can be loaded into parachute containers and deployed via airdrop. Used by `ParachuteContain` to determine which units can be transported by parachutes (infantry are always parachutable regardless of this flag). Used for non-infantry units that should be deployable via parachute, such as vehicles or equipment that can be airdropped. Note: Infantry units are automatically parachutable and do not need this flag. + +- **`ATTACK_NEEDS_LINE_OF_SIGHT`** *(v1.04)* - Unit requires clear line of sight to attack targets. Objects with this flag must have unobstructed line of sight to their targets before they can attack. Used by `AIStates` to check line of sight before allowing attacks. Used by weapon systems to enforce line of sight requirements for units with this flag. Units with this flag cannot attack targets that are blocked by terrain, structures, or other obstacles. Used for units that require direct visual contact with targets to attack. + +- **`FORCEATTACKABLE`** *(v1.04)* - Object can always be force-attacked, even if not selectable. Objects with this flag can be targeted by force-attack commands even when they cannot be selected normally. Used by command translation systems to allow force-attacking of non-selectable objects. Used by selection systems to prevent selection of objects with this flag that are not selectable (objects must be either selectable or force-attackable, not just force-attackable). Used by weapon systems to allow targeting of objects that would normally be untargetable. Used for objects like cargo planes that should be attackable but not selectable. + +- **`DONT_AUTO_CRUSH_INFANTRY`** *(v1.04)* - AI-controlled units with this flag do not automatically attempt to crush infantry. Objects with this flag are prevented from automatically crushing infantry units when controlled by AI. Used by `AIStates` to check if units should attempt to crush infantry - AI units without this flag will automatically try to crush infantry when possible. Used for units that should not engage in crushing behavior, such as transport vehicles or support units. Allows fine control over which units participate in infantry crushing mechanics. + +- **`SPAWNS_ARE_THE_WEAPONS`** *(v1.04)* - Spawned units (slaves) are treated as this object's weapons rather than separate entities. Objects with this flag evaluate their spawned units as weapons for targeting and attack purposes. Used by `WeaponSet` to handle range checking for immobile objects with spawn slaves (similar to how immobile objects work). Used by `Object` to disable spawn slaves when the object is disabled or when handling special states. Used by `AIStates` to pass the closest spawn member to weapon evaluation functions when attacking. Used by command systems to handle attack commands for objects where spawn members function as weapons. Used by stealth and EMP systems for special handling. Used for objects like Stinger Sites where the spawned soldiers function as the actual weapons of the structure. + +### Supply and Resources +- **`SUPPLY_SOURCE`** *(v1.04)* - Object provides supplies that can be harvested. Objects with this flag are identified as sources of supplies that harvesters can collect. Used by `DockUpdate` to identify supply sources that dozers and harvesters can dock with for resource collection. Used by `BuildAssistant` to check proximity restrictions when building near supply sources. Used for supply piles, oil derricks, and other objects that generate harvestable resources. + +- **`SUPPLY_SOURCE_ON_PREVIEW`** *(v1.04)* - Supply source that should be displayed on the map preview screen. Objects with this flag are identified as supply sources that should be visible on the map preview/minimap. Used by `MapUtil` to populate supply position lists for map preview display. Used for supply sources that players should be able to see on the map preview before starting the game. Typically combined with `SUPPLY_SOURCE` to indicate both functionality and preview visibility. + +- **`CANNOT_BUILD_NEAR_SUPPLIES`** *(v1.04)* - Structure cannot be built too close to supply sources. Objects with this flag are prevented from being constructed within a certain distance of objects with the `SUPPLY_SOURCE` flag. Used by `BuildAssistant` to enforce minimum distance requirements from supply sources (controlled by `TheGlobalData->m_SupplyBuildBorder`). Used for structures like supply centers that should maintain spacing from other supply sources. Prevents players from building supply-related structures too close together. + +### Gameplay and Scoring +- **`MP_COUNT_FOR_VICTORY`** *(v1.04)* - Structure counts toward victory conditions in multiplayer games. Objects with this flag are tracked for victory conditions - if a player loses all structures with this flag, they lose the game. Used by `Object` to trigger EVA announcements when structures with this flag are destroyed. Used by `PropagandaTowerBehavior` and scoring systems to identify structures that affect victory conditions. Used for critical structures like command centers and production facilities that determine player survival in multiplayer matches. + +- **`SCORE`** *(v1.04)* - Object counts for multiplayer scoring and short-game calculations. Objects with this flag contribute to player scores in multiplayer games for both creation and destruction. Used by `PropagandaTowerBehavior` to identify objects that receive propaganda bonuses. Used by scoring systems to track points earned from building and destroying objects with this flag. Used by `W3DScene` for scoring calculations. Used for buildings and structures that should contribute to overall player score in multiplayer matches. + +- **`SCORE_CREATE`** *(v1.04)* - Object only contributes to multiplayer score when created. Objects with this flag award points to the player when they are built, but do not award points when destroyed. Used by `PropagandaTowerBehavior` to identify objects that receive propaganda bonuses. Used by scoring systems to track points earned from creating objects with this flag. Used for structures where construction is rewarded but destruction is not scored separately. + +- **`SCORE_DESTROY`** *(v1.04)* - Object only contributes to multiplayer score when destroyed. Objects with this flag award points to the player who destroys them, but do not award points when created. Used by `PropagandaTowerBehavior` to identify objects that receive propaganda bonuses. Used by scoring systems to track points earned from destroying objects with this flag. Used for structures where destruction is rewarded but construction is not scored separately. + +### Special Object States +- **`CAPTURABLE`** *(v1.04)* - Is "capturable" even if not an enemy (should generally be used only for structures, eg, Tech buildings). Objects with this flag can be captured by players, even if they are not currently enemies. Used by object systems to determine if an object can be captured. Typically used for neutral tech buildings that can be captured by any player. Allows structures to be capturable regardless of current diplomatic status. + +- **`IMMUNE_TO_CAPTURE`** *(v1.04)* - Under no circumstances can this building ever be captured. Objects with this flag cannot be captured by any means. Used by capture systems to prevent capture of specific buildings. Overrides any capture attempts, ensuring the building remains with its original owner. + +- **`CLEARED_BY_BUILD`** *(v1.04)* - Is auto-cleared from the map when built over via construction. Objects with this flag are automatically removed from the map when a building is constructed on top of them. Used by game logic systems during construction to clear objects that would interfere with building placement. Used for objects that should be removed when players build structures in their location. + +- **`CLEANUP_HAZARD`** *(v1.04)* - Radiation and bio-poison are samples of area conditions that can be cleaned up (or avoided). Objects with this flag are identified as environmental hazards that can be cleaned up or avoided. Used by cleanup systems to identify hazards that units can remove or bypass. Used for area effects like radiation and bio-poison that affect gameplay but can be mitigated. + +- **`BLAST_CRATER`** *(v1.04, Zero Hour only)* - Deeply gouges out the terrain under object footprint. Objects with this flag create permanent terrain deformation when placed. Used by script actions to identify blast craters that modify terrain permanently. Used for explosion effects that leave permanent marks on the terrain. + +- **`INERT`** *(v1.04)* - This object shouldn't be considered for any sort of interaction with any player. Objects with this flag are ignored by player interaction systems. Used for objects that should not participate in any player-related gameplay mechanics. These objects exist in the game world but don't interact with players. + +- **`DRAWABLE_ONLY`** *(v1.04)* - Template is used only to create drawables (not Objects). Objects with this flag are templates that only create visual representations, not actual game objects. Used for visual-only templates that don't need game logic. These templates create drawable entities for rendering but don't have object functionality. + +- **`PRELOAD`** *(v1.04)* - All model data will be preloaded even if not on map. Objects with this flag have their model data preloaded at game start, even if they're not present on the current map. Used for performance optimization - preloading prevents loading delays when these objects are created. Used for commonly used objects that need instant availability. + +### Special Behaviors +- **`MOB_NEXUS`** *(v1.04)* - Object that coordinates the members of a mob (i.e. GLAInfantryAngryMob). Objects with this flag are identified as mob nexus objects that coordinate multiple mob member units. Used by mob contain systems to manage groups of units that act as a single entity. Mob nexus objects control the behavior of their member units, which typically have the `IGNORED_IN_GUI` flag. + +- **`AUTO_RALLYPOINT`** *(v1.04)* - When immobile-structure-object is selected, left clicking on ground will set new rally point without requiring command button. Objects with this flag automatically set rally points when selected and the player left-clicks on the ground. Used for structures that need quick rally point placement. Eliminates the need for a separate command button to set rally points. + +- **`PRODUCED_AT_HELIPAD`** *(v1.04)* - Hacky fix for Comanche. Objects with this flag are identified as units that are produced at helipads. Used for special handling of units that spawn at helipad locations rather than standard production facilities. + +- **`DRONE`** *(v1.04)* - Object drone type. Used for filtering them out of battle plan bonuses, making un-snipable, and whatever else may come up. Objects with this flag are identified as drone units. Used extensively by game systems: physics update systems check for drones to handle unmanned vehicle behavior, object systems check for drones to allow unmanned vehicle status, body systems check for drones for special death handling, AI dock systems check for drones for docking behavior, and selection systems may use drones for special selection behavior. Drones are typically autonomous units that can operate without a driver. + +- **`NO_HEAL_ICON`** *(v1.04)* - Do not ever display healing icons on these objects. Objects with this flag never display healing icons in the UI, even when being healed. Used by UI systems to suppress healing indicator display. Used for objects that shouldn't show healing feedback to the player. + +- **`EMP_HARDENED`** *(v1.04, Zero Hour only)* - Like a delivery plane (B52, B3, CargoPlane, etc.) or a SpectreGunship, which sort-of IS the weapon. Objects with this flag are identified as units that are resistant to EMP effects or function as both unit and weapon. Used for special units that have unique weapon/unit relationships. Used for units where the unit itself functions as the weapon delivery system. + +- **`IGNORE_DOCKING_BONES`** *(v1.04, Zero Hour only)* - Structure will not look up docking bones. Patch 1.03 hack. Objects with this flag skip docking bone lookup during structure placement. Used for structures that don't use standard docking bone systems. This is a workaround for specific structures that had docking issues in patch 1.03. + +- **`SPAWNS_ARE_THE_WEAPONS`** *(v1.04)* - Evaluate the spawn slaves as this object's weapons. Objects with this flag treat their spawned units as weapons rather than separate entities. Used by weapon systems for special weapon behavior - immobile objects with this flag or objects with spawn slaves evaluate spawn members as weapons for targeting and attack purposes. Used for objects like Stinger Sites where the spawn members function as the actual weapons. When ordered to attack, these objects pass the closest spawn member to weapon evaluation functions. + +### Water and Terrain +- **`WAVEGUIDE`** *(v1.04)* - Water wave propagation object. Objects with this flag are identified as water wave objects that create and propagate wave effects. Used by `WaveGuideUpdate` to identify and process water wave objects, ignoring them during wave collision detection. Used by `DamDie` to exclude wave guide objects from certain death processing. Used for objects that create water wave effects, such as tsunami generators or wave propagation systems. + +- **`WAVE_EFFECT`** *(v1.04)* - Wave effect point marker. Objects with this flag mark locations where wave effects should be applied or displayed. Used for marking specific points on the map where wave effects should occur. Used for visual effects and wave interaction points that trigger wave-related gameplay mechanics. + +### Custom/Extra Flags +- **`EXTRA1`** through **`EXTRA16`** *(v1.04)* - Custom KindOf types available for modder-defined object categories + +## Examples + +### Basic Infantry Unit +```ini +Object = MyInfantry + KindOf = INFANTRY SELECTABLE CAN_ATTACK +End +``` + +### Vehicle +```ini +Object = MyTank + KindOf = VEHICLE CAN_ATTACK SELECTABLE +End +``` + +### Structure with Special Behaviors +```ini +Object = MyBuilding + KindOf = STRUCTURE IMMOBILE MP_COUNT_FOR_VICTORY POWERED +End +``` + +### Aircraft +```ini +Object = MyHelicopter + KindOf = AIRCRAFT SELECTABLE CAN_ATTACK +End +``` + +## Notes + +### Usage +- Multiple KindOf flags can be combined on a single object. Objects typically have multiple KindOf flags set to describe their various properties. +- Some KindOf flags have dependencies. For example, `STICK_TO_TERRAIN_SLOPE` requires `IMMOBILE` to be set. +- KindOf flags are used throughout the game for filtering, targeting, and AI behavior. Systems like [Weapon](../Weapon.md) targeting and AI systems use KindOf flags to identify object types. +- The `EXTRA1` through `EXTRA16` flags are available for custom categorization by modders. +- Prison/surrender system flags (`PRISON`, `COLLECTS_PRISON_BOUNTY`, `POW_TRUCK`, `CAN_SURRENDER`) are conditionally compiled and may not be available in all builds. +- KindOf flags are case-sensitive and must match exactly as defined in the value list above. + +## Source Files + +**Header (Generals):** [KindOf.h](../../../Generals/Code/GameEngine/Include/Common/KindOf.h) *(if retail Generals codebase exists)* +- KindOf flag definitions (lines 41-254): Defines all available KindOf flags like `KINDOF_INFANTRY`, `KINDOF_VEHICLE`, etc. +- Type definitions (line 256): Defines how multiple flags are stored together + +**Header (Zero Hour):** [KindOf.h](../../Code/GameEngine/Include/Common/KindOf.h) +- KindOf flag definitions (lines 41-254): Defines all available KindOf flags like `KINDOF_INFANTRY`, `KINDOF_VEHICLE`, etc. +- Type definitions (line 256): Defines how multiple flags are stored together + +**Source (Generals):** [KindOf.cpp](../../../Generals/Code/GameEngine/Source/Common/System/KindOf.cpp) *(if retail Generals codebase exists)* +- Flag name mapping (line 35): Maps flag names to their values for INI file parsing (e.g., `"INFANTRY"`, `"VEHICLE"`) +- Initialization functions: Sets up predefined flag combinations like faction structure flags + +**Source (Zero Hour):** [KindOf.cpp](../../Code/GameEngine/Source/Common/System/KindOf.cpp) +- Flag name mapping (line 35): Maps flag names to their values for INI file parsing (e.g., `"INFANTRY"`, `"VEHICLE"`) +- Initialization functions: Sets up predefined flag combinations like faction structure flags + +## Changes History + +- In Retail Zero Hour, 25 new KindOf flags were added including 1 movement kindof, 11 faction structure kindofs, and 13 gameplay mechanics kindofs while `AIRFIELD` was replaced by `FS_AIRFIELD`. + +## Document Log + +- 16/12/2025 — AI — Initial document created. + + +## Status + +- Documentation Status: AI-generated, 0/2 reviews + +## Reviewers + +- *No reviewers yet* + diff --git a/Docs/INI/Object/Enums/ModelConditionFlagType.md b/Docs/INI/Object/Enums/ModelConditionFlagType.md new file mode 100644 index 0000000000..0039c4da37 --- /dev/null +++ b/Docs/INI/Object/Enums/ModelConditionFlagType.md @@ -0,0 +1,555 @@ +# ModelConditionFlagType + +Status: AI-generated, 0/2 reviews + +## Overview + +The `ModelConditionFlagType` (commonly referred to as `ModelConditionFlags` or `ModelCondition`) is a bit flag system used to represent visual states and animation conditions for objects. Model conditions affect which model animations, visual states, and particle effects are displayed. Objects can have multiple model condition flags set simultaneously, allowing for complex visual state combinations. Model conditions are used throughout the game for visual feedback, animations, damage states, weapon firing states, and various other visual representations. This is a system-level type, not a module added inside `Object` entries. + +Available in: *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) +- [Enum Value Lists](#enum-value-lists) + - [Damage States](#damage-states) + - [Environmental Conditions](#environmental-conditions) + - [Fire and Burn States](#fire-and-burn-states) + - [Construction States](#construction-states) + - [Movement and Action States](#movement-and-action-states) + - [Aircraft States](#aircraft-states) + - [Deployment and Packing](#deployment-and-packing) + - [Garrison and Containment](#garrison-and-containment) + - [Docking States](#docking-states) + - [Door States (4 doors, 4 states each)](#door-states-4-doors-4-states-each) + - [Combat and Weapon States - Weapon Slot A](#combat-and-weapon-states---weapon-slot-a) + - [Combat and Weapon States - Weapon Slot B](#combat-and-weapon-states---weapon-slot-b) + - [Combat and Weapon States - Weapon Slot C](#combat-and-weapon-states---weapon-slot-c) + - [Combat and Weapon States - Weapon Slots D-H](#combat-and-weapon-states---weapon-slots-d-h) + - [Turret and Rotation](#turret-and-rotation) + - [Special Combat States](#special-combat-states) + - [Radar and Power](#radar-and-power) + - [Capture and Special States](#capture-and-special-states) + - [Special Animations](#special-animations) + - [Preorder and Movement](#preorder-and-movement) + - [Rider States (8 riders)](#rider-states-8-riders) + - [Weapon Set and Upgrade States](#weapon-set-and-upgrade-states) + - [Armor Set States](#armor-set-states) + - [User-Definable Flags (5 user flags)](#user-definable-flags-5-user-flags) + - [Armor Upgrade Flags (5 armor upgrades)](#armor-upgrade-flags-5-armor-upgrades) + - [Weapon Upgrade Flags (5 weapon upgrades)](#weapon-upgrade-flags-5-weapon-upgrades) + - [Component Damage States](#component-damage-states) + - [Surrender State](#surrender-state) +- [Examples](#examples) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +**Limitations**: +- Model condition flags are bit flags that can be combined. Multiple flags can be set on a single object simultaneously. +- Model condition flags are set automatically by game systems based on object state, damage, actions, and other conditions. +- Some model condition flags are mutually exclusive or have specific activation conditions (e.g., `FIRING_A` and `RELOADING_A` cannot be active simultaneously for the same weapon slot). +- Model condition flags are used internally by the game engine; they are not directly set in INI files but are referenced in model definitions and animation configurations. + +**Conditions**: +- Model condition flags are set automatically by game systems based on object state (e.g., damage states, weapon firing, movement, construction). +- Multiple model condition flags can be active simultaneously (e.g., `DAMAGED` and `NIGHT` can both be active). +- Model condition flags affect which model animations and visual states are displayed. +- Some model condition flags are temporary and automatically cleared after a duration (e.g., `SPECIAL_CHEERING`). + +**Dependencies**: +- Model condition flags are used by model rendering systems to select appropriate animations and visual states. +- Various game systems automatically set model condition flags (e.g., damage systems set `DAMAGED`, weapon systems set `FIRING_A`, construction systems set `PARTIALLY_CONSTRUCTED`). +- Model definitions and animation configurations reference model condition flags to determine which animations to play. + +## Enum Value Lists + +### `ModelConditionFlagType` Values +Available in: *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* + +### Damage States +- **`TOPPLED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object has been toppled over. Set automatically by `ToppleUpdate` when a structure falls over due to structural damage. Used for visual feedback when structures collapse sideways rather than vertically. The flag is set when the toppling animation begins, allowing models to display toppled state animations. Used by structure collapse systems to indicate a toppled building state. + +- **`FRONTCRUSHED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Front of object has been crushed. Set automatically by `CrushDie` when a vehicle is crushed from the front or totally crushed. Used when crush damage type is `FRONT_END_CRUSH` or `TOTAL_CRUSH`. Provides visual feedback for vehicles that have been crushed by heavier units or crushed objects. Used to display front-end damage animations on vehicles. + +- **`BACKCRUSHED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Back of object has been crushed. Set automatically by `CrushDie` when a vehicle is crushed from the back or totally crushed. Used when crush damage type is `BACK_END_CRUSH` or `TOTAL_CRUSH`. Provides visual feedback for vehicles that have been crushed by heavier units or crushed objects. Used to display back-end damage animations on vehicles. + +- **`DAMAGED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is damaged. Set automatically by `Drawable::reactToBodyDamageStateChange()` when the object's body damage state changes to `BODYDAMAGETYPE_DAMAGED`. This corresponds to the first damage threshold (typically when health drops below 50-70% of maximum). Used extensively by garrison systems to find garrison fire points when structures are in damaged state. Used by damage state systems to trigger damage animations and visual effects. Automatically cleared and set as damage states change. + +- **`REALLYDAMAGED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is really damaged. Set automatically by `Drawable::reactToBodyDamageStateChange()` when the object's body damage state changes to `BODYDAMAGETYPE_REALLY_DAMAGED`. This corresponds to the second damage threshold (typically when health drops below 10-35% of maximum). Used by garrison systems to find garrison fire points when structures are in really damaged state. Used by damage state systems to trigger severe damage animations and visual effects. Structures in this state typically cannot accept new garrisoned units unless they have the `GARRISONABLE_UNTIL_DESTROYED` KindOf flag. + +- **`RUBBLE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is in rubble state. Set automatically by `Drawable::reactToBodyDamageStateChange()` when the object's body damage state changes to `BODYDAMAGETYPE_RUBBLE`. This is the final damage state before destruction. Used by minefield systems to indicate destroyed mine objects. Used by structure collapse and topple systems to clear the rubble state when structures are being toppled or collapsed. Used by rendering systems to determine if structures should be displayed as rubble (structures with this flag may have reduced height for collision detection). Automatically cleared by `StructureToppleUpdate` and `StructureCollapseUpdate` when structures begin toppling or collapsing. + +- **`SPECIAL_DAMAGED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object has special damage state. Set automatically by damage systems for objects that require special damage handling beyond the standard damage states. Used by garrison systems to clear this flag when finding garrison fire points. Used for objects that have unique damage states that don't fit the standard `DAMAGED`, `REALLY_DAMAGED`, or `RUBBLE` progression. + +- **`SPLATTED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object has been splatted. Used for visual feedback when objects are flattened or crushed flat by heavy units or objects. Used by death and damage systems to indicate objects that have been completely flattened. Allows models to display splatted animations for units that have been crushed flat. + +- **`EXPLODED_FLAILING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is exploding and flailing. Used for visual feedback during explosive death animations where the object flails around during destruction. Used by death animation systems to trigger flailing explosion animations. Allows models to display chaotic flailing animations during explosive destruction sequences. + +- **`EXPLODED_BOUNCING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is exploding and bouncing. Used for visual feedback during explosive death animations where the object bounces around during destruction. Used by death animation systems to trigger bouncing explosion animations. Allows models to display bouncing animations during explosive destruction sequences, particularly for vehicles or objects that bounce after explosions. + +### Environmental Conditions +- **`NIGHT`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Night time conditions. Set automatically by `Object::boundDrawableToObject()` when `TheGlobalData->m_forceModelsToFollowTimeOfDay` is enabled and the current time of day is `TIME_OF_DAY_NIGHT`. Updated dynamically as time of day changes. Used by rendering systems to determine if objects should display night-time visual effects (e.g., headlights on vehicles are hidden when this flag is set). Used by model rendering to select night-time animations and visual states. Allows models to display different appearances during night versus day. + +- **`SNOW`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Snow conditions. Set automatically by `Object::boundDrawableToObject()` when `TheGlobalData->m_forceModelsToFollowWeather` is enabled and the current weather is `WEATHER_SNOWY`. Updated dynamically as weather changes. Used by rendering systems to determine if objects should display snow-related visual effects. Used by model rendering to select snow-condition animations and visual states. Allows models to display different appearances in snowy weather conditions. + +- **`FLOODED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is flooded. Set automatically by `WaveGuideUpdate` when objects are submerged in water or flooded areas. Used for visual feedback when objects are in flooded conditions. Used by wave guide systems to indicate objects that are affected by water flooding. Allows models to display flooded state animations and visual effects. + +- **`OVER_WATER`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Units that can go over water want cool effects for doing so. Set automatically by `Locomotor` when units are moving over water surfaces. Cleared when units leave water. Used by locomotors to track when units are traversing water. Used by rendering systems to display water-traversal visual effects (e.g., water splashes, wake effects). Allows models to display special animations and effects when units move over water. Used by `RailroadGuideAIUpdate` for railroad guides that extend over water. + +### Fire and Burn States +- **`AFLAME`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is on fire. Set automatically by `FlammableUpdate::tryToIgnite()` when an object catches fire. Cleared when the fire duration expires (`AflameDuration`). While this flag is set, the object takes periodic fire damage (`AflameDamageAmount` every `AflameDamageDelay`). Used by `FlammableUpdate` to track active fire state. Triggers burning sound effects while active. Used by fire spread systems to propagate fire to nearby flammable objects. Automatically cleared when fire duration expires or when the object transitions to burned state. Allows models to display active fire animations and particle effects. + +- **`SMOLDERING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is smoldering. Set automatically by `FlammableUpdate` when the object transitions from `AFLAME` to burned state but the fire has not fully extinguished. Set when the burned delay expires while the object is still aflame. Used to indicate objects that have been burned but may still have residual smoke or smoldering effects. Allows models to display smoldering animations and smoke effects after the main fire has extinguished. + +- **`BURNED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object has been burned. Set automatically by `NeutronMissileSlowDeathUpdate` when objects are affected by neutron missile effects. Also set by `FlammableUpdate` when objects are burned. Used by `ToppleUpdate` to check if objects should create burned stump objects when toppled. Used to indicate objects that have been permanently burned or charred. Objects with this flag may have different visual appearances and cannot catch fire again if they have the burned status set. Allows models to display burned/charred animations and visual states. + +### Construction States +- **`AWAITING_CONSTRUCTION`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is awaiting construction. Set automatically by construction systems when a structure is placed but not yet being actively built. Used by `DozerAIUpdate` to identify structures that are ready for construction to begin. Used by worker AI systems to find construction targets. Cleared when construction begins. Used to indicate structures that are queued for construction but not currently being built. + +- **`PARTIALLY_CONSTRUCTED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is partially constructed. Set automatically by `BuildAssistant` when a structure's construction percent is greater than 0% but less than 100%. Used by `DozerAIUpdate` and `WorkerAIUpdate` to identify structures that are currently under construction. Used by construction systems to indicate structures that are partially built. Allows models to display partially constructed building animations. Typically set in combination with `ACTIVELY_BEING_CONSTRUCTED` when construction is in progress. + +- **`ACTIVELY_BEING_CONSTRUCTED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is actively being constructed. Set automatically by `BuildAssistant` when a structure is currently being built by workers. Used by `DozerAIUpdate` and `WorkerAIUpdate` to identify structures that are actively under construction. Used by construction systems to indicate structures that are being worked on right now. Allows models to display active construction animations (e.g., workers visible, construction effects). Typically set in combination with `PARTIALLY_CONSTRUCTED` when construction is in progress. + +- **`ACTIVELY_CONSTRUCTING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is actively constructing something. Set on construction units (like dozers) when they are actively building another structure. Used to indicate that the object itself is performing construction work. Allows models to display construction animations on the builder unit. Used by construction systems to track which units are currently building. + +- **`CONSTRUCTION_COMPLETE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object construction is complete. Set automatically when a structure reaches 100% construction completion. Used to indicate that construction has finished. Cleared when construction-related flags are reset. Allows models to display completion animations or transition to fully constructed state. + +- **`POST_COLLAPSE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object has collapsed. Set automatically by structure collapse systems when a structure has finished collapsing. Used to indicate the final state after a structure has collapsed. Used by collapse animation systems to mark the end of the collapse sequence. Allows models to display post-collapse animations or remain in collapsed state. + +### Movement and Action States +- **`MOVING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is moving. Set automatically by `AIStates` when units are actively moving across terrain. Cleared when units stop moving. Used by AI systems to track unit movement state. Used by pathfinding systems to determine if units are in motion. Used by `TensileFormationUpdate` to synchronize formation movement animations. Used by `RailedTransportDockUpdate` to indicate when units are being moved during docking operations. Used by `AIUpdate` to clear the flag when units stop. Mutually exclusive with `CLIMBING` - units set `CLIMBING` when traversing cliffs instead of `MOVING`. Allows models to display movement animations and effects. + +- **`PRONE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is in prone position. Set automatically by `ProneUpdate` when infantry units go prone. Cleared when units stand up. Used by prone update systems to track when units are in prone position. Allows models to display prone animations for infantry units. Used for units that can take cover or reduce their profile by going prone. + +- **`FREEFALL`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is in freefall. Set automatically by `ParachuteContain` when objects are falling without a parachute. Used in conjunction with `PARACHUTING` - objects transition from `FREEFALL` to `PARACHUTING` when the parachute deploys. Cleared when objects land or when the parachute is deployed. Used by parachute systems to track falling objects. Used by `SlowDeathBehavior` to display freefall animations for units that are falling (e.g., units snagged in trees). Allows models to display freefall animations. + +- **`CLIMBING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - For units climbing up or down cliffs. Set automatically by `AIStates` when units are traversing cliff terrain (`PathfindCell::CELL_CLIFF`). Mutually exclusive with `MOVING` - units set `CLIMBING` instead of `MOVING` when climbing cliffs. Used by pathfinding systems to indicate units that are climbing terrain features. Cleared when units finish climbing and return to normal movement. Allows models to display climbing animations for units traversing cliffs. + +- **`PARACHUTING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is parachuting. Set automatically by `ParachuteContain` when objects deploy their parachutes. Used in conjunction with `FREEFALL` - objects transition from `FREEFALL` to `PARACHUTING` when the parachute opens. Cleared when objects land. Used by parachute systems to track objects that are descending with parachutes. Used by `SlowDeathBehavior` to display parachuting animations for units that are falling (e.g., units snagged in trees look like they are parachuting). Allows models to display parachute deployment and descent animations. + +- **`RAPPELLING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is rappelling. Used for units that are rappelling down surfaces (typically infantry units using rappelling equipment). Allows models to display rappelling animations and visual effects. Used by units with the `CAN_RAPPEL` KindOf flag to indicate they are in rappelling state. + +### Aircraft States *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* +- **`JETAFTERBURNER`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Shows "flames" for extra motive force (eg, when taking off). Used by aircraft to display afterburner visual effects when extra thrust is needed. Allows models to display afterburner flame effects and increased exhaust visuals. Used during takeoff sequences or high-speed maneuvers. + +- **`JETEXHAUST`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Shows "exhaust" for motive force. Used by aircraft to display standard exhaust visual effects during normal flight. Allows models to display jet exhaust effects and trail visuals. Used to indicate aircraft engines are active and producing thrust. + +- **`LANDED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Aircraft landed state. Set automatically by `ChinookAIUpdate` when aircraft complete landing sequence. Used by aircraft AI systems to indicate aircraft are on the ground. Cleared when aircraft begin takeoff sequence. Used by `ChinookAIUpdate` to track landing state. Allows models to display landed aircraft animations and visual states. Used to indicate aircraft that have successfully landed and are stationary on the ground. + +- **`TAKEOFF`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Aircraft takeoff state. Set automatically by `ChinookAIUpdate` when aircraft begin takeoff sequence. Used by aircraft AI systems to indicate aircraft are preparing to take off. Transitions to `TAKING_OFF` during the takeoff sequence. Used by `ChinookAIUpdate` to track takeoff initiation. Cleared when aircraft complete takeoff or when landing sequences begin. Allows models to display takeoff preparation animations. + +- **`TAKING_OFF`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Aircraft taking off state. Set automatically by `ChinookAIUpdate` during active takeoff sequence. Used by aircraft AI systems to indicate aircraft are actively taking off. Cleared when aircraft complete takeoff or when landing sequences begin. Used by `ChinookAIUpdate` to track active takeoff. Allows models to display active takeoff animations and visual effects. Used to indicate aircraft that are in the process of lifting off from the ground. + +- **`LANDING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Aircraft landing state. Set automatically by `ChinookAIUpdate` during active landing sequence. Used by aircraft AI systems to indicate aircraft are actively landing. Cleared when aircraft complete landing (transitioning to `LANDED`) or when takeoff sequences begin. Used by `ChinookAIUpdate` to track active landing. Allows models to display landing animations and visual effects. Used to indicate aircraft that are in the process of descending and landing. + +### Deployment and Packing +- **`PACKING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Packs an object. Set automatically by `SlavedUpdate` and `DeployStyleAIUpdate` when objects begin packing (transitioning from deployed to packed state). Used by deployment systems to indicate objects are packing up. Used by `HackInternetAIUpdate` to clear packing state during hack sequences. Used by `ParticleUplinkCannonUpdate` to manage packing/unpacking states. Used by `SpecialAbilityUpdate` to clear packing state during special abilities. Mutually exclusive with `UNPACKING` and `DEPLOYED`. Allows models to display packing animations. Cleared when packing completes (transitioning to packed state). + +- **`UNPACKING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Unpacks an object. Set automatically by `DeployStyleAIUpdate` and `HackInternetAIUpdate` when objects begin unpacking (transitioning from packed to deployed state). Used by deployment systems to indicate objects are unpacking. Used by `ParticleUplinkCannonUpdate` to manage unpacking states. Used by `SpecialAbilityUpdate` to manage unpacking during special abilities. Mutually exclusive with `PACKING` and `DEPLOYED`. Allows models to display unpacking animations. Cleared when unpacking completes (transitioning to `DEPLOYED` state). + +- **`DEPLOYED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - A deployed object state. Set automatically by `ParticleUplinkCannonUpdate` and `DeployStyleAIUpdate` when objects complete unpacking. Used by deployment systems to indicate objects are fully deployed and operational. Used by `ParticleUplinkCannonUpdate` to manage deployed state. Cleared when objects begin packing. Mutually exclusive with `PACKING` and `UNPACKING`. Allows models to display deployed state animations. Indicates objects that are fully unpacked and ready for use. + +### Garrison and Containment +- **`GARRISONED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is garrisoned. Set automatically by `GarrisonContain` when units enter garrison positions in structures. Cleared when units exit garrison positions. Used by garrison systems to track which units are garrisoned. Used by `GarrisonContain` to find garrison fire points based on structure damage state (pristine, damaged, really damaged). Used by `CaveContain` to clear garrison state when units exit caves. Used by garrison initialization to set up fire point positions for different damage states. Allows models to display garrisoned unit animations and visual states. + +- **`ENEMYNEAR`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Enemy is near. Set automatically by `EnemyNearUpdate` when enemies are detected within range. Cleared when no enemies are nearby. Used by structures and units to indicate enemy presence. Used by `EnemyNearUpdate` to track enemy proximity and update visual states accordingly. Allows models to display different animations when enemies are nearby (e.g., defensive postures, alert states). + +- **`LOADED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Loaded woot! ... like a transport is loaded. Set automatically by `TransportContain` and `MobNexusContain` when units are loaded into transports or containers. Cleared when units are unloaded. Used by transport systems to indicate units are inside transports. Used by `TransportContain` to track loaded units. Used by `MobNexusContain` to track units in mob nexus containers. Allows models to display loaded state animations (e.g., units visible inside transports). + +- **`CARRYING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is carrying something. Set automatically by `W3DModelDraw` when objects are carrying other objects. Used by rendering systems to indicate objects that are visually carrying other objects. Cleared when objects stop carrying. Allows models to display carrying animations and visual effects. Used for objects that physically carry other objects (distinct from `LOADED` which is for transport containers). + +### Docking States +- **`DOCKING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - This encloses the whole time you are Entering, Actioning, and Exiting a dock. Set automatically by `DockUpdate` when units enter docking sequences. Used as a master flag that encompasses the entire docking process. Cleared when docking sequences complete. Used by `DockUpdate` to track overall docking state. Used in combination with `DOCKING_BEGINNING`, `DOCKING_ACTIVE`, and `DOCKING_ENDING` to indicate specific phases. Allows models to display general docking animations. Indicates objects are in some phase of the docking process. + +- **`DOCKING_BEGINNING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - From Enter to Action. Set automatically by `DockUpdate` when units begin docking (entering dock positions). Used by `DockUpdate` to track the initial docking phase. Transitions to `DOCKING_ACTIVE` when docking action begins. Used by `DockUpdate::isClearToApproach()` to check if docking is in beginning phase. Allows models to display docking entry animations. Cleared when transitioning to active phase or when docking completes. + +- **`DOCKING_ACTIVE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - From Action to Exit. Set automatically by `DockUpdate` when units are in the active docking phase (performing dock actions). Used by `DockUpdate` to track the active docking phase. Transitions from `DOCKING_BEGINNING` and transitions to `DOCKING_ENDING`. Allows models to display active docking animations (e.g., loading/unloading, repair actions). Cleared when transitioning to ending phase or when docking completes. + +- **`DOCKING_ENDING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Exit all the way to next enter (use only animations that end with this). Set automatically by `DockUpdate` when units are exiting dock positions. Used by `DockUpdate` to track the final docking phase. Transitions from `DOCKING_ACTIVE` when exit begins. Used for animations that properly end the docking sequence. Cleared when docking completes and units leave dock positions. Allows models to display docking exit animations. Only use animations that properly end with this state for smooth transitions. + +### Door States (4 doors, 4 states each) +- **`DOOR_1_OPENING`** through **`DOOR_4_OPENING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Door opening state for doors 1-4. Set automatically by `ProductionUpdate`, `BattlePlanUpdate`, `MissileLauncherBuildingUpdate`, `CheckpointUpdate`, `OpenContain`, `SpectreGunshipUpdate`, `DeliverPayloadAIUpdate`, and `BaikonurLaunchPower` when doors begin opening. Used by door control systems to indicate doors are in the process of opening. Transitions to `DOOR_*_WAITING_OPEN` when opening completes. Cleared when doors begin closing or are interrupted. Allows models to display door opening animations. Used for structures with doors that need to open for unit access or weapon deployment (e.g., production buildings, missile launchers, aircraft hangars). + +- **`DOOR_1_CLOSING`** through **`DOOR_4_CLOSING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Door closing state for doors 1-4. Set automatically by door control systems when doors begin closing. Used by `ProductionUpdate`, `BattlePlanUpdate`, `MissileLauncherBuildingUpdate`, `CheckpointUpdate`, `OpenContain`, `SpectreGunshipUpdate`, and `DeliverPayloadAIUpdate` to manage door closing. Transitions from `DOOR_*_WAITING_OPEN` or `DOOR_*_WAITING_TO_CLOSE` when closing begins. Cleared when doors finish closing or are interrupted. Allows models to display door closing animations. Used for structures with doors that need to close after unit access or weapon deployment. + +- **`DOOR_1_WAITING_OPEN`** through **`DOOR_4_WAITING_OPEN`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Door waiting open state for doors 1-4. Set automatically by door control systems when doors have finished opening and are waiting in the open position. Used by `ProductionUpdate`, `BattlePlanUpdate`, `MissileLauncherBuildingUpdate`, and `CheckpointUpdate` to indicate doors are open and waiting. Transitions from `DOOR_*_OPENING` when opening completes. Transitions to `DOOR_*_WAITING_TO_CLOSE` or `DOOR_*_CLOSING` when closing begins. Allows models to display open door state animations. Used for structures where doors remain open for a period before automatically closing. + +- **`DOOR_1_WAITING_TO_CLOSE`** through **`DOOR_4_WAITING_TO_CLOSE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Door waiting to close state for doors 1-4. Set automatically by door control systems when doors are open but scheduled to close soon. Used by `ProductionUpdate`, `BattlePlanUpdate`, `MissileLauncherBuildingUpdate`, and `CheckpointUpdate` to indicate doors are waiting to close. Transitions from `DOOR_*_WAITING_OPEN` when the close timer is initiated. Transitions to `DOOR_*_CLOSING` when closing begins. Allows models to display door state animations while waiting to close. Used for structures where doors have a delay before closing after opening. + +### Combat and Weapon States - Weapon Slot A +- **`ATTACKING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Simply set when a unit is fighting -- terrorist moving with a target will flail arms like a psycho. Set automatically by `AIStates` when units are engaged in combat. Cleared when units stop attacking. Used by AI systems to indicate units that are actively fighting. Used by special ability systems (like terrorist attacks) to trigger attack animations. Allows models to display combat animations (e.g., terrorist units flailing arms when moving with a target). Used to indicate general combat state regardless of specific weapon slot activity. + +- **`PREATTACK_A`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Use for pre-attack animations (like aiming, pulling out a knife, or detonating explosives). Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot A is in pre-attack state (`WSF_PREATTACK`). Used by weapon systems to indicate the weapon is preparing to fire. Allows models to display pre-attack animations such as aiming, drawing weapons, or preparing explosives. Used by special abilities like hack attacks and internet center attacks to trigger pre-attack sequences. Automatically sets `USING_WEAPON_A` when active. + +- **`FIRING_A`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot A is firing. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot A is firing (`WSF_FIRING`). Used by weapon systems to indicate the weapon is actively firing. Used by garrison systems to set firing state on garrisoned units when they fire. Used by `HackInternetAIUpdate` to clear firing state during hack sequences. Used by `MobMemberSlavedUpdate` to clear firing state for mob members. Used by `SlavedUpdate` to manage firing states for slaved objects. Automatically sets `USING_WEAPON_A` when active. Allows models to display firing animations and muzzle flash effects. + +- **`BETWEEN_FIRING_SHOTS_A`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot A is between firing shots. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot A is between firing shots (`WSF_BETWEEN_FIRING_SHOTS`). Used by weapon systems to indicate the brief pause between individual shots in a burst. Used by `SlavedUpdate` to clear this state for slaved objects. Used by `MobMemberSlavedUpdate` to clear this state for mob members. Automatically sets `USING_WEAPON_A` when active. Allows models to display brief pause animations between shots. + +- **`RELOADING_A`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot A is reloading. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot A is reloading (`WSF_RELOADING`). Used by weapon systems to indicate the weapon is reloading ammunition. Used by `SlavedUpdate` to clear reloading state for slaved objects. Used by `MobMemberSlavedUpdate` to clear reloading state for mob members. Automatically sets `USING_WEAPON_A` when active. Allows models to display reloading animations. Mutually exclusive with `FIRING_A` - weapons cannot fire and reload simultaneously. + +- **`USING_WEAPON_A`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - These bits are set if firing, reloading, between shots, or preattack. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` whenever weapon slot A is in any active state (`WSF_FIRING`, `WSF_RELOADING`, `WSF_BETWEEN_FIRING_SHOTS`, or `WSF_PREATTACK`). Used as a convenience flag to check if weapon slot A is in any active state without checking individual states. Used by `AIStates` to exclude units with active weapons from dying state transitions. Used by `SlavedUpdate` and `MobMemberSlavedUpdate` to clear weapon usage states. Allows models to display general weapon usage animations when any weapon activity is occurring. + +### Combat and Weapon States - Weapon Slot B +- **`PREATTACK_B`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Use for pre-attack animations (like aiming, pulling out a knife, or detonating explosives). Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot B is in pre-attack state (`WSF_PREATTACK`). Used by weapon systems to indicate weapon slot B is preparing to fire. Allows models to display pre-attack animations for weapon slot B. Automatically sets `USING_WEAPON_B` when active. + +- **`FIRING_B`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot B is firing. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot B is firing (`WSF_FIRING`). Used by weapon systems to indicate weapon slot B is actively firing. Used by `SlavedUpdate` to clear firing state for slaved objects. Automatically sets `USING_WEAPON_B` when active. Allows models to display firing animations for weapon slot B. + +- **`BETWEEN_FIRING_SHOTS_B`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot B is between firing shots. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot B is between firing shots (`WSF_BETWEEN_FIRING_SHOTS`). Used by weapon systems to indicate the brief pause between individual shots in a burst for weapon slot B. Used by `SlavedUpdate` to clear this state for slaved objects. Automatically sets `USING_WEAPON_B` when active. Allows models to display brief pause animations between shots for weapon slot B. + +- **`RELOADING_B`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot B is reloading. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot B is reloading (`WSF_RELOADING`). Used by weapon systems to indicate weapon slot B is reloading ammunition. Used by `SlavedUpdate` to clear reloading state for slaved objects. Automatically sets `USING_WEAPON_B` when active. Allows models to display reloading animations for weapon slot B. Mutually exclusive with `FIRING_B`. + +- **`USING_WEAPON_B`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - These bits are set if firing, reloading, between shots, or preattack. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` whenever weapon slot B is in any active state. Used as a convenience flag to check if weapon slot B is in any active state. Used by `AIStates` to exclude units with active weapons from dying state transitions. Allows models to display general weapon usage animations when weapon slot B is active. + +### Combat and Weapon States - Weapon Slot C +- **`PREATTACK_C`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Use for pre-attack animations (like aiming, pulling out a knife, or detonating explosives). Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot C is in pre-attack state (`WSF_PREATTACK`). Used by weapon systems to indicate weapon slot C is preparing to fire. Allows models to display pre-attack animations for weapon slot C. Automatically sets `USING_WEAPON_C` when active. + +- **`FIRING_C`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot C is firing. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot C is firing (`WSF_FIRING`). Used by weapon systems to indicate weapon slot C is actively firing. Used by `SlavedUpdate` to clear firing state for slaved objects. Automatically sets `USING_WEAPON_C` when active. Allows models to display firing animations for weapon slot C. + +- **`BETWEEN_FIRING_SHOTS_C`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot C is between firing shots. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot C is between firing shots (`WSF_BETWEEN_FIRING_SHOTS`). Used by weapon systems to indicate the brief pause between individual shots in a burst for weapon slot C. Used by `SlavedUpdate` to clear this state for slaved objects. Automatically sets `USING_WEAPON_C` when active. Allows models to display brief pause animations between shots for weapon slot C. + +- **`RELOADING_C`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon slot C is reloading. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when weapon slot C is reloading (`WSF_RELOADING`). Used by weapon systems to indicate weapon slot C is reloading ammunition. Used by `SlavedUpdate` to clear reloading state for slaved objects. Automatically sets `USING_WEAPON_C` when active. Allows models to display reloading animations for weapon slot C. Mutually exclusive with `FIRING_C`. + +- **`USING_WEAPON_C`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - These bits are set if firing, reloading, between shots, or preattack. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` whenever weapon slot C is in any active state. Used as a convenience flag to check if weapon slot C is in any active state. Used by `AIStates` to exclude units with active weapons from dying state transitions. Allows models to display general weapon usage animations when weapon slot C is active. + +### Combat and Weapon States - Weapon Slots D-H *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* +- **`PREATTACK_D`** through **`PREATTACK_H`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Pre-attack state for weapon slots D through H. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when the respective weapon slot is in pre-attack state (`WSF_PREATTACK`). Used by weapon systems to indicate the weapon slot is preparing to fire. Allows models to display pre-attack animations for the respective weapon slot. Automatically sets the corresponding `USING_WEAPON_*` flag when active. + +- **`FIRING_D`** through **`FIRING_H`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Firing state for weapon slots D through H. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when the respective weapon slot is firing (`WSF_FIRING`). Used by weapon systems to indicate the weapon slot is actively firing. Used by `AIStates` to exclude units with active weapons from dying state transitions. Automatically sets the corresponding `USING_WEAPON_*` flag when active. Allows models to display firing animations for the respective weapon slot. + +- **`BETWEEN_FIRING_SHOTS_D`** through **`BETWEEN_FIRING_SHOTS_H`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Between firing shots state for weapon slots D through H. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when the respective weapon slot is between firing shots (`WSF_BETWEEN_FIRING_SHOTS`). Used by weapon systems to indicate the brief pause between individual shots in a burst. Used by `AIStates` to exclude units with active weapons from dying state transitions. Automatically sets the corresponding `USING_WEAPON_*` flag when active. Allows models to display brief pause animations between shots for the respective weapon slot. + +- **`RELOADING_D`** through **`RELOADING_H`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Reloading state for weapon slots D through H. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` when the respective weapon slot is reloading (`WSF_RELOADING`). Used by weapon systems to indicate the weapon slot is reloading ammunition. Used by `AIStates` to exclude units with active weapons from dying state transitions. Automatically sets the corresponding `USING_WEAPON_*` flag when active. Allows models to display reloading animations for the respective weapon slot. Mutually exclusive with the corresponding `FIRING_*` flag. + +- **`USING_WEAPON_D`** through **`USING_WEAPON_H`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon usage state for weapon slots D through H. Set automatically by `WeaponSet::getModelConditionForWeaponSlot()` whenever the respective weapon slot is in any active state (firing, reloading, between shots, or preattack). Used as a convenience flag to check if the weapon slot is in any active state without checking individual states. Used by `AIStates` to exclude units with active weapons from dying state transitions. Allows models to display general weapon usage animations when the respective weapon slot is active. + +### Turret and Rotation +- **`TURRET_ROTATE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Turret is rotating. Set automatically by `TurretAI` when turrets are actively rotating to face targets. Cleared when turrets stop rotating (target acquired or rotation complete). Used by turret AI systems to indicate turrets are in motion. Used by `TurretAI` to track turret rotation state. Allows models to display turret rotation animations. Used to indicate when turrets are actively turning to face their targets. + +### Special Combat States +- **`DYING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is dying. Set automatically by `AIStates` when units enter death sequence. Cleared when units finish dying or are removed. Used by AI systems to transition units to death animations. Used in combination with other flags to exclude units from certain state transitions (units with `DYING` flag are excluded from other combat states). Mutually exclusive with weapon usage and movement states during death sequence. Allows models to display death animations and visual effects. + +- **`STUNNED_FLAILING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is stunned and flailing. Set automatically by `Object` when units receive stun damage that causes flailing behavior. Used by `PhysicsUpdate` to transition from flailing to regular stunned state when stun effects wear off. Used to indicate units that are in a more severe stun state with chaotic movement. Allows models to display flailing animations for stunned units. Transitioned to `STUNNED` when the flailing effect ends. + +- **`STUNNED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is stunned. Set automatically by `PhysicsUpdate` when stun effects are applied. Used by `PhysicsUpdate` to track stunned state. Cleared when stun effects wear off. Used to indicate units that are temporarily disabled by stun effects. Allows models to display stunned animations. Units with this flag are typically unable to move or attack until the flag is cleared. + +- **`PANICKING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Yes, it's spelled with a "k". look it up. Used for units that are in a panicking state. Allows models to display panic animations and visual effects. Used by morale systems to indicate units that are panicking due to combat stress or morale loss. + +- **`CONTINUOUS_FIRE_SLOW`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Continuous fire slow. Set automatically by `FiringTracker::coolDown()` when weapons transition from faster firing states to slower firing. Used by `FiringTracker` to track weapon firing intensity - indicates weapons that are firing continuously but at a slower rate. Mutually exclusive with `CONTINUOUS_FIRE_MEAN` and `CONTINUOUS_FIRE_FAST` - only one continuous fire state can be active at a time. Cleared when firing stops completely. Allows models to display slower continuous fire animations. Used to indicate weapons that have been firing for a while and are cooling down. + +- **`CONTINUOUS_FIRE_MEAN`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Continuous fire mean. Set automatically by `FiringTracker::heatUp()` when weapons have been firing for a moderate duration. Used by `FiringTracker` to track weapon firing intensity - indicates weapons that are firing continuously at a medium rate. Mutually exclusive with `CONTINUOUS_FIRE_SLOW` and `CONTINUOUS_FIRE_FAST`. Transitions to `CONTINUOUS_FIRE_FAST` if firing continues. Used to indicate weapons that are heating up from continuous fire. Triggers "VoiceRapidFire" audio event when set. Allows models to display medium-rate continuous fire animations. + +- **`CONTINUOUS_FIRE_FAST`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Continuous fire fast. Set automatically by `FiringTracker::heatUp()` when weapons have been firing continuously at maximum intensity. Used by `FiringTracker` to track weapon firing intensity - indicates weapons that are firing continuously at a fast rate due to heat buildup. Mutually exclusive with `CONTINUOUS_FIRE_SLOW` and `CONTINUOUS_FIRE_MEAN`. Represents the highest intensity continuous fire state. Used to indicate weapons that are at maximum firing rate due to continuous fire. Allows models to display fast-rate continuous fire animations and increased visual effects. + +### Radar and Power +- **`RADAR_EXTENDING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Radar is extending. Set automatically by `RadarUpdate` when radar structures begin extending their radar dishes. Used by `RadarUpdate` to track radar extension animation. Transitions to `RADAR_UPGRADED` when extension completes. Allows models to display radar extension animations. Used to indicate radar structures that are in the process of extending their radar equipment. + +- **`RADAR_UPGRADED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Radar is upgraded. Set automatically by `RadarUpdate` when radar extension completes. Used by `RadarUpdate` to indicate radar structures have fully extended and upgraded their radar equipment. Transitions from `RADAR_EXTENDING` when extension completes. Allows models to display upgraded radar visual states. Used to indicate radar structures that have completed their upgrade sequence. + +- **`POWER_PLANT_UPGRADED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - To show special control rods on the cold fusion plant. Set automatically by `PowerPlantUpdate` when power plant upgrades complete. Used by `PowerPlantUpdate` to indicate power plants have upgraded control rods. Transitions from `POWER_PLANT_UPGRADING` when upgrade completes. Allows models to display special control rod visual effects on cold fusion power plants. Used to indicate power plants that have upgraded to show special visual effects. + +- **`POWER_PLANT_UPGRADING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - While special control rods on the cold fusion plant are extending. Set automatically by `PowerPlantUpdate` when power plant upgrades begin. Used by `PowerPlantUpdate` to track power plant upgrade animation. Transitions to `POWER_PLANT_UPGRADED` when upgrade completes. Cleared when upgrade is cancelled or interrupted. Allows models to display control rod extension animations. Used to indicate power plants that are in the process of upgrading their control rods. + +### Capture and Special States +- **`RAISING_FLAG`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is raising flag. Set automatically by `SpecialAbilityUpdate` when units perform flag-raising actions (e.g., capturing buildings). Used by special ability systems to indicate flag-raising activities. Used by `SpecialAbilityUpdate` to clear this state during other special abilities. Allows models to display flag-raising animations. Used for units that are capturing structures or raising flags. + +- **`CAPTURED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object has been captured. Set automatically by `TechBuildingBehavior` when structures are captured by enemy forces. Used by capture systems to indicate structures that have been captured. Cleared when structures are recaptured or destroyed. Used by `TechBuildingBehavior` to track capture state. Allows models to display captured structure visual states (e.g., different flag colors, ownership changes). + +- **`SOLD`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is being sold. Set automatically by `BuildAssistant` when structures are being sold (construction percent reaches 0% during sale). Used by construction systems to indicate structures that are being sold back. Used during the sell-back process to track sale state. Allows models to display selling animations. Cleared when sale completes or is cancelled. + +- **`ARMED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Armed like a mine or bomb is armed (not like a human is armed). Used for objects like mines, bombs, or explosives that are in an armed/active state. Used to distinguish between armed and unarmed explosive objects. Allows models to display armed state animations and visual effects. Used by explosive systems to indicate objects that are ready to detonate. + +- **`DISGUISED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is disguised. Set automatically by `StealthUpdate` when units activate disguise abilities. Cleared when disguise is removed or units are detected. Used by stealth systems to track disguised units. Used by `StealthUpdate` to manage disguise state. Allows models to display disguised visual states (e.g., different model appearances, faction disguises). Used for units that can disguise themselves as enemy units. + +- **`JAMMED`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Jammed as in missile jammed by ECM. Set automatically by `MissileAIUpdate` when missiles are jammed by electronic countermeasures (ECM). Used by missile systems to indicate missiles that have been jammed. Used by ECM systems to track jammed projectiles. Allows models to display jammed state animations (e.g., missiles spiraling out of control). Used for missiles and projectiles that are affected by jamming systems. + +- **`SECOND_LIFE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is in second life state. Set automatically by `BattleBusSlowDeathBehavior` when objects with second life mechanics activate their second life. Used by `UndeadBody` to indicate objects that have been revived after death. Used by second life systems to track objects that have been given a second chance. Allows models to display second life visual states. Used for objects like the Battle Bus that can survive death and continue operating. + +### Special Animations +- **`SPECIAL_CHEERING`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - When units do a victory cheer (or player initiated cheer). Special model conditions work as following: Something turns it on... but a timer in the object will turn them off after a given amount of time. Set automatically by `AIGroup` when units perform victory cheers or player-initiated cheer commands. Used by AI and command systems to trigger cheering animations. Automatically cleared by `Object::clearModelConditionFlags()` after a duration (typically 3 seconds as set by `AIGroup`). Used by `Object` to clear the flag after the timer expires. Allows models to display cheering animations and visual effects. Used for units that want to celebrate victories or respond to player cheer commands. + +### Preorder and Movement +- **`PREORDER`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is in preorder state. Set automatically by `PreorderCreate` when objects are created for preorder players. Used by `PreorderCreate` to track preorder player objects. Cleared when preorder objects are finalized or converted to normal objects. Allows models to display preorder-specific visual states or animations. Used to indicate objects that were created for players who preordered the game. + +- **`CENTER_TO_LEFT`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is moving center to left. Set automatically by `AnimationSteeringUpdate` when units initiate a turn from center position to left. Used by steering animation systems to indicate units are turning left. Transitions to `LEFT_TO_CENTER` when the turn completes or unit straightens. Cleared when units complete the turn or change direction. Allows models to display turning animations for left turns. Used for smooth transition animations during unit steering. + +- **`LEFT_TO_CENTER`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is moving left to center. Set automatically by `AnimationSteeringUpdate` when units straighten from a left turn back to center. Used by steering animation systems to indicate units are straightening from a left turn. Transitions from `CENTER_TO_LEFT` when the turn completes. Cleared when units complete the straightening or change direction. Allows models to display straightening animations after left turns. Used for smooth transition animations during unit steering. + +- **`CENTER_TO_RIGHT`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is moving center to right. Set automatically by `AnimationSteeringUpdate` when units initiate a turn from center position to right. Used by steering animation systems to indicate units are turning right. Transitions to `RIGHT_TO_CENTER` when the turn completes or unit straightens. Cleared when units complete the turn or change direction. Allows models to display turning animations for right turns. Used for smooth transition animations during unit steering. + +- **`RIGHT_TO_CENTER`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Object is moving right to center. Set automatically by `AnimationSteeringUpdate` when units straighten from a right turn back to center. Used by steering animation systems to indicate units are straightening from a right turn. Transitions from `CENTER_TO_RIGHT` when the turn completes. Cleared when units complete the straightening or change direction. Allows models to display straightening animations after right turns. Used for smooth transition animations during unit steering. + +### Rider States (8 riders) +- **`RIDER1`** through **`RIDER8`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Rider states for different riders on multi-rider vehicles. Used by `RiderChangeContain` and `WeaponSet` to indicate which rider position is active. Used by `RiderChangeContain` to track rider model condition flags for vehicles like combat bikes that can carry multiple riders. Used by `FlightDeckBehavior` for flight deck door management. Allows models to display different rider positions and animations for multi-rider vehicles. Used for vehicles that can carry multiple riders in different positions (e.g., combat bikes with sidecar riders). + +### Weapon Set and Upgrade States +- **`WEAPONSET_VETERAN`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon set veteran. Set automatically by weapon set systems when units achieve veteran status. Used by `WeaponSet` to indicate veteran-level weapon sets. Allows models to display veteran weapon visual states. Used for units that have gained veterancy and upgraded their weapons. + +- **`WEAPONSET_ELITE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon set elite. Set automatically by weapon set systems when units achieve elite status. Used by `WeaponSet` to indicate elite-level weapon sets. Allows models to display elite weapon visual states. Used for units that have gained elite status and upgraded their weapons. + +- **`WEAPONSET_HERO`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon set hero. Set automatically by weapon set systems when units achieve hero status. Used by `WeaponSet` to indicate hero-level weapon sets. Allows models to display hero weapon visual states. Used for units that have gained hero status and upgraded their weapons. + +- **`WEAPONSET_CRATEUPGRADE_ONE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon set crate upgrade one. Set automatically by crate systems when units collect weapon upgrade crates. Used by `WeaponSet` to indicate first-level crate weapon upgrades. Used by `SalvageCrateCollide` for weapon crate upgrades. Allows models to display first-level crate upgrade weapon visual states. Used for units that have collected weapon upgrade crates. + +- **`WEAPONSET_CRATEUPGRADE_TWO`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon set crate upgrade two. Set automatically by crate systems when units collect second-level weapon upgrade crates. Used by `WeaponSet` to indicate second-level crate weapon upgrades. Used by `SalvageCrateCollide` for weapon crate upgrades (transitions from `WEAPONSET_CRATEUPGRADE_ONE`). Allows models to display second-level crate upgrade weapon visual states. Used for units that have collected multiple weapon upgrade crates. + +- **`WEAPONSET_PLAYER_UPGRADE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Weapon set player upgrade. Set automatically by upgrade systems when player upgrades are applied to units. Used by `WeaponSet` to indicate player-purchased weapon upgrades. Used by `MobMemberSlavedUpdate` to check for weapon upgrade states. Allows models to display player upgrade weapon visual states. Used for units that have received player-purchased weapon upgrades. + +- **`WEAPONSET_PLAYER_UPGRADE2`** through **`WEAPONSET_PLAYER_UPGRADE4`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Additional weapon set player upgrade levels 2-4. Set automatically by upgrade systems when multiple player upgrades are applied to units. Used by `WeaponSet` to indicate additional player-purchased weapon upgrade levels. Allows models to display multiple player upgrade weapon visual states. Used for units that have received multiple player-purchased weapon upgrades (GMX Zero Hour only for levels 2-4). + +### Armor Set States +- **`ARMORSET_CRATEUPGRADE_ONE`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Armor set crate upgrade one. Set automatically by crate systems when units collect armor upgrade crates. Used by `SalvageCrateCollide` to set armor set flags when armor crates are collected. Used by armor systems to indicate first-level crate armor upgrades. Transitions to `ARMORSET_CRATEUPGRADE_TWO` when second crate is collected. Allows models to display first-level crate upgrade armor visual states. Used for units that have collected armor upgrade crates. + +- **`ARMORSET_CRATEUPGRADE_TWO`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Armor set crate upgrade two. Set automatically by crate systems when units collect second-level armor upgrade crates. Used by `SalvageCrateCollide` to transition from `ARMORSET_CRATEUPGRADE_ONE` to `ARMORSET_CRATEUPGRADE_TWO` when second armor crate is collected. Used by armor systems to indicate second-level crate armor upgrades. Allows models to display second-level crate upgrade armor visual states. Used for units that have collected multiple armor upgrade crates. + +### User-Definable Flags (5 user flags) +- **`USER_1`** through **`USER_5`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Wildcard flags available for custom use by modders. These flags are not used by the default game systems and are reserved for modder-defined purposes. Can be used with upgrade modules, custom behaviors, or any other custom functionality. Allows modders to create custom visual states and animations that can be triggered by their own systems. These flags can be set and cleared by custom code to indicate any modder-defined states. + +### Armor Upgrade Flags (5 armor upgrades) +- **`ARMOR_UPGRADE_1`** through **`ARMOR_UPGRADE_5`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Wildcard flags for armor upgrade visual states. These flags are available for use with upgrade modules or custom armor upgrade systems. Can be used to indicate different levels or types of armor upgrades. Allows modders to create custom armor upgrade visual states and animations. These flags can be set by upgrade systems to display different armor appearances based on upgrade levels or types. + +### Weapon Upgrade Flags (5 weapon upgrades) +- **`WEAPON_UPGRADE_1`** through **`WEAPON_UPGRADE_5`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04)* - Wildcard flags for weapon upgrade visual states. These flags are available for use with upgrade modules or custom weapon upgrade systems. Can be used to indicate different levels or types of weapon upgrades. Allows modders to create custom weapon upgrade visual states and animations. These flags can be set by upgrade systems to display different weapon appearances based on upgrade levels or types. + +### Component Damage States *(GMX Zero Hour only)* +- **`COMPONENT_ENGINE_DESTROYED`** *(GMX Zero Hour only)* - Component engine has been destroyed. Set automatically by `Drawable::reactToBodyDamageStateChange()` when engine components are destroyed. Used by component damage systems to indicate engine destruction. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display destroyed engine visual states. Used for vehicles with component-based damage systems where engines can be individually destroyed. + +- **`COMPONENT_ENGINE_DAMAGED`** *(GMX Zero Hour only)* - Component engine has been damaged. Set automatically by `Drawable::reactToBodyDamageStateChange()` when engine components are damaged. Used by component damage systems to indicate engine damage. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display damaged engine visual states. Used for vehicles with component-based damage systems where engines can be individually damaged. + +- **`COMPONENT_TURRET_DESTROYED`** *(GMX Zero Hour only)* - Component turret has been destroyed. Set automatically by `Drawable::reactToBodyDamageStateChange()` when turret components are destroyed. Used by component damage systems to indicate turret destruction. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display destroyed turret visual states. Used for vehicles with component-based damage systems where turrets can be individually destroyed. + +- **`COMPONENT_TURRET_DAMAGED`** *(GMX Zero Hour only)* - Component turret has been damaged. Set automatically by `Drawable::reactToBodyDamageStateChange()` when turret components are damaged. Used by component damage systems to indicate turret damage. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display damaged turret visual states. Used for vehicles with component-based damage systems where turrets can be individually damaged. + +- **`COMPONENT_WEAPON_A_DESTROYED`** through **`COMPONENT_WEAPON_H_DESTROYED`** *(GMX Zero Hour only)* - Component weapon destroyed state for weapon slots A-H. Set automatically by `Drawable::reactToBodyDamageStateChange()` when weapon components are destroyed. Used by component damage systems to indicate specific weapon slot destruction. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display destroyed weapon visual states for specific weapon slots. Used for vehicles with component-based damage systems where individual weapons can be destroyed. + +- **`COMPONENT_WEAPON_A_DAMAGED`** through **`COMPONENT_WEAPON_H_DAMAGED`** *(GMX Zero Hour only)* - Component weapon damaged state for weapon slots A-H. Set automatically by `Drawable::reactToBodyDamageStateChange()` when weapon components are damaged. Used by component damage systems to indicate specific weapon slot damage. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display damaged weapon visual states for specific weapon slots. Used for vehicles with component-based damage systems where individual weapons can be damaged. + +- **`COMPONENT_A_DESTROYED`** through **`COMPONENT_H_DESTROYED`** *(GMX Zero Hour only)* - Component destroyed state for generic components A-H. Set automatically by `Drawable::reactToBodyDamageStateChange()` when generic components are destroyed. Used by component damage systems to indicate generic component destruction. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display destroyed component visual states. Used for vehicles with component-based damage systems where generic components can be destroyed. + +- **`COMPONENT_A_DAMAGED`** through **`COMPONENT_H_DAMAGED`** *(GMX Zero Hour only)* - Component damaged state for generic components A-H. Set automatically by `Drawable::reactToBodyDamageStateChange()` when generic components are damaged. Used by component damage systems to indicate generic component damage. Used by `Drawable` to clear all component damage flags when resetting damage states. Allows models to display damaged component visual states. Used for vehicles with component-based damage systems where generic components can be damaged. + +### Surrender State *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04 - conditional compilation)* +- **`SURRENDER`** *(GMX Generals, GMX Zero Hour, Retail Generals 1.04, Retail Zero Hour 1.04 - conditional compilation)* - When units surrender. Set automatically by surrender systems when units surrender to enemy forces. Used by surrender mechanics to indicate units that have surrendered. This flag is conditionally compiled and may not be available in all builds. Allows models to display surrender animations and visual states. Used for units that can surrender during combat, typically removing them from player control. + +## Examples + +Model condition flags are set automatically by game systems based on object state, damage, actions, and other conditions. However, they are configured in INI files through `W3DModelDraw` modules to define which models, animations, and visual states should be displayed for each combination of flags. + +### INI Configuration in W3DModelDraw Modules + +Model condition flags are used in `W3DModelDraw` modules (like `W3DDefaultDraw`) through the `ConditionState` property. Each `ConditionState` block defines a visual state that matches specific model condition flags. The system automatically selects the best matching state based on the object's current model condition flags. + +#### Basic Example: Damage States + +```ini +Draw = W3DModelDraw ModuleTag_Draw + ConditionState = NONE + Model = MyUnit.w3d + Animation = Idle + AnimationMode = LOOP + End + + ConditionState = DAMAGED + Model = MyUnitDamaged.w3d + Animation = IdleDamaged + AnimationMode = LOOP + End + + ConditionState = REALLY_DAMAGED + Model = MyUnitReallyDamaged.w3d + Animation = IdleReallyDamaged + AnimationMode = LOOP + End +End +``` + +In this example: +- When the object has no damage flags set, it uses the `NONE` state with `MyUnit.w3d` +- When the `DAMAGED` flag is set (health drops below first threshold), it switches to `MyUnitDamaged.w3d` +- When the `REALLY_DAMAGED` flag is set (health drops below second threshold), it switches to `MyUnitReallyDamaged.w3d` + +The system automatically sets these flags based on health percentage, and `W3DModelDraw::replaceModelConditionState()` calls `findBestInfo()` to select the matching visual state. + +#### Advanced Example: Multiple Flags Combined + +```ini +Draw = W3DModelDraw ModuleTag_Draw + ConditionState = NONE + Model = Tank.w3d + Animation = Idle + AnimationMode = LOOP + End + + ConditionState = DAMAGED + Model = TankDamaged.w3d + Animation = IdleDamaged + AnimationMode = LOOP + End + + ConditionState = NIGHT + Model = TankNight.w3d + Animation = Idle + AnimationMode = LOOP + End + + ConditionState = DAMAGED NIGHT + Model = TankDamagedNight.w3d + Animation = IdleDamaged + AnimationMode = LOOP + End + + ConditionState = FIRING_A + Model = Tank.w3d + Animation = Fire + AnimationMode = ONCE + End + + ConditionState = FIRING_A DAMAGED + Model = TankDamaged.w3d + Animation = FireDamaged + AnimationMode = ONCE + End +End +``` + +This example shows how multiple flags can be combined: +- `NIGHT` alone uses `TankNight.w3d` +- `DAMAGED` alone uses `TankDamaged.w3d` +- `DAMAGED NIGHT` combined uses `TankDamagedNight.w3d` (when both flags are active) +- `FIRING_A` uses the firing animation +- `FIRING_A DAMAGED` uses the firing animation on the damaged model + +The matching system (`findBestInfo()` in `W3DModelDrawModuleData`) finds the best matching state by comparing the object's current model condition flags with the flags specified in each `ConditionState`. + +#### Example: Using Transition States + +```ini +Draw = W3DModelDraw ModuleTag_Draw + DefaultConditionState = NONE + Model = Unit.w3d + Animation = Idle + AnimationMode = LOOP + End + + ConditionState = DAMAGED + Model = UnitDamaged.w3d + Animation = IdleDamaged + AnimationMode = LOOP + End + + TransitionState = NONE DAMAGED + Model = Unit.w3d + Animation = TakeDamage + AnimationMode = ONCE + End +End +``` + +Transition states are used for animations that play when transitioning between states: +- When transitioning from `NONE` to `DAMAGED`, the `TakeDamage` animation plays once +- After the transition completes, the system switches to the `DAMAGED` state + +#### Example: Hide/Show Subobjects Based on Flags + +```ini +Draw = W3DModelDraw ModuleTag_Draw + ConditionState = NONE + Model = Tank.w3d + Animation = Idle + AnimationMode = LOOP + HideSubObject = DamagedParts + ShowSubObject = IntactParts + End + + ConditionState = DAMAGED + Model = Tank.w3d + Animation = IdleDamaged + AnimationMode = LOOP + HideSubObject = IntactParts + ShowSubObject = DamagedParts + End +End +``` + +This example shows how the same model can have different subobjects visible/hidden based on flags: +- In `NONE` state, `DamagedParts` are hidden and `IntactParts` are shown +- In `DAMAGED` state, `IntactParts` are hidden and `DamagedParts` are shown + +### Runtime Usage + +At runtime, the system works as follows: + +1. **Flag Setting**: Game systems automatically set model condition flags based on object state (e.g., `Drawable::reactToBodyDamageStateChange()` sets `DAMAGED`, `REALLY_DAMAGED`, etc.) + +2. **State Selection**: `W3DModelDraw::replaceModelConditionState()` is called with the current flags, which calls `findBestInfo()` to find the best matching `ConditionState` + +3. **State Matching**: The `findBestInfo()` method uses `SparseMatchFinder` to match the object's current flags against all defined states, finding the one that best matches (can match multiple flags) + +4. **Visual Update**: Once a state is selected, the system: + - Loads/switches to the appropriate model (if different) + - Sets the appropriate animations + - Hides/shows subobjects as specified + - Updates other visual properties defined in that state + +### Code Reference + +The key code locations where this happens: + +- **INI Parsing**: `W3DModelDrawModuleData::parseConditionState()` (line 1417 in `W3DModelDraw.cpp`) parses `ConditionState` blocks and stores flags in `ModelConditionInfo::m_conditionsYesVec` + +- **State Matching**: `W3DModelDrawModuleData::findBestInfo()` (line 1741) matches current flags to states + +- **State Application**: `W3DModelDraw::replaceModelConditionState()` (line 3279) applies the selected state to the visual representation + +- **Flag Checking**: `ModelConditionFlags::test()` is used to check if specific flags are set (e.g., `c.test(MODELCONDITION_NIGHT)` checks if the NIGHT flag is active) + +## Notes + +- Model condition flags are bit flags that can be combined. Objects typically have multiple model condition flags set simultaneously. +- Model condition flags are set automatically by game systems based on object state, damage, actions, and other conditions. They are not directly set in INI files. +- Some model condition flags are mutually exclusive or have specific activation conditions (e.g., `FIRING_A` and `RELOADING_A` cannot be active simultaneously for the same weapon slot). +- Some model condition flags are temporary and automatically cleared after a duration (e.g., `SPECIAL_CHEERING`). +- Model condition flags affect which model animations and visual states are displayed. +- The `USER_1` through `USER_5`, `ARMOR_UPGRADE_1` through `ARMOR_UPGRADE_5`, and `WEAPON_UPGRADE_1` through `WEAPON_UPGRADE_5` flags are available for custom use by modders. +- Component damage states (`COMPONENT_*`) are only available in GMX Zero Hour. +- Surrender state (`SURRENDER`) is conditionally compiled and may not be available in all builds. +- Note: These values are saved in save files, so you MUST NOT REMOVE OR CHANGE existing values! + +## Source Files + +**Header (Generals):** [ModelState.h](../../Generals/Code/GameEngine/Include/Common/ModelState.h) +- `ModelConditionFlagType` enum definition (line 90) +- `ModelConditionFlags` typedef (line 353) + +**Header (Zero Hour):** [ModelState.h](../../GeneralsMD/Code/GameEngine/Include/Common/ModelState.h) +- `ModelConditionFlagType` enum definition (line 90) +- `ModelConditionFlags` typedef (line 353) + +**Source (Generals):** [BitFlags.cpp](../../Generals/Code/GameEngine/Source/Common/BitFlags.cpp) +- `ModelConditionFlags::s_bitNameList[]` array definition (line 41) + +**Source (Zero Hour):** [BitFlags.cpp](../../GeneralsMD/Code/GameEngine/Source/Common/BitFlags.cpp) +- `ModelConditionFlags::s_bitNameList[]` array definition (line 41) + +## Changes History + +- In GMX Zero Hour, 93 new ModelConditionFlagType flags were added including 4 aircraft landing states, 4 movement direction states, 8 rider states, 2 special combat states, 3 special states, 2 armor set states, 15 upgrade flags, 3 weapon set upgrade states, 25 weapon slot states, and 36 component damage states. + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated, 0/2 reviews + +## Reviewers + +- *No reviewers yet* + diff --git a/Docs/INI/Object/Enums/ObjectStatusTypes.md b/Docs/INI/Object/Enums/ObjectStatusTypes.md new file mode 100644 index 0000000000..e8d7f10153 --- /dev/null +++ b/Docs/INI/Object/Enums/ObjectStatusTypes.md @@ -0,0 +1,197 @@ +# ObjectStatusTypes + +Status: AI-generated, 0/2 reviews + +## Overview + +`ObjectStatusTypes` is a bit flag system used to represent various states and conditions of objects in the game. Object status flags are stackable, meaning multiple status flags can be active on an object simultaneously. These flags are used throughout the game to track object states, control behavior, enable/disable capabilities, and manage special conditions. + +Object status flags are used for many purposes: +- **State tracking**: Track object states like destroyed, under construction, on fire, etc. +- **Behavior control**: Enable or disable object capabilities (e.g., `CAN_ATTACK`, `NO_ATTACK`, `UNSELECTABLE`) +- **Special conditions**: Track special states like stealth, disguise, hijacked, etc. +- **Combat states**: Track combat-related states like firing weapons, attacking, aiming +- **Movement states**: Track movement-related states like braking, immobile, etc. + +**For modders**: Object status flags are set automatically by game systems based on object state and behavior. They are not directly set in INI files, but they can be referenced in various game systems and modules. Some modules allow you to require or forbid specific status flags for certain behaviors. + +Available in: *(v1.04)* + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) +- [Enum Value Lists](#enum-value-lists) + - [Basic States](#basic-states) + - [Combat and Attack States](#combat-and-attack-states) + - [Construction and Repair States](#construction-and-repair-states) + - [Stealth and Detection States](#stealth-and-detection-states) + - [Special Conditions](#special-conditions) + - [Movement and Physics States](#movement-and-physics-states) +- [Examples](#examples) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +**Limitations**: +- Object status flags are bit flags that can be combined. Multiple flags can be set on a single object simultaneously. +- Object status flags are set automatically by game systems based on object state, behavior, and conditions. +- Some object status flags are mutually exclusive or have specific activation conditions. +- Object status flags are used internally by the game engine; they are not directly set in INI files but can be referenced in module configurations. + +**Conditions**: +- Object status flags are set automatically by game systems based on object state (e.g., construction, combat, movement, special abilities). +- Multiple object status flags can be active simultaneously (e.g., `STEALTHED` and `DETECTED` can both be active). +- Some modules allow you to require or forbid specific status flags for certain behaviors (e.g., `StealthUpdate`, `AdvancedCollide`). +- Object status flags are saved in game state and persist across save/load operations. + +**Dependencies**: +- Object status flags are used by various game systems to control object behavior and state. +- Some modules reference object status flags to enable or disable behaviors (e.g., `StealthUpdate` uses `CAN_STEALTH`, `STEALTHED`, `DETECTED`). +- Object status flags can be checked by weapon systems, AI systems, and other game logic to determine object capabilities and states. + +## Enum Value Lists + +### ObjectStatusTypes Values + +Available in: *(v1.04)* + +### Basic States + +- **`OBJECT_STATUS_NONE`** *(v1.04)* - No status bit. This is the default/empty status flag. Used to indicate no special status is set. + +- **`OBJECT_STATUS_DESTROYED`** *(v1.04)* - Object has been destroyed, pending delete. Set automatically when an object is destroyed. Used to mark objects that are in the process of being removed from the game. Objects with this flag are typically pending deletion and should not be interacted with. + +- **`OBJECT_STATUS_UNDER_CONSTRUCTION`** *(v1.04)* - Object is being constructed and is not yet complete. Set automatically by construction systems when a structure is being built. Used to indicate structures that are currently under construction. Objects with this flag are not yet fully functional. + +### Combat and Attack States + +- **`OBJECT_STATUS_CAN_ATTACK`** *(v1.04)* - Object can attack. Used by garrisoned buildings - this flag is OR'ed with `KINDOF_CAN_ATTACK` in `isAbleToAttack()`. Allows garrisoned structures to attack even if they don't have the `CAN_ATTACK` KindOf flag. Used to enable attack capability for objects that normally cannot attack. + +- **`OBJECT_STATUS_NO_ATTACK`** *(v1.04)* - Absolute override to being able to attack. When set, the object cannot attack regardless of other flags or capabilities. Used to completely disable attack capability for objects. + +- **`OBJECT_STATUS_IS_FIRING_WEAPON`** *(v1.04)* - Object is firing a weapon, now. Not true for special attacks. Set automatically by weapon systems when a weapon is actively firing. Used to track when objects are in the process of firing weapons. Note: This does not apply to special attacks, only regular weapon fire. + +- **`OBJECT_STATUS_IS_ATTACKING`** *(v1.04)* - Object is in the general Attack state (including aim, approach, etc.). Note that `IS_FIRING_WEAPON` and `IS_AIMING_WEAPON` are subsets of this! Set automatically by AI systems when objects are in attack mode. Used to track when objects are actively engaging targets, including aiming and approaching phases. + +- **`OBJECT_STATUS_IS_AIMING_WEAPON`** *(v1.04)* - Object is aiming a weapon, now. Not true for special attacks. Set automatically by weapon systems when a weapon is being aimed at a target. Used to track when objects are in the aiming phase before firing. Note: This does not apply to special attacks, only regular weapon aiming. + +- **`OBJECT_STATUS_IS_USING_ABILITY`** *(v1.04)* - Object is in the process of preparing or firing a special ability. Set automatically by ability systems when objects are using special abilities. Used to track when objects are actively using special powers or abilities. + +- **`OBJECT_STATUS_NO_ATTACK_FROM_AI`** *(v1.04)* - Attacking this object may not be done from `commandSource == CMD_FROM_AI`. When set, AI-controlled units cannot attack this object. Used to prevent AI from targeting specific objects while still allowing player-controlled units to attack them. + +### Construction and Repair States + +- **`OBJECT_STATUS_RECONSTRUCTING`** *(v1.04)* - Object is reconstructing. Set automatically by reconstruction systems when objects are being rebuilt. Used to indicate objects that are in the process of being reconstructed after being destroyed or damaged. + +- **`OBJECT_STATUS_UNDERGOING_REPAIR`** *(v1.04)* - Object is awaiting/undergoing a repair order that has been issued. Set automatically by repair systems when objects are queued for or actively being repaired. Used to track objects that are in the repair queue or being repaired. + +- **`OBJECT_STATUS_SOLD`** *(v1.04)* - Object is being sold. Set automatically when a structure is sold by the player. Used to mark objects that are in the process of being sold and removed from the game. + +### Stealth and Detection States + +- **`OBJECT_STATUS_STEALTHED`** *(v1.04)* - Object is currently "stealthed". Set automatically by `StealthUpdate` when objects enter stealth mode. Used to indicate objects that are currently invisible or hidden from enemies. Objects with this flag are not visible to enemies unless they are detected. + +- **`OBJECT_STATUS_DETECTED`** *(v1.04)* - Object is in range of a stealth-detector unit (meaningless if `STEALTHED` not set). Set automatically by detection systems when stealthed objects are detected by detector units. Used to indicate that a stealthed object has been detected. This flag only has meaning when combined with `STEALTHED`. + +- **`OBJECT_STATUS_CAN_STEALTH`** *(v1.04)* - Object has ability to stealth allowing the stealth update module to run. Set automatically by `StealthUpdate` for objects that have stealth capabilities. Used to enable the stealth update module for objects that can enter stealth mode. + +- **`OBJECT_STATUS_IGNORING_STEALTH`** *(v1.04)* - Temporarily ignoring all stealth bits. Used only for some special-case mine clearing stuff. Set automatically by special systems when objects need to temporarily ignore stealth mechanics. Used for special cases like mine clearing where stealth detection needs to be bypassed. + +### Special Conditions + +- **`OBJECT_STATUS_UNSELECTABLE`** *(v1.04)* - Object cannot be selected. This is a negative condition since these statuses are overrides - their presence forces the condition, but their absence means nothing. Set automatically by various systems to prevent object selection. Used to make objects unselectable by players, typically for temporary states or special objects. + +- **`OBJECT_STATUS_MASKED`** *(v1.04)* - Masked objects are not selectable and targetable by players or AI. Set automatically by masking systems. Used to completely hide objects from player and AI interaction. Masked objects cannot be selected or targeted. + +- **`OBJECT_STATUS_NO_COLLISIONS`** *(v1.04)* - Object should be ignored for object-object collisions (but not object-ground). Used for things like collapsing parachutes that are intangible. Set automatically by physics systems for objects that should not collide with other objects. Used to make objects pass through other objects while still colliding with terrain. + +- **`OBJECT_STATUS_AIRBORNE_TARGET`** *(v1.04)* - InTheAir as far as AntiAir weapons are concerned only. Set automatically by aircraft systems to mark objects that should be treated as airborne targets. Used by anti-aircraft weapons to identify valid targets. This flag is separate from actual flight state and is specifically for weapon targeting purposes. + +- **`OBJECT_STATUS_PARACHUTING`** *(v1.04)* - Object is on a parachute. Set automatically by parachute systems when objects are descending with parachutes. Used to track objects that are currently parachuting. Objects with this flag are typically in the air and descending. + +- **`OBJECT_STATUS_REPULSOR`** *(v1.04)* - Object repulses "KINDOF_CAN_BE_REPULSED" objects. Set automatically by repulsor systems. Used to mark objects that push away units with the `CAN_BE_REPULSED` KindOf flag. Objects with this flag create a repulsion field around them. + +- **`OBJECT_STATUS_HIJACKED`** *(v1.04)* - Unit is in the possession of an enemy criminal, call the authorities. Set automatically by hijack systems when units are hijacked. Used to mark vehicles that have been hijacked by enemy units. Hijacked units typically change ownership to the hijacker. + +- **`OBJECT_STATUS_AFLAME`** *(v1.04)* - This object is on fire. Set automatically by fire systems when objects catch fire. Used to track objects that are currently burning. Objects with this flag take periodic fire damage. + +- **`OBJECT_STATUS_BURNED`** *(v1.04)* - This object has already burned as much as it can. Set automatically by fire systems when objects finish burning. Used to mark objects that have been completely burned and cannot burn further. + +- **`OBJECT_STATUS_WET`** *(v1.04)* - Object has been soaked with water. Set automatically by water systems when objects are exposed to water. Used to track objects that have been affected by water, which may affect fire resistance or other properties. + +- **`OBJECT_STATUS_IS_CARBOMB`** *(v1.04)* - Object is now a carbomb. Set automatically by carbomb systems when vehicles are converted to carbombs. Used to mark vehicles that have been rigged as explosive devices. Carbomb vehicles explode when they reach their target. + +### Movement and Physics States + +- **`OBJECT_STATUS_BRAKING`** *(v1.04)* - Object is braking, and subverts the physics. Set automatically by movement systems when objects are actively braking. Used to track when objects are slowing down. Objects with this flag may have modified physics behavior during braking. + +## Examples + +### Status Flag Usage in Modules + +Some modules allow you to require or forbid specific status flags: + +```ini +Behavior = StealthUpdate ModuleTag_Stealth + RequiredStatus = CAN_STEALTH + ForbiddenStatus = DETECTED +End +``` + +In this example, the `StealthUpdate` behavior requires the `CAN_STEALTH` status flag to be set and forbids the `DETECTED` status flag. + +### Status Flag Combinations + +Multiple status flags can be active simultaneously: + +- An object can be `STEALTHED` and `DETECTED` at the same time (stealthed but detected by enemy detectors) +- An object can be `IS_ATTACKING` and `IS_FIRING_WEAPON` at the same time (actively firing while in attack state) +- An object can be `UNDER_CONSTRUCTION` and `PARTIALLY_CONSTRUCTED` at the same time (being built and partially complete) + +## Notes + +- **Status Flag Persistence**: Object status flags are saved in game state and persist across save/load operations. The comment "These are saved. Do not insert or remove any!" in the enum definition indicates that the order and values of status flags must remain stable for save game compatibility. + +- **Status Flag Combinations**: Multiple status flags can be active simultaneously. The game systems check for specific combinations of flags to determine object behavior. + +- **Automatic Management**: Object status flags are set and cleared automatically by game systems. Modders typically do not need to manually manage these flags, but they can be referenced in module configurations. + +- **Bit Flag System**: Object status flags use a bit flag system (`BitFlags`), allowing efficient storage and checking of multiple flags simultaneously. + +## Source Files + +**Header (Generals):** [ObjectStatusTypes.h](../../../../Generals/Code/GameEngine/Include/Common/ObjectStatusTypes.h) *(if retail Generals codebase exists)* +- `ObjectStatusTypes` enum definition (lines 40-77): Defines all available object status types for Retail Generals + +**Header (Zero Hour):** [ObjectStatusTypes.h](../../Code/GameEngine/Include/Common/ObjectStatusTypes.h) +- `ObjectStatusTypes` enum definition (lines 40-77): Defines all available object status types for Retail Zero Hour + +**Source (Generals):** [ObjectStatusTypes.cpp](../../../../Generals/Code/GameEngine/Source/Common/System/ObjectStatusTypes.cpp) *(if retail Generals codebase exists)* +- Status flag name mapping: Maps status flag names to their values for INI file parsing + +**Source (Zero Hour):** [ObjectStatusTypes.cpp](../../Code/GameEngine/Source/Common/System/ObjectStatusTypes.cpp) +- Status flag name mapping: Maps status flag names to their values for INI file parsing + +## Changes History + +- In Retail Zero Hour, no new object status types were added (Retail Zero Hour has the same object status types as Retail Generals 1.04). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +AI-generated, 0/2 reviews + +## Reviewers + +- [ ] Reviewer 1 +- [ ] Reviewer 2 + diff --git a/Docs/INI/Object/Object.ini b/Docs/INI/Object/Object.ini new file mode 100644 index 0000000000..7ab218b2a2 --- /dev/null +++ b/Docs/INI/Object/Object.ini @@ -0,0 +1,37 @@ +# Object INI Documentation + +## Overview + +**⚠️ Work In Progress (WIP) ⚠️** + +This documentation page is currently under development. The Object class represents the base template for all game objects including units, buildings, and other entities. + +## Status + +- **Documentation Status**: In Progress +- **Completion**: ~10% +- **Last Updated**: [Current Date] + +## Planned Sections + +- [ ] Overview and Usage +- [ ] Properties +- [ ] Enum Value Lists +- [ ] Examples +- [ ] Best Practices +- [ ] Notes + +## Related Documentation + +- [CommandButton](CommandButton.md) - References Object templates +- [Weapon](Weapon.md) - Objects can have weapons +- [Upgrade](Upgrade.md) - Objects can be upgraded + +--- + +**Note**: This page will be completed as part of the GMX documentation effort. For now, refer to the existing game files and source code for Object template information. + +## Source Files + +- Header: [`GeneralsMD/Code/GameEngine/Include/GameLogic/Object.h`](../GeneralsMD/Code/GameEngine/Include/GameLogic/Object.h) +- Source: [`GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Object.cpp`](../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Object.cpp) diff --git a/Docs/INI/Object/ObjectBehaviorsModules/AutoHealBehavior.md b/Docs/INI/Object/ObjectBehaviorsModules/AutoHealBehavior.md new file mode 100644 index 0000000000..40ee80aa93 --- /dev/null +++ b/Docs/INI/Object/ObjectBehaviorsModules/AutoHealBehavior.md @@ -0,0 +1,516 @@ +# AutoHealBehavior + +Status: AI-generated, 0/2 reviews + +## Overview + +The `AutoHealBehavior` module manages automatic healing systems that can heal the object itself or nearby friendly units within a specified radius. It supports upgrade-based activation, area healing, particle effects, and selective healing based on object types. The behavior is commonly used for medical buildings, repair facilities, and units with regenerative abilities. This is a module added inside `Object` entries. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Properties](#properties) + - [Basic Healing Settings](#basic-healing-settings) + - [Area Healing Settings](#area-healing-settings) + - [Upgrade Integration](#upgrade-integration) + - [Particle Effects](#particle-effects) + - [Target Selection](#target-selection) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Usage](#usage) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Properties + +### Basic Healing Settings + +Available in: *(v1.04)* + +#### `HealingAmount` +Available in: *(v1.04)* + +- **Type**: `Int` +- **Description**: Amount of health points healed per healing pulse. Higher values heal more health per tick, providing faster recovery. Lower values heal less per tick, requiring more time for full healing. At 0 (default), no healing occurs and the behavior is effectively disabled. +- **Default**: `0` +- **Example**: `HealingAmount = 3` + +#### `HealingDelay` +Available in: *(v1.04)* + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time interval between healing pulses. Lower values provide faster healing rates, while higher values slow down the healing process. This controls how frequently healing occurs. The value is parsed as milliseconds and converted to game frames. If not specified (defaults to UINT_MAX), the behavior will not heal regularly and must be activated manually or through upgrades. +- **Default**: `4294967295` (UINT_MAX, effectively disabled - must be set for healing to occur) +- **Example**: `HealingDelay = 1000` + +#### `StartsActive` +Available in: *(v1.04)* + +- **Type**: `Bool` +- **Description**: Whether the healing behavior is active from the start. When `Yes`, healing begins immediately upon object creation. When `No` (default), healing must be activated by upgrades or other conditions. +- **Default**: `No` +- **Example**: `StartsActive = No` + +#### `SingleBurst` +Available in: *(v1.04)* + +- **Type**: `Bool` +- **Description**: Whether to perform only a single healing burst instead of continuous healing. When `Yes`, healing occurs once then stops. When `No` (default), healing continues at regular intervals until disabled. +- **Default**: `No` +- **Example**: `SingleBurst = Yes` + +#### `StartHealingDelay` +Available in: *(v1.04)* + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Delay after taking damage before auto-healing starts. Higher values require longer waiting periods after damage before healing begins. At 0 (default), healing starts immediately when conditions are met. This only applies when healing the object itself (radius = 0). +- **Default**: `0` +- **Example**: `StartHealingDelay = 5000` + +### Area Healing Settings + +Available in: *(v1.04)* + +#### `Radius` +Available in: *(v1.04)* + +- **Type**: `Real` (distance) +- **Description**: Radius for area healing effect. Higher values extend the healing range to affect more nearby units. At 0.0 (default), only heals the object itself. +- **Default**: `0.0` +- **Example**: `Radius = 50.0` + +#### `AffectsWholePlayer` +Available in: *(v1.04)* + +- **Type**: `Bool` +- **Description**: Whether to affect all objects owned by the player instead of just those in radius. When `Yes`, heals all player units regardless of distance. When `No` (default), only affects units within the specified [Radius](#radius). +- **Default**: `No` +- **Example**: `AffectsWholePlayer = Yes` + +#### `SkipSelfForHealing` +Available in: *(v1.04, Zero Hour only)* + +- **Type**: `Bool` +- **Description**: Whether to skip healing the object itself when doing area healing. When `Yes`, the healing object does not heal itself, only nearby units. When `No` (default), the object heals both itself and nearby units. +- **Default**: `No` +- **Example**: `SkipSelfForHealing = Yes` + +### Upgrade Integration + +Available in: *(v1.04)* + +These properties are inherited from `UpgradeMux` and allow AutoHealBehavior to be activated by upgrades. + +#### `TriggeredBy` +Available in: *(v1.04)* + +- **Type**: Upgrade name or list of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: Required upgrade names to activate the healing behavior. When set, healing only occurs when at least one of the specified upgrades is active (unless [RequiresAllTriggers](#requiresalltriggers) is `Yes`). When empty (default), healing can occur without upgrade requirements. Multiple upgrade names can be specified as a space-separated list. This property accepts a list of upgrade names that are resolved to upgrade flags internally. +- **Default**: `""` (empty, no requirements) +- **Example**: `TriggeredBy = Upgrade_GLAJunkRepair` + +#### `RequiredAnyUpgradeOf` +Available in: *(v1.04)* + +- **Type**: Upgrade name or list of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: Alternative upgrade names that can activate the healing behavior. When set, healing occurs when at least one of the specified upgrades is active (in addition to [TriggeredBy](#triggeredby) requirements). When empty (default), only [TriggeredBy](#triggeredby) upgrades are checked. Multiple upgrade names can be specified as a space-separated list. This property accepts a list of upgrade names that are resolved to upgrade flags internally. +- **Default**: `""` (empty) +- **Example**: `RequiredAnyUpgradeOf = Upgrade_MedicalUpgrade Upgrade_RepairUpgrade` + +#### `RequiredAllUpgradesOf` +Available in: *(v1.04)* + +- **Type**: Upgrade name or list of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: Upgrade names that must all be active for the healing behavior to activate. When set, all specified upgrades must be active (in addition to [TriggeredBy](#triggeredby) requirements). When empty (default), only [TriggeredBy](#triggeredby) upgrades are checked. Multiple upgrade names can be specified as a space-separated list. This property accepts a list of upgrade names that are resolved to upgrade flags internally. +- **Default**: `""` (empty) +- **Example**: `RequiredAllUpgradesOf = Upgrade_MedicalUpgrade Upgrade_TechUpgrade` + +#### `ConflictsWith` +Available in: *(v1.04)* + +- **Type**: Upgrade name or list of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: Upgrade names that conflict with this healing behavior. When any of the specified upgrades are active, healing is disabled. When empty (default), no upgrade conflicts prevent healing. Multiple upgrade names can be specified as a space-separated list. This property accepts a list of upgrade names that are resolved to upgrade flags internally. +- **Default**: `""` (empty, no conflicts) +- **Example**: `ConflictsWith = Upgrade_GLACamoNetting` + +#### `RemovesUpgrades` +Available in: *(v1.04)* + +- **Type**: Upgrade name or list of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: Upgrade names that are removed when this healing behavior activates. When set, the specified upgrades are removed from the object when the healing behavior is activated. When empty (default), no upgrades are removed. Multiple upgrade names can be specified as a space-separated list. This property accepts a list of upgrade names that are resolved to upgrade flags internally. +- **Default**: `""` (empty) +- **Example**: `RemovesUpgrades = Upgrade_OldHealing` + +#### `RequiresAllTriggers` +Available in: *(v1.04)* + +- **Type**: `Bool` +- **Description**: Whether all [TriggeredBy](#triggeredby) upgrades must be active (`Yes`) or just one (`No`). When `Yes`, all specified upgrades must be active for healing. When `No` (default), only one upgrade needs to be active. +- **Default**: `No` +- **Example**: `RequiresAllTriggers = Yes` + +#### `FXListUpgrade` +Available in: *(v1.04)* + +- **Type**: `FXList` (see [FXList documentation](../FXList.md)) +- **Description**: FXList played when the upgrade activates. When set, displays visual and audio effects when the healing behavior is activated by upgrades. When empty (default), no upgrade activation effects are shown. +- **Default**: `""` (empty) +- **Example**: `FXListUpgrade = FX_HealUpgrade` + +### Particle Effects + +Available in: *(v1.04)* + +#### `RadiusParticleSystemName` +Available in: *(v1.04)* + +- **Type**: `ParticleSystemTemplate` (see [ParticleSystem documentation](../ParticleSystem.md)) +- **Description**: Particle system played for the entire area healing effect duration. When set, displays visual effects during area healing. When empty (default), no particle effects are shown. +- **Default**: `""` (empty) +- **Example**: `RadiusParticleSystemName = FX_HealArea` + +#### `UnitHealPulseParticleSystemName` +Available in: *(v1.04)* + +- **Type**: `ParticleSystemTemplate` (see [ParticleSystem documentation](../ParticleSystem.md)) +- **Description**: Particle system played on each unit when it receives healing. When set, displays visual effects on individual units during healing. When empty (default), no pulse effects are shown. +- **Default**: `""` (empty) +- **Example**: `UnitHealPulseParticleSystemName = FX_HealPulse` + +### Target Selection + +Available in: *(v1.04)* + +#### `KindOf` +Available in: *(v1.04)* + +- **Type**: `KindOfMaskType` (bit flags) (see [KindOfMaskType Values](#kindofmasktype-values) section) +- **Description**: Object types that can be healed by this behavior. When set, only objects with matching types can be healed. When 0 (default, all bits set), all object types can be healed. +- **Default**: `0` (all types) +- **Example**: `KindOf = INFANTRY VEHICLE` + +#### `ForbiddenKindOf` +Available in: *(v1.04, Zero Hour only)* + +- **Type**: `KindOfMaskType` (bit flags) (see [KindOfMaskType Values](#kindofmasktype-values) section) +- **Description**: Object types that cannot be healed by this behavior. When set, objects with matching types are excluded from healing. When 0 (default), no object types are forbidden from healing. +- **Default**: `0` (no restrictions) +- **Example**: `ForbiddenKindOf = STRUCTURE` + +## Enum Value Lists + +#### `KindOfMaskType` Values +Available in: *(v1.04)* + +**Source:** `GeneralsMD/Code/GameEngine/Source/Common/System/KindOf.cpp` - `KindOfMaskType::s_bitNameList[]` array definition + +- **`OBSTACLE`** *(v1.04)* - Obstacle objects +- **`SELECTABLE`** *(v1.04)* - Selectable objects +- **`IMMOBILE`** *(v1.04)* - Immobile objects +- **`CAN_ATTACK`** *(v1.04)* - Objects that can attack +- **`STICK_TO_TERRAIN_SLOPE`** *(v1.04)* - Objects that stick to terrain slopes +- **`CAN_CAST_REFLECTIONS`** *(v1.04)* - Objects that can cast reflections +- **`SHRUBBERY`** *(v1.04)* - Shrubbery/vegetation +- **`STRUCTURE`** *(v1.04)* - Building structures +- **`INFANTRY`** *(v1.04)* - Infantry units +- **`VEHICLE`** *(v1.04)* - Vehicle units +- **`AIRCRAFT`** *(v1.04)* - Aircraft units +- **`HUGE_VEHICLE`** *(v1.04)* - Large vehicle units +- **`DOZER`** *(v1.04)* - Dozer vehicles +- **`HARVESTER`** *(v1.04)* - Harvester vehicles +- **`COMMANDCENTER`** *(v1.04)* - Command center buildings +- **`LINEBUILD`** *(v1.04)* - Line building structures +- **`SALVAGER`** *(v1.04)* - Salvager units +- **`WEAPON_SALVAGER`** *(v1.04)* - Weapon salvager units +- **`TRANSPORT`** *(v1.04)* - Transport units +- **`BRIDGE`** *(v1.04)* - Bridge structures +- **`LANDMARK_BRIDGE`** *(v1.04)* - Landmark bridge structures +- **`BRIDGE_TOWER`** *(v1.04)* - Bridge tower structures +- **`PROJECTILE`** *(v1.04)* - Projectile objects +- **`PRELOAD`** *(v1.04)* - Preloaded objects +- **`NO_GARRISON`** *(v1.04)* - Objects that cannot be garrisoned +- **`WAVEGUIDE`** *(v1.04)* - Wave guide objects +- **`WAVE_EFFECT`** *(v1.04)* - Wave effect objects +- **`NO_COLLIDE`** *(v1.04)* - Objects that don't collide +- **`REPAIR_PAD`** *(v1.04)* - Repair pad structures +- **`HEAL_PAD`** *(v1.04)* - Heal pad structures +- **`STEALTH_GARRISON`** *(v1.04)* - Stealth garrison structures +- **`CASH_GENERATOR`** *(v1.04)* - Cash generator structures +- **`DRAWABLE_ONLY`** *(v1.04)* - Drawable only objects +- **`MP_COUNT_FOR_VICTORY`** *(v1.04)* - Multiplayer victory count objects +- **`REBUILD_HOLE`** *(v1.04)* - Rebuild hole structures +- **`SCORE`** *(v1.04)* - Score objects +- **`SCORE_CREATE`** *(v1.04)* - Score creation objects +- **`SCORE_DESTROY`** *(v1.04)* - Score destruction objects +- **`NO_HEAL_ICON`** *(v1.04)* - Objects without heal icon +- **`CAN_RAPPEL`** *(v1.04)* - Objects that can rappel +- **`PARACHUTABLE`** *(v1.04)* - Parachutable objects +- **`CAN_BE_REPULSED`** *(v1.04)* - Objects that can be repulsed +- **`MOB_NEXUS`** *(v1.04)* - Mob nexus objects +- **`IGNORED_IN_GUI`** *(v1.04)* - Objects ignored in GUI +- **`CRATE`** *(v1.04)* - Crate objects +- **`CAPTURABLE`** *(v1.04)* - Capturable objects +- **`CLEARED_BY_BUILD`** *(v1.04)* - Objects cleared by building +- **`SMALL_MISSILE`** *(v1.04)* - Small missile projectiles +- **`ALWAYS_VISIBLE`** *(v1.04)* - Always visible objects +- **`UNATTACKABLE`** *(v1.04)* - Unattackable objects +- **`MINE`** *(v1.04)* - Mine objects +- **`CLEANUP_HAZARD`** *(v1.04)* - Cleanup hazard objects +- **`PORTABLE_STRUCTURE`** *(v1.04)* - Portable structure objects +- **`ALWAYS_SELECTABLE`** *(v1.04)* - Always selectable objects +- **`ATTACK_NEEDS_LINE_OF_SIGHT`** *(v1.04)* - Objects requiring line of sight to attack +- **`WALK_ON_TOP_OF_WALL`** *(v1.04)* - Objects that walk on top of walls +- **`DEFENSIVE_WALL`** *(v1.04)* - Defensive wall structures +- **`FS_POWER`** *(v1.04)* - Firestorm power structures +- **`FS_FACTORY`** *(v1.04)* - Firestorm factory structures +- **`FS_BASE_DEFENSE`** *(v1.04)* - Firestorm base defense structures +- **`FS_TECHNOLOGY`** *(v1.04)* - Firestorm technology structures +- **`AIRCRAFT_PATH_AROUND`** *(v1.04)* - Objects aircraft path around +- **`LOW_OVERLAPPABLE`** *(v1.04)* - Low overlappable objects +- **`FORCEATTACKABLE`** *(v1.04)* - Force attackable objects +- **`AUTO_RALLYPOINT`** *(v1.04)* - Auto rally point objects +- **`TECH_BUILDING`** *(v1.04)* - Technology buildings +- **`POWERED`** *(v1.04)* - Powered structures +- **`PRODUCED_AT_HELIPAD`** *(v1.04)* - Objects produced at helipad +- **`DRONE`** *(v1.04)* - Drone objects +- **`CAN_SEE_THROUGH_STRUCTURE`** *(v1.04)* - Objects that can see through structures +- **`BALLISTIC_MISSILE`** *(v1.04)* - Ballistic missile projectiles +- **`CLICK_THROUGH`** *(v1.04)* - Click through objects +- **`SUPPLY_SOURCE_ON_PREVIEW`** *(v1.04)* - Supply source on preview objects +- **`PARACHUTE`** *(v1.04)* - Parachute objects +- **`GARRISONABLE_UNTIL_DESTROYED`** *(v1.04)* - Garrisonable until destroyed objects +- **`BOAT`** *(v1.04)* - Boat objects +- **`IMMUNE_TO_CAPTURE`** *(v1.04)* - Immune to capture objects +- **`HULK`** *(v1.04)* - Hulk objects +- **`SHOW_PORTRAIT_WHEN_CONTROLLED`** *(v1.04)* - Show portrait when controlled objects +- **`SPAWNS_ARE_THE_WEAPONS`** *(v1.04)* - Spawns are the weapons objects +- **`CANNOT_BUILD_NEAR_SUPPLIES`** *(v1.04)* - Cannot build near supplies objects +- **`SUPPLY_SOURCE`** *(v1.04)* - Supply source objects +- **`REVEAL_TO_ALL`** *(v1.04)* - Reveal to all objects +- **`DISGUISER`** *(v1.04)* - Disguiser objects +- **`INERT`** *(v1.04)* - Inert objects +- **`HERO`** *(v1.04)* - Hero objects +- **`IGNORES_SELECT_ALL`** *(v1.04)* - Ignores select all objects +- **`DONT_AUTO_CRUSH_INFANTRY`** *(v1.04)* - Don't auto crush infantry objects +- **`CLIFF_JUMPER`** *(v1.04)* - Cliff jumper objects +- **`FS_SUPPLY_DROPZONE`** *(v1.04)* - Firestorm supply dropzone structures +- **`FS_SUPERWEAPON`** *(v1.04)* - Firestorm superweapon structures +- **`FS_BLACK_MARKET`** *(v1.04)* - Firestorm black market structures +- **`FS_SUPPLY_CENTER`** *(v1.04)* - Firestorm supply center structures +- **`FS_STRATEGY_CENTER`** *(v1.04)* - Firestorm strategy center structures +- **`MONEY_HACKER`** *(v1.04)* - Money hacker objects +- **`ARMOR_SALVAGER`** *(v1.04)* - Armor salvager objects +- **`REVEALS_ENEMY_PATHS`** *(v1.04)* - Reveals enemy paths objects +- **`BOOBY_TRAP`** *(v1.04)* - Booby trap objects +- **`FS_FAKE`** *(v1.04)* - Firestorm fake structures +- **`FS_INTERNET_CENTER`** *(v1.04)* - Firestorm internet center structures +- **`BLAST_CRATER`** *(v1.04)* - Blast crater structures +- **`PROP`** *(v1.04)* - Prop objects +- **`OPTIMIZED_TREE`** *(v1.04)* - Optimized tree objects +- **`FS_ADVANCED_TECH`** *(v1.04)* - Firestorm advanced tech structures +- **`FS_BARRACKS`** *(v1.04)* - Firestorm barracks structures +- **`FS_WARFACTORY`** *(v1.04)* - Firestorm war factory structures +- **`FS_AIRFIELD`** *(v1.04)* - Firestorm airfield structures +- **`AIRCRAFT_CARRIER`** *(v1.04)* - Aircraft carrier objects +- **`NO_SELECT`** *(v1.04)* - No select objects +- **`REJECT_UNMANNED`** *(v1.04)* - Reject unmanned objects +- **`CANNOT_RETALIATE`** *(v1.04)* - Cannot retaliate objects +- **`TECH_BASE_DEFENSE`** *(v1.04)* - Tech base defense objects +- **`EMP_HARDENED`** *(v1.04)* - EMP hardened objects +- **`DEMOTRAP`** *(v1.04)* - Demo trap objects +- **`CONSERVATIVE_BUILDING`** *(v1.04)* - Conservative building objects +- **`IGNORE_DOCKING_BONES`** *(v1.04)* - Ignore docking bones objects +- **`TANK`** *(v1.04)* - Tank vehicles +- **`APC`** *(v1.04)* - Armored Personnel Carrier vehicles +- **`IFV`** *(v1.04)* - Infantry Fighting Vehicle vehicles +- **`TRUCK`** *(v1.04)* - Truck vehicles +- **`VTOL`** *(v1.04)* - Vertical Take-Off and Landing aircraft +- **`JET`** *(v1.04)* - Jet aircraft +- **`HELICOPTER`** *(v1.04)* - Helicopter aircraft +- **`HOT_AIR_BALLOON`** *(v1.04)* - Hot air balloon aircraft +- **`BLIMP`** *(v1.04)* - Blimp aircraft +- **`LARGE_AIRCRAFT`** *(v1.04)* - Large aircraft +- **`MEDIUM_AIRCRAFT`** *(v1.04)* - Medium aircraft +- **`SMALL_AIRCRAFT`** *(v1.04)* - Small aircraft +- **`ARTILLERY`** *(v1.04)* - Artillery units +- **`HEAVY_ARTILLERY`** *(v1.04)* - Heavy artillery units +- **`ANTI_AIR`** *(v1.04)* - Anti-air units +- **`SAM`** *(v1.04)* - Surface-to-Air Missile units +- **`SCOUT`** *(v1.04)* - Scout units +- **`COMMANDO`** *(v1.04)* - Commando units +- **`HEAVY_INFANTRY`** *(v1.04)* - Heavy infantry units +- **`SUPERHEAVY_VEHICLE`** *(v1.04)* - Super heavy vehicle units +- **`EW_RADAR`** *(v1.04)* - Electronic Warfare radar units +- **`EW_RADAR_JAMMER`** *(v1.04)* - Electronic Warfare radar jammer units +- **`EW_RADIO_JAMMER`** *(v1.04)* - Electronic Warfare radio jammer units +- **`EW_JAMMABLE`** *(v1.04)* - Electronic Warfare jammable units +- **`EW_DIRECT_JAMMABLE`** *(v1.04)* - Electronic Warfare directly jammable units +- **`EW_AREA_JAMMABLE`** *(v1.04)* - Electronic Warfare area jammable units +- **`EW_RADIO_JAMMABLE`** *(v1.04)* - Electronic Warfare radio jammable units +- **`EXTRA1`** through **`EXTRA16`** *(v1.04)* - Custom KindOf types + +## Examples + +### Scout Van Auto Heal +```ini +Behavior = AutoHealBehavior ModuleTag_01 + HealingAmount = 3 + HealingDelay = 1000 + TriggeredBy = Upgrade_GLAJunkRepair +End +``` + +### Scrap Yard Auto Heal +```ini +Behavior = AutoHealBehavior ModuleTag_02 + HealingAmount = 2 + HealingDelay = 1000 + StartsActive = No + TriggeredBy = Upgrade_GLAJunkRepair +End +``` + +### Medical Building Area Heal +```ini +Behavior = AutoHealBehavior ModuleTag_03 + HealingAmount = 5 + HealingDelay = 2000 + Radius = 100.0 + KindOf = INFANTRY VEHICLE + ForbiddenKindOf = STRUCTURE + RadiusParticleSystemName = FX_HealArea + UnitHealPulseParticleSystemName = FX_HealPulse + StartsActive = Yes +End +``` + +### Single Burst Heal +```ini +Behavior = AutoHealBehavior ModuleTag_04 + HealingAmount = 50 + SingleBurst = Yes + KindOf = INFANTRY + AffectsWholePlayer = Yes + SkipSelfForHealing = Yes +End +``` + +## Usage + +Place under `Behavior = AutoHealBehavior ModuleTag_XX` inside [Object](../Object.md) entries. See [Template](#template) for correct syntax. + +**Placement**: +- AutoHealBehavior can only be added to `Object` entries. + +Multiple instances of AutoHealBehavior can be added to the same object. Each instance operates independently with its own healing rates, conditions, and upgrade requirements. + +**Limitations**: +- Healing only works on objects within the same team/player. Objects must be owned by the same player as the healing object. +- Area healing is limited by the specified [Radius](#radius) or player ownership ([AffectsWholePlayer](#affectswholeplayer)). Objects outside the radius (or not owned by the player when `AffectsWholePlayer` is `No`) cannot be healed. +- The behavior can be configured for single burst healing ([SingleBurst](#singleburst)) or continuous healing over time. When [SingleBurst](#singleburst) is `Yes`, healing occurs once then stops. +- Objects must have a health system (typically [ActiveBody](../ObjectBody/ActiveBody.md)) to receive healing. Objects without health systems cannot be healed. +- When [HealingAmount](#healingamount) is 0, no healing occurs and the behavior is effectively disabled. +- When [HealingDelay](#healingdelay) is not specified (defaults to UINT_MAX), the behavior will not heal regularly and must be activated manually or through upgrades. + +**Conditions**: +- AutoHealBehavior can heal individual objects (when [Radius](#radius) is 0.0) or provide area healing within a specified radius (when [Radius](#radius) > 0.0). +- The behavior integrates with the upgrade system for conditional activation. When [TriggeredBy](#triggeredby) is set, healing only occurs when the specified upgrades are active (see [Upgrade Integration](#upgrade-integration) properties). +- Area healing can target specific object types using [KindOf](#kindof) and [ForbiddenKindOf](#forbiddenkindof) filters (see [Target Selection](#target-selection) properties). +- Particle effects provide visual feedback for healing operations when [RadiusParticleSystemName](#radiusparticlesystemname) or [UnitHealPulseParticleSystemName](#unithealpulseparticlesystemname) are set. +- When [StartsActive](#startsactive) is `Yes`, healing begins immediately upon object creation. When `No`, healing must be activated by upgrades. +- When [SingleBurst](#singleburst) is `Yes`, healing occurs once then the behavior goes to sleep. When `No`, healing continues at regular intervals. +- When [StartHealingDelay](#starthealingdelay) is set, the object waits for the specified delay after taking damage before auto-healing starts. This only applies when healing the object itself ([Radius](#radius) = 0). +- AutoHealBehavior continues to heal even when objects are held (stunned/immobilized) or jammed (electronically disabled). Healing is not interrupted by these disabled states. +- **Multiple instances behavior**: Multiple instances of AutoHealBehavior can coexist on the same object. Each instance operates independently with its own healing rates, conditions, upgrade requirements, and target filters. +- **ObjectReskin**: ObjectReskin uses the same module system as Object. Adding AutoHealBehavior to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires an object with a health system (typically [ActiveBody](../ObjectBody/ActiveBody.md)) to function. AutoHealBehavior works with all body types that implement `BodyModuleInterface`: [ActiveBody](../ObjectBody/ActiveBody.md), [StructureBody](../ObjectBody/StructureBody.md), [HighlanderBody](../ObjectBody/HighlanderBody.md), [ImmortalBody](../ObjectBody/ImmortalBody.md), [UndeadBody](../ObjectBody/UndeadBody.md) (both first and second life), and [HiveStructureBody](../ObjectBody/HiveStructureBody.md). AutoHealBehavior does not work with [InactiveBody](../ObjectBody/InactiveBody.md) because those objects are marked as "effectively dead" and are skipped by the healing system. +- Healing is affected by damage types and armor systems (see [Armor](../Armor.md)). Armor and damage type interactions apply to healing calculations. + +## Template + +```ini +Behavior = AutoHealBehavior ModuleTag_XX + ; Basic Healing Settings + HealingAmount = 0 ; // health points healed per pulse *(v1.04)* + HealingDelay = 4294967295 ; // milliseconds between healing pulses (must be set for healing) *(v1.04)* + StartsActive = No ; // whether healing starts active *(v1.04)* + SingleBurst = No ; // whether to perform single burst only *(v1.04)* + StartHealingDelay = 0 ; // delay after damage before healing starts *(v1.04)* + + ; Area Healing Settings + Radius = 0.0 ; // healing radius (0 = self only) *(v1.04)* + AffectsWholePlayer = No ; // affect all player objects *(v1.04)* + SkipSelfForHealing = No ; // skip self when area healing *(v1.04, Zero Hour only)* + + ; Upgrade Integration + TriggeredBy = ; // required upgrade names *(v1.04)* + RequiredAnyUpgradeOf = ; // alternative upgrade names (any required) *(v1.04)* + RequiredAllUpgradesOf = ; // upgrade names (all required) *(v1.04)* + ConflictsWith = ; // conflicting upgrade names *(v1.04)* + RemovesUpgrades = ; // upgrade names to remove on activation *(v1.04)* + RequiresAllTriggers = No ; // require all TriggeredBy upgrades *(v1.04)* + FXListUpgrade = ; // upgrade activation FXList *(v1.04)* + + ; Particle Effects + RadiusParticleSystemName = ; // area healing particle system *(v1.04)* + UnitHealPulseParticleSystemName = ; // unit healing particle system *(v1.04)* + + ; Target Selection + KindOf = ; // allowed object types *(v1.04)* + ForbiddenKindOf = ; // forbidden object types *(v1.04, Zero Hour only)* +End +``` + +## Notes + +- AutoHealBehavior can heal individual objects or provide area healing within a specified radius. The behavior supports three modes: self-healing ([Radius](#radius) = 0), radius-based area healing, and player-wide healing ([AffectsWholePlayer](#affectswholeplayer) = Yes). +- The behavior integrates with the upgrade system for conditional activation. When [TriggeredBy](#triggeredby) is set, healing only occurs when the specified upgrades are active. Upgrade conflicts ([ConflictsWith](#conflictswith)) can disable healing when conflicting upgrades are active. Additional upgrade requirements can be specified using [RequiredAnyUpgradeOf](#requiredanyupgradeof) and [RequiredAllUpgradesOf](#requiredallupgradesof). +- Area healing can target specific object types using [KindOf](#kindof) and [ForbiddenKindOf](#forbiddenkindof) filters. Objects must match [KindOf](#kindof) types and not match [ForbiddenKindOf](#forbiddenkindof) types to be healed. +- Particle effects provide visual feedback for healing operations. [RadiusParticleSystemName](#radiusparticlesystemname) displays effects for the entire area healing duration, while [UnitHealPulseParticleSystemName](#unithealpulseparticlesystemname) displays effects on each unit when it receives healing. +- The behavior can be configured for single burst healing ([SingleBurst](#singleburst)) or continuous healing over time. When [SingleBurst](#singleburst) is `Yes`, healing occurs once then stops. +- Objects with [ActiveBody](../ObjectBody/ActiveBody.md) can be healed by AutoHealBehavior. Healing is affected by damage types and armor systems (see [Armor](../Armor.md)). +- When [StartHealingDelay](#starthealingdelay) is set, the object waits for the specified delay after taking damage before auto-healing starts. This only applies when healing the object itself ([Radius](#radius) = 0). +- AutoHealBehavior continues to heal even when objects are held (stunned/immobilized) or jammed (electronically disabled). Healing is not interrupted by these disabled states. +- Multiple instances of AutoHealBehavior can coexist on the same object. Each instance operates independently with its own healing rates, conditions, upgrade requirements, and target filters. + +## Modder Recommended Use Scenarios + +(pending modder review) + +## Source Files + +**Base Class:** `UpdateModule`, `UpgradeMux`, `DamageModuleInterface` + +- Header (Retail Zero Hour 1.04): `GeneralsMD/Code/GameEngine/Include/GameLogic/Module/AutoHealBehavior.h` +- Source (Retail Zero Hour 1.04): `GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Behavior/AutoHealBehavior.cpp` +- Header (Retail Generals 1.04): `Generals/Code/GameEngine/Include/GameLogic/Module/AutoHealBehavior.h` +- Source (Retail Generals 1.04): `Generals/Code/GameEngine/Source/GameLogic/Object/Behavior/AutoHealBehavior.cpp` + +## Changes History + +- No changes done since 1.04 + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + diff --git a/Docs/INI/Object/ObjectBehaviorsModules/ParkingPlaceBehavior.md b/Docs/INI/Object/ObjectBehaviorsModules/ParkingPlaceBehavior.md new file mode 100644 index 0000000000..f502bd23c3 --- /dev/null +++ b/Docs/INI/Object/ObjectBehaviorsModules/ParkingPlaceBehavior.md @@ -0,0 +1,238 @@ +# ParkingPlaceBehavior + +Status: AI-generated, 0/2 reviews + +## Overview + +The `ParkingPlaceBehavior` module manages aircraft parking systems for aircraft carriers and airfields. It handles parking space allocation, runway management, aircraft healing, and exit coordination. The module supports configurable grid layouts with rows and columns, runway systems, and healing mechanics for parked aircraft. This creates realistic aircraft carrier and airfield operations with proper space management. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) + - [Parking Layout](#parking-layout) + - [Aircraft Handling](#aircraft-handling) + - [Runway Configuration](#runway-configuration) + - [Parking Behavior](#parking-behavior) + - [Healing System](#healing-system) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place under `Update = ParkingPlaceBehavior ModuleTag_XX` inside [Object](../Object.md) entries. ParkingPlaceBehavior can only be added to [Object](../Object.md) entries in Retail . See [Template](#template) for correct syntax. + +Multiple ParkingPlaceBehavior modules can exist independently on the same object, each managing different parking systems. Each instance operates independently with its own parking layout, runways, and healing settings. + +**Limitations**: +- Requires objects with production capabilities for proper integration. ParkingPlaceBehavior interfaces with [ProductionUpdate](../ObjectModules/ProductionUpdate.md) systems to manage door states and exit coordination. +- Limited to configured parking space counts. The total number of parking spaces is determined by [NumRows](#numrows) multiplied by [NumCols](#numcols). If more aircraft attempt to park than spaces are available, the module cannot accommodate them. +- Cannot function without proper bone structure for parking positions. The module requires specific bone names in the object's model: + - For each parking space: `Runway%dPark%dHan` (hangar start), `Runway%dParking%d` (parking location), `Runway%dPrep%d` (preparation point) where `%d` represents column and row numbers + - For runways (if [HasRunways](#hasrunways) is `Yes`): `RunwayStart%d` and `RunwayEnd%d` for each column + - For helipad functionality: `HeliPark01` bone + - If required bones are missing, parking positions may be incorrectly placed or the module may not function properly. +- Requires proper aircraft AI systems for carrier operations. Aircraft must use [JetAIUpdate](../ObjectModules/JetAIUpdate.md) for proper runway and parking coordination. +- Healing only affects parked aircraft. Aircraft must be parked in a parking space to receive healing from [HealAmountPerSecond](#healamountpersecond). + +**Conditions**: +- Objects with ParkingPlaceBehavior can be targeted by aircraft for landing and parking. The module manages parking space reservations, runway allocations, and exit coordination. +- ParkingPlaceBehavior integrates with [ProductionUpdate](../ObjectModules/ProductionUpdate.md) systems to manage door states and coordinate unit exits. Doors are automatically opened when spaces are reserved and closed when spaces are released. +- Aircraft with [JetAIUpdate](../ObjectModules/JetAIUpdate.md) coordinate with ParkingPlaceBehavior to reserve runways and parking spaces. The module provides runway reservation queuing for takeoff operations. +- Healing occurs automatically at regular intervals (every 0.2 seconds) for all parked aircraft. The healing amount per tick is calculated based on [HealAmountPerSecond](#healamountpersecond) and the time interval. +- Helipad aircraft (with `KINDOF_PRODUCED_AT_HELIPAD`) use special handling and do not require parking space reservations. They use the `HeliPark01` bone position instead. +- Runway reservations are managed per column. If [HasRunways](#hasrunways) is `Yes`, each column has its own runway that can be reserved for landing or takeoff. Aircraft queue for runway access when runways are busy. +- Parking space allocation uses a grid system based on [NumRows](#numrows) and [NumCols](#numcols). Each space is assigned to a specific runway (column) and can be reserved for parking or exit coordination. +- When the object with ParkingPlaceBehavior is destroyed, all parked aircraft are automatically killed via the DieModuleInterface. This prevents aircraft from being stranded in destroyed structures. + +**Dependencies**: +- Requires objects with production capabilities. ParkingPlaceBehavior interfaces with [ProductionUpdate](../ObjectModules/ProductionUpdate.md) to manage door states and coordinate unit exits. +- Depends on bone structure for parking position calculations. The object's model must have the required bone names as described in Limitations. +- Requires proper aircraft AI systems. Aircraft should use [JetAIUpdate](../ObjectModules/JetAIUpdate.md) for proper runway and parking coordination. +- Inherits functionality from [UpdateModule](../ModuleBase/UpdateModule.md), DieModuleInterface, and ExitInterface. + +## Properties + +### Parking Layout + +#### `NumRows` *(v1.04)* +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Int` +- **Description**: Number of rows in the parking grid layout. Higher values create more parking spaces vertically. The total number of parking spaces is determined by [NumRows](#numrows) multiplied by [NumCols](#numcols). When set to 0 (default), no parking rows are available and the module cannot function properly. Each row requires corresponding bone names in the model (`Runway%dPark%dHan`, `Runway%dParking%d`, `Runway%dPrep%d` for each column). +- **Default**: `0` +- **Example**: `NumRows = 3` + +#### `NumCols` *(v1.04)* +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Int` +- **Description**: Number of columns in the parking grid layout. Higher values create more parking spaces horizontally and determine the number of runways (if [HasRunways](#hasrunways) is enabled). The total number of parking spaces is determined by [NumRows](#numrows) multiplied by [NumCols](#numcols). When set to 0 (default), no parking columns are available and the module cannot function properly. Each column requires corresponding bone names in the model. +- **Default**: `0` +- **Example**: `NumCols = 4` + +### Aircraft Handling + +#### `ApproachHeight` *(v1.04)* +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` (distance) +- **Description**: Height at which aircraft approach the parking area from the runway end. Higher values make aircraft approach from greater heights, providing more clearance during landing approaches. Lower values make aircraft approach closer to the deck surface. When set to 0 (default), no specific approach height offset is applied beyond the runway end height. This value is added to the runway end height to calculate the final approach position. +- **Default**: `0.0` +- **Example**: `ApproachHeight = 50.0` + +#### `LandingDeckHeightOffset` *(v1.04, Zero Hour only)* +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `Real` (distance) +- **Description**: Height offset for the landing deck surface. Higher values raise the landing deck, affecting how aircraft are positioned when parked. This offset is applied to aircraft that park on the deck, setting the `OBJECT_STATUS_DECK_HEIGHT_OFFSET` status flag. When set to 0 (default), no height offset is applied and aircraft use the standard terrain height. This property is only available in Zero Hour versions. +- **Default**: `0.0` +- **Example**: `LandingDeckHeightOffset = 10.0` + +### Runway Configuration + +#### `HasRunways` *(v1.04)* +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Bool` +- **Description**: Determines if each column has a runway in front of it. When `Yes`, runways are available for each column, allowing aircraft to land and take off. Each runway requires `RunwayStart%d` and `RunwayEnd%d` bone names in the model (where `%d` is the column number). When `No` (default), no runways are available and aircraft cannot use runway-based landing or takeoff operations. Runways are used for approach coordination, landing sequences, and takeoff queuing. +- **Default**: `No` +- **Example**: `HasRunways = Yes` + +### Parking Behavior + +#### `ParkInHangars` *(v1.04)* +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Bool` +- **Description**: Determines if aircraft park at hangar production spots instead of real parking places. When `Yes`, aircraft park at the hangar start positions (`Runway%dPark%dHan` bones) instead of the designated parking locations (`Runway%dParking%d` bones). This affects both the parking position and orientation used by aircraft. When `No` (default), aircraft park in the designated parking spaces. Hangar parking is typically used for aircraft that should appear inside structures rather than on deck. +- **Default**: `No` +- **Example**: `ParkInHangars = Yes` + +### Healing System + +#### `HealAmountPerSecond` *(v1.04)* +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` (health per second) +- **Description**: Amount of health restored per second to parked aircraft. Higher values heal aircraft faster, providing quicker recovery from damage. Lower values heal more slowly, requiring more time for full healing. The healing occurs automatically at regular intervals (every 0.2 seconds) for all aircraft that are currently parked in a parking space. When set to 0 (default), no healing occurs. Healing only affects parked aircraft - aircraft must be in a reserved parking space to receive healing. +- **Default**: `0.0` +- **Example**: `HealAmountPerSecond = 10.0` + +## Examples + +### Basic Aircraft Carrier +```ini +Update = ParkingPlaceBehavior ModuleTag_01 + NumRows = 2 + NumCols = 3 + ApproachHeight = 75.0 + LandingDeckHeightOffset = 15.0 + HasRunways = Yes + ParkInHangars = No + HealAmountPerSecond = 5.0 +End +``` + +### Large Airfield +```ini +Update = ParkingPlaceBehavior ModuleTag_02 + NumRows = 4 + NumCols = 6 + ApproachHeight = 100.0 + HasRunways = Yes + ParkInHangars = No + HealAmountPerSecond = 15.0 +End +``` + +### Hangar-Based Parking +```ini +Update = ParkingPlaceBehavior ModuleTag_03 + NumRows = 1 + NumCols = 2 + ApproachHeight = 50.0 + LandingDeckHeightOffset = 5.0 + HasRunways = No + ParkInHangars = Yes + HealAmountPerSecond = 8.0 +End +``` + +## Template + +```ini +Update = ParkingPlaceBehavior ModuleTag_XX + ; Parking Layout + NumRows = 0 ; // number of parking rows *(v1.04)* + NumCols = 0 ; // number of parking columns *(v1.04)* + + ; Aircraft Handling + ApproachHeight = 0.0 ; // aircraft approach height from runway end *(v1.04)* + LandingDeckHeightOffset = 0.0 ; // landing deck height offset *(v1.04, Zero Hour only)* + + ; Runway Configuration + HasRunways = No ; // enable runways for each column *(v1.04)* + + ; Parking Behavior + ParkInHangars = No ; // park aircraft in hangars instead of parking spaces *(v1.04)* + + ; Healing System + HealAmountPerSecond = 0.0 ; // health restored per second to parked aircraft *(v1.04)* +End +``` + +## Notes + +- ParkingPlaceBehavior manages comprehensive aircraft parking systems for carriers and airfields with configurable grid layouts, runway management, and healing capabilities. +- Supports configurable grid layouts with rows and columns. The total number of parking spaces is [NumRows](#numrows) multiplied by [NumCols](#numcols). Each space requires specific bone names in the object's model. +- Includes runway management for aircraft landing and takeoff operations. Runways are allocated per column when [HasRunways](#hasrunways) is enabled, with queuing support for multiple aircraft waiting to take off. +- Provides automatic healing for parked aircraft at regular intervals (every 0.2 seconds). Healing only affects aircraft that are currently parked in a reserved parking space. +- Requires proper bone structure in the object's model. Missing bones may cause parking positions to be incorrectly placed or the module may not function properly. The module expects bones named `Runway%dPark%dHan`, `Runway%dParking%d`, `Runway%dPrep%d` for parking spaces, `RunwayStart%d` and `RunwayEnd%d` for runways, and `HeliPark01` for helipad functionality. +- ParkingPlaceBehavior integrates with [ProductionUpdate](../ObjectModules/ProductionUpdate.md) to manage door states and coordinate unit exits. Doors are automatically opened when spaces are reserved and closed when spaces are released. +- Aircraft with [JetAIUpdate](../ObjectModules/JetAIUpdate.md) coordinate with ParkingPlaceBehavior to reserve runways and parking spaces. The module provides runway reservation queuing for takeoff operations. +- Helipad aircraft (with `KINDOF_PRODUCED_AT_HELIPAD`) use special handling and do not require parking space reservations. They use the `HeliPark01` bone position and can use rally points for positioning. +- When the object with ParkingPlaceBehavior is destroyed, all parked aircraft are automatically killed. This prevents aircraft from being stranded in destroyed structures. +- Commonly used for aircraft carriers, airfields, and aviation facilities that need realistic aircraft management with proper space allocation and runway coordination. +- The module handles parking space allocation, runway reservations, exit coordination, and continuous healing operations for parked aircraft. + +## Source Files + +**Base Class:** `UpdateModule` + +- Header (Retail Zero Hour): [ParkingPlaceBehavior.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ParkingPlaceBehavior.h) +- Source (Retail Zero Hour): [ParkingPlaceBehavior.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Behavior/ParkingPlaceBehavior.cpp) +- Header (Retail Generals): [ParkingPlaceBehavior.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/ParkingPlaceBehavior.h) +- Source (Retail Generals): [ParkingPlaceBehavior.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Behavior/ParkingPlaceBehavior.cpp) + +## Changes History + +- v1.04 — Adds ParkingPlaceBehavior (aircraft parking systems with grid layouts, runways, and healing). +- v1.04 (Zero Hour only) — Adds [LandingDeckHeightOffset](#landingdeckheightoffset) for landing deck height offset support. + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + diff --git a/Docs/INI/Object/ObjectBody/ActiveBody.md b/Docs/INI/Object/ObjectBody/ActiveBody.md new file mode 100644 index 0000000000..35cd6e6600 --- /dev/null +++ b/Docs/INI/Object/ObjectBody/ActiveBody.md @@ -0,0 +1,204 @@ +# ActiveBody + +Status: AI-generated, 0/2 reviews + +## Overview + +The `ActiveBody` module manages health and damage systems for objects that can take damage, be healed, and be destroyed through combat. It handles health tracking, damage states, healing, subdual damage (Zero Hour only), and visual damage effects. Objects with ActiveBody can be damaged by weapons, healed by repair systems, and transition through different damage states that affect their appearance and functionality. This is a module added inside `Object` entries. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Properties](#properties) + - [Health Settings](#health-settings) + - [Subdual Damage Settings](#subdual-damage-settings) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Usage](#usage) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Properties + +### Health Settings + +Available in: *(v1.04)* (Generals, Zero Hour) + +#### `MaxHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum health points the object can have. Higher values make objects more durable and resistant to damage. This determines the total damage capacity before destruction. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the current health will be clamped to [MaxHealth](#maxhealth) during health operations. Health is automatically clamped to [MaxHealth](#maxhealth) as the upper limit and `0.0` as the lower limit during damage and healing operations. +- **Default**: `0.0` +- **Example**: `MaxHealth = 500.0` + +#### `InitialHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Starting health points when the object is created. Lower values spawn objects at reduced health. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` during normal operations. +- **Default**: `0.0` +- **Example**: `InitialHealth = 500.0` + +### Subdual Damage Settings + +Available only in: *(v1.04, Zero Hour only)* + +#### `SubdualDamageCap` +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `Real` +- **Description**: Maximum subdual damage that can accumulate before the object is subdued (disabled). Higher values allow objects to absorb more subdual damage before becoming incapacitated. At 0 (default), objects cannot be subdued (disabled). Subdual damage accumulates separately from normal health damage and can disable objects without destroying them. When subdual damage equals or exceeds [MaxHealth](#maxhealth), the object becomes subdued (disabled). Only subdual damage types affect this cap: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). +- **Default**: `0.0` +- **Example**: `SubdualDamageCap = 350.0` + +#### `SubdualDamageHealRate` +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time interval between subdual damage healing attempts. Lower values heal subdual damage more frequently, while higher values heal less often. At 0 (default), no automatic subdual healing occurs. Subdual damage is healed automatically by the subdual damage helper system at the specified interval. +- **Default**: `0` +- **Example**: `SubdualDamageHealRate = 500` + +#### `SubdualDamageHealAmount` +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `Real` +- **Description**: Amount of subdual damage healed per healing interval. Higher values heal more subdual damage per tick, while lower values heal less. At 0 (default), no subdual healing occurs. This amount is subtracted from the current subdual damage each time the healing interval elapses. +- **Default**: `0.0` +- **Example**: `SubdualDamageHealAmount = 50.0` + +## Enum Value Lists + +#### `BodyDamageType` Values +Available in: *(v1.04)* (Generals, Zero Hour) + +**Source:** `BodyModule.h` - `BodyDamageType` enum definition + +Damage states are calculated based on health percentage thresholds defined in [GameData](../GameData.md) (typically `UnitDamagedThreshold` = 50-70% and `UnitReallyDamagedThreshold` = 10-35%): + +- **`PRISTINE`** *(v1.04)* - Unit appears in pristine condition (health > `UnitDamagedThreshold`, typically > 50-70%) +- **`DAMAGED`** *(v1.04)* - Unit has been damaged (health between `UnitReallyDamagedThreshold` and `UnitDamagedThreshold`, typically 10-35% to 50-70%) +- **`REALLYDAMAGED`** *(v1.04)* - Unit is extremely damaged / nearly destroyed (health between 0% and `UnitReallyDamagedThreshold`, typically 0% to 10-35%) +- **`RUBBLE`** *(v1.04)* - Unit has been reduced to rubble/corpse/exploded-hulk (health = 0%) + +## Examples + +```ini +Body = ActiveBody ModuleTag_02 + MaxHealth = 200.0 + InitialHealth = 200.0 + SubdualDamageCap = 350.0 + SubdualDamageHealRate = 500 + SubdualDamageHealAmount = 50.0 +End +``` + +```ini +Body = ActiveBody ModuleTag_02 + MaxHealth = 75.0 + InitialHealth = 75.0 +End +``` + +```ini +Body = ActiveBody ModuleTag_02 + MaxHealth = 400 + InitialHealth = 400 + SubdualDamageCap = 700 + SubdualDamageHealRate = 500 + SubdualDamageHealAmount = 50 +End +``` + +```ini +Body = ActiveBody ModuleTag_02 + MaxHealth = 200 + InitialHealth = 200 + SubdualDamageCap = 350 + SubdualDamageHealRate = 500 + SubdualDamageHealAmount = 50 +End +``` + +## Usage + +Place under `Body = ActiveBody ModuleTag_XX` inside [Object](../Object.md) entries. ActiveBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: ActiveBody can only be added to `Object` entries. + +Only one body module (ActiveBody, InactiveBody, StructureBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- ActiveBody automatically manages damage states ([BodyDamageType Values](#bodydamagetype-values)) based on health percentage thresholds defined in [GameData](../GameData.md). Damage states affect visual appearance and particle systems. +- If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` or above [MaxHealth](#maxhealth). +- [SubdualDamageCap](#subdualdamagecap) can disable objects without destroying them when subdual damage equals or exceeds [MaxHealth](#maxhealth). Subdual damage properties are available only in Zero Hour. +- Objects automatically heal subdual damage over time if healing properties are set. The healing is handled by helper systems that run at the specified intervals. + +**Conditions**: +- Objects with ActiveBody can be targeted by [Weapon](../Weapon.md) attacks and affected by [DamageType](../DamageType.md). Health is reduced when weapons deal damage. +- Veterancy levels can modify maximum health and healing rates through the veterancy bonus system (see [GameData](../GameData.md) for veterancy health bonuses). +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding ActiveBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires proper [Armor](../Armor.md) and [DamageType](../DamageType.md) definitions to function correctly. ActiveBody relies on armor systems to modify incoming damage before it is applied to health. +- Objects with ActiveBody can be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). AutoHealBehavior heals main health of objects with ActiveBody. + +## Template + +```ini +Body = ActiveBody ModuleTag_XX + MaxHealth = 0.0 ; // maximum health points *(v1.04)* + InitialHealth = 0.0 ; // starting health points *(v1.04)* + + SubdualDamageCap = 0.0 ; // maximum subdual damage before subdual *(v1.04, Zero Hour only)* + SubdualDamageHealRate = 0 ; // milliseconds between subdual damage healing *(v1.04, Zero Hour only)* + SubdualDamageHealAmount = 0.0 ; // amount of subdual damage healed per interval *(v1.04, Zero Hour only)* +End +``` + +## Notes + +- Damage states ([BodyDamageType Values](#bodydamagetype-values)) are updated automatically when [MaxHealth](#maxhealth) changes. +- Subdual damage types that affect this system: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). + +## Modder Recommended Use Scenarios + +- ActiveBody is the most common body type, used by most units such as vehicles, infantry, and aircraft. It provides the standard health and damage management system that most objects in the game rely on. + +## Source Files + +**Base Class:** [BodyModule](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/BodyModule.h) (Retail Zero Hour), [BodyModule](../../Generals/Code/GameEngine/Include/GameLogic/Module/BodyModule.h) (Retail Generals) + +- Header (Retail Zero Hour): [ActiveBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) +- Source (Retail Zero Hour): [ActiveBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/ActiveBody.cpp) +- Header (Retail Generals): [ActiveBody.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) +- Source (Retail Generals): [ActiveBody.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Body/ActiveBody.cpp) + +## Changes History + +*(No changes - ActiveBody exists in Retail 1.04)* + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + diff --git a/Docs/INI/Object/ObjectBody/HighlanderBody.md b/Docs/INI/Object/ObjectBody/HighlanderBody.md new file mode 100644 index 0000000000..0676f5e075 --- /dev/null +++ b/Docs/INI/Object/ObjectBody/HighlanderBody.md @@ -0,0 +1,195 @@ +# HighlanderBody + +Status: AI-generated, 0/2 reviews + +## Overview + +The `HighlanderBody` module makes objects effectively unkillable by normal damage: their health is clamped to never drop below 1 point from resistable damage. Only unresistable damage can finish them. This is useful for special objectives or units that can only be destroyed by specific weapons. This is a module added inside `Object` entries. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Properties](#properties) + - [Health Settings](#health-settings) + - [Subdual Damage Settings](#subdual-damage-settings) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Usage](#usage) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Properties + +### Health Settings + +Available in: *(v1.04)* (Generals, Zero Hour) + +#### `MaxHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum health points the object can have. Higher values make objects more durable and resistant to damage. This determines the total damage capacity before destruction. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the current health will be clamped to [MaxHealth](#maxhealth) during health operations. Health is automatically clamped to [MaxHealth](#maxhealth) as the upper limit and `0.0` as the lower limit during damage and healing operations. +- **Default**: `0.0` +- **Example**: `MaxHealth = 500.0` + +#### `InitialHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Starting health points when the object is created. Lower values spawn objects at reduced health. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `1.0` for normal damage (or `0.0` for unresistable damage). +- **Default**: `0.0` +- **Example**: `InitialHealth = 500.0` + +### Subdual Damage Settings + +Available only in: *(v1.04, Zero Hour only)* + +#### `SubdualDamageCap` +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `Real` +- **Description**: Maximum subdual damage that can accumulate before the object is subdued (disabled). Higher values allow objects to absorb more subdual damage before becoming incapacitated. At 0 (default), objects cannot be subdued (disabled). Subdual damage accumulates separately from normal health damage and can disable objects without destroying them. When subdual damage equals or exceeds [MaxHealth](#maxhealth), the object becomes subdued (disabled). Only subdual damage types affect this cap: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). +- **Default**: `0.0` +- **Example**: `SubdualDamageCap = 350.0` + +#### `SubdualDamageHealRate` +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time interval between subdual damage healing attempts. Lower values heal subdual damage more frequently, while higher values heal less often. At 0 (default), no automatic subdual healing occurs. Subdual damage is healed automatically by the subdual damage helper system at the specified interval. +- **Default**: `0` +- **Example**: `SubdualDamageHealRate = 500` + +#### `SubdualDamageHealAmount` +Available only in: *(v1.04, Zero Hour only)* + +- **Type**: `Real` +- **Description**: Amount of subdual damage healed per healing interval. Higher values heal more subdual damage per tick, while lower values heal less. At 0 (default), no subdual healing occurs. This amount is subtracted from the current subdual damage each time the healing interval elapses. +- **Default**: `0.0` +- **Example**: `SubdualDamageHealAmount = 50.0` + +## Enum Value Lists + +#### `BodyDamageType` Values +Available in: *(v1.04)* (Generals, Zero Hour) + +**Source:** `BodyModule.h` - `BodyDamageType` enum definition + +Damage states are calculated based on health percentage thresholds defined in [GameData](../GameData.md) (typically `UnitDamagedThreshold` = 50-70% and `UnitReallyDamagedThreshold` = 10-35%): + +- **`PRISTINE`** *(v1.04)* - Unit appears in pristine condition (health > `UnitDamagedThreshold`, typically > 50-70%) +- **`DAMAGED`** *(v1.04)* - Unit has been damaged (health between `UnitReallyDamagedThreshold` and `UnitDamagedThreshold`, typically 10-35% to 50-70%) +- **`REALLYDAMAGED`** *(v1.04)* - Unit is extremely damaged / nearly destroyed (health between 0% and `UnitReallyDamagedThreshold`, typically 0% to 10-35%) +- **`RUBBLE`** *(v1.04)* - Unit has been reduced to rubble/corpse/exploded-hulk (health = 0%) + +## Examples + +```ini +Body = HighlanderBody ModuleTag_01 + MaxHealth = 1000.0 + InitialHealth = 1000.0 +End +``` + +```ini +Body = HighlanderBody ModuleTag_02 + MaxHealth = 400.0 + InitialHealth = 400.0 + SubdualDamageCap = 350.0 + SubdualDamageHealRate = 500 + SubdualDamageHealAmount = 50.0 +End +``` + +```ini +Body = HighlanderBody ModuleTag_03 + MaxHealth = 200.0 + InitialHealth = 200.0 +End +``` + +## Usage + +Place under `Body = HighlanderBody ModuleTag_XX` inside [Object](../Object.md) entries. HighlanderBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: HighlanderBody can only be added to `Object` entries. + +Only one body module (ActiveBody, InactiveBody, StructureBody, HighlanderBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- HighlanderBody automatically manages damage states ([BodyDamageType Values](#bodydamagetype-values)) based on health percentage thresholds defined in [GameData](../GameData.md). Damage states affect visual appearance and particle systems. +- HighlanderBody prevents death from normal damage types by clamping health to a minimum of 1 point. Only unresistable damage can reduce health below 1 point and cause death. +- If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `1.0` for normal damage (or `0.0` for unresistable damage). +- [SubdualDamageCap](#subdualdamagecap) can disable objects without destroying them when subdual damage equals or exceeds [MaxHealth](#maxhealth). Subdual damage properties are available only in Zero Hour. +- Objects automatically heal subdual damage over time if healing properties are set. The healing is handled by helper systems that run at the specified intervals. + +**Conditions**: +- Objects with HighlanderBody can be targeted by [Weapon](../Weapon.md) attacks and affected by [DamageType](../DamageType.md). Health is reduced when weapons deal damage, but normal damage cannot reduce health below 1 point. Only unresistable damage can kill HighlanderBody objects. +- Veterancy levels can modify maximum health and healing rates through the veterancy bonus system (see [GameData](../GameData.md) for veterancy health bonuses). +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding HighlanderBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires proper [Armor](../Armor.md) and [DamageType](../DamageType.md) definitions to function correctly. HighlanderBody relies on armor systems to modify incoming damage before it is applied to health. The unresistable damage type must be properly defined for the death mechanism to work. +- Objects with HighlanderBody can be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). AutoHealBehavior heals main health of objects with HighlanderBody. + +## Template + +```ini +Body = HighlanderBody ModuleTag_XX + MaxHealth = 0.0 ; // maximum health points *(v1.04)* + InitialHealth = 0.0 ; // starting health points *(v1.04)* + + SubdualDamageCap = 0.0 ; // maximum subdual damage before subdual *(v1.04, Zero Hour only)* + SubdualDamageHealRate = 0 ; // milliseconds between subdual healing *(v1.04, Zero Hour only)* + SubdualDamageHealAmount = 0.0 ; // subdual damage healed per interval *(v1.04, Zero Hour only)* +End +``` + +## Notes + +- Damage states ([BodyDamageType Values](#bodydamagetype-values)) are updated automatically when [MaxHealth](#maxhealth) changes. +- The name references the "Highlander" concept of near-immortality ("there can be only one"). Health is clamped to minimum 1 point for normal damage types, but unresistable damage can reduce health below 1 and cause death. +- Subdual damage types that affect this system: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). + +## Modder Recommended Use Scenarios + +- HighlanderBody is commonly used by TreeStumps objects, some laser objects, and bomb-like objects such as C4Charge. + + +## Source Files + +**Base Class:** [ActiveBody](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Zero Hour), [ActiveBody](../../Generals/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Generals) + +- Header (Retail Zero Hour): [HighlanderBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/HighlanderBody.h) +- Source (Retail Zero Hour): [HighlanderBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/HighlanderBody.cpp) +- Header (Retail Generals): [HighlanderBody.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/HighlanderBody.h) +- Source (Retail Generals): [HighlanderBody.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Body/HighlanderBody.cpp) + +## Changes History + +*(No changes - HighlanderBody exists in Retail 1.04)* + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + + diff --git a/Docs/INI/Object/ObjectBody/HiveStructureBody.md b/Docs/INI/Object/ObjectBody/HiveStructureBody.md new file mode 100644 index 0000000000..64d1f9c9e4 --- /dev/null +++ b/Docs/INI/Object/ObjectBody/HiveStructureBody.md @@ -0,0 +1,145 @@ +# HiveStructureBody + +Status: AI-generated, 0/2 reviews + +## Overview + +`HiveStructureBody` redirects specified damage types from the structure to its slave objects (created by SpawnBehavior) or to contained objects (via ContainModule) when they are present. If no slaves/contained objects exist, it can optionally absorb (swallow) certain damage types instead of taking them normally. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) + - [Damage Propagation](#damage-propagation) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place under `Body = HiveStructureBody ModuleTag_XX` inside [Object](../Object.md) entries. HiveStructureBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: HiveStructureBody can only be added to `Object` entries. + +Only one body module (ActiveBody, InactiveBody, StructureBody, ImmortalBody, HiveStructureBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- HiveStructureBody automatically manages damage states ([BodyDamageType Values](#bodydamagetype-values)) based on health percentage thresholds defined in [GameData](../GameData.md). HiveStructureBody uses the same damage state system as StructureBody and ActiveBody (see [ActiveBody documentation](ActiveBody.md#bodydamagetype-values) for complete damage state enum values). Damage states affect visual appearance and particle systems. +- If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` or above [MaxHealth](#maxhealth). +- Only redirects or swallows the damage types listed in [PropagateDamageTypesToSlavesWhenExisting](#propagatedamagetypestoslaveswhenexisting) and [SwallowDamageTypesIfSlavesNotExisting](#swallowdamagetypesifslavesnotexisting); other types behave normally. + +**Conditions**: +- Objects with HiveStructureBody can be targeted by [Weapon](../Weapon.md) attacks; [Armor](../Armor.md) applies before redirection/swallowing. +- When [SpawnBehavior](../ObjectBehaviorsModules/SpawnBehavior.md) or [ContainModule](../ObjectModules/ContainModule.md) supplies slave/contained objects, damage types listed in [PropagateDamageTypesToSlavesWhenExisting](#propagatedamagetypestoslaveswhenexisting) are redirected to the closest slave/contained object. When no slaves/contained objects exist, damage types listed in [SwallowDamageTypesIfSlavesNotExisting](#swallowdamagetypesifslavesnotexisting) are completely absorbed (no effect on the structure). Without SpawnBehavior or ContainModule, no damage redirection or swallowing occurs. +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding HiveStructureBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- [SpawnBehavior](../ObjectBehaviorsModules/SpawnBehavior.md) and/or [ContainModule](../ObjectModules/ContainModule.md) to supply slaves/contained objects. +- Valid [DamageType](../DamageType.md) names. +- Has all the same health and visual-state properties as [StructureBody](./StructureBody.md) and [ActiveBody](./ActiveBody.md). +- Objects with HiveStructureBody can be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). AutoHealBehavior heals main health of objects with HiveStructureBody. + +## Properties + +### Damage Propagation + +#### `PropagateDamageTypesToSlavesWhenExisting` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `DamageTypeFlags` (see [DamageType](../DamageType.md) documentation) +- **Description**: Redirect these damage types to the closest slave/contained object when present. Empty means no redirection. Use valid damage type names; invalid names will fail to parse. +- **Default**: `0` (none) +- **Example**: `PropagateDamageTypesToSlavesWhenExisting = EXPLOSION BALLISTIC` + +#### `SwallowDamageTypesIfSlavesNotExisting` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `DamageTypeFlags` (see [DamageType](../DamageType.md) documentation) +- **Description**: When no slaves/contained objects exist, completely absorb these damage types (no effect on the structure). Empty means damage is taken normally. Use valid damage type names; invalid names will fail to parse. +- **Default**: `0` (none) +- **Example**: `SwallowDamageTypesIfSlavesNotExisting = EXPLOSION` + +## Examples + +```ini +Body = HiveStructureBody ModuleTag_01 + MaxHealth = 2000.0 + InitialHealth = 2000.0 + + PropagateDamageTypesToSlavesWhenExisting = EXPLOSION BALLISTIC + SwallowDamageTypesIfSlavesNotExisting = EXPLOSION +End +``` + +```ini +Body = HiveStructureBody ModuleTag_Transport + MaxHealth = 1500.0 + InitialHealth = 1500.0 + + PropagateDamageTypesToSlavesWhenExisting = BALLISTIC + SwallowDamageTypesIfSlavesNotExisting = 0 +End +``` + +## Template + +```ini +Body = HiveStructureBody ModuleTag_XX + MaxHealth = 100.0 ; // maximum health *(v1.04)* + InitialHealth = 100.0 ; // starting health *(v1.04)* + + PropagateDamageTypesToSlavesWhenExisting = 0 ; // redirect these types to slaves/contained *(v1.04)* + SwallowDamageTypesIfSlavesNotExisting = 0 ; // absorb these types if no slaves/contained *(v1.04)* +End +``` + +## Notes + +- Damage states ([BodyDamageType Values](#bodydamagetype-values)) are updated automatically when [MaxHealth](#maxhealth) changes. HiveStructureBody uses the same damage state system as StructureBody and ActiveBody (see [ActiveBody documentation](ActiveBody.md#bodydamagetype-values) for complete damage state enum values). +- HiveStructureBody requires either [SpawnBehavior](../ObjectBehaviorsModules/SpawnBehavior.md) or [ContainModule](../ObjectModules/ContainModule.md) to redirect or swallow damage. Without these modules, no damage redirection or swallowing occurs. +- The closest slave/contained object to the damage source receives the redirected damage. Damage absorption (swallowing) only occurs when no slaves exist and the damage type matches the swallow criteria. +- If no slaves exist and the damage type doesn't match swallow criteria, damage is taken normally by the structure. + +## Modder Recommended Use Scenarios + +- HiveStructureBody is used by objects like StingerSite which has slaved objects. + +## Source Files + +**Base Class:** [StructureBody](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/StructureBody.h) (Retail Zero Hour), [StructureBody](../../Generals/Code/GameEngine/Include/GameLogic/Module/StructureBody.h) (Retail Generals) + +- Header (Retail Zero Hour): [HiveStructureBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/HiveStructureBody.h) +- Source (Retail Zero Hour): [HiveStructureBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/HiveStructureBody.cpp) +- Header (Retail Generals): [HiveStructureBody.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/HiveStructureBody.h) +- Source (Retail Generals): [HiveStructureBody.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Body/HiveStructureBody.cpp) + +## Changes History + +- v1.04 — Adds HiveStructureBody (damage redirection/swallowing for structures). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) diff --git a/Docs/INI/Object/ObjectBody/ImmortalBody.md b/Docs/INI/Object/ObjectBody/ImmortalBody.md new file mode 100644 index 0000000000..34dbafe5d4 --- /dev/null +++ b/Docs/INI/Object/ObjectBody/ImmortalBody.md @@ -0,0 +1,215 @@ +# ImmortalBody + +Status: AI-generated, 0/2 reviews + +## Overview + +The `ImmortalBody` module is a specialized body module that prevents objects from ever dying by ensuring their health never drops below 1 point. Unlike ActiveBody which allows objects to die when health reaches 0, ImmortalBody prevents health from falling below 1, making objects truly immortal. Objects can still take damage, show damage states, and be affected by all other body systems, but they can never be destroyed through health loss. This is a module added inside `Object` entries. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) + - [Health Settings](#health-settings) + - [Subdual Damage Settings](#subdual-damage-settings) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place under `Body = ImmortalBody ModuleTag_XX` inside [Object](../Object.md) entries. ImmortalBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: ImmortalBody can only be added to `Object` entries. + +Only one body module (ActiveBody, ImmortalBody, StructureBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- ImmortalBody automatically manages damage states ([BodyDamageType Values](#bodydamagetype-values)) based on health percentage thresholds defined in [GameData](../GameData.md). Damage states affect visual appearance and particle systems. +- Health is automatically clamped to minimum 1 point - objects can never die from any type of damage, regardless of how much damage is dealt. +- If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `1.0` or above [MaxHealth](#maxhealth). +- [SubdualDamageCap](#subdualdamagecap) can disable objects without destroying them when subdual damage equals or exceeds [MaxHealth](#maxhealth). Subdual damage properties are available only in Zero Hour. + +**Conditions**: +- Objects with ImmortalBody can be targeted by [Weapon](../Weapon.md) attacks and affected by [DamageType](../DamageType.md). Health is reduced when weapons deal damage, but cannot fall below 1 point. +- When upgrades are applied that increase maximum health, ImmortalBody ensures health never drops below 1 point, even when health changes occur during upgrade application. +- When objects gain veterancy levels (Veteran, Elite, Heroic), veterancy bonuses modify maximum health and scale health proportionally. ImmortalBody's health protection ensures objects remain at minimum 1 health even after veterancy changes. +- In single-player games, difficulty settings modify object maximum health. ImmortalBody's protection applies during these scaling operations. +- Healing behaviors and repair systems can heal ImmortalBody objects normally. ImmortalBody allows healing to work normally, but ensures health never goes below 1 point. +- Scripts can damage ImmortalBody objects, but ImmortalBody prevents script-based damage from killing objects. Scripts can also modify maximum health, and ImmortalBody's protection applies to these changes. +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding ImmortalBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires proper [Armor](../Armor.md) and [DamageType](../DamageType.md) definitions to function correctly. ImmortalBody relies on armor systems to modify incoming damage before it is applied to health. +- Has all the same properties as [ActiveBody](ActiveBody.md) while preventing health from falling below 1 point. +- Objects with ImmortalBody can be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). AutoHealBehavior heals main health of objects with ImmortalBody. Even though ImmortalBody prevents death, healing still increases health up to [MaxHealth](#maxhealth). + +## Properties + +ImmortalBody has all the same properties as [ActiveBody](ActiveBody.md) with no additional INI-parsable properties. All properties listed below function identically to ActiveBody, except that health is prevented from dropping below 1 point. + +### Health Settings + +Available in: *(v1.04)* (Generals, Zero Hour) + +#### `MaxHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum health points the object can have. Higher values make objects more durable and resistant to damage. This determines the total damage capacity before destruction. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the current health will be clamped to [MaxHealth](#maxhealth) during health operations. Health is automatically clamped to [MaxHealth](#maxhealth) as the upper limit and `1.0` as the lower limit (instead of `0.0` for ActiveBody) during damage and healing operations. +- **Default**: `0.0` +- **Example**: `MaxHealth = 500.0` + +#### `InitialHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Starting health points when the object is created. Lower values spawn objects at reduced health. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `1.0` for normal damage (or `0.0` for unresistable damage) (instead of `0.0` for ActiveBody). +- **Default**: `0.0` +- **Example**: `InitialHealth = 500.0` + +### Subdual Damage Settings + +Available in: *(v1.04)* (Zero Hour only) + +#### `SubdualDamageCap` +Available in: *(v1.04)* (Zero Hour only) + +- **Type**: `Real` +- **Description**: Maximum subdual damage that can accumulate before the object is subdued (disabled). Higher values allow objects to absorb more subdual damage before becoming incapacitated. At 0 (default), objects cannot be subdued (disabled). Subdual damage accumulates separately from normal health damage and can disable objects without destroying them. When subdual damage equals or exceeds [MaxHealth](#maxhealth), the object becomes subdued (disabled). Only subdual damage types affect this cap: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). +- **Default**: `0.0` +- **Example**: `SubdualDamageCap = 350.0` + +#### `SubdualDamageHealRate` +Available in: *(v1.04)* (Zero Hour only) + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time interval between subdual damage healing attempts. Lower values heal subdual damage more frequently, while higher values heal less often. At 0 (default), no automatic subdual healing occurs. Subdual damage is healed automatically by the subdual damage helper system at the specified interval. +- **Default**: `0` +- **Example**: `SubdualDamageHealRate = 500` + +#### `SubdualDamageHealAmount` +Available in: *(v1.04)* (Zero Hour only) + +- **Type**: `Real` +- **Description**: Amount of subdual damage healed per healing interval. Higher values heal more subdual damage per tick, while lower values heal less. At 0 (default), no subdual healing occurs. This amount is subtracted from the current subdual damage each time the healing interval elapses. +- **Default**: `0.0` +- **Example**: `SubdualDamageHealAmount = 50.0` + +## Enum Value Lists + +#### `BodyDamageType` Values +Available in: *(v1.04)* (Generals, Zero Hour) + +**Source:** [BodyModule.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/BodyModule.h#54) - `BodyDamageType` enum definition; string names from `TheBodyDamageTypeNames[]` + +**Retail 1.04 Values** *(available in v1.04)*: + +Damage states are calculated based on health percentage thresholds defined in [GameData](../GameData.md) (typically `UnitDamagedThreshold` = 50-70% and `UnitReallyDamagedThreshold` = 10-35%): + +- **`PRISTINE`** *(v1.04)* - Unit appears in pristine condition (health > `UnitDamagedThreshold`, typically > 50-70%) +- **`DAMAGED`** *(v1.04)* - Unit has been damaged (health between `UnitReallyDamagedThreshold` and `UnitDamagedThreshold`, typically 10-35% to 50-70%) +- **`REALLYDAMAGED`** *(v1.04)* - Unit is extremely damaged / nearly destroyed (health between 0% and `UnitReallyDamagedThreshold`, typically 0% to 10-35%) +- **`RUBBLE`** *(v1.04)* - Unit has been reduced to rubble/corpse/exploded-hulk (health = 0%) + +## Examples + +### Truly Immortal Hero Unit +```ini +Body = ImmortalBody ModuleTag_01 + MaxHealth = 1000.0 + InitialHealth = 1000.0 + SubdualDamageCap = 0.0 + SubdualDamageHealRate = 0 + SubdualDamageHealAmount = 0.0 +End +``` + +### Indestructible Objective Marker +```ini +Body = ImmortalBody ModuleTag_02 + MaxHealth = 500.0 + InitialHealth = 500.0 + SubdualDamageCap = 0.0 + SubdualDamageHealRate = 0 + SubdualDamageHealAmount = 0.0 +End +``` + +### Immortal Unit with Subdual Damage (Zero Hour only) +```ini +Body = ImmortalBody ModuleTag_03 + MaxHealth = 800.0 + InitialHealth = 800.0 + SubdualDamageCap = 700.0 + SubdualDamageHealRate = 500 + SubdualDamageHealAmount = 50.0 +End +``` + +## Template + +```ini +Body = ImmortalBody ModuleTag_XX + MaxHealth = 0.0 ; // maximum health points *(v1.04)* + InitialHealth = 0.0 ; // starting health points *(v1.04)* + + SubdualDamageCap = 0.0 ; // maximum subdual damage before subdual *(v1.04, Zero Hour only)* + SubdualDamageHealRate = 0 ; // milliseconds between subdual damage healing *(v1.04, Zero Hour only)* + SubdualDamageHealAmount = 0.0 ; // amount of subdual damage healed per interval *(v1.04, Zero Hour only)* +End +``` + +## Notes + +- Damage states ([BodyDamageType Values](#bodydamagetype-values)) are updated automatically when [MaxHealth](#maxhealth) changes. +- Health is automatically clamped to minimum 1 point for all damage types. Objects can take damage normally but cannot die from it, regardless of how much damage is dealt. +- All damage calculations, armor, and status effects work normally. Objects still show damage states and visual effects based on health percentage. +- Subdual damage types that affect this system: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). + +## Modder Recommended Use Scenarios + +- ImmortalBody is commonly used by neutral objects such as SupplyDock and SupplyPileSmall. + +(pending modder review) + +## Source Files + +**Base Class:** [ActiveBody](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Zero Hour), [ActiveBody](../../Generals/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Generals) + +- Header (Retail Zero Hour): [ImmortalBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ImmortalBody.h) +- Source (Retail Zero Hour): [ImmortalBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/ImmortalBody.cpp) +- Header (Retail Generals): [ImmortalBody.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/ImmortalBody.h) +- Source (Retail Generals): [ImmortalBody.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Body/ImmortalBody.cpp) + +## Changes History + +- v1.04 — Adds ImmortalBody (prevents health from dropping below 1 point, making objects truly immortal). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + diff --git a/Docs/INI/Object/ObjectBody/InactiveBody.md b/Docs/INI/Object/ObjectBody/InactiveBody.md new file mode 100644 index 0000000000..fa91b53fc0 --- /dev/null +++ b/Docs/INI/Object/ObjectBody/InactiveBody.md @@ -0,0 +1,136 @@ +# InactiveBody + +Status: AI-generated, 0/2 reviews + +## Overview + +The `InactiveBody` module provides an indestructible body system for objects that cannot be damaged or affected by normal game mechanics. Objects with InactiveBody are marked as "effectively dead" and bypass most health and damage calculations. These objects have no health system and ignore all damage and healing attempts except unresistable damage, which can trigger death modules. This behavior is commonly used for decorative objects, terrain features, and objects that should not interact with the damage system. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place under `Body = InactiveBody ModuleTag_XX` inside [Object](../Object.md) entries. InactiveBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: InactiveBody can only be added to `Object` entries. + +Only one body module (ActiveBody, InactiveBody, StructureBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- InactiveBody objects have no health system and cannot be damaged or healed through normal means. +- All damage and healing attempts are ignored except unresistable damage type. +- Objects are automatically marked as "effectively dead" on construction, which affects targeting, weapon attacks, and UI interactions. +- Cannot be used on prerequisite objects (`IsPrerequisite = Yes`); the game will crash with an assertion if attempted. +- No veterancy interactions - veterancy level changes are ignored. +- No armor interactions - armor set flags cannot be modified or tested. +- Health modifications from upgrades, veterancy, or difficulty scaling have no effect. + +**Conditions**: +- Objects with InactiveBody are automatically marked as "effectively dead" on construction, which affects weapon targeting (weapons will not attack), UI interactions (may be excluded from selection), player systems (excluded from gameplay interactions), and contain systems (status checked when processing contained objects). +- All damage attempts are ignored except unresistable damage type. When unresistable damage is applied, death modules are processed (object can be removed), but health is not modified. +- All healing attempts are ignored and have no effect. +- Script actions can remove InactiveBody objects using unresistable damage type. +- Objects can be removed via selling if death modules are present. +- Contain systems (garrisons, transports) can remove contained InactiveBody objects with unresistable damage when containers are destroyed, if death modules are present. +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding InactiveBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires the object system to function correctly. +- Compatible with death modules - unresistable damage can trigger death modules for object removal. +- Objects with InactiveBody cannot be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). InactiveBody has no health system and all healing attempts are ignored. + +## Properties + +InactiveBody has no INI-parsable properties. All health, damage, and armor functionality is disabled or bypassed. + +## Examples + +### Decorative Object +```ini +Body = InactiveBody ModuleTag_Decorative +End +``` + +### Terrain Feature +```ini +Body = InactiveBody ModuleTag_Terrain +End +``` + +### Special Indestructible Object +```ini +Body = InactiveBody ModuleTag_Indestructible +End +``` + +## Template + +```ini +Body = InactiveBody ModuleTag_XX + ; No additional properties - InactiveBody has no INI-parsable properties +End +``` + +## Notes + +- InactiveBody objects have no health system and cannot be damaged or healed through normal means. +- Objects are automatically marked as "effectively dead" on construction, which affects targeting, weapon attacks, UI interactions, player systems, and contain systems. +- All damage and healing attempts are ignored except unresistable damage type, which can trigger death modules for object removal. +- Cannot be used on prerequisite objects (`IsPrerequisite = Yes`); the game will crash with an assertion if attempted. +- No veterancy, armor, or component interactions. +- Health modifications from upgrades, veterancy, or difficulty scaling have no effect. +- Commonly used for decorative objects, terrain features, and objects that should not interact with the damage system. +- Objects can still be removed through other means (like special powers, script commands using unresistable damage, or death modules triggered by unresistable damage). +- Only one body module is allowed per object; multiple bodies cause a startup assertion. + +## Modder Recommended Use Scenarios + +- InactiveBody is used by objects that are not damageable like FireFieldSmall and MultiplayerBeacon which should not be killed. + +(pending modder review) + +## Source Files + +**Base Class:** [BodyModule](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/BodyModule.h) (Retail Zero Hour), [BodyModule](../../Generals/Code/GameEngine/Include/GameLogic/Module/BodyModule.h) (Retail Generals) + +- Header (Retail Zero Hour): [InactiveBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/InactiveBody.h) +- Source (Retail Zero Hour): [InactiveBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/InactiveBody.cpp) +- Header (Retail Generals): [InactiveBody.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/InactiveBody.h) +- Source (Retail Generals): [InactiveBody.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Body/InactiveBody.cpp) + +## Changes History + +- v1.04 — Adds InactiveBody (indestructible body system for decorative objects). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) diff --git a/Docs/INI/Object/ObjectBody/StructureBody.md b/Docs/INI/Object/ObjectBody/StructureBody.md new file mode 100644 index 0000000000..123f32628f --- /dev/null +++ b/Docs/INI/Object/ObjectBody/StructureBody.md @@ -0,0 +1,203 @@ +# StructureBody + +Status: AI-generated, 0/2 reviews + +## Overview + +The `StructureBody` module extends ActiveBody with additional functionality for structures, including constructor object tracking. It manages health, damage states, healing, subdual damage (Zero Hour only), and visual damage effects like ActiveBody, but also tracks which object built the structure. This allows structures to maintain relationships with their builders for gameplay systems like AI, player events, and script interactions. Objects with StructureBody can be damaged by weapons, healed by repair systems, and transition through different damage states that affect their appearance and functionality. This is a module added inside `Object` entries. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place under `Body = StructureBody ModuleTag_XX` inside [Object](../Object.md) entries. StructureBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: StructureBody can only be added to `Object` entries. + +Only one body module (ActiveBody, InactiveBody, StructureBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- StructureBody automatically manages damage states ([BodyDamageType Values](#bodydamagetype-values)) based on health percentage thresholds defined in [GameData](../GameData.md). Damage states affect visual appearance and particle systems. +- If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` or above [MaxHealth](#maxhealth). +- [SubdualDamageCap](#subdualdamagecap) can disable objects without destroying them when subdual damage equals or exceeds [MaxHealth](#maxhealth). Subdual damage properties are available only in Zero Hour. +- Objects automatically heal subdual damage over time if healing properties are set. The healing is handled by helper systems that run at the specified intervals. +- Constructor tracking is limited to a single constructor object ID. If the constructor object is destroyed or invalid, the constructor ID remains set but may reference an invalid object. + +**Conditions**: +- Objects with StructureBody can be targeted by [Weapon](../Weapon.md) attacks and affected by [DamageType](../DamageType.md). Health is reduced when weapons deal damage. +- Veterancy levels can modify maximum health and healing rates through the veterancy bonus system (see [GameData](../GameData.md) for veterancy health bonuses). +- **Constructor tracking**: StructureBody tracks which object built the structure. The constructor object is set automatically when structures are built via build systems. The constructor object ID can be retrieved and is used by gameplay systems for AI decisions, player events, and script interactions. If the constructor object is destroyed, the constructor ID remains set but may reference an invalid object. +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding StructureBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires proper [Armor](../Armor.md) and [DamageType](../DamageType.md) definitions to function correctly. StructureBody relies on armor systems to modify incoming damage before it is applied to health. +- Has all the same properties as [ActiveBody](ActiveBody.md). +- Objects with StructureBody can be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). AutoHealBehavior heals main health of objects with StructureBody. + +## Properties + +StructureBody has all the same properties as [ActiveBody](ActiveBody.md) with no additional INI-parsable properties. The constructor object tracking is handled internally and set automatically when structures are built. See [ActiveBody](ActiveBody.md) for complete property list. + +### Health Settings + +Available in: *(v1.04)* (Generals, Zero Hour) + +#### `MaxHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum health points the object can have. Higher values make objects more durable and resistant to damage. This determines the total damage capacity before destruction. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the current health will be clamped to [MaxHealth](#maxhealth) during health operations. Health is automatically clamped to [MaxHealth](#maxhealth) as the upper limit and `0.0` as the lower limit during damage and healing operations. +- **Default**: `0.0` +- **Example**: `MaxHealth = 500.0` + +#### `InitialHealth` +Available in: *(v1.04)* (Generals, Zero Hour) + +- **Type**: `Real` +- **Description**: Starting health points when the object is created. Lower values spawn objects at reduced health. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` during normal operations. +- **Default**: `0.0` +- **Example**: `InitialHealth = 500.0` + +### Subdual Damage Settings + +Available in: *(v1.04)* (Zero Hour) + +#### `SubdualDamageCap` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum subdual damage that can accumulate before the object is subdued (disabled). Higher values allow objects to absorb more subdual damage before becoming incapacitated. At 0 (default), objects cannot be subdued (disabled). Subdual damage accumulates separately from normal health damage and can disable objects without destroying them. When subdual damage equals or exceeds [MaxHealth](#maxhealth), the object becomes subdued (disabled). Only subdual damage types affect this cap: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). +- **Default**: `0.0` +- **Example**: `SubdualDamageCap = 350.0` + +#### `SubdualDamageHealRate` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time interval between subdual damage healing attempts. Lower values heal subdual damage more frequently, while higher values heal less often. At 0 (default), no automatic subdual healing occurs. Subdual damage is healed automatically by the subdual damage helper system at the specified interval. +- **Default**: `0` +- **Example**: `SubdualDamageHealRate = 500` + +#### `SubdualDamageHealAmount` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Amount of subdual damage healed per healing interval. Higher values heal more subdual damage per tick, while lower values heal less. At 0 (default), no subdual healing occurs. This amount is subtracted from the current subdual damage each time the healing interval elapses. +- **Default**: `0.0` +- **Example**: `SubdualDamageHealAmount = 50.0` + +## Enum Value Lists + +#### `BodyDamageType` Values +Available in: *(v1.04)* (Generals, Zero Hour) + +**Source:** [BodyModule.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/BodyModule.h#54) - `BodyDamageType` enum definition; string names from `TheBodyDamageTypeNames[]` + +**Retail 1.04 Values** *(available in Retail Generals 1.04, Retail Zero Hour 1.04)*: + +Damage states are calculated based on health percentage thresholds defined in [GameData](../GameData.md) (typically `UnitDamagedThreshold` = 50-70% and `UnitReallyDamagedThreshold` = 10-35%): + +- **`PRISTINE`** *(v1.04)* - Unit appears in pristine condition (health > `UnitDamagedThreshold`, typically > 50-70%) +- **`DAMAGED`** *(v1.04)* - Unit has been damaged (health between `UnitReallyDamagedThreshold` and `UnitDamagedThreshold`, typically 10-35% to 50-70%) +- **`REALLYDAMAGED`** *(v1.04)* - Unit is extremely damaged / nearly destroyed (health between 0% and `UnitReallyDamagedThreshold`, typically 0% to 10-35%) +- **`RUBBLE`** *(v1.04)* - Unit has been reduced to rubble/corpse/exploded-hulk (health = 0%) + +## Examples + +### Standard Structure Body +```ini +Body = StructureBody ModuleTag_Structure + MaxHealth = 500.0 + InitialHealth = 500.0 +End +``` + +### Defensive Structure with Subdual Damage +```ini +Body = StructureBody ModuleTag_Defense + MaxHealth = 1000.0 + InitialHealth = 1000.0 + SubdualDamageCap = 350.0 + SubdualDamageHealRate = 500 + SubdualDamageHealAmount = 50.0 +End +``` + +### Production Structure +```ini +Body = StructureBody ModuleTag_Production + MaxHealth = 800.0 + InitialHealth = 800.0 +End +``` + +## Template + +```ini +Body = StructureBody ModuleTag_XX + MaxHealth = 0.0 ; // maximum health points *(v1.04)* + InitialHealth = 0.0 ; // starting health points *(v1.04)* + + SubdualDamageCap = 0.0 ; // maximum subdual damage before subdual *(v1.04, Zero Hour only)* + SubdualDamageHealRate = 0 ; // milliseconds between subdual damage healing *(v1.04, Zero Hour only)* + SubdualDamageHealAmount = 0.0 ; // amount of subdual damage healed per interval *(v1.04, Zero Hour only)* +End +``` + +## Notes + +- Damage states ([BodyDamageType Values](#bodydamagetype-values)) are updated automatically when [MaxHealth](#maxhealth) changes. +- Subdual damage types that affect this system: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). + +## Modder Recommended Use Scenarios + +- StructureBody is used by most of the buildings in the game. It provides active health management and constructor tracking for structures that need to maintain relationships with their builders. + + +## Source Files + +**Base Class:** [ActiveBody](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Zero Hour), [ActiveBody](../../Generals/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Generals) + +- Header (Retail Zero Hour): [StructureBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/StructureBody.h) +- Source (Retail Zero Hour): [StructureBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/StructureBody.cpp) +- Header (Retail Generals): [StructureBody.h](../../Generals/Code/GameEngine/Include/GameLogic/Module/StructureBody.h) +- Source (Retail Generals): [StructureBody.cpp](../../Generals/Code/GameEngine/Source/GameLogic/Object/Body/StructureBody.cpp) + +## Changes History + +- v1.04 — Adds StructureBody (active body system for structures with constructor tracking). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + diff --git a/Docs/INI/Object/ObjectBody/UndeadBody.md b/Docs/INI/Object/ObjectBody/UndeadBody.md new file mode 100644 index 0000000000..409eb34414 --- /dev/null +++ b/Docs/INI/Object/ObjectBody/UndeadBody.md @@ -0,0 +1,239 @@ +# UndeadBody + +Status: AI-generated, 0/2 reviews + +## Overview + +The `UndeadBody` module extends ActiveBody with a "second life" mechanic that intercepts the first death and grants the object a second life instead of dying. When the object would normally die from health-damaging damage, it instead survives with 1 health point, then immediately transitions to its second life with new maximum health, fully healed, and a different armor set. This creates a "zombie" or "undead" effect where objects appear to die but continue fighting. The second death is permanent and cannot be prevented. UndeadBody manages health, damage states, healing, subdual damage, and visual damage effects like ActiveBody, but adds the second life transition mechanic. This is a module added inside `Object` entries. + +Available in: *(v1.04)* (Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) + - [Second Life Settings](#second-life-settings) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place under `Body = UndeadBody ModuleTag_XX` inside [Object](../Object.md) entries. UndeadBody can only be added to [Object](../Object.md) entries in Retail. See [Template](#template) for correct syntax. + +**Placement**: +- **Retail**: UndeadBody can only be added to `Object` entries. + +Only one body module (ActiveBody, InactiveBody, StructureBody, UndeadBody, etc.) can exist per object. If multiple body modules are added to the same object, the game will crash with a "Duplicate bodies" assertion error during object creation. This restriction applies regardless of `ModuleTag` names - the object can only have one body module total. + +**Limitations**: +- UndeadBody automatically manages damage states ([BodyDamageType Values](#bodydamagetype-values) such as PRISTINE, DAMAGED, REALLYDAMAGED, RUBBLE) based on health percentage thresholds defined in game data. Damage states affect visual appearance and particle systems. +- The second life mechanic only works once per object lifetime. After the first death is intercepted, the object enters its second life and cannot use the mechanic again. +- The second death is permanent and cannot be prevented. Once in second life, the object will die normally when health reaches 0. +- Unresistable damage bypasses the second life mechanic entirely and causes immediate death, even on the first life. +- Requires SlowDeathBehavior module to function properly. The game will crash with an assertion if UndeadBody is used without SlowDeathBehavior: `"Hmm, this is wrong"`. +- If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` or above [MaxHealth](#maxhealth) during first life. +- [SubdualDamageCap](#subdualdamagecap) can disable objects without destroying them when subdual damage equals or exceeds [MaxHealth](#maxhealth). Subdual damage properties are available only in Zero Hour. + +**Conditions**: +- Objects with UndeadBody can be targeted by [Weapon](../Weapon.md) attacks and affected by [DamageType](../DamageType.md). Health is reduced when weapons deal damage. +- **Second life activation**: When the object would die from health-damaging damage (excluding unresistable damage), the death is intercepted. The damage amount is clamped to leave exactly 1 health point, then the object transitions to second life. The transition occurs after damage is applied but before death modules are processed, allowing damage effects to play normally. +- **Second life transition**: When second life activates, the object transitions to its second life with new maximum health set to [SecondLifeMaxHealth](#secondlifemaxhealth) and is fully healed. The second life uses a different armor set for different damage resistance. SlowDeathBehavior module plays death animations and effects without actually killing the object. Visual effects are updated to show the second life state. The object is marked as in second life, preventing further second life activations. +- **Second life behavior**: Once in second life, the object behaves like a normal ActiveBody object. It can take damage, be healed, and die normally. The second death is permanent and cannot be prevented. +- **Unresistable damage bypass**: Unresistable damage bypasses the second life mechanic entirely. If unresistable damage would kill the object, it dies immediately regardless of whether it's on first or second life. +- Veterancy levels can modify maximum health and healing rates through the veterancy bonus system (see [GameData](../GameData.md) for veterancy health bonuses). Veterancy bonuses apply to both first and second life. +- **ObjectReskin (Retail)**: ObjectReskin uses the same module system as [Object](../Object.md). Adding UndeadBody to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires proper [Armor](../Armor.md) and [DamageType](../DamageType.md) definitions to function correctly. UndeadBody relies on armor systems to modify incoming damage before it is applied to health. Second life uses a different armor set for different damage resistance. +- Requires SlowDeathBehavior module to function properly. When second life activates, UndeadBody triggers SlowDeathBehavior to play death animations and effects without actually killing the object. +- Has all the same properties as [ActiveBody](ActiveBody.md). +- Objects with UndeadBody can be healed by [AutoHealBehavior](../ObjectBehaviorsModules/AutoHealBehavior.md). AutoHealBehavior heals main health for both first life and second life of objects with UndeadBody. When an object transitions to second life, AutoHealBehavior continues to work normally using the new [SecondLifeMaxHealth](#secondlifemaxhealth) value. + +## Properties + +UndeadBody has all the same properties as [ActiveBody](ActiveBody.md) and adds one additional property for second life configuration. + +### Health Settings + +Available in: *(v1.04)* (Zero Hour) + +#### `MaxHealth` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum health points the object can have during its first life. Higher values make objects more durable and resistant to damage. This determines the total damage capacity before second life activation. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the current health will be clamped to [MaxHealth](#maxhealth) during health operations. Health is automatically clamped to [MaxHealth](#maxhealth) as the upper limit and `0.0` as the lower limit during damage and healing operations in first life. When second life activates, maximum health changes to [SecondLifeMaxHealth](#secondlifemaxhealth). +- **Default**: `0.0` +- **Example**: `MaxHealth = 500.0` + +#### `InitialHealth` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Starting health points when the object is created. Lower values spawn objects at reduced health. If [InitialHealth](#initialhealth) exceeds [MaxHealth](#maxhealth), the health will be clamped to [MaxHealth](#maxhealth) during health operations. Health cannot go below `0.0` during first life. When second life activates, the object is fully healed to [SecondLifeMaxHealth](#secondlifemaxhealth). +- **Default**: `0.0` +- **Example**: `InitialHealth = 500.0` + +### Subdual Damage Settings + +Available in: *(v1.04)* (Zero Hour) + +#### `SubdualDamageCap` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum subdual damage that can accumulate before the object is subdued (disabled). Higher values allow objects to absorb more subdual damage before becoming incapacitated. At 0 (default), objects cannot be subdued (disabled). Subdual damage accumulates separately from normal health damage and can disable objects without destroying them. When subdual damage equals or exceeds [MaxHealth](#maxhealth), the object becomes subdued (disabled). Only subdual damage types affect this cap: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). Subdual damage does not trigger second life activation. +- **Default**: `0.0` +- **Example**: `SubdualDamageCap = 350.0` + +#### `SubdualDamageHealRate` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time interval between subdual damage healing attempts. Lower values heal subdual damage more frequently, while higher values heal less often. At 0 (default), no automatic subdual healing occurs. Subdual damage is healed automatically by the subdual damage helper system at the specified interval. +- **Default**: `0` +- **Example**: `SubdualDamageHealRate = 500` + +#### `SubdualDamageHealAmount` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Amount of subdual damage healed per healing interval. Higher values heal more subdual damage per tick, while lower values heal less. At 0 (default), no subdual healing occurs. This amount is subtracted from the current subdual damage each time the healing interval elapses. +- **Default**: `0.0` +- **Example**: `SubdualDamageHealAmount = 50.0` + +### Second Life Settings + +Available in: *(v1.04)* (Zero Hour) + +#### `SecondLifeMaxHealth` +Available in: *(v1.04)* (Zero Hour) + +- **Type**: `Real` +- **Description**: Maximum health points for the object's second life. When the object "dies" the first time, it transitions to this new maximum health and is fully healed. Higher values make the second life more durable and resistant to damage. Lower values make the second life fragile. When set to 1 (default), the second life is very fragile and can be killed with minimal damage. The second life uses a different armor set for different damage resistance than the first life. +- **Default**: `1.0` +- **Example**: `SecondLifeMaxHealth = 50.0` + +## Enum Value Lists + +#### `BodyDamageType` Values +Available in: *(v1.04)* (Zero Hour) + +**Source:** BodyModule.h - `BodyDamageType` enum definition; string names from `TheBodyDamageTypeNames[]` + +**Retail 1.04 Values** *(available in v1.04)*: + +Damage states are calculated based on health percentage thresholds defined in [GameData](../GameData.md) (typically `UnitDamagedThreshold` = 50-70% and `UnitReallyDamagedThreshold` = 10-35%): + +- **`PRISTINE`** *(v1.04)* - Unit appears in pristine condition (health > `UnitDamagedThreshold`, typically > 50-70%) +- **`DAMAGED`** *(v1.04)* - Unit has been damaged (health between `UnitReallyDamagedThreshold` and `UnitDamagedThreshold`, typically 10-35% to 50-70%) +- **`REALLYDAMAGED`** *(v1.04)* - Unit is extremely damaged / nearly destroyed (health between 0% and `UnitReallyDamagedThreshold`, typically 0% to 10-35%) +- **`RUBBLE`** *(v1.04)* - Unit has been reduced to rubble/corpse/exploded-hulk (health = 0%) + +## Examples + +### Zombie Infantry Unit +```ini +Body = UndeadBody ModuleTag_01 + MaxHealth = 100.0 + InitialHealth = 100.0 + SecondLifeMaxHealth = 50.0 + SubdualDamageCap = 0.0 + SubdualDamageHealRate = 0 + SubdualDamageHealAmount = 0.0 +End + +Behavior = SlowDeathBehavior ModuleTag_02 + DeathTypes = NORMAL + MinDamage = 0.0 + MaxDamage = 1000.0 + Probability = 100 +End +``` + +### Undead Vehicle +```ini +Body = UndeadBody ModuleTag_03 + MaxHealth = 500.0 + InitialHealth = 500.0 + SecondLifeMaxHealth = 200.0 + SubdualDamageCap = 0.0 + SubdualDamageHealRate = 0 + SubdualDamageHealAmount = 0.0 +End + +Behavior = SlowDeathBehavior ModuleTag_04 + DeathTypes = NORMAL + MinDamage = 0.0 + MaxDamage = 1000.0 + Probability = 100 +End +``` + +## Template + +```ini +Body = UndeadBody ModuleTag_XX + MaxHealth = 0.0 ; // maximum health points (first life) *(v1.04)* + InitialHealth = 0.0 ; // starting health points (first life) *(v1.04)* + + SubdualDamageCap = 0.0 ; // maximum subdual damage before subdual *(v1.04)* + SubdualDamageHealRate = 0 ; // milliseconds between subdual damage healing *(v1.04)* + SubdualDamageHealAmount = 0.0 ; // amount of subdual damage healed per interval *(v1.04)* + + ; Second Life Settings + SecondLifeMaxHealth = 1.0 ; // maximum health for second life (fully healed on transition) *(v1.04)* +End +``` + +## Notes + +- Damage states ([BodyDamageType Values](#bodydamagetype-values)) are updated automatically when [MaxHealth](#maxhealth) changes. +- UndeadBody provides a "second life" mechanic where objects survive their first death. When the object would die, it instead transitions to second life with new maximum health, fully healed, and a different armor set for different damage resistance. +- Requires SlowDeathBehavior module to properly trigger the second life transition. The game will crash with an assertion if UndeadBody is used without SlowDeathBehavior. +- Unresistable damage bypasses the second life mechanic entirely and causes immediate death, even on the first life. +- Second death is permanent and cannot be prevented. Once in second life, the object behaves like a normal ActiveBody object and will die normally when health reaches 0. +- Subdual damage types that affect this system: `SUBDUAL_MISSILE`, `SUBDUAL_VEHICLE`, `SUBDUAL_BUILDING`, and `SUBDUAL_UNRESISTABLE` (see [DamageType documentation](../DamageType.md)). + +## Modder Recommended Use Scenarios + +- UndeadBody is used by objects such as Battle Bus. + +(pending modder review) + +## Source Files + +**Base Class:** [ActiveBody](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/ActiveBody.h) (Retail Zero Hour) + +- Header (Retail Zero Hour): [UndeadBody.h](../../GeneralsMD/Code/GameEngine/Include/GameLogic/Module/UndeadBody.h) +- Source (Retail Zero Hour): [UndeadBody.cpp](../../GeneralsMD/Code/GameEngine/Source/GameLogic/Object/Body/UndeadBody.cpp) + +## Changes History + +- Retail Zero Hour 1.04 — Adds UndeadBody (second life mechanic that intercepts first death). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + diff --git a/Docs/INI/Object/ObjectUpgrades/MaxHealthUpgrade.md b/Docs/INI/Object/ObjectUpgrades/MaxHealthUpgrade.md new file mode 100644 index 0000000000..81aca79563 --- /dev/null +++ b/Docs/INI/Object/ObjectUpgrades/MaxHealthUpgrade.md @@ -0,0 +1,234 @@ +# MaxHealthUpgrade + +Status: AI-generated, 0/2 reviews + +## Overview + +The `MaxHealthUpgrade` upgrade module increases an object's maximum health when specific upgrades are applied. This upgrade allows objects to gain enhanced durability and survivability by adding a specified amount to their maximum health. The behavior supports different health change types to control how the current health is affected when the maximum health is increased. + +Available in: *(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Properties](#properties) + - [Health Modification Settings](#health-modification-settings) + - [Upgrade Integration Settings](#upgrade-integration-settings) +- [Enum Value Lists](#enum-value-lists) + - [MaxHealthChangeType Values](#maxhealthchangetype-values) +- [Examples](#examples) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Status](#status) + - [Reviewers](#reviewers) + +## Properties + +### Health Modification Settings + +#### `AddMaxHealth` + +Available in: *(v1.04)* + +- **Type**: `Real` +- **Description**: The amount of maximum health to add to the object. Positive values increase maximum health, providing enhanced durability. The value is always treated as an absolute amount and is added directly to maximum health. The health increase is applied when the upgrade is activated and remains until the upgrade is removed. +- **Default**: `0.0` +- **Example**: `AddMaxHealth = 100.0` + +#### `ChangeType` + +Available in: *(v1.04)* + +- **Type**: `MaxHealthChangeType` (see [MaxHealthChangeType Values](#maxhealthchangetype-values) section) +- **Description**: Controls how the current health is affected when maximum health is increased. Different types provide different behaviors for health management: `SAME_CURRENTHEALTH` keeps current health unchanged, `PRESERVE_RATIO` maintains the same health percentage, `ADD_CURRENT_HEALTH_TOO` adds the same amount to current health as maximum health, and `FULLY_HEAL` fully heals the object. This property works in conjunction with [AddMaxHealth](#addmaxhealth) to determine the final health state after the upgrade is applied. +- **Default**: `SAME_CURRENTHEALTH` +- **Example**: `ChangeType = PRESERVE_RATIO` +- **Available Values**: see [MaxHealthChangeType Values](#maxhealthchangetype-values) + +### Upgrade Integration Settings + +#### `TriggeredBy` + +Available in: *(v1.04)* + +- **Type**: List of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: List of upgrade names that must be active for this upgrade module to activate. When any of the listed upgrades (or all, if [RequiresAllTriggers](#requiresalltriggers) is `Yes`) become active, this upgrade module will activate and increase the object's maximum health. The upgrade names must reference valid `Upgrade` entries defined in the game. Multiple upgrade names can be specified by listing them multiple times or using a space-separated list, depending on the parser implementation. +- **Default**: Empty (no trigger required) +- **Example**: `TriggeredBy = Upgrade_HealthTraining` + +#### `ConflictsWith` + +Available in: *(v1.04)* + +- **Type**: List of upgrade names (see [Upgrade documentation](../Upgrade.md)) +- **Description**: List of upgrade names that conflict with this upgrade module. If any of the conflicting upgrades are active, this upgrade module will not activate, even if [TriggeredBy](#triggeredby) conditions are met. This allows modders to create mutually exclusive upgrade paths. The upgrade names must reference valid `Upgrade` entries. Multiple conflicting upgrades can be specified. +- **Default**: Empty (no conflicts) +- **Example**: `ConflictsWith = Upgrade_BasicTraining` + +#### `RequiresAllTriggers` + +Available in: *(v1.04)* + +- **Type**: `Bool` +- **Description**: Controls whether all [TriggeredBy](#triggeredby) upgrades must be active, or if any one is sufficient. When `Yes`, all listed `TriggeredBy` upgrades must be active for this upgrade module to activate. When `No`, any one of the `TriggeredBy` upgrades being active is sufficient. This provides fine-grained control over upgrade activation conditions. +- **Default**: `No` +- **Example**: `RequiresAllTriggers = Yes` + +#### `FXListUpgrade` + +Available in: *(v1.04)* + +- **Type**: `FXList` (see [FXList documentation](../FXList.md)) +- **Description**: FXList to play when this upgrade module activates. The FXList is played once when the upgrade is applied, providing visual and audio feedback for the upgrade activation. The FXList must reference a valid `FXList` entry defined in the game. If not specified, no effects are played when the upgrade activates. +- **Default**: `NULL` (no effects) +- **Example**: `FXListUpgrade = FX_HealthUpgradeActivation` + +## Enum Value Lists + + +#### `MaxHealthChangeType` Values + +Available in: *(v1.04)* + +- **Source**: Header file - `TheMaxHealthChangeTypeNames[]` array definition + +- **`SAME_CURRENTHEALTH`** *(v1.04)* — Keeps current health unchanged when maximum health is increased. If the object has 80 health out of 100 maximum, and maximum health is increased by 50, the object will have 80 health out of 150 maximum. +- **`PRESERVE_RATIO`** *(v1.04)* — Maintains the same health percentage when maximum health is increased. If the object has 80 health out of 100 maximum (80% health), and maximum health is increased by 50, the object will have 120 health out of 150 maximum (maintaining 80%). +- **`ADD_CURRENT_HEALTH_TOO`** *(v1.04)* — Adds the same amount to current health as is added to maximum health. If maximum health is increased by 50, current health is also increased by 50 (unless it would exceed the new maximum, in which case it is clamped to maximum). +- **`FULLY_HEAL`** *(v1.04)* — Fully heals the object when maximum health is increased. Regardless of current health, the object's health is set to the new maximum health value. + +## Examples + +### Basic Health Increase + +```ini +Upgrade = MaxHealthUpgrade ModuleTag_HealthBoost + AddMaxHealth = 100.0 + ChangeType = SAME_CURRENTHEALTH + TriggeredBy = Upgrade_HealthTraining +End +``` + +### Health Increase with Ratio Preservation + +```ini +Upgrade = MaxHealthUpgrade ModuleTag_HealthUpgrade + AddMaxHealth = 50.0 + ChangeType = PRESERVE_RATIO + TriggeredBy = Upgrade_AdvancedTraining +End +``` + +### Health Increase with Current Health Boost + +```ini +Upgrade = MaxHealthUpgrade ModuleTag_HealthBoost + AddMaxHealth = 75.0 + ChangeType = ADD_CURRENT_HEALTH_TOO + TriggeredBy = Upgrade_MedicalTraining +End +``` + +### Full Heal with Health Increase + +```ini +Upgrade = MaxHealthUpgrade ModuleTag_HealthRestore + AddMaxHealth = 200.0 + ChangeType = FULLY_HEAL + TriggeredBy = Upgrade_EmergencyHealing +End +``` + +### Conditional Upgrade with Conflicts + +```ini +Upgrade = MaxHealthUpgrade ModuleTag_ConditionalHealth + AddMaxHealth = 150.0 + ChangeType = ADD_CURRENT_HEALTH_TOO + TriggeredBy = Upgrade_EliteTraining + ConflictsWith = Upgrade_BasicTraining + RequiresAllTriggers = Yes +End +``` + +## Usage + +Place under `Upgrade = MaxHealthUpgrade ModuleTag_XX` inside [Object](../Object.md) entries. See [Template](#template) for correct syntax. + +**Placement**: +- `MaxHealthUpgrade` can only be added to [Object](../Object.md) entries. + +**Limitations**: +- Objects must have a body module (such as [ActiveBody](../ObjectBody/ActiveBody.md)) to function properly. If no body module exists, the upgrade will not affect health. +- Health increases are additive, not multiplicative. Multiple `MaxHealthUpgrade` instances will each add their [AddMaxHealth](#addmaxhealth) value to the maximum health. +- The health increase is permanent until the upgrade is removed. Removing the triggering upgrade will not automatically revert the health increase unless the upgrade system is configured to handle removal. + +- **Conditions**: +- `MaxHealthUpgrade` increases the object's maximum health when the specified upgrade in [TriggeredBy](#triggeredby) is applied. +- The upgrade integrates with the upgrade system for conditional activation based on [TriggeredBy](#triggeredby), [ConflictsWith](#conflictswith), and other upgrade conditions. +- Different health change types control how current health is affected when maximum health is increased. The [ChangeType](#changetype) property determines whether current health remains unchanged, maintains ratio, is boosted, or is fully healed. +- The upgrade works with objects that have body modules (such as [ActiveBody](../ObjectBody/ActiveBody.md)). +- **Multiple instances behavior**: Multiple instances can coexist; each operates independently with its own health increases and conditions. Each instance will add its [AddMaxHealth](#addmaxhealth) value when its [TriggeredBy](#triggeredby) conditions are met. +- **ObjectReskin**: [ObjectReskin](../ObjectReskin.md) uses the same module system as [Object](../Object.md). Adding `MaxHealthUpgrade` to an ObjectReskin entry with the same `ModuleTag` name as the base object will cause a duplicate module tag error, as ObjectReskin does not support automatic module replacement. + +**Dependencies**: +- Requires an object with a body module (such as [ActiveBody](../ObjectBody/ActiveBody.md)) to function properly. The upgrade calls `BodyModuleInterface::setMaxHealth()` to modify health, so without a body module, the upgrade has no effect. +- Requires the upgrade system to be properly configured. The [TriggeredBy](#triggeredby) property must reference valid [Upgrade](../Upgrade.md) entries defined in the game. If the referenced upgrades do not exist, the upgrade module will not activate. + +## Template + +```ini +Upgrade = MaxHealthUpgrade ModuleTag_XX + ; Health Modification Settings + AddMaxHealth = 0.0 ; // amount of maximum health to add *(v1.04)* + ChangeType = SAME_CURRENTHEALTH ; // how current health is affected *(v1.04)* + + ; Upgrade Integration Settings + TriggeredBy = ; // required upgrade flags *(v1.04)* + ConflictsWith = ; // conflicting upgrade flags *(v1.04)* + RequiresAllTriggers = No ; // require all TriggeredBy upgrades *(v1.04)* + FXListUpgrade = ; // effects to play when activated *(v1.04)* +End +``` + +## Notes + +- `MaxHealthUpgrade` increases the object's maximum health when the specified upgrade is applied, providing enhanced durability and survivability. +- The upgrade integrates with the upgrade system for conditional activation, allowing complex upgrade trees and dependencies. +- Different health change types (`ChangeType`) control how current health is affected, providing flexibility in health management strategies. +- Health increases are additive: if multiple `MaxHealthUpgrade` instances are active, each adds its `AddMaxHealth` value to the maximum health. +- The upgrade works with objects that have body modules (such as ActiveBody). Objects without body modules will not be affected. +- The health increase is permanent until the upgrade is removed. Removing the triggering upgrade does not automatically revert the health increase unless the upgrade system handles removal explicitly. + +## Modder Recommended Use Scenarios + +(pending modder review) + +## Source Files + +**Base Class:** UpgradeModule + +- Header: MaxHealthUpgrade.h +- Source: MaxHealthUpgrade.cpp + +## Changes History + +- 03/01/2025 — AI — Reconstructs documentation following DocAuthoringGuide with complete property documentation, versioning, enum lists, and examples + +## Status + +- **Documentation Status**: AI-generated +- **Last Updated**: 03/01/2025 by @AI +- **Certification**: 0/2 reviews + +### Reviewers + +- No reviews yet + diff --git a/Docs/INI/Object/Prerequisites/ProductionPrerequisite.md b/Docs/INI/Object/Prerequisites/ProductionPrerequisite.md new file mode 100644 index 0000000000..a314426ab4 --- /dev/null +++ b/Docs/INI/Object/Prerequisites/ProductionPrerequisite.md @@ -0,0 +1,105 @@ +# ProductionPrerequisite + +Status: AI-generated, 0/2 reviews + +## Overview + +The `ProductionPrerequisite` block defines checks used by production/build systems to decide whether a player may produce a unit/structure. It supports unit presence/absence, sciences via simple key lines. Used as a child block inside features that validate production availability. + +Available in: +*(v1.04)* (Generals, Zero Hour) + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) + - [Limitations](#limitations) + - [Conditions](#conditions) + - [Dependencies](#dependencies) +- [Properties](#properties) +- [Examples](#examples) +- [Template](#template) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +Place as a child block under systems that decide whether production is allowed (e.g., factories/build menus). Lines inside the block are evaluated according to their semantics (presence/absence requirements, OR grouping for repeated unit entries as supported by the parser). + +**Limitations**: +- Requires a valid owning player context. + +**Conditions**: +- Multiple unit lines may form OR groups across sequential entries. + +**Dependencies**: +- References must match actual entity names: units/objects use [Object](../Object.md); upgrades use [Upgrade](../Upgrade.md); sciences use [Science](../Science.md). + +## Properties + +- `Object` + - Type: Object name or list of object names (see [Object](../Object.md)) + - Description: Player must own the listed object(s). Multiple names on the same line are OR; repeating this line creates additional checks combined by AND. If an object name is misspelled or doesn't exist, the game can behave unpredictably — always use exact object names. + - Default: none + - Example: `Object = AmericaWarFactory Barracks` + +- `Science` + - Type: Science name or list of science names (see [Science documentation](../Science.md)) + - Description: Player must own all listed sciences (AND within the same line). If a science name is wrong or doesn't exist, the game will stop at load with an error — use exact science names. + - Default: none + - Example: `Science = SCIENCE_TechLevel2` + + +## Examples + +```ini +ProductionPrerequisite ; block name varies by parent; under objects use 'Prerequisite' (follows parent property name) + Object = WarFactory Barracks + Science = SCIENCE_TechLevel2 +End +``` + +```ini +Prerequisite ; block name varies by parent; under objects use 'Prerequisite' (follows parent property name) + Science = ChinaNuclearMissile +End +``` + +## Template + +```ini +ProductionPrerequisite ; block name varies by parent; under objects use 'Prerequisite' (follows parent property name) + Object = ObjectName ; player must own (OR within line; AND across lines) + Science = ScienceName ; player must own all listed sciences +End +``` + +## Notes + +- Where lines repeat, groups may be evaluated with OR semantics across sequential entries. +- Use exact names as defined in their respective docs. + + +## Source Files + +- Header: [Code/GameEngine/Include/Common/ProductionPrerequisite.h](../../Code/GameEngine/Include/Common/ProductionPrerequisite.h) +- Source: [Code/GameEngine/Source/Common/RTS/ProductionPrerequisite.cpp](../../Code/GameEngine/Source/Common/RTS/ProductionPrerequisite.cpp) + +## Changes History + +- 2003 — Retail 1.04 — ProductionPrerequisite used for production gating. + +## Status + +- Documentation Status: AI-generated +- Last Updated: 15/01/2025 by AI +- Certification: 0/2 reviews + +### Reviewers + +- (pending) + + diff --git a/Docs/INI/Weapon/Enum/DamageType.md b/Docs/INI/Weapon/Enum/DamageType.md new file mode 100644 index 0000000000..0103546f4d --- /dev/null +++ b/Docs/INI/Weapon/Enum/DamageType.md @@ -0,0 +1,176 @@ +# DamageType + +Status: AI-generated, 0/2 reviews + +## Overview + +`DamageType` is an enum that defines the different types of damage that can be dealt to objects in the game. Damage types are used to determine how damage interacts with armor, what visual and audio effects are played, and what special behaviors are triggered. Different damage types can have different effectiveness against different armor types, and some damage types have special mechanics (e.g., surrender damage, status damage). + +Damage types are used throughout the game for: +- **Weapon damage**: Weapons specify their damage type to determine how they interact with targets +- **Armor resistance**: Armor types can have different resistances to different damage types +- **Visual effects**: Different damage types trigger different visual and audio effects +- **Special mechanics**: Some damage types have special behaviors (e.g., surrender damage causes units to surrender, status damage applies status conditions) + +**For modders**: In INI files, you specify the damage type for weapons using the `DamageType` property. Damage types interact with armor types defined in [Armor](../Armor.md) templates to determine final damage amounts. Some damage types have special mechanics that affect how they interact with objects. + +Available in: *(v1.04)* + +## Table of Contents + +- [Overview](#overview) +- [Usage](#usage) +- [Enum Value Lists](#enum-value-lists) + - [Standard Damage Types](#standard-damage-types) +- [Examples](#examples) +- [Notes](#notes) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Usage + +**Limitations**: +- Damage types are assigned to weapons in the [Weapon](../Weapon.md) template using the `DamageType` property. +- Damage types interact with armor types to determine final damage amounts through damage multipliers. +- Some damage types have special mechanics that bypass normal health damage (e.g., status damage). +- Damage types are used by visual effect systems to determine which effects to play when damage is dealt. + +**Conditions**: +- Damage types are specified in weapon templates to define how weapons deal damage. +- Armor templates define resistance multipliers for each damage type. +- Some damage types have special behaviors that trigger when they are dealt (e.g., `DAMAGE_SURRENDER` causes units to surrender instead of die). +- Damage types can be combined in damage type flags for systems that need to check for multiple damage types. + +**Dependencies**: +- Damage types are used by [Weapon](../Weapon.md) templates to define weapon damage characteristics. +- Damage types interact with [Armor](../Armor.md) templates to determine damage multipliers. +- Some damage types require specific body modules or behaviors to function (e.g., surrender damage requires units with the `CAN_SURRENDER` KindOf flag). + +## Enum Value Lists + +### DamageType Values + +Available in: *(v1.04)* + +### Standard Damage Types + +- **`DAMAGE_EXPLOSION`** *(v1.04)* - Explosive damage. Standard explosive damage type used by most explosive weapons like grenades, rockets, and bombs. Used for weapons that deal damage through explosive force. Typically effective against structures and vehicles. **Reduces health points**. + +- **`DAMAGE_CRUSH`** *(v1.04)* - Crush damage. Damage type used when objects are crushed by heavier units or objects. Used for vehicles running over lighter units or objects. Typically very effective against infantry and light vehicles. **Reduces health points**. + +- **`DAMAGE_ARMOR_PIERCING`** *(v1.04)* - Armor-piercing damage. Damage type designed to penetrate armor. Used by anti-tank weapons and armor-piercing rounds. Typically very effective against heavily armored targets. **Reduces health points**. + +- **`DAMAGE_SMALL_ARMS`** *(v1.04)* - Small arms damage. Damage type used by small firearms like pistols and rifles. Used for infantry weapons and light firearms. Typically effective against infantry and light targets. **Reduces health points**. + +- **`DAMAGE_GATTLING`** *(v1.04)* - Gatling gun damage. Damage type used by rapid-fire weapons like gatling guns and miniguns. Used for high-rate-of-fire weapons. Typically effective against infantry and light vehicles. **Reduces health points**. + +- **`DAMAGE_RADIATION`** *(v1.04)* - Radiation damage. Damage type used by radiation-based weapons. Used for weapons that deal damage through radiation exposure. May have special effects on certain unit types. **Reduces health points**. + +- **`DAMAGE_FLAME`** *(v1.04)* - Flame damage. Damage type used by flamethrowers and fire-based weapons. Used for weapons that deal damage through fire. Can set objects on fire and cause burning effects. **Reduces health points**. + +- **`DAMAGE_LASER`** *(v1.04)* - Laser damage. Damage type used by laser weapons. Used for precision energy weapons. Typically very accurate and effective against various targets. **Reduces health points**. + +- **`DAMAGE_SNIPER`** *(v1.04)* - Sniper damage. Damage type used by sniper rifles. Used for long-range precision weapons. Typically very effective against infantry and can kill pilots in vehicles. **Reduces health points**. + +- **`DAMAGE_POISON`** *(v1.04)* - Poison damage. Damage type used by poison-based weapons. Used for weapons that deal damage through toxic effects. May have special effects on biological targets. **Reduces health points**. + +- **`DAMAGE_HEALING`** *(v1.04)* - Healing damage (negative damage). Special damage type that heals instead of damages. Used by healing systems to restore health. Negative damage values heal the target. **Reduces health points**. + +- **`DAMAGE_UNRESISTABLE`** *(v1.04)* - Unresistable damage. Damage type that bypasses all armor resistances. Used for scripting to cause 'armorproof' damage. This damage type ignores all armor multipliers and deals full damage. **Reduces health points**. + +- **`DAMAGE_WATER`** *(v1.04)* - Water damage. Damage type used by water-based attacks. Used for weapons that deal damage through water or flooding. May have special effects on certain unit types. **Reduces health points**. + +- **`DAMAGE_DEPLOY`** *(v1.04)* - Deploy damage. Special damage type for transports to deploy units and order them to all attack. Used by transport systems to deploy passengers. Does not deal actual damage but triggers deployment behavior. **Reduces health points**. + +- **`DAMAGE_SURRENDER`** *(v1.04)* - Surrender damage. If something "dies" to surrender damage, they surrender instead of being destroyed. Used by surrender systems to force units to surrender. Units with the `CAN_SURRENDER` KindOf flag will surrender instead of die when killed by this damage type. **Reduces health points**. + +- **`DAMAGE_HACK`** *(v1.04)* - Hack damage. Damage type used by hacking attacks. Used for weapons that hack or disable electronic systems. May have special effects on electronic targets. **Reduces health points**. + +- **`DAMAGE_KILLPILOT`** *(v1.04)* - Kill pilot damage. Special snipe attack that kills the pilot and renders a vehicle unmanned. Used by sniper weapons to kill vehicle pilots. Vehicles affected by this damage type become unmanned and can be hijacked. **Does not reduce health points**. + +- **`DAMAGE_PENALTY`** *(v1.04)* - Penalty damage. Damage from game penalty (you won't receive radar warnings BTW). Used by penalty systems to deal damage as a penalty. Does not trigger radar warnings. **Reduces health points**. + +- **`DAMAGE_FALLING`** *(v1.04)* - Falling damage. Damage type used when objects fall from heights. Used by physics systems when objects take fall damage. Typically results in `DEATH_SPLATTED` death type. **Reduces health points**. + +- **`DAMAGE_MELEE`** *(v1.04)* - Melee damage. Blades, clubs, and other melee weapons. Used for close-combat weapons. Typically effective against infantry. **Reduces health points**. + +- **`DAMAGE_DISARM`** *(v1.04)* - Disarm damage. "Special" damage type used for disarming mines, bombs, etc. (NOT for "disarming" an opponent!). Used by mine clearing systems to disarm explosive devices. Does not deal health damage but disarms explosive objects. **Reduces health points**. + +- **`DAMAGE_HAZARD_CLEANUP`** *(v1.04)* - Hazard cleanup damage. Special damage type for cleaning up hazards like radiation or bio-poison. Used by cleanup systems to remove environmental hazards. Does not deal health damage but removes hazard effects. **Reduces health points**. + +- **`DAMAGE_PARTICLE_BEAM`** *(v1.04)* - Particle beam damage. Incinerates virtually everything (insanely powerful orbital beam). Used by superweapon systems. Extremely powerful damage type that can destroy almost anything. **Reduces health points**. + +- **`DAMAGE_TOPPLING`** *(v1.04)* - Toppling damage. Damage from getting toppled. Used by topple systems when structures fall over. Results in toppled state rather than destruction. **Reduces health points**. + +- **`DAMAGE_INFANTRY_MISSILE`** *(v1.04)* - Infantry missile damage. Damage type used by infantry-carried missile weapons. Used for portable missile launchers. Typically effective against vehicles and structures. **Reduces health points**. + +- **`DAMAGE_AURORA_BOMB`** *(v1.04)* - Aurora bomb damage. Damage type used by Aurora bomber weapons. Used for specialized bomber weapons. Typically very effective against structures. **Reduces health points**. + +- **`DAMAGE_LAND_MINE`** *(v1.04)* - Land mine damage. Damage type used by land mines. Used for explosive traps. Typically very effective against vehicles and infantry. **Reduces health points**. + +- **`DAMAGE_JET_MISSILES`** *(v1.04)* - Jet missile damage. Damage type used by jet aircraft missiles. Used for air-to-ground and air-to-air missiles from jet aircraft. Typically effective against various targets. **Reduces health points**. + +- **`DAMAGE_STEALTHJET_MISSILES`** *(v1.04)* - Stealth jet missile damage. Damage type used by stealth jet aircraft missiles. Used for specialized stealth aircraft weapons. Typically effective against various targets. **Reduces health points**. + +- **`DAMAGE_MOLOTOV_COCKTAIL`** *(v1.04)* - Molotov cocktail damage. Damage type used by molotov cocktail weapons. Used for incendiary thrown weapons. Sets targets on fire. **Reduces health points**. + +- **`DAMAGE_COMANCHE_VULCAN`** *(v1.04)* - Comanche Vulcan damage. Damage type used by Comanche helicopter Vulcan cannon. Used for specialized helicopter weapons. Typically very effective against infantry and light vehicles. **Reduces health points**. + +- **`DAMAGE_FLESHY_SNIPER`** *(v1.04, Zero Hour only)* - Fleshy sniper damage. Like `DAMAGE_SNIPER`, but generally does no damage to vehicles. Used by sniper weapons that are specifically designed to target infantry. Only effective against infantry, vehicles are immune. **Reduces health points**. + +## Examples + +### Basic Damage Type Usage + +```ini +Weapon = TankCannon WeaponSlot_PRIMARY + DamageType = ARMOR_PIERCING + Damage = 150 + Range = 200 +End +``` + +In this example, the weapon uses `ARMOR_PIERCING` damage type, which is effective against armored targets. + +## Notes + +- **Damage Type and Armor Interaction**: Damage types interact with armor types through damage multipliers defined in [Armor](../Armor.md) templates. The final damage amount is calculated by multiplying the base damage by the armor's resistance multiplier for that specific damage type. + +- **Health Point Damage**: In Retail Zero Hour, all damage types **reduce health points** (there are no non-HP damage types in retail versions). + +- **Damage Type Combinations**: Multiple damage types can be checked simultaneously by systems that need to verify if a weapon deals any of several damage types. + +## Source Files + +**Header (Generals):** [Damage.h](../../../../Generals/Code/GameEngine/Include/GameLogic/Damage.h) *(if retail Generals codebase exists)* +- `DamageType` enum definition (lines 43-97): Defines all available damage types for Retail Generals + +**Header (Zero Hour):** [Damage.h](../../Code/GameEngine/Include/GameLogic/Damage.h) +- `DamageType` enum definition (lines 43-97): Defines all available damage types for Retail Zero Hour + +**Source (Generals):** [Damage.cpp](../../../../Generals/Code/GameEngine/Source/GameLogic/Damage.cpp) *(if retail Generals codebase exists)* +- Damage type name mapping: Maps damage type names to their values for INI file parsing + +**Source (Zero Hour):** [Damage.cpp](../../Code/GameEngine/Source/GameLogic/Damage.cpp) +- Damage type name mapping: Maps damage type names to their values for INI file parsing + +## Changes History + +- In Retail Zero Hour, 1 new damage type was added: `DAMAGE_FLESHY_SNIPER` (like `DAMAGE_SNIPER`, but generally does no damage to vehicles). + +## Document Log + +- 16/12/2025 — AI — Initial document created. + +## Status + +AI-generated, 0/2 reviews + +## Reviewers + +- [ ] Reviewer 1 +- [ ] Reviewer 2 + diff --git a/Docs/INI/Weapon/Weapon.md b/Docs/INI/Weapon/Weapon.md new file mode 100644 index 0000000000..c05f59673f --- /dev/null +++ b/Docs/INI/Weapon/Weapon.md @@ -0,0 +1,1001 @@ +# Weapon + +Status: AI-generated, 0/2 reviews + +## Overview + +The `Weapon` class defines the properties and behavior of weapons in the game. Weapons are used by units, buildings, and special powers to deal damage, apply status effects, or trigger other game mechanics. Each weapon template specifies damage values, range, firing mechanics, visual effects, and targeting rules. + +Available in: *(v1.04)* + +**File Location**: Weapon definitions are stored in the file `Data\INI\Weapon\weapon.ini`. This file can exist in multiple locations: inside archives (`.big` , `.gib` files) and as a loose file in the game directory. Only `weapon.ini` is loaded from these locations. + +When multiple `weapon.ini` files are found, they are loaded in this order: +1. Files inside archives are loaded first, in descending alphabetical order (Z to A) +2. Loose files in the game directory are loaded last + +Since loose files are loaded last, they take precedence over archive files. If the same weapon name appears in multiple `weapon.ini` files, the later-loaded file completely overwrites the earlier one. Each weapon must have a unique name within each file, or the engine will crash when parsing duplicate names. + +Unlike some other subsystems, weapons do not use a default folder structure (e.g., `Data\INI\Default\Weapon\`). + +Weapons are defined as a list of entries (many entries allowed) in these `.ini` files. They are referenced by units, buildings, and special powers to define their combat capabilities and special abilities. + + +## Table of Contents + +- [Overview](#overview) +- [Properties](#properties) + - [Basic Damage Properties](#basic-damage-properties) + - [Range and Targeting](#range-and-targeting) + - [Firing Mechanics](#firing-mechanics) + - [Projectile Properties](#projectile-properties) + - [Visual and Audio Effects](#visual-and-audio-effects) + - [Targeting and Collision](#targeting-and-collision) + - [Continuous Fire Properties](#continuous-fire-properties) + - [Laser and Stream Properties](#laser-and-stream-properties) + - [Weapon Bonus Properties](#weapon-bonus-properties) + - [Historic Bonus Properties](#historic-bonus-properties) + - [Scatter and Accuracy Properties](#scatter-and-accuracy-properties) + - [Advanced Properties](#advanced-properties) +- [Enum Value Lists](#enum-value-lists) +- [Examples](#examples) +- [Usage](#usage) +- [Template](#template) +- [Notes](#notes) +- [Modder Recommended Use Scenarios](#modder-recommended-use-scenarios) +- [Source Files](#source-files) +- [Changes History](#changes-history) +- [Document Log](#document-log) +- [Status](#status) +- [Reviewers](#reviewers) + +## Properties + +### Basic Damage Properties + +#### `PrimaryDamage` *(v1.04)* +- **Type**: `Real` +- **Description**: The damage amount applied to objects within the primary damage radius. When a weapon deals damage, objects at or closer than [`PrimaryDamageRadius`](#primarydamageradius) from the impact point receive this damage amount. The primary target (if any) always receives primary damage regardless of distance. This damage is modified by weapon bonuses, armor types, and damage multipliers. If [`PrimaryDamageRadius`](#primarydamageradius) is 0, only the direct target receives this damage (no area effect). +- **Default**: `0.0` +- **Example**: `PrimaryDamage = 350.0` + +#### `PrimaryDamageRadius` *(v1.04)* +- **Type**: `Real` +- **Description**: The radius (in world units) from the impact point within which objects receive [`PrimaryDamage`](#primarydamage). Objects at a distance squared less than or equal to this radius squared take primary damage. If this is 0, the weapon only affects the direct target (no area effect). [`SecondaryDamageRadius`](#secondarydamageradius) must be greater than or equal to [`PrimaryDamageRadius`](#primarydamageradius) (or zero). This radius is modified by weapon bonuses that affect radius. +- **Default**: `0.0` +- **Example**: `PrimaryDamageRadius = 40.0` + +#### `SecondaryDamage` *(v1.04)* +- **Type**: `Real` +- **Description**: The damage amount applied to objects beyond the primary damage radius but within the secondary damage radius. Objects farther than [`PrimaryDamageRadius`](#primarydamageradius) but at or within [`SecondaryDamageRadius`](#secondarydamageradius) from the impact point receive this damage amount instead of primary damage. This allows creating weapons with a high-damage core area and a lower-damage outer area. If [`SecondaryDamageRadius`](#secondarydamageradius) is 0 or equal to [`PrimaryDamageRadius`](#primarydamageradius), secondary damage is never applied. This damage is modified by weapon bonuses, armor types, and damage multipliers. +- **Default**: `0.0` +- **Example**: `SecondaryDamage = 200.0` + +#### `SecondaryDamageRadius` *(v1.04)* +- **Type**: `Real` +- **Description**: The radius (in world units) from the impact point within which objects can receive [`SecondaryDamage`](#secondarydamage). Objects beyond [`PrimaryDamageRadius`](#primarydamageradius) but at or within this radius take secondary damage. This value must be greater than or equal to [`PrimaryDamageRadius`](#primarydamageradius) (or zero). If this is 0 or equal to [`PrimaryDamageRadius`](#primarydamageradius), only primary damage is applied. If this is greater than [`PrimaryDamageRadius`](#primarydamageradius), objects in the ring between the two radii receive secondary damage. This radius is modified by weapon bonuses that affect radius. +- **Default**: `0.0` +- **Example**: `SecondaryDamageRadius = 60.0` + +#### `DamageType` +Available in: *(v1.04)* + +- **Type**: `DamageType` (see [DamageType documentation](Enum/DamageType.md)) +- **Description**: The type of damage this weapon deals, which determines how the damage interacts with armor types, affects gameplay mechanics, and triggers special behaviors. Different damage types are modified differently by armor values - for example, some armor types may be more resistant to certain damage types, while being vulnerable to others. This creates tactical depth where certain weapons are more effective against specific targets. The damage type also affects how the damage is calculated and applied, whether it reduces health points, and what special effects or behaviors it may trigger. Some damage types have unique properties: explosive damage may cause area effects, flame damage may set targets on fire, laser damage may have high accuracy, and status damage may apply special conditions without reducing health. The damage type works in combination with [`PrimaryDamage`](#primarydamage) and [`SecondaryDamage`](#secondarydamage) to determine the final damage dealt, and should typically match the weapon's visual and audio effects for consistency. Commonly paired with appropriate [`DeathType`](#deathtype) values to create cohesive weapon theming (e.g., explosive damage with explosion death type). See the [DamageType documentation](Enum/DamageType.md) for a complete list of available damage types and their specific properties. +- **Default**: `EXPLOSION` +- **Example**: `DamageType = EXPLOSION` + +#### `DeathType` *(v1.04)* +- **Type**: `DeathType` +- **Description**: The type of death animation and visual/audio effects that are triggered when this weapon kills a target unit. This property controls how units die visually and audibly, providing appropriate death feedback that matches the weapon type and creates immersive gameplay. Different death types trigger different death animations, visual effects (such as explosions, fire, or laser effects), and audio effects, creating distinct death experiences for different weapon types. The death type is purely cosmetic and does not affect damage calculations, armor interactions, or gameplay mechanics - it only affects how the death is displayed. However, choosing an appropriate death type enhances the player experience by providing visual and audio feedback that matches the weapon's nature. For example, explosive weapons should use explosion death types to show dramatic explosions, while flame weapons should use fire death types to show units burning. The death type should typically match the weapon's [`DamageType`](#damagetype) for thematic consistency (e.g., explosive damage with explosion death, flame damage with fire death). Some death types have special gameplay interactions: for instance, the `BURNED` death type allows flame weapons to target and destroy vegetation regardless of other factors. See the [`DeathType` Values](#deathtype-values) section below for a complete list of available death types and their specific properties. +- **Default**: `NORMAL` +- **Example**: `DeathType = EXPLODED` +- **Available Values**: See [`DeathType` Values](#deathtype-values) section below + + +#### `DamageStatusType` +Available in: *(v1.04, Zero Hour only)* + +- **Type**: `ObjectStatusTypes` (see [ObjectStatusTypes documentation](../Object/Enums/ObjectStatusTypes.md)) +- **Description**: If the damage type is [`DAMAGE_STATUS`](Enum/DamageType.md#damage_status) (see [DamageType documentation](Enum/DamageType.md)), this specifies which status effect to apply to the target. The status effect is applied when the weapon deals damage. +- **Default**: [`OBJECT_STATUS_NONE`](../Object/Enums/ObjectStatusTypes.md) (see [ObjectStatusTypes documentation](../Object/Enums/ObjectStatusTypes.md)) +- **Example**: `DamageStatusType = CAN_ATTACK` + +### Range and Targeting + +#### `AttackRange` *(v1.04)* +- **Type**: `Real` +- **Description**: Maximum distance (in world units) at which this weapon will consider targets valid for acquisition and firing. Targets beyond this range are ignored for both targeting and firing. A small margin is applied to prevent targets from teetering on the edge of range. For projectile weapons, this works in combination with [`WeaponSpeed`](#weaponspeed)/[`MinWeaponSpeed`](#minweaponspeed) and accuracy properties. The effective range may be modified by weapon bonuses that affect range. If this is 0, the weapon cannot acquire targets (contact weapons may still function differently). +- **Default**: `0.0` +- **Example**: `AttackRange = 450.0` + +#### `MinimumAttackRange` *(v1.04)* +- **Type**: `Real` +- **Description**: Minimum distance (in world units) required before this weapon may fire. If a target is closer than this value (with a small margin applied), the weapon will not fire even if it is otherwise valid and acquired. This prevents self-damage from area effect weapons, enforces standoff behavior for artillery, and prevents units from firing point-blank when that would be undesirable. A small margin is applied to this value to ensure consistent behavior. If this is 0, there is no minimum range restriction. +- **Default**: `0.0` +- **Example**: `MinimumAttackRange = 5.0` + +#### `AcceptableAimDelta` *(v1.04)* +- **Type**: `Real` (angle in degrees) +- **Description**: Maximum allowed angular error (in degrees) between the weapon's current aim direction and the ideal direction to the target before a shot can be released. The weapon will wait until the aim error is within this tolerance before firing. Smaller values (e.g., 1-2 degrees) enforce very precise aiming, requiring the weapon to be nearly perfectly aligned before firing - useful for sniper weapons or high-accuracy weapons. Larger values (e.g., 10-15 degrees) allow the weapon to fire while still tracking or moving, creating a more "spray and pray" behavior. A value of 0 means the weapon must be perfectly aimed (may cause issues with moving targets). Very large values (e.g., 999) effectively disable aim checking, allowing immediate firing. +- **Default**: `0.0` +- **Example**: `AcceptableAimDelta = 1` + +#### `RequestAssistRange` *(v1.04)* +- **Type**: `Real` +- **Description**: Range (in world units) within which other units with the same weapon will be called to assist in attacking the same target. When a unit with this weapon acquires a target, it broadcasts a request for assistance to other units within this range. Units that receive the request and can target the same enemy will join the attack, creating coordinated fire. This allows multiple units to focus fire on a single target, increasing damage output. The range is measured from the requesting unit's position. If set to 0, the weapon does not request assistance from other units. This property is useful for coordinating attacks from groups of units. +- **Default**: `0.0` +- **Example**: `RequestAssistRange = 100.0` + +### Firing Mechanics + +#### `DelayBetweenShots` *(v1.04)* +- **Type**: `Int` (milliseconds) or `Min:Max` range +- **Description**: Time delay between consecutive shots fired by this weapon. This property accepts two formats: (1) A single integer value (e.g., `1000`) which creates a constant delay between all shots, or (2) A labeled range format `Min:1000 Max:2000` which creates a variable delay where a random value between min and max (inclusive) is selected for each shot. The values are specified in milliseconds but are converted to game frames. If both min and max are 0, there is no enforced delay between shots (weapon fires as fast as possible). Variable delays add unpredictability to weapon firing patterns. +- **Default**: `0` (no enforced delay) +- **Example**: `DelayBetweenShots = 1000` or `DelayBetweenShots = Min:800 Max:1200` + +#### `ClipSize` *(v1.04)* +- **Type**: `Int` +- **Description**: Number of shots that can be fired before the weapon must reload. When the weapon fires, it consumes one shot from the clip. Once the clip is empty (all shots fired), the weapon must reload using [`ClipReloadTime`](#clipreloadtime) before it can fire again. If set to 0, the weapon has infinite ammo and never needs to reload. Higher values allow more shots before reloading, but also increase the time required to reload. This property works in combination with [`AutoReloadsClip`](#autoreloadsclip) and [`AutoReloadWhenIdle`](#autoreloadwhenidle) to control reload behavior. +- **Default**: `0` +- **Example**: `ClipSize = 30` + +#### `ClipReloadTime` *(v1.04)* +- **Type**: `Int` (milliseconds) +- **Description**: Time (in milliseconds) required to reload the weapon when the clip is empty. This delay is applied after the weapon has fired all shots in the [`ClipSize`](#clipsize) and needs to reload before it can fire again. The reload time prevents the weapon from firing during this period. If [`AutoReloadsClip`](#autoreloadsclip) is enabled, the reload happens automatically when the clip is empty. Higher values create longer reload times, balancing weapons with large clip sizes. If [`ClipSize`](#clipsize) is 0 (infinite ammo), this property has no effect. +- **Default**: `0` +- **Example**: `ClipReloadTime = 3000` + +#### `AutoReloadsClip` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon automatically begins reloading when the [`ClipSize`](#clipsize) is exhausted. When enabled, the weapon automatically starts the reload process (using [`ClipReloadTime`](#clipreloadtime)) as soon as the last shot in the clip is fired. When disabled, the weapon will not reload automatically and must be manually reloaded or will reload when [`AutoReloadWhenIdle`](#autoreloadwhenidle) triggers. This property only has an effect if [`ClipSize`](#clipsize) is greater than 0. +- **Default**: `Yes` +- **Example**: `AutoReloadsClip = Yes` + +#### `AutoReloadWhenIdle` *(v1.04)* +- **Type**: `Int` (milliseconds) +- **Description**: Time (in milliseconds) of inactivity (not firing) before the weapon automatically reloads if the clip is not full. If the weapon has not fired for this duration and the current clip has fewer shots than [`ClipSize`](#clipsize), the weapon will automatically reload to fill the clip. This allows weapons to reload during lulls in combat without manual intervention. If set to 0, the weapon will not automatically reload when idle. This property only has an effect if [`ClipSize`](#clipsize) is greater than 0. +- **Default**: `0` +- **Example**: `AutoReloadWhenIdle = 5000` + +#### `PreAttackDelay` *(v1.04)* +- **Type**: `Int` (milliseconds) +- **Description**: Delay (in milliseconds) before the weapon fires after acquiring a target. This delay is applied based on the [`PreAttackType`](#preattacktype) setting, which determines when the delay occurs (before each shot, before each new target, or before each new clip). The delay allows time for aiming, charging, or other preparation before firing. Higher values create longer preparation times, useful for weapons that need to lock on, charge up, or aim precisely before firing. If set to 0, there is no pre-attack delay and the weapon fires immediately when ready. +- **Default**: `0` +- **Example**: `PreAttackDelay = 2000` + +#### `PreAttackType` *(v1.04)* +- **Type**: `WeaponPrefireType` +- **Description**: Controls when the [`PreAttackDelay`](#preattackdelay) is applied. This determines the timing of the pre-attack delay: before each shot (`PER_SHOT`), before each new target (`PER_ATTACK`), or before each new clip (`PER_CLIP`). This works in combination with [`PreAttackDelay`](#preattackdelay) to create different firing patterns. For example, `PER_ATTACK` allows a weapon to have an initial delay when acquiring a new target but then fire rapidly at that same target, while `PER_SHOT` applies the delay before every single shot. +- **Default**: `PER_SHOT` +- **Example**: `PreAttackType = PER_SHOT` +- **Available Values**: See [WeaponPrefireType Values](#weaponprefiretype-values) section below + +### Projectile Properties + +#### `ProjectileObject` *(v1.04)* +- **Type**: `object` (see [Object documentation](Object.md)) +- **Description**: The projectile object template that is created and launched when the weapon fires. This object represents the physical projectile that travels from the firing point to the target. The projectile object is created at the weapon's firing point with an initial velocity determined by [`WeaponSpeed`](#weaponspeed) and [`MinWeaponSpeed`](#minweaponspeed), and travels toward the target following the weapon's trajectory. The projectile object must be defined in the game's object definitions and can have its own behaviors, visual effects, and collision properties. If not specified, the weapon is an instant-hit weapon that deals damage immediately without a visible projectile. The projectile object is destroyed when it impacts the target, hits terrain, or reaches its maximum range. +- **Example**: `ProjectileObject = TankShell` + +#### `WeaponSpeed` *(v1.04)* +- **Type**: `Real` (distance per second) +- **Description**: Speed (in world units per second) at which the projectile travels from the firing point to the target. For projectile weapons, this determines how fast the projectile moves through the air. For instant-hit weapons (no projectile), this property may not apply. Higher values make projectiles travel faster, reducing the time to impact. This works in combination with [`AttackRange`](#attackrange) to determine the effective engagement time. For variable-speed weapons, use [`MinWeaponSpeed`](#minweaponspeed) to set a minimum speed, and if [`ScaleWeaponSpeed`](#scaleweaponspeed) is enabled, the speed may scale with range for lobbed projectiles. +- **Default**: `0.0` +- **Example**: `WeaponSpeed = 1000.0` + +#### `MinWeaponSpeed` *(v1.04)* +- **Type**: `Real` (distance per second) +- **Description**: Minimum speed (in world units per second) for variable-speed weapons. This sets the lower bound for projectile speed when the weapon uses variable speed mechanics. The actual speed may vary between [`MinWeaponSpeed`](#minweaponspeed) and [`WeaponSpeed`](#weaponspeed) based on range, angle, or other factors. If [`ScaleWeaponSpeed`](#scaleweaponspeed) is enabled, the speed scales with range, and this minimum ensures the projectile never travels slower than this value. If this is 0 or equal to [`WeaponSpeed`](#weaponspeed), the weapon uses a constant speed. +- **Default**: `0.0` +- **Example**: `MinWeaponSpeed = 500.0` + +#### `ScaleWeaponSpeed` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon speed scales with range for lobbed projectiles. When enabled, the projectile speed varies based on the distance to the target, creating a more realistic arc trajectory for artillery or mortar-style weapons. The speed scales between [`MinWeaponSpeed`](#minweaponspeed) and [`WeaponSpeed`](#weaponspeed) based on range, with longer ranges potentially using different speeds to create the desired arc. This is useful for weapons that need to arc over obstacles or create a parabolic trajectory. When disabled, the weapon uses a constant speed as specified by [`WeaponSpeed`](#weaponspeed). +- **Default**: `No` +- **Example**: `ScaleWeaponSpeed = Yes` + +#### `WeaponRecoil` *(v1.04)* +- **Type**: `Real` (radians) +- **Description**: Amount of recoil (angular displacement in radians) imparted to the firing unit when the weapon fires. Recoil causes the firing unit to rotate or move backward slightly when firing, simulating the physical force of weapon discharge. Higher values create more pronounced recoil effects, causing the unit to rotate more or move backward further. Recoil can affect the unit's aim and position, making subsequent shots less accurate if the unit hasn't recovered. This is useful for balancing powerful weapons by adding a physical cost to firing. If set to 0, there is no recoil effect. The recoil is applied in the direction opposite to the firing direction. +- **Default**: `0.0` +- **Example**: `WeaponRecoil = 0.1` + +### Visual and Audio Effects + +#### `FireFX` *(v1.04)* +- **Type**: `FXList` (per veterancy level) +- **Description**: Visual effects (FXList) that are played at the weapon's firing point when the weapon fires. These effects are displayed at the muzzle or firing location and provide visual feedback for weapon discharge. The effects are played every time the weapon fires, synchronized with the firing animation. If you need different effects for different veterancy levels, use [`VeterancyFireFX`](#veterancyfirefx) instead. The FXList can contain multiple effects that play simultaneously or in sequence. +- **Example**: `FireFX = FX_TankCannonFire` + +#### `ProjectileDetonationFX` *(v1.04)* +- **Type**: `FXList` (per veterancy level) +- **Description**: Visual effects (FXList) that are played when the projectile from this weapon impacts its target or detonates. These effects are displayed at the impact point and provide visual feedback for the weapon's damage delivery. The effects are played when the projectile collides with a target, hits terrain, or reaches its detonation point. If you need different effects for different veterancy levels, use [`VeterancyProjectileDetonationFX`](#veterancyprojectiledetonationfx) instead. The FXList can contain multiple effects that play simultaneously or in sequence. +- **Example**: `ProjectileDetonationFX = FX_ExplosionLarge` + +#### `FireSound` *(v1.04)* +- **Type**: `AudioEventRTS` +- **Description**: Audio event (AudioEventRTS) that is played when the weapon fires. This sound is triggered at the weapon's firing point and provides audio feedback for weapon discharge. The sound plays every time the weapon fires, synchronized with the firing animation. For continuous-fire weapons, you can use [`FireSoundLoopTime`](#firesoundlooptime) to loop the sound for a specified duration. The audio event must be defined in the game's audio system and can include 3D positional audio that varies based on the listener's position relative to the firing unit. +- **Example**: `FireSound = TankCannonFire` + +#### `FireSoundLoopTime` *(v1.04)* +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Duration (in milliseconds) for looping the [`FireSound`](#firesound) audio event. When this is set to a non-zero value, the fire sound loops for the specified duration, creating a continuous firing sound effect. This is useful for weapons that fire continuously or have a sustained firing pattern, such as machine guns or flamethrowers. The sound loops from the start of the audio event for the specified duration. If this is 0, the fire sound plays once per shot without looping. +- **Default**: `0` +- **Example**: `FireSoundLoopTime = 1000` + +#### `FireOCL` *(v1.04)* +- **Type**: `ObjectCreationList` (per veterancy level) +- **Description**: ObjectCreationList that specifies objects to be created at the weapon's firing point when the weapon fires. These objects are spawned at the muzzle or firing location and can include muzzle flashes, shell casings, smoke, or other visual elements. The objects are created every time the weapon fires, synchronized with the firing animation. If you need different objects for different veterancy levels, use [`VeterancyFireOCL`](#veterancyfireocl) instead. The ObjectCreationList can contain multiple objects that are created simultaneously or in sequence. +- **Example**: `FireOCL = OCL_MuzzleFlash` + +#### `ProjectileDetonationOCL` *(v1.04)* +- **Type**: `ObjectCreationList` (per veterancy level) +- **Description**: ObjectCreationList that specifies objects to be created when the projectile from this weapon impacts its target or detonates. These objects are spawned at the impact point and can include debris, fragments, secondary projectiles, or other visual elements. The objects are created when the projectile collides with a target, hits terrain, or reaches its detonation point. If you need different objects for different veterancy levels, use [`VeterancyProjectileDetonationOCL`](#veterancyprojectiledetonationocl) instead. The ObjectCreationList can contain multiple objects that are created simultaneously or in sequence. +- **Example**: `ProjectileDetonationOCL = OCL_ExplosionDebris` + +#### `ProjectileExhaust` *(v1.04)* +- **Type**: `ParticleSystemTemplate` (per veterancy level) +- **Description**: Particle system template that defines the exhaust trail or smoke trail emitted by the projectile as it travels. This creates a visual trail that follows the projectile from the firing point to the impact point, providing visual feedback for projectile movement. The particle system is attached to the projectile and renders continuously while the projectile is in flight. If you need different particle effects for different veterancy levels, use [`VeterancyProjectileExhaust`](#veterancyprojectileexhaust) instead. The particle system template must be defined in the game's particle system definitions. +- **Example**: `ProjectileExhaust = PS_TankShellTrail` + +#### `VeterancyFireFX` *(v1.04)* +- **Type**: `FXList` (per veterancy level) +- **Description**: Visual effects (FXList) that are played at the weapon's firing point when the weapon fires, specified per veterancy level. This allows you to define different visual effects for each veterancy level (Veteran, Elite, Heroic). Use this instead of [`FireFX`](#firefx) when you need different effects for each veterancy level. The effects are played every time the weapon fires, synchronized with the firing animation. The format allows specifying effects for each veterancy level separately. +- **Example**: `VeterancyFireFX = VETERAN FX_TankCannonFireVeteran` + +#### `VeterancyProjectileDetonationFX` *(v1.04)* +- **Type**: `FXList` (per veterancy level) +- **Description**: Visual effects (FXList) that are played when the projectile impacts its target or detonates, specified per veterancy level. This allows you to define different visual effects for each veterancy level (Veteran, Elite, Heroic). Use this instead of [`ProjectileDetonationFX`](#projectiledetonationfx) when you need different effects for each veterancy level. The effects are displayed at the impact point and provide visual feedback for the weapon's damage delivery. The format allows specifying effects for each veterancy level separately. +- **Example**: `VeterancyProjectileDetonationFX = VETERAN FX_ExplosionLargeVeteran` + +#### `VeterancyFireOCL` *(v1.04)* +- **Type**: `ObjectCreationList` (per veterancy level) +- **Description**: ObjectCreationList that specifies objects to be created at the weapon's firing point when the weapon fires, specified per veterancy level. This allows you to define different objects for each veterancy level (Veteran, Elite, Heroic). Use this instead of [`FireOCL`](#fireocl) when you need different objects for each veterancy level. The objects are spawned at the muzzle or firing location and can include muzzle flashes, shell casings, smoke, or other visual elements. The format allows specifying objects for each veterancy level separately. +- **Example**: `VeterancyFireOCL = VETERAN OCL_MuzzleFlashVeteran` + +#### `VeterancyProjectileDetonationOCL` *(v1.04)* +- **Type**: `ObjectCreationList` (per veterancy level) +- **Description**: ObjectCreationList that specifies objects to be created when the projectile impacts its target or detonates, specified per veterancy level. This allows you to define different objects for each veterancy level (Veteran, Elite, Heroic). Use this instead of [`ProjectileDetonationOCL`](#projectiledetonationocl) when you need different objects for each veterancy level. The objects are spawned at the impact point and can include debris, fragments, secondary projectiles, or other visual elements. The format allows specifying objects for each veterancy level separately. +- **Example**: `VeterancyProjectileDetonationOCL = VETERAN OCL_ExplosionDebrisVeteran` + +#### `VeterancyProjectileExhaust` *(v1.04)* +- **Type**: `ParticleSystemTemplate` (per veterancy level) +- **Description**: Particle system template that defines the exhaust trail or smoke trail emitted by the projectile as it travels, specified per veterancy level. This allows you to define different particle effects for each veterancy level (Veteran, Elite, Heroic). Use this instead of [`ProjectileExhaust`](#projectileexhaust) when you need different effects for each veterancy level. The particle system is attached to the projectile and renders continuously while the projectile is in flight. The format allows specifying particle systems for each veterancy level separately. +- **Example**: `VeterancyProjectileExhaust = VETERAN PS_TankShellTrailVeteran` + +### Targeting and Collision + +#### `RadiusDamageAffects` *(v1.04)* +- **Type**: `WeaponAffectsMaskType` (bit flags) +- **Description**: Bit flags that determine which types of objects are affected by the weapon's radius damage (both [`PrimaryDamageRadius`](#primarydamageradius) and [`SecondaryDamageRadius`](#secondarydamageradius)). This property controls whether the weapon's area effect damage affects allies, enemies, neutral units, or specific object categories. Multiple flags can be combined to affect multiple types. This allows weapons to selectively damage only certain types of targets, such as weapons that only damage enemies or weapons that damage everything including allies. If no flags are set, radius damage does not affect any objects (only direct hits apply damage). This property works in combination with the weapon's targeting properties to determine what can be damaged. +- **Example**: `RadiusDamageAffects = ALLIES ENEMIES NEUTRALS` +- **Available Values**: See [WeaponAffectsMaskType Values](#weaponaffectsmasktype-values) section below + + +#### `ProjectileCollidesWith` *(v1.04)* +- **Type**: `WeaponCollideMaskType` (bit flags) +- **Description**: Bit flags that determine which types of objects the [`ProjectileObject`](#projectileobject) can collide with during flight. This property controls collision detection for projectiles, determining what objects will cause the projectile to impact and detonate. Multiple flags can be combined to allow collisions with multiple object types. This allows projectiles to pass through certain objects (by not including their flags) or to impact specific types of objects. For example, a projectile that can only collide with structures and walls will pass through units and terrain, while a projectile that collides with everything will impact the first object it encounters. This property only applies to weapons with a [`ProjectileObject`](#projectileobject) specified. +- **Example**: `ProjectileCollidesWith = STRUCTURES WALLS` +- **Available Values**: See [WeaponCollideMaskType Values](#weaponcollidemasktype-values) section below + +#### `AntiGround` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at ground-based units and objects. When enabled, the weapon can acquire and attack targets that are on the ground, including ground vehicles, infantry, and ground-based structures. When disabled, the weapon cannot target ground units, restricting it to other target types (airborne units, projectiles, etc.). This property works in combination with other Anti- properties ([`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiProjectile`](#antiprojectile), [`AntiSmallMissile`](#antismallmissile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiMine`](#antimine), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. All Anti- properties can be enabled simultaneously to allow the weapon to target multiple categories. +- **Default**: `Yes` +- **Example**: `AntiGround = Yes` + +#### `AntiAirborneVehicle` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at airborne vehicles (aircraft). When enabled, the weapon can acquire and attack targets that are flying vehicles, such as helicopters, jets, and other aircraft. When disabled, the weapon cannot target airborne vehicles, restricting it to other target types (ground units, projectiles, etc.). This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiProjectile`](#antiprojectile), [`AntiSmallMissile`](#antismallmissile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiMine`](#antimine), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. This is essential for anti-aircraft weapons that need to engage flying targets. +- **Default**: `No` +- **Example**: `AntiAirborneVehicle = Yes` + +#### `AntiAirborneInfantry` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at airborne infantry units (paratroopers, flying infantry). When enabled, the weapon can acquire and attack targets that are infantry units that are airborne or flying. When disabled, the weapon cannot target airborne infantry, restricting it to other target types (ground units, vehicles, projectiles, etc.). This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiProjectile`](#antiprojectile), [`AntiSmallMissile`](#antismallmissile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiMine`](#antimine), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. This is useful for weapons that need to engage paratroopers or other flying infantry units. +- **Default**: `No` +- **Example**: `AntiAirborneInfantry = No` + +#### `AntiProjectile` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at projectile objects in flight. When enabled, the weapon can acquire and attack targets that are projectiles (missiles, shells, etc.) that are currently in flight. When disabled, the weapon cannot target projectiles, restricting it to other target types (units, structures, etc.). This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiSmallMissile`](#antismallmissile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiMine`](#antimine), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. This is essential for point-defense weapons or anti-missile systems that intercept incoming projectiles. +- **Default**: `No` +- **Example**: `AntiProjectile = Yes` + +#### `AntiSmallMissile` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at small missile objects specifically. When enabled, the weapon can acquire and attack targets that are small missiles (typically defined by the `KINDOF_SMALL_MISSILE` flag). When disabled, the weapon cannot target small missiles, restricting it to other target types. This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiProjectile`](#antiprojectile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiMine`](#antimine), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. This allows weapons to specifically target small missiles (like anti-tank missiles) while potentially ignoring larger projectiles or other target types. This is useful for point-defense systems that need to intercept specific types of missiles. +- **Default**: `No` +- **Example**: `AntiSmallMissile = Yes` + +#### `AntiBallisticMissile` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at ballistic missile objects specifically. When enabled, the weapon can acquire and attack targets that are ballistic missiles (typically defined by the `KINDOF_BALLISTIC_MISSILE` flag). When disabled, the weapon cannot target ballistic missiles, restricting it to other target types. This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiProjectile`](#antiprojectile), [`AntiSmallMissile`](#antismallmissile), [`AntiMine`](#antimine), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. This is essential for anti-ballistic missile defense systems that need to intercept long-range ballistic missiles. +- **Default**: `No` +- **Example**: `AntiBallisticMissile = Yes` + +#### `AntiMine` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at mine objects. When enabled, the weapon can acquire and attack targets that are mines (land mines, naval mines, etc.). When disabled, the weapon cannot target mines, restricting it to other target types. This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiProjectile`](#antiprojectile), [`AntiSmallMissile`](#antismallmissile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiParachute`](#antiparachute)) to define the weapon's targeting capabilities. This is useful for mine-clearing weapons or units that need to destroy mines. +- **Default**: `No` +- **Example**: `AntiMine = Yes` + +#### `AntiParachute` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can target and fire at parachute objects. When enabled, the weapon can acquire and attack targets that are parachutes (typically used by paratroopers or supply drops). When disabled, the weapon cannot target parachutes, restricting it to other target types. This property works in combination with other Anti- properties ([`AntiGround`](#antiground), [`AntiAirborneVehicle`](#antiairbornevehicle), [`AntiAirborneInfantry`](#antiairborneinfantry), [`AntiProjectile`](#antiprojectile), [`AntiSmallMissile`](#antismallmissile), [`AntiBallisticMissile`](#antibalisticmissile), [`AntiMine`](#antimine)) to define the weapon's targeting capabilities. This is useful for weapons that need to engage paratroopers while they are descending or to destroy supply drops. +- **Default**: `No` +- **Example**: `AntiParachute = Yes` + + +### Advanced Properties + +#### `ShockWaveAmount` *(v1.04, Generals Zero Hour only)* +- **Type**: `Real` +- **Description**: Intensity or magnitude of the shockwave effect generated when the weapon impacts. The shockwave effect creates a visual and potentially physical disturbance in the environment, simulating the force of an explosion. Higher values create more intense shockwave effects, with stronger visual distortion and potentially greater environmental impact. The shockwave effect is applied within the [`ShockWaveRadius`](#shockwaveradius) and tapers off based on [`ShockWaveTaperOff`](#shockwavetaperoff). This property works in combination with the other shockwave properties to create realistic explosion effects. If set to 0, no shockwave effect is generated. +- **Default**: `0.0` +- **Example**: `ShockWaveAmount = 25.0` + +#### `ShockWaveRadius` *(v1.04, Generals Zero Hour only)* +- **Type**: `Real` +- **Description**: Radius (in world units) within which the shockwave effect is applied when the weapon impacts. The shockwave effect extends from the impact point to this distance, creating a circular area of effect. Objects and the environment within this radius experience the shockwave effect with intensity determined by [`ShockWaveAmount`](#shockwaveamount) and distance from the impact point. The effect tapers off toward the edge of the radius based on [`ShockWaveTaperOff`](#shockwavetaperoff). Higher values create larger shockwave areas, affecting a wider area around the impact point. This property works in combination with the other shockwave properties to create realistic explosion effects. +- **Default**: `0.0` +- **Example**: `ShockWaveRadius = 70.0` + +#### `ShockWaveTaperOff` *(v1.04, Generals Zero Hour only)* +- **Type**: `Real` +- **Description**: Multiplier (0.0 to 1.0) that determines how much of the [`ShockWaveAmount`](#shockwaveamount) remains at the edge of the [`ShockWaveRadius`](#shockwaveradius). This creates a falloff effect where the shockwave intensity decreases from the impact point to the edge of the radius. A value of 1.0 means the full shockwave amount is applied even at the edge (no falloff), while a value of 0.0 means no shockwave effect at the edge (maximum falloff). Values between 0.0 and 1.0 create a gradual falloff, with the shockwave intensity linearly interpolating from full strength at the impact point to this multiplier value at the edge. This property works in combination with [`ShockWaveAmount`](#shockwaveamount) and [`ShockWaveRadius`](#shockwaveradius) to create realistic explosion effects with proper distance-based intensity falloff. +- **Default**: `0.0` +- **Example**: `ShockWaveTaperOff = 0.50` + +#### `ScatterRadius` *(v1.04)* +- **Type**: `Real` +- **Description**: Maximum random offset radius (in world units) applied to the intended impact point to simulate weapon inaccuracy. When the weapon fires, the actual impact point is randomly offset from the target position by up to this radius in any direction. This creates a circular area of potential impact. This scatter is applied to all targets. If this is 0, there is no random scatter (weapon is perfectly accurate). Scatter is useful for simulating artillery, mortars, or low-accuracy weapons. The scatter is applied in addition to any [`ScatterRadiusVsInfantry`](#scatterradiusvsinfantry) when targeting infantry. +- **Default**: `0.0` +- **Example**: `ScatterRadius = 5.0` + +#### `ScatterTargetScalar` *(v1.04)* +- **Type**: `Real` +- **Description**: Multiplier applied to the coordinates specified in [`ScatterTarget`](#scattertarget) entries. This allows you to scale preset scatter target offsets without redefining all the coordinates. A value of 1.0 uses the scatter targets at their defined scale. Values greater than 1.0 increase the scatter spread, values less than 1.0 decrease it. This only affects weapons that use [`ScatterTarget`](#scattertarget) entries; it has no effect if [`ScatterTarget`](#scattertarget) is not used. +- **Default**: `0.0` +- **Example**: `ScatterTargetScalar = 1.0` + +#### `ScatterRadiusVsInfantry` *(v1.04)* +- **Type**: `Real` +- **Description**: Additional random scatter radius (in world units) applied specifically when the target is infantry. This extra inaccuracy is added to the base [`ScatterRadius`](#scatterradius) when targeting infantry units, simulating the difficulty of hitting small, mobile targets. If the target is not infantry, only [`ScatterRadius`](#scatterradius) applies. This allows weapons to be more accurate against vehicles/buildings but less accurate against infantry. If this is 0, there is no extra scatter against infantry (only base [`ScatterRadius`](#scatterradius) applies). +- **Default**: `0.0` +- **Example**: `ScatterRadiusVsInfantry = 10.0` + +#### `DamageDealtAtSelfPosition` *(v1.04)* +- **Type**: `Bool` +- **Description**: When enabled, the damage epicenter is the firing unit's current position rather than the target's position. This causes all radius damage calculations to originate from the shooter, not the impact point. This is essential for suicide weapons (like car bombs) where the explosion should occur at the attacker's location. When disabled (default), damage originates from the target position (for direct hits) or the projectile impact point (for projectile weapons). This property affects both [`PrimaryDamageRadius`](#primarydamageradius) and [`SecondaryDamageRadius`](#secondarydamageradius) calculations. +- **Default**: `No` +- **Example**: `DamageDealtAtSelfPosition = Yes` + +#### `ContinueAttackRange` *(v1.04)* +- **Type**: `Real` +- **Description**: Radius (in world units) within which the weapon will automatically search for and acquire new similar targets after destroying the current target, without requiring manual reacquisition. When a target is destroyed, becomes effectively dead, or is a mine that becomes masked, the weapon automatically looks for another valid target of the same type within this range. This allows weapons to chain attacks across multiple targets without player intervention. The weapon temporarily sets the `IGNORING_STEALTH` status flag to find stealthed targets during this search. If this is 0, the weapon does not automatically continue attacking after destroying a target (normal behavior). +- **Default**: `0.0` +- **Example**: `ContinueAttackRange = 50.0` + +#### `MinTargetPitch` *(v1.04)* +- **Type**: `Real` (angle in radians) +- **Description**: Lowest vertical aim angle (pitch) allowed when acquiring and firing at targets. This restricts the weapon's ability to aim downward. Values are in radians, where negative values allow aiming below horizontal (downward) and positive values restrict downward aiming. The default of -PI allows aiming in any downward direction. This is useful for weapons that should not be able to fire straight down (e.g., certain artillery) or for balancing purposes. +- **Default**: `-PI` (can aim straight down) +- **Example**: `MinTargetPitch = -30.0` + +#### `MaxTargetPitch` *(v1.04)* +- **Type**: `Real` (angle in radians) +- **Description**: Highest vertical aim angle (pitch) allowed when acquiring and firing at targets. This restricts the weapon's ability to aim upward. Values are in radians, where positive values allow aiming above horizontal (upward) and negative values restrict upward aiming. The default of PI allows aiming in any upward direction. This is useful for ground-based weapons that should not be able to fire straight up (e.g., certain cannons) or for balancing purposes. +- **Default**: `PI` (can aim straight up) +- **Example**: `MaxTargetPitch = 30.0` + +#### `RadiusDamageAngle` *(v1.04, Generals Zero Hour only)* +- **Type**: `Real` (angle in radians) +- **Description**: Limits radius damage to a directional cone centered on the firing unit's forward orientation. When this value is less than PI (180 degrees), radius damage only affects objects within a cone extending from the firing unit in its facing direction. The cone angle is measured from the center line (half-angle). Objects outside this cone are not affected by radius damage even if they are within the damage radius. When this is PI or greater, radius damage applies in all directions (full 360 degrees). This allows creating directional blasts, flamethrowers, or forward-facing area weapons. The angle between the firing unit's forward direction and the direction to each potential victim is checked; if the victim is outside the allowed cone angle, the victim is skipped. +- **Default**: `PI` (full 360° coverage) +- **Example**: `RadiusDamageAngle = 45.0` + +### Continuous Fire Properties + +#### `ContinuousFireOne` *(v1.04)* +- **Type**: `Int` +- **Description**: Number of consecutive shots that must be fired before the weapon enters the first continuous fire mode. Once this many shots have been fired in succession, the weapon gains enhanced firing properties (typically faster firing rate or reduced [`DelayBetweenShots`](#delaybetweenshots)). The continuous fire mode persists as long as the weapon continues firing, and resets when firing stops for longer than [`ContinuousFireCoast`](#continuousfirecoast). This allows weapons to "warm up" and fire faster after sustained use. If set to 0, the weapon never enters continuous fire mode. This property works in combination with [`ContinuousFireTwo`](#continuousfiretwo) to create multiple stages of continuous fire. +- **Example**: `ContinuousFireOne = 5` + +#### `ContinuousFireTwo` *(v1.04)* +- **Type**: `Int` +- **Description**: Number of consecutive shots that must be fired before the weapon enters the second continuous fire mode (enhanced continuous fire). This is a higher tier of continuous fire that activates after [`ContinuousFireOne`](#continuousfireone) has been reached. Once this many shots have been fired in succession, the weapon gains even more enhanced firing properties. The continuous fire mode persists as long as the weapon continues firing, and resets when firing stops for longer than [`ContinuousFireCoast`](#continuousfirecoast). This allows weapons to have multiple "warm up" stages with progressively better performance. If set to 0, the weapon never enters the second continuous fire mode. This value must be greater than [`ContinuousFireOne`](#continuousfireone) to have any effect. +- **Example**: `ContinuousFireTwo = 10` + +#### `ContinuousFireCoast` *(v1.04)* +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time (in milliseconds) after the weapon stops firing before the continuous fire mode (activated by [`ContinuousFireOne`](#continuousfireone) and [`ContinuousFireTwo`](#continuousfiretwo)) ends and resets. If the weapon stops firing for longer than this duration, the continuous fire counter resets to 0 and the weapon must fire the required number of shots again to re-enter continuous fire mode. This creates a "cooldown" period where the weapon loses its enhanced firing properties if not used continuously. Lower values make the continuous fire mode reset quickly, while higher values allow brief pauses in firing without losing the continuous fire benefits. If set to 0, continuous fire mode resets immediately when firing stops. +- **Example**: `ContinuousFireCoast = 1000` + +### Laser and Stream Properties + +#### `LaserName` *(v1.04)* +- **Type**: `AsciiString` +- **Description**: Name of the laser object template that is created and persists while the weapon is firing. The laser object is a visual effect that appears as a continuous beam or line from the weapon's firing point to the target, providing visual feedback for laser weapons or beam weapons. The laser object is created when firing begins and is destroyed when firing stops. This creates a persistent visual connection between the weapon and its target during the firing duration. The laser object must be defined in the game's object definitions. If [`LaserBoneName`](#laserbonename) is specified, the laser is attached to that bone on the firing unit's model; otherwise, it attaches to the default firing point. +- **Example**: `LaserName = LaserBeam` + +#### `LaserBoneName` *(v1.04, Generals Zero Hour only)* +- **Type**: `AsciiString` +- **Description**: Name of the bone on the firing unit's 3D model where the [`LaserName`](#lasername) object is attached. This allows precise control over where the laser beam originates on the unit's model. The bone name must match a bone defined in the unit's W3D model file. When specified, the laser object attaches to this bone instead of the default firing point, allowing the laser to originate from specific locations like a weapon barrel, turret muzzle, or other model attachment points. This is useful for units with multiple weapon mounts or when the laser should originate from a specific visual location on the model. If not specified, the laser attaches to the default weapon firing point. +- **Example**: `LaserBoneName = Muzzle` + +#### `ProjectileStreamName` *(v1.04)* +- **Type**: `AsciiString` +- **Description**: Name of the object template that is created to visually track and follow the [`ProjectileObject`](#projectileobject) as it travels from the firing point to the target. This object creates a visual stream or trail effect that follows the projectile's path, providing visual feedback for projectile movement. The stream object is created when the projectile is fired and is automatically positioned to track the projectile's current location. This is useful for creating missile trails, smoke trails, or other visual effects that follow projectiles. The stream object must be defined in the game's object definitions and will be automatically destroyed when the projectile impacts or is destroyed. +- **Example**: `ProjectileStreamName = MissileTrail` + +### Weapon Bonus Properties + +#### `WeaponBonus` *(v1.04)* +- **Type**: `WeaponBonusSet` +- **Description**: Additional bonuses that modify this weapon's properties when specific conditions are met. Weapon bonuses can increase damage, range, rate of fire, or other weapon attributes based on player upgrades, veterancy levels, or other game conditions. Multiple bonus entries can be specified, and they stack multiplicatively or additively depending on the bonus type. Bonuses are typically tied to player upgrades or research, allowing weapons to become more powerful as the game progresses. The bonus format specifies the condition (e.g., `PLAYER_UPGRADE`), the property to modify (e.g., `DAMAGE`, `RANGE`), and the modifier value (e.g., `125%` for 25% increase, or `+50` for absolute increase). This allows creating upgradeable weapons that improve with technology or experience. +- **Example**: `WeaponBonus = PLAYER_UPGRADE DAMAGE 125%` + +### Historic Bonus Properties + +#### `HistoricBonusTime` *(v1.04)* +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time window (in milliseconds) within which multiple weapon instances must fire to trigger the historic bonus. When multiple units with this weapon fire within this time window and within the [`HistoricBonusRadius`](#historicbonusradius), and the total number of firing instances reaches [`HistoricBonusCount`](#historicbonuscount), the historic bonus is triggered and the [`HistoricBonusWeapon`](#historicbonusweapon) is fired. This creates a coordinated attack bonus where multiple units firing together can trigger a special weapon. The time window starts when the first weapon fires, and all qualifying weapon fires must occur within this duration. If the time window expires before the required count is reached, the counter resets. This property works in combination with [`HistoricBonusRadius`](#historicbonusradius), [`HistoricBonusCount`](#historicbonuscount), and [`HistoricBonusWeapon`](#historicbonusweapon) to create coordinated attack bonuses. +- **Example**: `HistoricBonusTime = 5000` + +#### `HistoricBonusRadius` *(v1.04)* +- **Type**: `Real` +- **Description**: Radius (in world units) within which weapon instances must be located to count toward the historic bonus trigger. When multiple units with this weapon fire, only those within this radius of each other are considered for the historic bonus count. The radius is measured from the firing units' positions, and all qualifying units must be within this distance of each other. This ensures that only coordinated attacks from nearby units can trigger the historic bonus, creating a tactical requirement for units to be positioned together. This property works in combination with [`HistoricBonusTime`](#historicbonustime), [`HistoricBonusCount`](#historicbonuscount), and [`HistoricBonusWeapon`](#historicbonusweapon) to create coordinated attack bonuses. +- **Example**: `HistoricBonusRadius = 100.0` + +#### `HistoricBonusCount` *(v1.04)* +- **Type**: `Int` +- **Description**: Minimum number of weapon instances that must fire within the [`HistoricBonusTime`](#historicbonustime) window and within the [`HistoricBonusRadius`](#historicbonusradius) to trigger the historic bonus. When this many units with this weapon fire within the time window and radius, the historic bonus is activated and the [`HistoricBonusWeapon`](#historicbonusweapon) is fired. This creates a requirement for coordinated attacks, where multiple units must fire together to unlock the special bonus weapon. Higher values require more coordination and units, making the bonus more difficult to trigger but potentially more powerful. This property works in combination with [`HistoricBonusTime`](#historicbonustime), [`HistoricBonusRadius`](#historicbonusradius), and [`HistoricBonusWeapon`](#historicbonusweapon) to create coordinated attack bonuses. +- **Example**: `HistoricBonusCount = 3` + +#### `HistoricBonusWeapon` *(v1.04)* +- **Type**: `weapon` (see [Weapon documentation](Weapon.md)) +- **Description**: The weapon template that is fired when the historic bonus conditions are met. When [`HistoricBonusCount`](#historicbonuscount) weapon instances fire within the [`HistoricBonusTime`](#historicbonustime) window and within the [`HistoricBonusRadius`](#historicbonusradius), this weapon is automatically fired as a bonus effect. This allows creating special coordinated attack bonuses, such as a nuclear strike when multiple units fire together, or other powerful effects that reward tactical coordination. The weapon is fired at a location determined by the game logic (typically at or near the target of the coordinated attack). This property works in combination with [`HistoricBonusTime`](#historicbonustime), [`HistoricBonusRadius`](#historicbonusradius), and [`HistoricBonusCount`](#historicbonuscount) to create coordinated attack bonuses. The weapon must be defined in the game's weapon definitions. +- **Example**: `HistoricBonusWeapon = NuclearStrike` + +### Scatter and Accuracy Properties + +#### `ScatterTarget` *(v1.04)* +- **Type**: `Coord2D` (multiple entries) +- **Description**: Specific preset coordinates (relative to the target position) that define where projectiles will impact instead of using random scatter. When this property is used, the weapon cycles through these preset coordinates for each shot, creating a predictable scatter pattern. The coordinates are specified as X, Y offsets from the target position in world units. Multiple entries can be specified, and the weapon will cycle through them sequentially. This allows creating specific impact patterns like a cross, circle, or grid formation. The coordinates can be scaled using [`ScatterTargetScalar`](#scattertargetscalar) to adjust the spread without redefining all coordinates. If this property is not used, the weapon uses random scatter based on [`ScatterRadius`](#scatterradius) and [`ScatterRadiusVsInfantry`](#scatterradiusvsinfantry) instead. +- **Example**: +``` +ScatterTarget = 10.0, 5.0 +ScatterTarget = -5.0, 15.0 +``` + +#### `ShotsPerBarrel` *(v1.04)* +- **Type**: `Int` +- **Description**: Number of shots that must be fired from the current barrel or launch point before the weapon cycles to the next available barrel or launch point. This property is used for multi-barrel weapons (like rocket launchers with multiple tubes or multi-cannon weapons) to control the firing sequence. When a weapon has multiple barrels or launch points defined on the unit's model, this property determines how many shots are fired from each barrel before moving to the next one. This creates a realistic firing pattern where barrels fire in sequence rather than all at once. For example, if set to 3, the weapon will fire 3 shots from the first barrel, then 3 shots from the second barrel, and so on, cycling through all available barrels. If set to 0 or 1, the weapon cycles to the next barrel after each shot. This property only has an effect if the unit has multiple barrels or launch points defined in its model. +- **Default**: `0` +- **Example**: `ShotsPerBarrel = 3` + +### Additional Advanced Properties + +#### `LeechRangeWeapon` *(v1.04)* +- **Type**: `Bool` +- **Description**: When enabled, once the weapon fires at a target within its normal [`AttackRange`](#attackrange), it gains unlimited range for the remainder of that attack cycle. This allows the weapon to continue tracking and hitting the target even if it moves beyond the normal attack range. The "leech range" is activated when the weapon fires and remains active until the attack cycle completes (e.g., projectile hits or misses, or the attack is cancelled). This is useful for weapons like homing missiles that should maintain lock-on regardless of range after launch. If disabled, the weapon respects normal range limits throughout the entire attack. +- **Default**: `No` +- **Example**: `LeechRangeWeapon = Yes` + +#### `CapableOfFollowingWaypoints` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the [`ProjectileObject`](#projectileobject) from this weapon can follow waypoint paths defined in the projectile's object definition. When enabled, projectiles can navigate through a series of waypoints instead of traveling directly to the target. This allows creating complex flight paths, curved trajectories, or projectiles that navigate around obstacles. The waypoints must be defined in the projectile object's definition. When disabled, projectiles travel directly toward their target in a straight line (or following their normal trajectory). This property only applies to weapons with a [`ProjectileObject`](#projectileobject) specified. Useful for cruise missiles, guided projectiles, or weapons that need to follow specific flight paths. +- **Default**: `No` +- **Example**: `CapableOfFollowingWaypoints = Yes` + +#### `ShowsAmmoPips` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon displays ammunition pips (visual indicators) in the user interface to show the current ammunition status. When enabled, the UI displays small pips or indicators that represent the current ammunition count, typically shown as filled or empty pips corresponding to the number of shots remaining in the clip. This provides visual feedback to the player about the weapon's ammunition status. The pips are typically displayed near the unit's health bar or in the unit's status display. When disabled, no ammunition indicators are shown in the UI. This property is useful for weapons with limited ammunition (when [`ClipSize`](#clipsize) > 0) to provide visual feedback about remaining shots. +- **Default**: `No` +- **Example**: `ShowsAmmoPips = Yes` + +#### `AllowAttackGarrisonedBldgs` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether the weapon can attack garrisoned buildings even when the estimated damage would be zero (typically due to the building's armor or the weapon's damage type being ineffective). When enabled, the weapon can still acquire and fire at garrisoned buildings even if the damage calculation indicates no damage would be dealt. This allows weapons to attack buildings for tactical purposes (like suppressing fire, visual effects, or triggering building behaviors) even when they cannot damage them. When disabled, the weapon will not attack garrisoned buildings if the estimated damage is zero, preventing wasted attacks on invulnerable targets. This property is useful for weapons that should be able to target buildings for non-damage purposes, or weapons that should skip ineffective targets. +- **Default**: `No` +- **Example**: `AllowAttackGarrisonedBldgs = No` + +#### `PlayFXWhenStealthed` *(v1.04)* +- **Type**: `Bool` +- **Description**: Whether visual effects (specified by [`FireFX`](#firefx), [`ProjectileDetonationFX`](#projectiledetonationfx), and related properties) are played even when the firing unit is in a stealthed state. When enabled, the weapon's visual effects are displayed normally even if the firing unit is stealthed, potentially revealing the unit's position. When disabled, visual effects are suppressed when the firing unit is stealthed, helping maintain stealth. This property allows balancing stealth mechanics - weapons that should reveal the unit when firing (like loud explosions) can have this enabled, while weapons that should maintain stealth (like silenced weapons) can have this disabled. The audio effects are typically not affected by this property and may still play based on other game logic. +- **Default**: `No` +- **Example**: `PlayFXWhenStealthed = No` + +#### `SuspendFXDelay` *(v1.04)* +- **Type**: `UnsignedInt` (milliseconds) +- **Description**: Time delay (in milliseconds) before visual effects are suspended or stopped. This property controls how long visual effects (specified by [`FireFX`](#firefx), [`ProjectileDetonationFX`](#projectiledetonationfx), and related properties) continue to play before being automatically suspended. After this duration, the effects are stopped or suspended, even if they would normally continue playing. This is useful for managing effect duration, preventing effects from playing indefinitely, or creating timed visual effects. If set to 0, effects are not automatically suspended and play for their natural duration. This property works in combination with the effect system to control effect lifetime. +- **Default**: `0` +- **Example**: `SuspendFXDelay = 2000` + +#### `MissileCallsOnDie` *(v1.04, Generals Zero Hour only)* +- **Type**: `Bool` +- **Description**: Whether the [`ProjectileObject`](#projectileobject) (when it is a missile) calls its `OnDie` script or behavior when it detonates normally. When enabled, the missile's `OnDie` script or death behavior is triggered when the missile detonates (hits its target, reaches its destination, or detonates normally). This allows missiles to execute custom scripts, spawn objects, trigger effects, or perform other actions when they detonate. When disabled, the missile's `OnDie` is not called during normal detonation, only when the missile is destroyed by other means (like being shot down). This property only applies to weapons with a [`ProjectileObject`](#projectileobject) that is a missile-type object. Useful for missiles that need to trigger special behaviors or scripts upon detonation. +- **Default**: `No` +- **Example**: `MissileCallsOnDie = Yes` + +## Enum Value Lists + +**Note**: Some enums used by Weapon have their own dedicated documentation files and their details are not listed here: +- **`DamageType`** - See [DamageType documentation](Enum/DamageType.md) +- **`ObjectStatusTypes`** - See [ObjectStatusTypes documentation](../Object/Enums/ObjectStatusTypes.md) +- **`KindOfMaskType`** - See [KindOf documentation](../Object/Enums/KindOf.md) + + +#### `DeathType` Values *(v1.04)* +**Source:** [Damage.h](../../Code/GameEngine/Include/GameLogic/Damage.h) - `DeathType` enum definition + +- **`NORMAL`** *(v1.04)* - Standard death animation. The default death type used for most weapons when no specific death type is required. Units killed with this death type use their standard death animation and visual effects as defined in the unit's object definition. This is the most common death type and provides a generic death animation that works for most situations. The death animation typically shows the unit collapsing or falling over in a standard manner. Used by default for most weapons (especially bullet-based weapons), scripted damage, and when no special death effect is needed. This death type does not trigger any special visual or audio effects beyond the unit's standard death animation. +- **`EXPLODED`** *(v1.04)* - Explosion death. Used when units are killed by explosive weapons such as grenades, rockets, artillery shells, or other explosive ordnance. This death type triggers explosion visual effects (typically fire and smoke), explosion animations, and explosion audio effects. The death animation shows the unit being destroyed in an explosion, with debris and fire effects. Commonly used with explosive damage types like [`DAMAGE_EXPLOSION`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) to create appropriate death visuals that match the weapon type. This death type is ideal for weapons that cause explosive damage, as it provides visual and audio feedback that matches the destructive nature of the weapon. The explosion effects are typically more dramatic than standard death animations, providing clear visual feedback that the unit was destroyed by an explosion. +- **`BURNED`** *(v1.04)* - Fire death. Used when units are killed by fire-based weapons. This death type triggers fire-related death animations and visual effects. Special handling: when a weapon with [`DEATH_BURNED`](#deathtype-values) targets shrubbery ([`SHRUBBERY`](../Object/Enums/KindOf.md) (see [KindOf documentation](../Object/Enums/KindOf.md))), it always returns a valid damage estimate (1.0) regardless of other factors, allowing flame weapons to target and destroy vegetation. Commonly used with [`DAMAGE_FLAME`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type. +- **`LASERED`** *(v1.04)* - Laser death. Used when units are killed by laser weapons. This death type triggers laser-specific death animations and visual effects. Used with precision energy weapons to create appropriate death visuals. Commonly paired with [`DAMAGE_LASER`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type. +- **`SUICIDED`** *(v1.04)* - Suicide death. Used when units kill themselves, typically through self-destruct mechanisms, suicide attacks, or scripted suicide behaviors. This death type is used for scripted suicides and self-destruct behaviors where the unit intentionally destroys itself. The death animation and effects reflect a self-inflicted death rather than being killed by an external source, which may affect how the death is displayed or counted in game statistics. This death type is commonly used for terrorist units, suicide bombers, self-destructing vehicles, or units that explode when destroyed. The visual effects may differ from standard death animations to indicate that the unit destroyed itself intentionally, and the death may not count as a kill for the attacking player in some game modes. +- **`CRUSHED`** *(v1.04)* - Crushed death. Used when units are crushed by heavier units or objects. This death type is automatically applied when units are run over by vehicles or crushed by falling objects. Applied during collision detection when a unit is crushed. Death animations show the unit being flattened or crushed. Used with [`DAMAGE_CRUSH`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type. +- **`DETONATED`** *(v1.04)* - Detonation death. Used when projectiles, missiles, or explosive objects detonate normally (as opposed to being shot down, destroyed, or intercepted). This death type represents the normal, intended detonation of an explosive object when it reaches its target or destination, rather than its destruction by other means. The death animation and effects show the explosive object detonating as intended, with appropriate explosion visual and audio effects. Used to distinguish between normal detonations (where the explosive object successfully detonates) and other forms of destruction (where the object is destroyed before it can detonate). This death type is commonly used for missiles, bombs, or other explosive projectiles that are designed to detonate on impact or at a specific location. The visual effects typically show a controlled explosion appropriate for the explosive object's type and size. +- **`TOPPLED`** *(v1.04)* - Toppled death. Used when structures fall over or are toppled. This death type is used for structures that collapse rather than explode. The death animation shows the structure falling over. Used with [`DAMAGE_TOPPLING`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type. +- **`FLOODED`** *(v1.04)* - Flooded death. Used when units are killed by water or flooding. This death type is used by wave guide systems and water-based damage. Units killed by flooding use this death type to show appropriate death visuals. Used with [`DAMAGE_WATER`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type. +- **`SPLATTED`** *(v1.04)* - Splatted death. Used when units fall from heights and are killed by fall damage. This death type is automatically applied by the physics system when units take fatal fall damage. The death animation shows the unit being flattened from impact. Used with [`DAMAGE_FALLING`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type. +- **`POISONED`** *(v1.04)* - Poisoned death. Used when units are killed by poison. This death type is used by poison-based weapons and behaviors. Units killed by poison use this death type to show appropriate death visuals. Used with [`DAMAGE_POISON`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) damage type and `PoisonedBehavior` module. +- **`POISONED_BETA`** *(v1.04)* - Alternative poisoned death. A variant of poisoned death used for different poison effects or visual styles. Used as an alternative to `POISONED` when a different poison death animation is desired. +- **`EXTRA_1`** through **`EXTRA_10`** *(v1.04)* - Custom death types. Reserved death types for modders to define custom death animations and behaviors. These death types can be used to create unique death effects that don't fit into the standard categories. Each extra death type can be assigned custom visual effects and animations through the object's death modules. + + +#### `WeaponPrefireType` Values *(v1.04)* +**Source:** [Weapon.h](../../Code/GameEngine/Include/GameLogic/Weapon.h#77) - `WeaponPrefireType` enum definition + +- **`PER_SHOT`** *(v1.04)* - Prefire delay for every shot. The `PreAttackDelay` is applied before every single shot fired by this weapon, regardless of target or clip status. This creates a consistent delay between each shot, useful for weapons that need time to aim, charge, or prepare before each individual shot. This is the default behavior and provides the most predictable firing pattern. Useful for weapons that require precise aiming before each shot, such as sniper rifles or charged weapons. +- **`PER_ATTACK`** *(v1.04)* - Prefire delay for each new target. The `PreAttackDelay` is only applied when starting to attack a new target. Once the weapon has fired at least one shot at a target, subsequent shots at the same target do not apply the prefire delay. The game tracks how many shots have been fired at the current target, and if any shots have already been fired, the prefire delay is skipped. This allows weapons to have an initial aiming/charging delay when acquiring a new target, but then fire rapidly at the same target. Useful for weapons that need time to lock onto a new target but can then fire quickly at that target, such as missile launchers or weapons with target acquisition systems. +- **`PER_CLIP`** *(v1.04)* - Prefire delay for each new clip. The `PreAttackDelay` is only applied when firing the first shot from a new clip. If the weapon has a `ClipSize` greater than 0 and the current ammo in clip is less than the clip size (meaning it's not the first shot in the clip), the prefire delay is skipped. This allows weapons to have a delay when starting a new clip but then fire rapidly for the rest of the clip. Useful for weapons that need time to prepare or charge when loading a new clip, such as weapons with clip-based charging mechanisms or weapons that need to stabilize after reloading. + + +#### `WeaponAffectsMaskType` Values *(v1.04)* +**Source:** [Weapon.h](../../Code/GameEngine/Include/GameLogic/Weapon.h#110) - `WeaponAffectsMaskType` enum definition + +- **`SELF`** *(v1.04)* - Affects the firing unit. When set, the weapon's radius damage can affect the unit that fired it. By default, the firing unit is excluded from radius damage to prevent self-damage. When this flag is set, the firing unit can be damaged by its own weapon's area effect. If the potential victim is the same unit that fired the weapon (or the unit that created the projectile), the victim is included only if this flag is set. Useful for suicide weapons or weapons where self-damage is intentional, such as car bombs or area-effect weapons that should damage the user. +- **`ALLIES`** *(v1.04)* - Affects allied units. When set, the weapon's radius damage affects units that are allied to the firing unit. Allied units are those with an `ALLIES` relationship to the source. This flag controls whether friendly fire is enabled for area damage. If the potential victim is allied to the firing unit, the victim is included only if this flag is set. By default, most weapons include this flag to allow area damage to affect allies. Useful for weapons where friendly fire is acceptable or desired, such as artillery or area-effect weapons. +- **`ENEMIES`** *(v1.04)* - Affects enemy units. When set, the weapon's radius damage affects units that are enemies of the firing unit. Enemy units are those with an `ENEMIES` relationship to the source. This flag controls whether the weapon can damage enemy units within the radius (excluding the primary target, which is always affected). If the potential victim is an enemy of the firing unit, the victim is included only if this flag is set. This is the most common flag and is typically included for offensive weapons. Note: The primary target is always affected regardless of this flag - this flag only affects secondary targets within the radius. +- **`NEUTRALS`** *(v1.04)* - Affects neutral units. When set, the weapon's radius damage affects units that are neutral to the firing unit. Neutral units are those with a `NEUTRAL` relationship to the source. This flag controls whether the weapon can damage neutral units (such as civilians or neutral structures) within the radius. If the potential victim is neutral to the firing unit, the victim is included only if this flag is set. Useful for weapons that should affect neutral units, such as area-effect weapons that don't distinguish between friend and foe, or weapons designed to clear neutral obstacles. +- **`SUICIDE`** *(v1.04)* - Ensures firing unit cannot survive self-damage. When set, this flag guarantees that the firing unit will be killed by its own weapon, even if the calculated damage would not normally be fatal. If this flag is set and the potential victim is the source unit itself, the unit is forced to die. This ensures that suicide weapons always kill the user, regardless of health, armor, or damage calculations. Enough damage is dealt to guarantee death when this flag is active. Used for suicide weapons like car bombs, terrorist attacks, or self-destruct mechanisms where the user must die when the weapon is used. +- **`NOT_SIMILAR`** *(v1.04)* - Doesn't affect similar units (prevents chain reactions). When set, the weapon's radius damage will not affect units that are the same type as the firing unit and are allied to it. If the potential victim is the same unit type as the firing unit and is allied to it, the victim is excluded from damage. This prevents chain reactions where one unit's explosion kills nearby units of the same type, which then explode and kill more, creating a domino effect. Useful for weapons used by groups of similar units (like terrorist bombs) where you want to prevent all units in a group from exploding simultaneously. The primary target is still affected - this only applies to secondary targets within the radius. +- **`NOT_AIRBORNE`** *(v1.04)* - Doesn't affect airborne units (unless primary target). When set, the weapon's radius damage will not affect units that are significantly above the terrain (airborne units), unless the airborne unit is the primary target. If a potential victim is airborne and is not the primary target, the victim is excluded from damage. This allows weapons to affect ground units while ignoring aircraft or paratroopers in the area. Useful for ground-based area weapons like poison fields, radiation zones, or ground explosions that should not affect aircraft. The primary target is always affected regardless of this flag - this only applies to secondary targets within the radius. + + +#### `WeaponCollideMaskType` Values *(v1.04)* +**Source:** [Weapon.h](../../Code/GameEngine/Include/GameLogic/Weapon.h#136) - `WeaponCollideMaskType` enum definition + +- **`ALLIES`** *(v1.04)* - Projectiles collide with allied units. When set, projectiles from this weapon will collide with and detonate when hitting units that are allied to the firing unit. If the potential collision target is allied to the firing unit, a collision occurs only if this flag is set. This allows projectiles to pass through friendly units (when not set) or collide with them (when set). Useful for weapons that should not be blocked by friendly units, or weapons where friendly collisions are desired for gameplay reasons. Note: The primary target is always collided with regardless of this flag - this only applies to non-targeted units that get in the way. +- **`ENEMIES`** *(v1.04)* - Projectiles collide with enemy units. When set, projectiles from this weapon will collide with and detonate when hitting enemy units that are not the primary target. If the potential collision target is an enemy of the firing unit, a collision occurs only if this flag is set. This allows projectiles to pass through enemy units (when not set) or collide with them (when set). Useful for weapons that should only hit their intended target, or weapons where hitting any enemy is desired. Note: The primary target is always collided with regardless of this flag - this only applies to non-targeted units that get in the way. +- **`STRUCTURES`** *(v1.04)* - Projectiles collide with structures. When set, projectiles from this weapon will collide with and detonate when hitting structures that are not controlled by the projectile's owner. If the potential collision target is a structure (has the [`STRUCTURE`](../Object/Enums/KindOf.md) (see [KindOf documentation](../Object/Enums/KindOf.md)) flag) and is not controlled by the same player as the projectile, a collision occurs only if this flag is set. This flag specifically excludes structures controlled by the projectile's owner - use `CONTROLLED_STRUCTURES` to collide with owner's structures. Useful for weapons that should be blocked by enemy or neutral structures, such as most projectile weapons. This is the default collision flag for most weapons. +- **`SHRUBBERY`** *(v1.04)* - Projectiles collide with shrubbery. When set, projectiles from this weapon will collide with and detonate when hitting vegetation, trees, or other shrubbery objects. If the potential collision target is shrubbery (has the [`SHRUBBERY`](../Object/Enums/KindOf.md) (see [KindOf documentation](../Object/Enums/KindOf.md)) flag), a collision occurs only if this flag is set. This allows projectiles to pass through vegetation (when not set) or be blocked by it (when set). Useful for weapons that should interact with terrain features, or weapons that should ignore vegetation for gameplay reasons. +- **`PROJECTILES`** *(v1.04)* - Projectiles collide with other projectiles. When set, projectiles from this weapon will collide with and detonate when hitting other projectiles in flight. If the potential collision target is a projectile (has the [`PROJECTILE`](../Object/Enums/KindOf.md) (see [KindOf documentation](../Object/Enums/KindOf.md)) flag), a collision occurs only if this flag is set. This enables projectile interception mechanics, allowing weapons to shoot down incoming projectiles. Useful for point defense weapons, anti-missile systems, or weapons designed to intercept other projectiles. Note: All missiles are also projectiles, so this flag affects missiles as well. +- **`WALLS`** *(v1.04)* - Projectiles collide with walls. When set, projectiles from this weapon will collide with and detonate when hitting walls or fences. If the potential collision target is a wall or fence, a collision occurs only if this flag is set. This allows projectiles to pass through walls (when not set) or be blocked by them (when set). Useful for weapons that should interact with map geometry, or weapons that should ignore walls for gameplay reasons. +- **`SMALL_MISSILES`** *(v1.04)* - Projectiles collide with small missiles. When set, projectiles from this weapon will collide with and detonate when hitting small missiles. If the potential collision target is a small missile (has the [`SMALL_MISSILE`](../Object/Enums/KindOf.md) (see [KindOf documentation](../Object/Enums/KindOf.md)) flag), a collision occurs only if this flag is set. Note that all missiles are also projectiles, so the `PROJECTILES` flag also affects missiles. This flag provides specific targeting for small missiles, allowing weapons to specifically target this missile type. Useful for point defense weapons that need to distinguish between different missile types, or weapons designed specifically to intercept small missiles. +- **`BALLISTIC_MISSILES`** *(v1.04)* - Projectiles collide with ballistic missiles. When set, projectiles from this weapon will collide with and detonate when hitting ballistic missiles (large missiles typically used by superweapons). If the potential collision target is a ballistic missile (has the [`BALLISTIC_MISSILE`](../Object/Enums/KindOf.md) (see [KindOf documentation](../Object/Enums/KindOf.md)) flag), a collision occurs only if this flag is set. Note that all missiles are also projectiles, so the `PROJECTILES` flag also affects missiles. This flag provides specific targeting for ballistic missiles, allowing weapons to specifically target this missile type. Useful for base defense weapons, anti-missile systems, or weapons designed specifically to intercept large ballistic missiles from superweapons. +- **`CONTROLLED_STRUCTURES`** *(v1.04)* - Projectiles collide with structures controlled by the same player. When set, projectiles from this weapon will collide with and detonate when hitting structures that are controlled by the same player as the projectile's owner. If the potential collision target is a structure and is controlled by the same player, a collision occurs only if this flag is set. This is separate from the `STRUCTURES` flag, which only affects structures not controlled by the owner. This allows fine-grained control over whether projectiles can pass through the owner's own structures. Useful for weapons that should be blocked by friendly structures, or weapons that should ignore friendly structures to prevent accidental friendly fire on your own buildings. + + +## Examples + +### Basic Infantry Weapon +``` +Weapon USAInfantryRifle + PrimaryDamage = 25.0 + PrimaryDamageRadius = 0.0 + AttackRange = 200.0 + MinimumAttackRange = 0.0 + AcceptableAimDelta = 5.0 + DamageType = BULLET + DeathType = NORMAL + WeaponSpeed = 1000.0 + DelayBetweenShots = 1000 + ClipSize = 30 + ClipReloadTime = 3000 + AutoReloadsClip = Yes + RadiusDamageAffects = ENEMIES + AntiGround = Yes + AntiAirborneInfantry = Yes + FireSound = RifleFire + FireFX = FX_RifleMuzzleFlash +End +``` + +### Tank Cannon Weapon +``` +Weapon USATankCannon + PrimaryDamage = 150.0 + PrimaryDamageRadius = 5.0 + SecondaryDamage = 75.0 + SecondaryDamageRadius = 15.0 + AttackRange = 300.0 + MinimumAttackRange = 10.0 + AcceptableAimDelta = 2.0 + DamageType = EXPLOSION + DeathType = EXPLODED + WeaponSpeed = 800.0 + ProjectileObject = TankShell + DelayBetweenShots = 3000 + ClipSize = 1 + ClipReloadTime = 3000 + AutoReloadsClip = Yes + RadiusDamageAffects = ALLIES ENEMIES NEUTRALS + AntiGround = Yes + AntiAirborneVehicle = Yes + FireSound = TankCannonFire + FireFX = FX_TankCannonMuzzleFlash + ProjectileDetonationFX = FX_ExplosionLarge + ProjectileCollidesWith = STRUCTURES WALLS + ShockWaveAmount = 10.0 + ShockWaveRadius = 20.0 + ShockWaveTaperOff = 0.5 +End +``` + +### Missile Weapon +``` +Weapon USAMissileLauncher + PrimaryDamage = 200.0 + PrimaryDamageRadius = 10.0 + SecondaryDamage = 100.0 + SecondaryDamageRadius = 25.0 + AttackRange = 400.0 + MinimumAttackRange = 50.0 + AcceptableAimDelta = 1.0 + DamageType = EXPLOSION + DeathType = EXPLODED + WeaponSpeed = 600.0 + ProjectileObject = AntiTankMissile + DelayBetweenShots = 5000 + ClipSize = 1 + ClipReloadTime = 5000 + AutoReloadsClip = Yes + RadiusDamageAffects = ALLIES ENEMIES NEUTRALS + AntiGround = Yes + AntiAirborneVehicle = Yes + FireSound = MissileLaunch + FireFX = FX_MissileLaunch + ProjectileDetonationFX = FX_MissileExplosion + ProjectileCollidesWith = STRUCTURES WALLS PROJECTILES + ShockWaveAmount = 15.0 + ShockWaveRadius = 30.0 + ShockWaveTaperOff = 0.4 +End +``` + +### Status Effect Weapon +``` +Weapon StealthHawkTargetDesignator + PrimaryDamage = 10.0 + PrimaryDamageRadius = 10.0 + AcceptableAimDelta = 1.0 + AttackRange = 450.0 + MinimumAttackRange = 5.0 + PreAttackDelay = 5000 + PreAttackType = PER_SHOT + DamageType = STATUS + DamageStatusType = CAN_ATTACK + ProjectileObject = S300Fakemissile + ClipSize = 1 + ClipReloadTime = 60000 + AutoReloadsClip = Yes + AutoReloadWhenIdle = 60000 + FireFX = FX_StealthHawkAttackAirstrike +End +``` + +### Area Effect Weapon +``` +Weapon SCUDMissileDetonation + PrimaryDamage = 350.0 + PrimaryDamageRadius = 40.0 + SecondaryDamage = 200.0 + SecondaryDamageRadius = 60.0 + AttackRange = 100.0 + DamageType = FLAME + DeathType = EXPLODED + RadiusDamageAffects = ALLIES ENEMIES NEUTRALS NOT_SIMILAR + FireSound = ScudLauncherWeapon + DelayBetweenShots = 30000 + ClipSize = 1 + ClipReloadTime = 30000 + ProjectileCollidesWith = STRUCTURES + ShockWaveAmount = 25.0 + ShockWaveRadius = 70.0 + ShockWaveTaperOff = 0.50 +End +``` + +### Anti-Air Weapon +``` +Weapon AntiAirMissile + PrimaryDamage = 100.0 + PrimaryDamageRadius = 5.0 + AttackRange = 350.0 + MinimumAttackRange = 20.0 + AcceptableAimDelta = 3.0 + DamageType = EXPLOSION + DeathType = EXPLODED + WeaponSpeed = 1200.0 + ProjectileObject = AntiAirMissile + DelayBetweenShots = 2000 + ClipSize = 4 + ClipReloadTime = 8000 + AutoReloadsClip = Yes + RadiusDamageAffects = ENEMIES + AntiAirborneVehicle = Yes + AntiAirborneInfantry = Yes + AntiProjectile = Yes + AntiSmallMissile = Yes + FireSound = AntiAirMissileLaunch + FireFX = FX_AntiAirLaunch + ProjectileDetonationFX = FX_AntiAirExplosion +End +``` + +### Point Defense Weapon +``` +Weapon PointDefenseLaser + PrimaryDamage = 350.0 + PrimaryDamageRadius = 22.5 + SecondaryDamage = 85.0 + SecondaryDamageRadius = 35.0 + AttackRange = 15.0 + DamageType = PENALTY + DeathType = LASERED + RadiusDamageAffects = SELF ALLIES ENEMIES NEUTRALS + WeaponSpeed = 999999.0 + DelayBetweenShots = 1 + ClipSize = 0 + ClipReloadTime = 0 + AcceptableAimDelta = 999 + AntiSmallMissile = No + AntiProjectile = No + AntiAirborneVehicle = No + AntiAirborneInfantry = No + AntiBallisticMissile = Yes +End +``` + +### Suicide Weapon +``` +Weapon CarbombExplosion + PrimaryDamage = 500.0 + PrimaryDamageRadius = 20.0 + AttackRange = 1.0 + DamageType = EXPLOSION + DeathType = EXPLODED + RadiusDamageAffects = ALLIES ENEMIES NEUTRALS NOT_SIMILAR + DamageDealtAtSelfPosition = Yes + WeaponSpeed = 999999.0 + ClipSize = 1 + ClipReloadTime = 999999 + AutoReloadsClip = No + FireFX = FX_CarbombExplosion + ShockWaveAmount = 20.0 + ShockWaveRadius = 25.0 + ShockWaveTaperOff = 0.3 +End +``` + +### Continuous Fire Weapon +``` +Weapon MinigunWeapon + PrimaryDamage = 15.0 + PrimaryDamageRadius = 0.0 + AttackRange = 250.0 + MinimumAttackRange = 0.0 + AcceptableAimDelta = 10.0 + DamageType = BULLET + DeathType = NORMAL + WeaponSpeed = 999999.0 + DelayBetweenShots = 100 + ClipSize = 200 + ClipReloadTime = 5000 + AutoReloadsClip = Yes + ContinuousFireOne = 10 + ContinuousFireTwo = 20 + ContinuousFireCoast = 500 + FireSoundLoopTime = 1000 + RadiusDamageAffects = ENEMIES + AntiGround = Yes + AntiAirborneInfantry = Yes + FireSound = MinigunFire + FireFX = FX_MinigunMuzzleFlash + ShowsAmmoPips = Yes +End +``` + +### Laser Weapon with Targeting Restrictions +``` +Weapon LaserCannon + PrimaryDamage = 100.0 + PrimaryDamageRadius = 2.0 + AttackRange = 400.0 + MinimumAttackRange = 20.0 + AcceptableAimDelta = 1.0 + DamageType = LASER + DeathType = LASERED + WeaponSpeed = 999999.0 + DelayBetweenShots = 2000 + ClipSize = 10 + ClipReloadTime = 8000 + AutoReloadsClip = Yes + LaserName = LaserBeam + LaserBoneName = Muzzle + RadiusDamageAffects = ENEMIES + AntiGround = Yes + AntiAirborneVehicle = Yes + FireSound = LaserCannonFire + FireFX = FX_LaserCannonFire + ProjectileDetonationFX = FX_LaserImpact +End +``` + +### Scatter Weapon with Historic Bonus +``` +Weapon ArtilleryCannon + PrimaryDamage = 200.0 + PrimaryDamageRadius = 25.0 + SecondaryDamage = 100.0 + SecondaryDamageRadius = 40.0 + AttackRange = 500.0 + MinimumAttackRange = 100.0 + AcceptableAimDelta = 5.0 + DamageType = EXPLOSION + DeathType = EXPLODED + WeaponSpeed = 400.0 + ScaleWeaponSpeed = Yes + ProjectileObject = ArtilleryShell + DelayBetweenShots = 8000 + ClipSize = 1 + ClipReloadTime = 8000 + AutoReloadsClip = Yes + ScatterRadius = 10.0 + ScatterTargetScalar = 1.0 + ScatterTarget = 5.0, 0.0 + ScatterTarget = -5.0, 0.0 + ScatterTarget = 0.0, 5.0 + ScatterTarget = 0.0, -5.0 + HistoricBonusTime = 10000 + HistoricBonusRadius = 150.0 + HistoricBonusCount = 3 + HistoricBonusWeapon = NuclearStrike + RadiusDamageAffects = ALLIES ENEMIES NEUTRALS + AntiGround = Yes + FireSound = ArtilleryFire + FireFX = FX_ArtilleryMuzzleFlash + ProjectileDetonationFX = FX_ArtilleryExplosion + ProjectileCollidesWith = STRUCTURES WALLS + ShockWaveAmount = 15.0 + ShockWaveRadius = 35.0 + ShockWaveTaperOff = 0.4 +End +``` + +### Limited Area Effect Weapon +``` +Weapon PrecisionStrike + PrimaryDamage = 500.0 + PrimaryDamageRadius = 30.0 + AttackRange = 300.0 + DamageType = EXPLOSION + DeathType = EXPLODED + WeaponSpeed = 999999.0 + DelayBetweenShots = 15000 + ClipSize = 1 + ClipReloadTime = 15000 + AutoReloadsClip = Yes + RadiusDamageAffects = ENEMIES + AntiGround = Yes + FireSound = PrecisionStrikeLaunch + FireFX = FX_PrecisionStrikeLaunch + ProjectileDetonationFX = FX_PrecisionStrikeExplosion + ShockWaveAmount = 20.0 + ShockWaveRadius = 25.0 + ShockWaveTaperOff = 0.3 +End +``` + +## Usage + +Weapons are defined in `.ini` files within the game's data directories in a root folder called "Weapon". Multiple weapon entries can exist in the same file or across multiple files. Each weapon must have a unique name. See Template for correct syntax. + +**Limitations**: +- Each weapon must have a unique name - no two weapons can share the same name even across multiple files. +- Weapons are templates that are referenced by objects, not directly instantiated. +- Weapon slot assignment is handled by [WeaponSet](../WeaponSet.md), not by the Weapon template itself. + +**Conditions**: +- Weapons are referenced by units, buildings, and special powers through [WeaponSet](../WeaponSet.md) to define their combat capabilities. +- When a weapon is assigned to a weapon slot, it becomes available for that object to use in combat. +- The game automatically selects the appropriate weapon slot based on target type, range, and weapon preferences. + +**Dependencies**: +- Weapons are assigned to objects through [WeaponSet](../WeaponSet.md) which manages multiple weapons on an object. +- Weapons that use projectiles require a valid [Object](../Object.md) template for the `ProjectileObject` property. +- Weapons that use visual effects require valid [FXList](../FXList.md) templates for `FireFX` and `ProjectileDetonationFX` properties. +- Weapons that use status effects require [`DamageType = STATUS`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) and a valid `DamageStatusType` value. + +## Template + +```ini +Weapon WeaponName + PrimaryDamage = 0.0 ; // Main damage amount *(v1.04)* + PrimaryDamageRadius = 0.0 ; // Primary damage radius *(v1.04)* + SecondaryDamage = 0.0 ; // Secondary damage amount *(v1.04)* + SecondaryDamageRadius = 0.0 ; // Secondary damage radius *(v1.04)* + DamageType = EXPLOSION ; // Damage type (see DamageType documentation) *(v1.04)* + DeathType = NORMAL ; // Death animation type *(v1.04)* + AttackRange = 0.0 ; // Maximum attack range *(v1.04)* + MinimumAttackRange = 0.0 ; // Minimum attack range *(v1.04)* + AcceptableAimDelta = 0.0 ; // Aim accuracy requirement (degrees) *(v1.04)* + WeaponSpeed = 999999.0 ; // Projectile speed (distance per second) *(v1.04)* + DelayBetweenShots = 0 ; // Time between shots (milliseconds) *(v1.04)* + ClipSize = 0 ; // Shots per clip (0 = infinite) *(v1.04)* + ClipReloadTime = 0 ; // Reload time (milliseconds) *(v1.04)* + AutoReloadsClip = YES ; // Auto-reload when clip empty *(v1.04)* + RadiusDamageAffects = ALLIES ENEMIES NEUTRALS ; // What is affected by radius damage *(v1.04)* + AntiGround = YES ; // Can target ground units *(v1.04)* +End +``` + +## Notes + +- Weapons are defined in `.ini` files within the game's data directories in a root folder called "Weapon". +- Each weapon must have a unique name - no two weapons can share the same name even across multiple files. +- Weapons can be referenced by units, buildings, and special powers. +- Veterancy levels affect visual effects and object creation lists. +- Projectile weapons create separate objects that handle their own movement and collision. +- Status effect weapons use [`DamageType = STATUS`](Enum/DamageType.md) (see [DamageType documentation](Enum/DamageType.md)) and specify the effect in [DamageStatusType](#damagestatustype). +- Area effect weapons use radius damage properties to affect multiple targets. +- Anti-air weapons should target airborne units and projectiles appropriately. +- Point defense weapons typically have very short ranges but high damage and fast firing rates. + +## Modder Recommended Use Scenarios + +(pending modder review) + +## Source Files + +**Header (Zero Hour):** [Weapon.h](../../Code/GameEngine/Include/GameLogic/Weapon.h) +**Source (Zero Hour):** [Weapon.cpp](../../Code/GameEngine/Source/GameLogic/Object/Weapon.cpp) +**Header (Generals):** [Weapon.h](../../../../Generals/Code/GameEngine/Include/GameLogic/Weapon.h) +**Source (Generals):** [Weapon.cpp](../../../../Generals/Code/GameEngine/Source/GameLogic/Object/Weapon.cpp) + +## Changes History + +### Retail Generals 1.04 → Retail Zero Hour 1.04 + +**7 new properties added** to enhance weapon functionality: + +- **`DamageStatusType`** *(v1.04, Zero Hour only)*: Added support for status effect weapons. See [`DamageStatusType`](#damagestatustype) property documentation. + +- **`ShockWaveAmount`**, **`ShockWaveRadius`**, **`ShockWaveTaperOff`** *(v1.04, Generals Zero Hour only)*: Added three properties for shockwave visual effects. See [`ShockWaveAmount`](#shockwaveamount), [`ShockWaveRadius`](#shockwaveradius), and [`ShockWaveTaperOff`](#shockwavetaperoff) property documentation. + +- **`RadiusDamageAngle`** *(v1.04, Generals Zero Hour only)*: Added support for directional radius damage. See [`RadiusDamageAngle`](#radiusdamageangle) property documentation. + +- **`LaserBoneName`** *(v1.04, Generals Zero Hour only)*: Added ability to specify laser attachment bone. See [`LaserBoneName`](#laserbonename) property documentation. + +- **`MissileCallsOnDie`** *(v1.04, Generals Zero Hour only)*: Added control over missile OnDie script execution. See [`MissileCallsOnDie`](#missilecallsondie) property documentation. + +## Document Log + +- 16/12/2025 — AI — Initial document created by AI + +## Status + +- Documentation Status: AI-generated +- Last Updated: 16/12/2025 by @AI +- Certification: 0/2 reviews + +## Reviewers + +- [ ] Reviewer 1 +- [ ] Reviewer 2 diff --git a/Docs/README.md b/Docs/README.md new file mode 100644 index 0000000000..364185c7a2 --- /dev/null +++ b/Docs/README.md @@ -0,0 +1,106 @@ +## Generals Modding Guide + +### What is this documentation and its purpose? + +This folder hosts the authoritative, living documentation for the community-maintained Generals Game Code project (Generals and Zero Hour). The docs explain how gameplay systems, INI classes, modules, behaviors, and enums work in this open-source upgrade of the original games, so modders can rely on a single, consistent reference. + +We expect the docs to be: + +- Accurate: Reflect the Retail 1.08 (Generals) and 1.04 (Zero Hour) code +- Complete: Each property lists type, description, default, example, and version flags +- Consistent: Shared concepts are described identically across documents +- Practical: Avoid engine-internal jargon; focus on modder outcomes + +### Versions explained (community upgrade branch) + +These docs track the community upgrade branch built on the classic releases. Use flags on every property and enum value to communicate baseline availability: + +- `*(Retail Generals 1.08 baseline)*` — rooted in the original Generals 1.08 behavior +- `*(Retail Zero Hour 1.04 baseline)*` — rooted in the original Zero Hour 1.04 behavior + +Notes: + +- The project fixes bugs and may add improvements while striving for compatibility; behavior may differ from the original binaries where fixes apply. +- When something exists only in Zero Hour, mark it `*(Retail Zero Hour 1.04 baseline)*`. + +### Why documentation belongs in the open-source community repo + +Keeping docs here ensures: + +- Updates to code and docs are reviewed together +- Docs remain current with fixes and clarifications +- Contributors can maintain docs alongside code changes +- Consistent standards across all documents + +### How documentation is created (with AI involvement) + +Process used to author and maintain Retail docs: + +1) Code and behavior study +- Identify the class/behavior and its base class +- Read `buildFieldParse` and `FieldParse` tables in `.cpp` +- Verify member types/defaults in headers +- Locate enums and their string tables + +2) Draft the document +- Overview and Usage (Limitations, Conditions, Dependencies) +- Properties: Type, Description, Default, Example, Version flags +- Enums: full value lists with flags +- Examples and a complete Template + +3) Versioning +- Mark Retail Generals 1.08 vs Retail Zero Hour 1.04 per property/enum value + +4) Cross-linking +- Link to other Retail docs using relative paths + +5) Review cycle +- Self-consistency check against related docs +- Peer review (target 2 approvals) +- Apply feedback and update Last Updated + Document Log + +6) AI assistance +- AI may assist with drafting and standardization +- Authors validate details against source and correct inaccuracies +- Avoid mentioning engine-internal function names in user-facing text + +### Contributor guide: required structure for each document + +1) Overview +2) Usage +- Limitations +- Conditions +- Dependencies + +3) Table of Contents + +4) Properties +- One subsection per property: Type, Description, Default, Example, Version flags +- Enum sections listing every value with flags + +5) Examples + +6) Template +- Use ```ini with inline comments and version flags +- Defaults should reflect source initializers + +7) Notes + +8) Source Files +- Base class line first +- Include both Retail Generals and Retail Zero Hour paths + +9) Changes History + +10) Document Log +- Reset to: “- 16/12/2025 — AI — Initial document created.” + +11) Status and Reviewers + +Style and consistency rules: + +- Use modder-friendly language; no internal function names +- Keep shared text identical across related body modules +- Use `Type: Alias (see [DocName](RelativePath.md))` for cross-references +- Apply the same section ordering across all docs +