Weapon

Script Reference

Weapon Functions

Weapon

Properties

Name

Name of the weapon.

WeaponId

The id of the weapon. Should correspond to an entry in the global WEAPON table. This id MUST match the numeric weapon id expected by the mod interface.

MinUseTime

The minimum time the bot should maintain the weapon once selected.

PrimaryFire

Returns a reference to the primary Fire Mode

SecondaryFire

Returns a reference to the secondary Fire Mode

Fire Mode

Properties

RequiresAmmo

This weapon requires ammo to operate. The type of ammo is determined by the Properties|AmmoType.

WaterProof

The weapon can be fired underwater. If false, the weapon will not be considered when the user is underwater.

HasClip

The weapon has a clip. Helps determine how ammo checking is performed.

InheritsVelocity

The weapon projectile inherits the velocity of the player when fired. This is used for a bit more accuracy in the projectile leading calculations.

ManageHeat

The weapon can overheat, so the bot should oscillate the firing to attempt to keep from overheating.

IgnoreReload

Ignore this weapon if it needs to reload. Normally bot would switch to weapons to reload them if they have no target. This option disables that.

RequiresTargetOutside

This weapon requires that the target is outdoors.

RequiresShooterOutside

This weapon requires that the shooter is outdoors.

WeaponType

The type of weapon this fire mode is.

• melee - Melee attacks are close range. Bots attack only if desirability is greater than default desirability.
• instant - Instant hit means no leading or projectile velocity is necessary.
• projectile - Bot will lead targets based on projectile velocity.
• grenade - Not yet implemented. Same as projectile.
• item - cannot be used in combat (dynamite, landmine, syringe, ammo pack, ...).

MustBeOnGround

The bot must be standing on the ground to use this weapon(not airborne).

FireOnRelease

The weapon is fired when the fire button is released, as opposed to firing when the fire button is pressed.

UseMortarTrajectory

The weapon should use the mortar trajectory when calculating trajectory.

MaxAimError

The maximum aim error to use for the fire mode. Aim Error is a Vector2(x,y), where x is the horizontal aim error and y is the vertical aim error.

AimOffset

The offset where to aim at players. AimOffset is a Vector3(x,y,z) that represents a world offset to aim the weapon.

PitchOffset

Normally a projectile comes out along the aim vector of the bot, but some weapons can come out at an angle. PitchOffset is the pitch offset(in degrees) the projectile shoots at.

ShootButton

The button id of the button used to fire the weapon. Defaults to BTN.ATTACK1

LowAmmoThreshold

Used for ammo desirability calculations. This is the threshold the weapon will be considered low on ammo.

LowAmmoPriority

When the ammo is below the threshold above, this is the priority used for the desirability of the ammo.

LowAmmoGetAmmoAmount

Ammo amount to get from a cabinet. Used for mortar.

FuseTime

The countdown timer the projectile takes before it explodes/activates.

AmmoType

The ammo id the weapon uses. Depending on the game, this may be a duplicate of the weapon id or it may be an actual ammo id, from the global AMMO table.

ProjectileSpeed

The speed the projectile flies at. Only relevant to projectile fire modes.

MinChargeTime

The minimum time the bot should charge this weapon before shooting. Normally used with FireOnRelease property. Used as a minimum range for a random charge time, along with MaxChargeTime.

MaxChargeTime

The maximum time the bot should charge this weapon before shooting. Normally used with FireOnRelease property. Used as a maximum range for a random charge time, along with MinChargeTime.

DelayAfterFiring

How long the bot should wait to choose this weapon again after firing.

ProjectileGravity

The gravity multiplier used for the projectile. Used to calculate trajectory of the projectile. Projectiles that aren't effected by gravity will have a ProjectileGravity of 0. A projectile that has half gravity is a 0.5, while full gravity is 1.0

DefaultDesirability

Default desirability is the desirability used for choosing a weapon when the bot has no target. The highest default desirability will be equipped when the bot has no target, after all weapons that need reloading is considered.

MinAimAdjustmentTime

Minimum time between new calculations of aim error.

MaxAimAdjustmentTime

Maximum time between new calculations of aim error.

CalculateDefaultDesirability

Script function callback to calculate the default desirability. Should return a 0-1 desirability value.

CalculateDesirability

Script function callback to calculate the desirability of the weapon. Should return a 0-1 desirability value. This callback will be passed the TargetInfo of the current target.

CalculateAimPoint

Script function callback to calculate an aim point for the weapon. Should return a Vector3 world aim position. This callback will be passed the TargetInfoof the current target.

Not used properties

SplashDamage

The weapon produces splash damage, and should be disfavored when there are allies in the target area.

HasZoom

The weapon has a zoom mode.

Stealth

The weapon should be favored when stealth is desired.

NeedsInRange

The bot must be within the MinRange and MaxRange to use, even if that means the bot should chase the target. Typically used for melee weapons.

MaxEquipMoveMode

The fastest the bot should move when this weapon is equipped (run, walk, still).

Offhand

Weapon can be used simultaneously with another weapon, such as offhand grenades.

ManualDetonation

The weapon projectile must be manually detonated.

SniperWeapon

The weapon is a sniper weapon, and should be considered for use for goals that require a sniper weapon.

ZoomButton

The button id of the button used to zoom the weapon. Defaults to BTN.AIM

MinRange

The minimum range the bot should consider using this fire mode.

MaxRange

The maximum range the bot should consider using this fire mode.

PreShoot

Script function callback to that is called just before the weapon is fired.

Functions

SetBurstRange

This function can be called multiple times in order to set several ranges for burst firing. Whenever the target is within one of the ranges, the bot will use controlled burst fire as set up by this function.

Parameters: (minrange, maxrange, numrounds, mindelay, maxdelay)

Returns: none

Example:

 // from 200-500 units away, set up a 3 shot burst rate, with a 1-2 second delay between each burst
 w.PrimaryFire.SetBurstRange(200, 500, 3, 1, 2);

SetDesirabilityRange

This function can be called multiple times to assign a desirability to use the weapon when the target is within a given range of the bot.

Parameters: (minrange, maxrange, desirability)

Returns: none

Example:

 // between 200 and 500 range, we want the desirability to be 0.5
 w.PrimaryFire.SetDesirabilityRange(200, 500, 0.5);

SetTargetBias

Sets a bias multiplier for a target type. This bias will be multiplied with the desirability when calculating the desirability of a weapon versus a target.

Parameters: (targettype, bias)

Returns: none

Example:

 // make this weapon 1.5 times more likely to be used against heavy vehicles
 w.PrimaryFire.SetTargetBias(CLASS.VEHICLE_HVY, 1.5);