Weapon Systems in OpenRA: Bullet and Missile Projectiles - guidebee/OpenRA GitHub Wiki

Weapon Systems in OpenRA: Bullet and Missile Projectiles

Introduction

OpenRA uses a sophisticated weapon system that combines projectiles and warheads to create varied combat experiences. This document explores how bullet and missile projectile types work, particularly focusing on damage mechanics, range definition, physics like gravity, and how warheads affect different actor types.

Projectile and Warhead Relationship

Weapons in OpenRA are defined through a combination of projectile types (which control movement patterns) and warheads (which determine effects upon impact). This separation allows for great flexibility in weapon design.

Core Components

  1. Weapon Definition: The main container that specifies:

    • Range parameters
    • Reload timing
    • Projectile type
    • Warheads to apply on impact

  2. Projectile: Determines how the weapon travels through the world

    • Movement patterns
    • Visual representation
    • Physics behaviors

  3. Warheads: Define what happens when the projectile reaches its target

    • Damage application
    • Special effects
    • Terrain modification

Bullet Projectiles

Bullets in OpenRA are typically implemented using the Bullet or InstantHit projectile types.

Example Definition

^HeavyMG:
  ReloadDelay: 35          # Time between shots in ticks
  Range: 6c0               # Maximum weapon range (6 cells)
  Report: gun13.aud        # Sound when firing
  ValidTargets: Ground, Water, GroundActor, WaterActor
  Projectile: InstantHit   # Instant hit projectile type (no travel time)
    Blockable: true        # Can be blocked by terrain/buildings
  Warhead@1Dam: SpreadDamage
    Spread: 128            # Damage radius
    Damage: 2500           # Base damage value

Key Characteristics

  1. Movement Mechanics:

    • InstantHit bullets have no travel time, hitting targets instantly
    • Regular Bullets travel at a defined speed and can arc based on LaunchAngle
    • Bullets can be affected by inaccuracy settings, causing them to deviate from the perfect line

  2. Range Definition:

    • Weapon range is defined by the Range parameter in the weapon definition
    • Bullets will travel exactly to the target position or maximum range
    • Some bullets can bounce off surfaces with the BounceCount parameter

  3. Gravity Effects:

    • Bullets can be affected by an arc defined through the LaunchAngle parameter
    • This creates parabolic trajectories similar to gravity effects
    • Unlike missiles, bullets don't have continuous gravity acceleration

  4. Damage Application:

    • Upon reaching the target or maximum range, bullets trigger their warheads
    • The SpreadDamage warhead is commonly used to apply damage in a radius
    • Damage can be modified based on armor types via the Versus property

Missile Projectiles

Missiles in OpenRA offer more complex behaviors, including homing capabilities and physics-based movement.

Example Definition

^AntiGroundMissile:
  ReloadDelay: 50
  Range: 5c0                # Maximum weapon range (5 cells)
  MinRange: 0c512           # Minimum weapon range
  Report: missile6.aud
  ValidTargets: Ground, Water, GroundActor, WaterActor
  Projectile: Missile
    Speed: 213              # Initial speed
    Arm: 2                  # Ticks before missile arms and can explode
    Blockable: false        # Ignores obstacles
    ContrailLength: 10      # Visual trail length
    Inaccuracy: 128         # Starting inaccuracy
    Image: DRAGON           # Visual representation
    Shadow: True            # Shows shadow on ground
    HorizontalRateOfTurn: 20 # How quickly it can change direction
    RangeLimit: 6c0         # Maximum distance missile can travel

Key Characteristics

  1. Movement Mechanics:

    • Missiles have physics-based movement with acceleration
    • Can home in on targets with a defined turning rate
    • Start in a "freefall" state before homing mode activates
    • Support terrain awareness for navigation around obstacles

  2. Range Definition:

    • Similar to bullets, the base range is defined in the weapon definition
    • Missiles have additional parameters like:
      • MinRange: Minimum firing distance
      • RangeLimit: Maximum travel distance (can be longer than targeting range)
      • CloseEnough: Proximity radius to trigger detonation

  3. Gravity Effects:

    • Missiles are heavily affected by gravity defined by the Gravity parameter
    • During "freefall" state, gravity pulls missiles downward
    • In "homing" state, missiles fight gravity to pursue targets
    • The TerrainHeightAware parameter allows missiles to detect and climb over terrain

  4. Homing Capabilities:

    • Can track moving targets with HorizontalRateOfTurn and VerticalRateOfTurn
    • LockOnProbability determines chance of successfully tracking target
    • Can be jammed by defensive systems through the Jammable property
    • AllowSnapping lets missiles jump to target position when very close

Warheads

Warheads define what happens when a projectile reaches its target. Multiple warheads can be attached to a single weapon to create complex effects.

SpreadDamageWarhead

The most common warhead type applies damage within a radius:

Warhead@1Dam: SpreadDamage
  Spread: 128              # Base damage radius
  Damage: 5000             # Base damage amount
  ValidTargets: GroundActor, WaterActor
  Versus:                  # Damage multipliers against armor types
    None: 10
    Wood: 74
    Light: 34
    Heavy: 100
    Concrete: 50
  DamageTypes: Prone50Percent, TriggerProne, ExplosionDeath

Damage Calculation

  1. Falloff Mechanics:

    • Damage decreases as distance from impact increases
    • Controlled by Falloff and Range or Spread parameters
    • Example: Falloff: { 100, 37, 14, 5, 0 } means 100% damage at center, 37% at first ring, etc.

  2. Armor Type Modifiers:

    • The Versus property defines effectiveness against different armor types
    • Values are percentages (100 = full damage, 50 = half damage)
    • Allows creating specialized weapons (anti-infantry, anti-vehicle, etc.)

  3. Hit Location:

    • DamageCalculationType determines how distance is calculated:
      • HitShape: Uses actor's defined collision shapes
      • ClosestTargetablePosition: Uses closest targetable position
      • CenterPosition: Uses actor's center

  4. Self-Damage:

    • Weapons can damage their own firer through CanTargetSelf property
    • Useful for creating self-destruct mechanics

Multiple Effect Warheads

Weapons typically have several warheads to create a complete effect:

Warhead@2Smu: LeaveSmudge     # Creates terrain damage
  SmudgeType: Crater
  ValidTargets: Ground, Infantry
Warhead@3Eff: CreateEffect     # Visual/audio effects
  Explosions: med_explosion
  ImpactSounds: kaboom25.aud
  ValidTargets: Ground, Air, GroundActor, AirborneActor, WaterActor, Trees
Warhead@4EffWater: CreateEffect # Water-specific effects
  Explosions: med_splash
  ImpactSounds: splash9.aud
  ValidTargets: Water, Underwater
  InvalidTargets: Bridge

Conclusion

The OpenRA weapon system's separation of projectiles and warheads creates a flexible framework for designing varied weapon behaviors. Bullets provide simple, direct attacks while missiles offer complex, physics-based behaviors. Warheads allow for specialized damage application and visual effects.

This design enables developers to create weapons ranging from simple machine guns to complex guided missiles with minimal code duplication by leveraging inheritance and composition through the YAML configuration system.