# Sandbox.BaseCombatWeapon

The base for anything a player holds and uses - weapons, tools, cameras, and so on. Adds a
first-person view model, a third-person world model attached to the holder's hand, and an aim ray
on top of [Sandbox.BaseInventoryItem](/api/Sandbox.BaseInventoryItem). Combat is opt-in: subclass this, override the attack,
and call the utility methods (ShootBullet, ShootBullets, ...) - they do the host-authoritative
tracing and damage for you. Non-combat items just don't call them.

## Remarks

Hold-type animation stays animation agnostic: [Sandbox.BaseCombatWeapon.HoldType](/api/Sandbox.BaseCombatWeapon/HoldType) is an option name resolved
against whatever "holdtype" enum the holder's animgraph defines - the engine ships no hold-type
enum of its own.

- Kind: class
- Namespace: `Sandbox`
- Assembly: `Sandbox.Engine`
- Inherits: [Sandbox.BaseInventoryItem](/api/Sandbox.BaseInventoryItem)

## Constructors

- [`BaseCombatWeapon`](/api/Sandbox.BaseCombatWeapon/.ctor)

## Properties

- [`AimRay`](/api/Sandbox.BaseCombatWeapon/AimRay): Where this weapon is aiming. When held by a player: the holder's eye-forward, or the camera-forward in third person (so you aim where the camera looks, not where the head points). When not held it defers to [Sandbox.BaseCombatWeapon.UnheldAimRay](/api/Sandbox.BaseCombatWeapon/UnheldAimRay).
- [`Ammo1`](/api/Sandbox.BaseCombatWeapon/Ammo1): Reserve ammo available to primary fire - the holder's pool of [Sandbox.BaseCombatWeapon.PrimaryAmmoType](/api/Sandbox.BaseCombatWeapon/PrimaryAmmoType) (GMod's Ammo1).
- [`Ammo2`](/api/Sandbox.BaseCombatWeapon/Ammo2): Reserve ammo available to secondary fire (GMod's Ammo2).
- [`AttackSound`](/api/Sandbox.BaseCombatWeapon/AttackSound): Sound played when the weapon attacks - the gunshot, swing, launch. Played by the base [Sandbox.BaseCombatWeapon.OnShootEffects](/api/Sandbox.BaseCombatWeapon/OnShootEffects), so it reaches every peer that sees the shot.
- [`AutoReload`](/api/Sandbox.BaseCombatWeapon/AutoReload): Start a reload automatically when the trigger is pulled on an empty magazine.
- [`Ballistics`](/api/Sandbox.BaseCombatWeapon/Ballistics): How the default [Sandbox.BaseCombatWeapon.PrimaryAttack](/api/Sandbox.BaseCombatWeapon/PrimaryAttack) shoots - damage, pellets, spread and reach.
- [`CanCancelReload`](/api/Sandbox.BaseCombatWeapon/CanCancelReload): Can the reload be cancelled (e.g. by firing) part-way through?
- [`Clip1`](/api/Sandbox.BaseCombatWeapon/Clip1): Rounds currently in the primary magazine, or -1 when the weapon doesn't use one (GMod's Clip1). Host owned - the owner spends it locally for instant feedback and the spend is mirrored to the host (see [Sandbox.BaseCombatWeapon.TakePrimaryAmmo](/api/Sandbox.BaseCombatWeapon/TakePrimaryAmmo)), whose count is the truth.
- [`Clip2`](/api/Sandbox.BaseCombatWeapon/Clip2): Rounds currently in the secondary magazine, or -1 when unused (GMod's Clip2). Host authoritative.
- [`ClipMaxSize`](/api/Sandbox.BaseCombatWeapon/ClipMaxSize): Primary magazine size.
- [`CurrentSpread`](/api/Sandbox.BaseCombatWeapon/CurrentSpread): The current spread cone in degrees - the base cone widened by recent firing. Override to modify it (e.g. narrow while aiming down sights).
- [`DeployTime`](/api/Sandbox.BaseCombatWeapon/DeployTime): Seconds after deploying (switching to) this weapon before it can fire.
- [`DryFireSound`](/api/Sandbox.BaseCombatWeapon/DryFireSound): Sound played when the trigger is pulled with no ammo.
- [`FirstShellReloadTime`](/api/Sandbox.BaseCombatWeapon/FirstShellReloadTime): Extra delay after the first round before the rest (e.g. a longer first insert). Incremental only.
- [`Handedness`](/api/Sandbox.BaseCombatWeapon/Handedness): Which hand(s) the holder carries this in - drives the holder animgraph's "holdtype_handedness" parameter alongside [Sandbox.BaseCombatWeapon.HoldType](/api/Sandbox.BaseCombatWeapon/HoldType). Only some hold types support it (e.g. pistol, holditem).
- [`HoldBone`](/api/Sandbox.BaseCombatWeapon/HoldBone): The bone on the holder's renderer to attach the world model to.
- [`HolderRenderer`](/api/Sandbox.BaseCombatWeapon/HolderRenderer): The body renderer the world model attaches to - the holder's renderer.
- [`HoldType`](/api/Sandbox.BaseCombatWeapon/HoldType): How the holder poses their arms while this is deployed - an option name on the holder animgraph's "holdtype" enum parameter (e.g. "pistol", "rifle"). Set on the holder's renderer when equipped. Empty doesn't drive it.
- [`IncrementalReloading`](/api/Sandbox.BaseCombatWeapon/IncrementalReloading): Load one round at a time instead of the whole magazine (shotgun-style).
- [`IsHeld`](/api/Sandbox.BaseCombatWeapon/IsHeld): True while held by a player.
- [`IsReloading`](/api/Sandbox.BaseCombatWeapon/IsReloading): True while a reload is in progress. Host authoritative, synced so every peer can animate.
- [`MaxReserveAmmo`](/api/Sandbox.BaseCombatWeapon/MaxReserveAmmo): Most reserve ammo the holder can carry for primary fire (from the ammo type).
- [`Npc`](/api/Sandbox.BaseCombatWeapon/Npc): How an NPC fights with this weapon.
- [`Owner`](/api/Sandbox.BaseCombatWeapon/Owner): The player controller holding this, or null if it isn't held by one (it's in the world, or held by something that isn't a [Sandbox.PlayerController](/api/Sandbox.PlayerController)). Derived from the hierarchy.
- [`PrimaryAmmoType`](/api/Sandbox.BaseCombatWeapon/PrimaryAmmoType): The reserve ammo type primary fire draws from. Null means a bottomless reserve - the magazine still forces the reload rhythm, it just never runs out. Assign a type for a finite reserve, shared with other weapons of the same type.
- [`PrimaryAutomatic`](/api/Sandbox.BaseCombatWeapon/PrimaryAutomatic): When true primary fire keeps firing while the button is held; when false it fires once per press (GMod's `Primary.Automatic`).
- [`PrimaryClipSize`](/api/Sandbox.BaseCombatWeapon/PrimaryClipSize): Magazine size for primary fire, or -1 when it feeds straight from reserve (GMod's Primary.ClipSize). Derived from [Sandbox.BaseCombatWeapon.UsesAmmo](/api/Sandbox.BaseCombatWeapon/UsesAmmo) / [Sandbox.BaseCombatWeapon.UsesClips](/api/Sandbox.BaseCombatWeapon/UsesClips) / [Sandbox.BaseCombatWeapon.ClipMaxSize](/api/Sandbox.BaseCombatWeapon/ClipMaxSize).
- [`PrimaryDelay`](/api/Sandbox.BaseCombatWeapon/PrimaryDelay): Seconds between primary shots - the fire rate (GMod's `Primary.Delay`).
- [`ReloadStartTime`](/api/Sandbox.BaseCombatWeapon/ReloadStartTime): Delay before the first round goes in. Zero uses [Sandbox.BaseCombatWeapon.ReloadTime](/api/Sandbox.BaseCombatWeapon/ReloadTime).
- [`ReloadTime`](/api/Sandbox.BaseCombatWeapon/ReloadTime): How long a (full) reload takes, in seconds. For incremental reloads, the time per round.
- [`SecondaryAmmoType`](/api/Sandbox.BaseCombatWeapon/SecondaryAmmoType)
- [`SecondaryAutomatic`](/api/Sandbox.BaseCombatWeapon/SecondaryAutomatic): When true secondary fire is full-auto while held.
- [`SecondaryClipSize`](/api/Sandbox.BaseCombatWeapon/SecondaryClipSize): Magazine size for secondary fire, or -1 when it doesn't use one (GMod's Secondary.ClipSize). Set directly - unlike [Sandbox.BaseCombatWeapon.PrimaryClipSize](/api/Sandbox.BaseCombatWeapon/PrimaryClipSize), it isn't derived from the clip settings.
- [`SecondaryDefaultClip`](/api/Sandbox.BaseCombatWeapon/SecondaryDefaultClip): Rounds loaded into the secondary magazine when first given. -1 fills it.
- [`SecondaryDelay`](/api/Sandbox.BaseCombatWeapon/SecondaryDelay): Seconds between secondary shots.
- [`ShouldAvoid`](/api/Sandbox.BaseCombatWeapon/ShouldAvoid): Avoid auto-switching to a gun with nothing left to fire or load (see [Sandbox.BaseInventoryItem.ShouldAvoid](/api/Sandbox.BaseInventoryItem/ShouldAvoid)).
- [`SpreadScale`](/api/Sandbox.BaseCombatWeapon/SpreadScale): Runtime multiplier on the spread cone - 1 is the configured ballistics. NPCs set this to the weapon's [Sandbox.BaseCombatWeapon.Npc](/api/Sandbox.BaseCombatWeapon/Npc) spread scale times their own skill when they equip it.
- [`StartingAmmo`](/api/Sandbox.BaseCombatWeapon/StartingAmmo): Reserve ammo granted on first pickup, seeded into the holder's pool.
- [`UsableByNpcs`](/api/Sandbox.BaseCombatWeapon/UsableByNpcs): Can NPCs fight with this weapon at all?
- [`UsesAmmo`](/api/Sandbox.BaseCombatWeapon/UsesAmmo): Does primary fire consume ammo at all? When false the weapon never runs dry - for melee, tools and the like. Switches the whole Ammo feature off.
- [`UsesClips`](/api/Sandbox.BaseCombatWeapon/UsesClips): Feed primary fire from a magazine (true) or straight from the reserve pool (false).
- [`UsesPrimaryClip`](/api/Sandbox.BaseCombatWeapon/UsesPrimaryClip): True when primary fire feeds from a magazine rather than straight from reserve.
- [`UsesSecondaryClip`](/api/Sandbox.BaseCombatWeapon/UsesSecondaryClip): True when secondary fire feeds from a magazine.
- [`ViewModel`](/api/Sandbox.BaseCombatWeapon/ViewModel): The spawned view model instance, or null. Owner-only and not networked - each client makes its own.
- [`ViewModelPrefab`](/api/Sandbox.BaseCombatWeapon/ViewModelPrefab): First-person view model prefab. Spawned only on the client holding this item.
- [`WeaponModel`](/api/Sandbox.BaseCombatWeapon/WeaponModel): The [Sandbox.BaseWeaponModel](/api/Sandbox.BaseWeaponModel) on the currently-shown model - the view model when it's being drawn, otherwise the world model, otherwise the weapon's own hierarchy (standalone weapons). Null when none carries one.
- [`WorldModel`](/api/Sandbox.BaseCombatWeapon/WorldModel): The spawned world model instance, or null. Not networked - each peer makes its own.
- [`WorldModelPrefab`](/api/Sandbox.BaseCombatWeapon/WorldModelPrefab): Third-person world model prefab, attached to the holder's hand bone. Seen by everyone.

## Methods

- [`CancelReload`](/api/Sandbox.BaseCombatWeapon/CancelReload): Abort a reload before it finishes, loading nothing further.
- [`CanPrimaryAttack`](/api/Sandbox.BaseCombatWeapon/CanPrimaryAttack): Can primary fire right now? Base checks the cooldown, that we're not mid-reload, and that there's ammo. A pure check, safe to call from HUDs - the trigger dry-fires on empty, not this. Override to add conditions.
- [`CanReload`](/api/Sandbox.BaseCombatWeapon/CanReload): Can we start a reload? Yes when not already reloading, the magazine isn't full, and there's reserve to load. Override to add conditions.
- [`CanSecondaryAttack`](/api/Sandbox.BaseCombatWeapon/CanSecondaryAttack)
- [`DrawCrosshair`](/api/Sandbox.BaseCombatWeapon/DrawCrosshair): Draw this weapon's crosshair at the aim position. Base draws a simple four-line cross.
- [`DrawHud`](/api/Sandbox.BaseCombatWeapon/DrawHud): Draw this weapon's HUD on the given camera - the crosshair goes at screen centre when the camera sits on the aim ray, otherwise (third person, mounted weapons) at the projected aim point. Games call this for weapons they draw manually, e.g. seat-controlled ones.
- [`DryFire`](/api/Sandbox.BaseCombatWeapon/DryFire): The player pulled the trigger with no ammo. Base plays [Sandbox.BaseCombatWeapon.DryFireSound](/api/Sandbox.BaseCombatWeapon/DryFireSound), throttles both triggers so it doesn't spam, and starts a reload when [Sandbox.BaseCombatWeapon.AutoReload](/api/Sandbox.BaseCombatWeapon/AutoReload) allows. Override to extend.
- [`FirePrimary`](/api/Sandbox.BaseCombatWeapon/FirePrimary): Pull the primary trigger - fires if [Sandbox.BaseCombatWeapon.CanPrimaryAttack](/api/Sandbox.BaseCombatWeapon/CanPrimaryAttack) allows, putting it on cooldown. Returns whether it fired. The way to shoot from code (AI, turrets) - calling [Sandbox.BaseCombatWeapon.PrimaryAttack](/api/Sandbox.BaseCombatWeapon/PrimaryAttack) directly skips the fire rate. Runs on whoever controls the weapon; the attack doesn't re-run on the host.
- [`FireSecondary`](/api/Sandbox.BaseCombatWeapon/FireSecondary)
- [`GetMuzzleTransform`](/api/Sandbox.BaseCombatWeapon/GetMuzzleTransform): The transform that shots and muzzle effects fire from. Resolves the active weapon model's muzzle attachment, then the weapon itself. Override to add other model-driven resolution.
- [`HasPrimaryAmmo`](/api/Sandbox.BaseCombatWeapon/HasPrimaryAmmo): True if primary fire has a round ready - in the magazine, or in reserve for a clipless weapon. Weapons with neither a magazine nor an ammo type are treated as unlimited (melee, tools).
- [`HasSecondaryAmmo`](/api/Sandbox.BaseCombatWeapon/HasSecondaryAmmo)
- [`ImpactEffect`](/api/Sandbox.BaseCombatWeapon/ImpactEffect): Spawn a bullet impact at a trace hit - the hit surface's impact sound and decal/particle, oriented to the surface and parented to what was hit (its nearest bone for skinned models, so decals stick to moving things). A hit object that's already gone - killed by this very shot - still gets its impact, left where it landed in the world. A pure presentation utility like [Sandbox.BaseCombatWeapon.ShootBullet](/api/Sandbox.BaseCombatWeapon/ShootBullet); call it wherever you resolve a hit. Does nothing on a dedicated server or for a trace that missed.
- [`ImpactPrefab`](/api/Sandbox.BaseCombatWeapon/ImpactPrefab): Spawn just the surface impact prefabs (decal/particles) at a hit, stuck to what was hit - no sound. For attacks that want the visual but their own impact audio (a melee thunk instead of a ricochet).
- [`PrimaryAttack`](/api/Sandbox.BaseCombatWeapon/PrimaryAttack): Fire the primary attack. The default fires [Sandbox.BaseCombatWeapon.Ballistics](/api/Sandbox.BaseCombatWeapon/Ballistics) - spends a round, shoots the volley from [Sandbox.BaseCombatWeapon.AimRay](/api/Sandbox.BaseCombatWeapon/AimRay) with [Sandbox.BaseCombatWeapon.CurrentSpread](/api/Sandbox.BaseCombatWeapon/CurrentSpread), and plays the effects on every peer. Override for melee, projectiles and tools. Runs once, on whoever controls the weapon - the owning client for a held weapon (its hits reach the host as claims, see [Sandbox.BaseCombatWeapon.ShootBullet](/api/Sandbox.BaseCombatWeapon/ShootBullet)), or the host for seat/NPC/world weapons (damage applies directly).
- [`Reload`](/api/Sandbox.BaseCombatWeapon/Reload): Begin reloading. Routed to the host, which runs it authoritatively. Override [Sandbox.BaseCombatWeapon.OnReloadStarted](/api/Sandbox.BaseCombatWeapon/OnReloadStarted) and friends for presentation rather than this.
- [`SecondaryAttack`](/api/Sandbox.BaseCombatWeapon/SecondaryAttack): Fire the secondary attack. Base does nothing - override it. Same contract as [Sandbox.BaseCombatWeapon.PrimaryAttack](/api/Sandbox.BaseCombatWeapon/PrimaryAttack): runs once, on whoever controls the weapon.
- [`SetNextFire`](/api/Sandbox.BaseCombatWeapon/SetNextFire): Put both triggers on cooldown for `delay` seconds - for weapons where a shot blocks primary and secondary alike.
- [`SetNextPrimaryFire`](/api/Sandbox.BaseCombatWeapon/SetNextPrimaryFire): Put primary fire on cooldown for `delay` seconds.
- [`SetNextSecondaryFire`](/api/Sandbox.BaseCombatWeapon/SetNextSecondaryFire): Put secondary fire on cooldown for `delay` seconds.
- [`ShootBullet`](/api/Sandbox.BaseCombatWeapon/ShootBullet): Traces a bullet through the world and, on the host, damages and pushes whatever it hits. This is a pure utility - it holds no state, so you can call it from anywhere (a weapon, a trap, an NPC, an explosion). Returns the trace result so the caller can spawn tracers, decals and play sounds.
- [`ShootBullets`](/api/Sandbox.BaseCombatWeapon/ShootBullets): Fires a volley of bullets - one trace per pellet, each randomly deflected within `spread`, resolved through [Sandbox.BaseCombatWeapon.ShootBullet](/api/Sandbox.BaseCombatWeapon/ShootBullet) (GMod's `FireBullets`). A pure utility like ShootBullet - damage and impulse apply on the host only. Returns every pellet's trace so the caller can drive tracers and impacts.
- [`ShootEffects`](/api/Sandbox.BaseCombatWeapon/ShootEffects): Play the shot's muzzle/fire presentation with no ranged hit - muzzle flash, fire sound, shell eject. For melee swings and projectile launches. See [Sandbox.BaseCombatWeapon.ShootEffects](/api/Sandbox.BaseCombatWeapon/ShootEffects).
- [`TakePrimaryAmmo`](/api/Sandbox.BaseCombatWeapon/TakePrimaryAmmo): Spend `amount` rounds for a primary shot - from the magazine if it has one, otherwise reserve, otherwise free. Returns false if there wasn't enough (GMod's TakePrimaryAmmo).
- [`TakeSecondaryAmmo`](/api/Sandbox.BaseCombatWeapon/TakeSecondaryAmmo)