Weapons
Overview
The WeaponsSystem
provides a way to fire projectiles or repeat a firing actions at a specific rate.
Weapon Setup
Every weapon is its own entity with a Weapons
component and a specialized controller inheriting from the base WeaponController
. This setup allows to add and remove weapons from player entities at runtime.
WeaponController
All weapon controllers inherit from the WeaponController
class and thus will have this properties available to them:
FireOffset
: Relative offset from hand to weapon barrel / point where the projectile spawnsMinRange
: Minimum distance from target to start shooting automaticallyMaxRange
: Maximum distance from target to start shooting automaticallyCriticalChance
: Percentage chance to double damageMinRangeAutoFireAngle
: Maximum angle from player aim direction to start shooting automatically when distance from the target equalsMinRange
in degreesMaxRangeAutoFireAngle
: Maximum angle from player aim direction to start shooting automatically when distance from target equalsMaxRange
in degreesAutoFireAngleBendFactor
: Controls interpolation linearity of theAutoFire
angle betweenMinRangeAutoFireAngle
andMaxRangeAutoFireAngle
Execution Flow
The WeaponsSystem
orchestrates the coordination of the WeaponsDesires
, the Weapons
component and the various WeaponControllers
in the game. The following diagram presents the execution flow and the APIs used to interface between the different moving parts.
AutoFire
In the following diagram the relationship between the WeaponController
properties and AutoFire
is illustrated from a simplified top-down perspective.
The AutoFire
behaviour between MinRange
and MaxRange
is controlled by the AutoFireAngleBendFactor
property. The higher the bend factor, the faster the AutoFire
angle interpolates from MinRangeAutoFireAngle
towards MaxRangeAutoFireAngle
; in other words the AutoFire
area is shrinking.
Included Controllers
The FPS Template implements the WeaponController
in two concrete examples:
- the
ProjectileWeaponController
; and, - the
MeleeWeaponController
.
ProjectileWeapon
The ProjectileWeaponController
can be used for any weapon shooting a projectile. The behaviour is dependent on how the properties are tweaked and which projectile is referenced in the Projectile
property.
Projectile
: Reference to projectile prototypeProjectileCount
: Number of projectiles fired on single weapon useMagazineAmmo
: Number of projectiles in weapon magazineWeaponAmmo
: Total number of projectiles the weapon can holdUnlimitedAmmo
: Set to true for unlimited number of projectilesCadence
: Number of projectiles fired per minuteReloadDuration
: How long it takes to reload the weaponDispersionAngle
: Per-axis fire direction dispersion in degrees
MeleeWeapon
The MeleeWeaponController
can be used for any melee type weapon. In addition to simple melee damage, additional effects can be applied by using the Effect
property.
Effect
: Reference to melee effect prototypeAttackDelay
: How long it takes before spawning the EffectCooldown
: How long it takes to execute next attack
Creating a New Weapon
This is the step-by-step procedure to create a new Weapon in the FPS Template.
- In the Quantum solution, create a new
MyWeaponController
which inherits fromWeaponController
. - Add serializable fields to the controller (configuration).
- If needed, create a
MyWeapon.qtn
which contains the definition for theMyWeapon
component and other data structures such as roll-backable data. - Override the base properties if needed and implement the
Initialize()
,Deinitialize()
,Update()
andFire()
methods in the controller. - Implement the available controller interfaces (e.g.
IAttributesProvider
, ...). - Recompile the
quantum.code
solution. - In Unity, create an empty GameObject and add the visual components / model as a child object.
- Add the
Entity
,EntityPrototype
,EntityComponentController
andEntityComponentWeapon
scripts to the GameObject. - On the
Entity
component, set:Transform Synchronization
toNone
if the weapon is always snapped to the handleRequire Owner
totrue
if the weapon cannot exist without the owning entity
- On the
EntityComponentController
component, selectMyWeaponController
from theWeaponController
drop-down menu and fill out the defined properties. - On the
EntityComponentWeapon
fill out the defined properties. - Add other entity components to define the behavior of the entity (e.g.
EntityComponentMyWeapon
, ...). - Create a prefab of the entity (Optional).
- Execute the asset resource generation via the
Quantum > Generate Asset Resources
menu. - Execute the prefab baking procedure via the
Quantum > Bake > Prefabs
menu. - The weapon is now ready to use - reference entity prototype.