Skip to main content

Game Balance - Items

Overview#

Item Property Modification can be used to modify the balance properties of equipment items, such as weapons, grenades, packs and deployables.

All item modification functions and properties fall under the Items namespace. Properties fall under the Items.Properties namespace. So for instance, one could reference a property with Items.Properties.ClipAmmo.

When listing weapon types: the term shot weapons is used to refer to all weapons which act via shooting - i.e. all except grenades, mines and deployables.

Setting Item Properties#

Getter and Setter functions for property values are provided.

Items.setProperty(className: string, itemName: string, property: ItemProperty, value: T)

setProperty sets the value of the property property for the item itemName on the class className. The type T represents the type of the values of that property - depending on the property this may be a boolean, integer, float or string.

Items.getProperty(className: string, itemName: string, property: ItemProperty): T

getProperty retrieves the value of the given property. The type T is the type of values of that property.

Example#

Logger.setLevel(Logger.Levels.Info)
Logger.info("Old AR clip size: " .. Items.getProperty("Medium", "Light Assault Rifle", Items.Properties.ClipAmmo))
Items.setProperty("Medium", "Light Assault Rifle", Items.Properties.ClipAmmo, 50)
Logger.info("New AR clip size: " .. Items.getProperty("Medium", "Light Assault Rifle", Items.Properties.ClipAmmo))

Ammo#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
ClipAmmointegerWeapons with a clip> 0BulletsThe number of bullets in a clip
SpareAmmointegerAll weapons>= 0BulletsStarting amount of spare ammo
AmmoPerShotintegerAll weapons>= 0BulletsAmount of ammo consumed by each shot
LowAmmoCutoffintegerAll weapons>= 0BulletsAmmo count (either in the clip, or overall) at which 'low ammo' warnings will appear on the weapon

Reloading and Firing#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
ReloadTimefloatShot weapons> 0SecondsReload time
FireIntervalfloatShot weapons> 0SecondsTime between shots
HoldToFirebooleanAll weaponsWhether the player can hold the button to keep firing
CanZoombooleanAll weapons(Currently not working) Whether the weapon may be fired while zoomed
ReloadSinglebooleanWeapons with a clipWhether the weapon should be reloaded one bullet at a time, like the Light's shotgun
ReloadApplicationProportionfloatShot weapons0 <= x <= 1Proportion of the way through the reload that ammo actually reloads; affects reload cancelling
BurstShotCountintegerLight Assault Rifle> 0BulletsNumber of shots in a LAR burst
BurstShotRefireTimefloatLight Assault Rifle> 0SecondsTime between shots in a LAR burst
SpinupTimefloatChain gun/cannon, X1 LMG>= 0SecondsTime for chain-gun type weapons to spin up before firing begins
ShotgunShotCountintegerShotguns> 0ShotsNumber of shots fired with each shotgun blast
ShotEnergyCostfloatShot weapons>= 0EnergyAmount of energy consumed by shooting

Damage and Impact#

Damage#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
DamagefloatAll weapons>= 0DamageDamage the weapon does, before considering multipliers, falloff etc.
DirectHitMultiplierfloatProjectile weapons>= 0Damage multiplier to apply to the damage done on a direct hit
EnergyDrainfloatAll weapons>= 0EnergyAmount of energy to drain from targets
DamageAgainstArmorMultiplierfloatAll weapons>= 0Multiplier for damage against armoured targets
DamageAgainstGeneratorMultiplierfloatAll weapons>= 0Multiplier for damage against generators
DamageAgainstBaseTurretMultiplierfloatAll weapons>= 0Multiplier for damage against base turrets
DamageAgainstBaseSensorMultiplierfloatAll weapons>= 0Multiplier for damage against sensors
DamageAgainstGravCycleMultiplierfloatAll weapons>= 0Multiplier for damage against Grav Cycles
DamageAgainstBeowulfMultiplierfloatAll weapons>= 0Multiplier for damage against Beowulfs
DamageAgainstShrikeMultiplierfloatAll weapons>= 0Multiplier for damage against Shrikes

Impulse#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
ImpactMomentumfloatProjectile weapons>= 0MomentumAmount of momentum applied to a player hit by this weapon
SelfImpactMomentumMultiplierfloatProjectile weapons>= 0Multiplier to apply to the impact momentum when the player hit is the one who shot the weapon
SelfImpactExtraZMomentumfloatProjectile weapons>= 0MomentumAdditional vertical momentum to apply when self-impulsing

To give a sense of the reasonable scale for values: the Spinfusor gives 85000 units of ImpactMomentum, with a SelfImpactMomentumMultiplier of 1.5.

Falloff#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
ExplosiveRadiusfloatExplosive weapons>= 0UUSize of the weapon's damaging explosion
BulletDamageRangefloatBullet Weapons>= 0UUSize of the damage range (not the total range of the weapon)
MaxDamageRangeProportionfloatAll weapons0 <= x <= 1Proportion of the damage range at which falloff starts
MinDamageRangeProportionfloatAll weapons0 <= x <= 1Proportion of the damage range at which falloff ends
MinDamageProportionfloatAll weapons0 <= x <= 1Proportion of the normal damage dealt at the MinDamageRangeProportion

Weapon falloff is applied both to explosive and bullet weapons. For explosive weapons, falloff causes lower damage to targets further away from the explosion. For bullet weapons, falloff causes lower dmaage to targets further from the shooting player.

In both cases falloff is calculated over a distance scale known as the damage range; falloff is not necessarily linear over this range.

For explosive weapons, the damage range is the range from the central point of the explosion through to the damage radius (the ExplosiveRadius). For bullet weapons, the damage range is the range from the shooting player's position through to the value of the BulletDamageRange property. For hitscan weapons, the damage range is the WeaponRange.

Within this damage range, there is a MaxDamageRangeProportion - the proportion of the whole damage range for which the maximum damage is applied. Similarly there is a MinDamageRangeProportion, the distance after which the MinDamageProportion, the minimum proportion of the normal damage, is applied.

Below is an example set values and a graph:

PropertyValue
Damage500
ExplosiveRadius300
MaxDamageRangeProportion0.3
MinDamageRangeProportion0.7
MinDamageProportion0.4

Function describing damage done

Below is the graph for the (Medium) Spinfusor, for which falloff is linear over the radius of its explosion.

Function describing damage done

The Assault Rifle is not linear over its whole range. Note that for bullet weapons, the BulletDamageRange, defining its damage range is not the same thing as the range for the bullet; for projectiles, total range is controlled by the ProjectileLifespan property (described in Projectile and Tracer below).

Function describing damage done

The formula for the final proportion of the normal damage after falloff is:

Function describing damage done

where x is the distance, r is the damage range, m is the minimum damage proportion, p_max is the maximum range proportion and p_min is the minimum range proportion.

Sniper Rifles#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
PhaseDamagePerEnergyfloatPhase Rifle, SAP20> 0DamageDamage done per unit energy consumed by the Phase Rifle / SAP20
PhaseMaxConsumedEnergyfloatPhase Rifle, SAP20> 0DamageMaximum energy consumed by the Phase Rifle
BXTChargeMaxDamagefloatBXT1> 0DamageDamage done by the BXT when fully charged
BXTChargeTimefloatBXT1> 0SecondsTime for a full BXT charge
BXTChargeMultCoefficientfloatBXT1> 0Multiplicative coefficient controlling BXT charge curve
BXTChargeDivCoefficientfloatBXT1> 0Divisor coefficient controlling BXTcharge curve

Miscellaneous#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
DoesImpulseFlagbooleanExplosive weaponsWhether the weapon's explosion pushes the flag around
DoesGibOnKillbooleanAll weaponsWhether this weapon will cause a killed enemy to explode into pieces
GibImpulseRadiusfloatAll weaponsUnreal UnitsRadius for which gibbing impulse is applied to pieces of deceased enemy
GibStrengthfloatAll weaponsMomentumMomentum applied to gibbed pieces of an enemy

Projectile and Tracer#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
ProjectileSpeedfloatProjectile weapons>= 0UU / SLaunch speed of the projectile
ProjectileMaxSpeedfloatProjectile weapons>= 0UU / SCap on the absolute projectile speed, regardless of inheritance
CollisionSizefloatProjectile weapons>= 0UURadius of the projectile's collision sphere
ProjectileInheritancefloatProjectile weapons>= 0Proportion of the shooter's velocity the projectile inherits
ProjectileLifespanfloatProjectile weapons>= 0SHow long the projectile travels for before exploding in midair
ProjectileGravityfloatProjectile weapons>= 0Multiplier by which gravity affects the projectile
ProjectileTerminalVelocityfloatProjectile weapons>= 0UU / STerminal velocity due to gravity
ProjectileBounceDampingfloatProjectile weapons>= 0For projectiles which don't explode on impact, the proportion of energy lost on bounce
HitscanRangefloatHitscan weapons>= 0The range of the hitscan weapon
FireOffsetXfloatAll weaponsUUOffset to the player of the spawned projectile in the X direction (forwards/backwards)
FireOffsetYfloatAll weaponsUUOffset to the player of the spawned projectile in the Y direction (left/right)
FireOffsetZfloatAll weaponsUUOffset to the player of the spawned projectile in the Z direction (up/down)

Fractal Grenades#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
FractalDurationfloatFractals> 0SecondsDuration of the Fractal effect
FractalShardIntervalfloatFractals> 0SecondsInterval at which Fractal 'shards' fire
FractalAscentTimefloatFractals> 0SecondsHow long the Fractal takes to float off the ground to full height
FractalAscentHeightfloatFractals>= 0UUHeight off the ground that the Fractal ascends to
FractalShardDistancefloatFractals> 0UUHorizontal distance which Fractal shards extend to
FractalShardHeightfloatFractals>= 0UUVertical distance above/below the Fractal which shards extend to
FractalShardDamagefloatFractals>= 0DamageDamage done by each shard
FractalShardDamageRadiusfloatFractals> 0UUDamage radius from the end of each shard

Melee#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
MeleeDamageRadiusfloatMelee>= 0UUDistance at which melee will hit
MeleeConeAnglefloatMelee0 <= x <= 360DegreesAngle of the cone for which melee will hit

Accuracy#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
AccuracyfloatAll weapons0 <= x <= 1Proportion of accuracy for the weapon's shot
AccuracyLossOnShotfloatAll weapons0 <= x <= 1Accuracy decrease after shooting
AccuracyLossOnJumpfloatAll weapons0 <= x <= 1Accuracy decrease when jumping
AccuracyLossMaxfloatAll weapons0 <= x <= 1Maximum decrease in accuracy at a given time
AccuracyCorrectionRatefloatAll weapons0 <= x <= 1Rate at which accuracy returns after decreasing
ShotgunUseGOTYSpreadbooleanShotgunsWhether to use the older GOTY-patch shotgun spread (tighter, random) as opposed to the OOTB-patch spread (wider, non-random)

Grenades and Thrown Weapons#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
ThrowDelayfloatThrown weapons>= 0STime taken for the projectile to be thrown
ThrowPullPinTimefloatThrown weapons>= 0STime before the pin is pulled; after this it will be spawned even if the thrower dies
StuckDamageMultiplierfloatSticky weapons>= 0Multiplier for damage when projectile is stuck to an enemy
StuckMomentumMultiplierfloatSticky weapons>= 0Multiplier for impulse when projectile is stuck to an enemy
FuseTimerfloatThrown Weapons>= 0SFuse time on the grenade
ExplodeOnContactbooleanThrown weaponsWhether the projectile explodes on contact with an enemy
ExplodeOnFusebooleanThrown weaponsWhether the projectile explodes after its fuse timer
MustBounceBeforeExplodebooleanThrown weaponsWhether the projectile must bounce at least once before exploding due to a fuse

Packs#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
PackSustainedEnergyCostfloatActive Packs>= 0Energy / SEnergy per second to maintain a given pack
ThrustPackEnergyCostfloatThrust Pack>= 0EnergyEnergy cost to thrust
ThrustPackImpulsefloatThrust PackMomentumForward momentum given by a thrust
ThrustPackSidewaysImpulsefloatThrust PackMomentumSideways momentum given by a thrust
ThrustPackMinVerticalImpulsefloatThrust Pack>= 0MomentumMinimum amount of vertical impulse given by a thrust
ThrustPackCooldownTimefloatThrust Pack>= 0SCooldown before thrust can be used again
ThrustPackSpeedRangeStartfloatThrust Pack>= 0UU / SSpeed at which impulse generated by a thrust begins to falloff
ThrustPackSpeedRangeEndfloatThrust Pack>= 0UU / SSpeed cap at which thrust impulse is fully lowered
ThrustPackSpeedCapReductionfloatThrust Pack0 <= x <= 1Proportion of thrust impulse reduced when past the speed cap
ShieldPackEnergyCostPerDamagePointfloatShield Pack>= 0Energy / DamageHow much energy is consumed by the shield pack when taking a point of damage
JammerPackRangefloatJammer Pack>= 0UURadius for how far the jammer pack effect extends
PackBuffAmountfloatBuffing Packs>= 0VariousBuff effect amount for buffing packs like the energy recharge pack
StealthPackMaxSpeedfloatStealth Pack>= 0UU / SSpeed threshold past which a stealthed player is visible

Deployables#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
DeployableRangefloatDeployables>= 0UURange of a deployable (e.g. turret range)
DeployableMaxAllowedintegerDeployables>= 0Maximum number of deployables of this type a player can have
DeployableMinProximityfloatDeployables>= 0UUHow close two deployables of the same type can be placed
TurretTimeToAcquireTargetfloatDeployable Turrets>= 0SHow long a turret takes to lock onto a target
TurretCanTargetVehiclebooleanDeployable TurretsWhether the turret can target vehicles
ForcefieldMinDamagefloatForcefield>= 0DamageMinimum damage incurred by passing through a forcefield
ForcefieldMaxDamagefloatForcefield>= 0DamageMaximum damage incurred by passing through a forcefield
ForcefieldMinDamageSpeedfloatForcefield>= 0UU / SThe minimum speed at which damage will be dealt when passing through a forcefield
ForcefieldMaxDamageSpeedfloatForcefield>= 0UU / SThe speed at which the maximum forcefield damage occurs

Mines#

PropertyTypeApplicable ItemsValue RestrictionsUnitsDescription
MineDeployTimefloatMines>= 0SHow long before the mine is active and armed
MineMaxAllowedintegerMines>= 0Maximum number of mines of this type a player can have out
MineCollisionCylinderRadiusfloatMines>= 0UURadius of the collision cylinder used to check detonation
MineCollisionCylinderHeightfloatMines>= 0UUHeight of the collision cylinder used to check detonation
ClaymoreDetonationAnglefloatClaymore Mines0 <= x <= 360DegreesCone angle at which the Claymore will trigger
PrismMineTripDistancefloatPrism Mines>= 0UUAmount the Prism Mine's tripwire extends left and right