BaseCombatWeaponclass
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`. 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.
Note
Hold-type animation stays animation agnostic: `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.
Constructors1
Showing 1 constructors
public BaseCombatWeapon()
No results match this filter.
Methods61
Showing 61 methods
protected virtual Sandbox.SceneTrace BulletTrace(Ray ray, float distance, float radius)
The trace used for this weapon's bullets. Base traces against hitboxes and ignores the `Sandbox.BaseCombatWeapon.Attacker`'s hierarchy. Override to add collision rules or filters.
| Parameter | Type | Description |
|---|---|---|
| ray | Ray | — |
| distance | float | — |
| radius | float | — |
public virtual void CancelReload()
Abort a reload before it finishes, loading nothing further.
void—public virtual bool 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.
bool—public virtual bool 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.
bool—public virtual bool CanSecondaryAttack()
bool—protected virtual void CreateViewModel()
Spawns the view model from `Sandbox.BaseCombatWeapon.ViewModelPrefab` and plays its deploy presentation. Owner only, idempotent - safe to call when one already exists.
void—protected virtual void CreateWorldModel()
Spawns the world model from `Sandbox.BaseCombatWeapon.WorldModelPrefab` onto the holder's `Sandbox.BaseCombatWeapon.HoldBone`, replacing any previous one.
void—protected virtual void DestroyViewModel()
Destroys the spawned view model, if any.
void—protected virtual void DestroyWorldModel()
Destroys the spawned world model, if any.
void—public virtual void DrawCrosshair(Sandbox.Rendering.HudPainter hud, Vector2 center)
Draw this weapon's crosshair at the aim position. Base draws a simple four-line cross.
| Parameter | Type | Description |
|---|---|---|
| hud | HudPainter | — |
| center | Vector2 | — |
void—public virtual void DryFire()
The player pulled the trigger with no ammo. Base plays `Sandbox.BaseCombatWeapon.DryFireSound`, throttles both triggers so it doesn't spam, and starts a reload when `Sandbox.BaseCombatWeapon.AutoReload` allows. Override to extend.
void—public bool FirePrimary()
Pull the primary trigger - fires if `Sandbox.BaseCombatWeapon.CanPrimaryAttack` allows, putting it on cooldown. Returns whether it fired. The way to shoot from code (AI, turrets) - calling `Sandbox.BaseCombatWeapon.PrimaryAttack` directly skips the fire rate. Runs on whoever controls the weapon; the attack doesn't re-run on the host.
bool—public bool FireSecondary()
bool—public virtual Transform 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.
protected virtual int GetReserveAmmo(Sandbox.BaseAmmoResource ammoType)
Reserve ammo of the given type available to this weapon. Reads the owning inventory's shared pool (`Sandbox.BaseInventoryComponent.GetAmmo(Sandbox.BaseAmmoResource)`) - reserve ammo lives on the inventory, not the weapon, so guns of the same type share it. A null ammo type is a bottomless reserve. Returns 0 when the weapon isn't in an inventory. Override to use a different store.
| Parameter | Type | Description |
|---|---|---|
| ammoType | BaseAmmoResource | — |
int—public virtual bool 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).
bool—public virtual bool HasSecondaryAmmo()
bool—public static void ImpactPrefab(Sandbox.GameObject hitObject, Sandbox.Surface surface, Vector3 position, Vector3 normal)
Spawn just the surface impact prefab (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).
| Parameter | Type | Description |
|---|---|---|
| hitObject | GameObject | — |
| surface | Surface | — |
| position | Vector3 | — |
| normal | Vector3 | — |
void—protected virtual void ModifyCamera(Sandbox.CameraComponent camera, Sandbox.CameraView view)
Reshape the holder's view while this weapon is deployed - scope zoom, offsets, lean. Runs in the camera's modifier chain on the owning client, after the player's camera and vehicles. Base does nothing.
| Parameter | Type | Description |
|---|---|---|
| camera | CameraComponent | — |
| view | CameraView | — |
void—protected virtual void OnAdded(Sandbox.BaseInventoryComponent inventory)
Seed the magazines with their default contents, and the inventory's reserve pool with `Sandbox.BaseCombatWeapon.StartingAmmo`. Host only, runs once when the weapon enters an inventory.
| Parameter | Type | Description |
|---|---|---|
| inventory | BaseInventoryComponent | — |
void—protected virtual bool OnAdding(Sandbox.BaseInventoryComponent inventory)
One of each - picking up a weapon the inventory already holds donates its ammo to the reserve instead (GMod's duplicate pickup), when there's an ammo type with room. The duplicate is consumed by the donation, or left where it is.
| Parameter | Type | Description |
|---|---|---|
| inventory | BaseInventoryComponent | — |
bool—protected virtual void OnControl()
Per-frame weapon logic, pumped by the inventory on the owning client. Reads input and drives the fire/reload loop. Override the individual hooks (PrimaryAttack, Think, ...) rather than this.
void—protected virtual void OnEquipped()
void—protected virtual void OnHolstered()
void—protected virtual void OnReloadCancelled()
The reload was cancelled part-way (fired, holstered). Fires on every peer, alongside `Sandbox.BaseCombatWeapon.OnReloadFinished` - use it to stop timed reload sounds and the like.
void—protected virtual void OnReloadFinished()
Reload ended (finished or cancelled). Drives the active weapon model.
void—protected virtual void OnReloadInserted()
A round was loaded (incremental). Drives the active weapon model's per-shell insert.
void—protected virtual void OnReloadStarted()
Reload started. Plays the reload animation on the weapon model, and fires the "b_reload" gesture on the holder's body. Fires once, on every peer, off the synced IsReloading.
void—protected virtual void OnShootEffects(Sandbox.BaseCombatWeapon.ShotEffect shot)
Define the presentation for a resolved shot. Base spawns the surface impact and flies the tracer for every pellet, then plays `Sandbox.BaseCombatWeapon.AttackSound`, fires the holder's "b_attack" gesture and runs `Sandbox.BaseWeaponModel.OnAttack(System.Nullable,System.Nullable)` on the shown model (muzzle flash, brass) - those are skipped for `Sandbox.BaseCombatWeapon.ShotEffect.NoEvents` pellets, which share the lead pellet's. Call it when you override. Runs on every peer that should see the shot.
| Parameter | Type | Description |
|---|---|---|
| shot | ShotEffect | — |
void—protected virtual void OnShootImpact(Sandbox.BaseCombatWeapon.ShotEffect& modreq(System.Runtime.InteropServices.InAttribute) shot)
| Parameter | Type | Description |
|---|---|---|
| shot | ShotEffect& modreq(InAttribute) | — |
void—protected virtual void OnUpdate()
void—protected virtual bool OnValidateShotClaim(Sandbox.BaseCombatWeapon.ShotClaim& modreq(System.Runtime.InteropServices.InAttribute) claim)
| Parameter | Type | Description |
|---|---|---|
| claim | ShotClaim& modreq(InAttribute) | — |
bool—protected virtual void PlaceViewModel(Sandbox.CameraComponent camera, Sandbox.CameraView& modreq(System.Runtime.InteropServices.InAttribute) view)
| Parameter | Type | Description |
|---|---|---|
| camera | CameraComponent | — |
| view | CameraView& modreq(InAttribute) | — |
void—protected void PlayAttackSound()
Play `Sandbox.BaseCombatWeapon.AttackSound` from the weapon - non-spatialized when the local player is the shooter, so your own gun doesn't pan around your head.
void—public virtual void PrimaryAttack()
Fire the primary attack. The default fires `Sandbox.BaseCombatWeapon.Ballistics` - spends a round, shoots the volley from `Sandbox.BaseCombatWeapon.AimRay` with `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(Sandbox.SceneTraceResult,System.Single,System.Single,Sandbox.TagSet,System.Boolean)`), or the host for seat/NPC/world weapons (damage applies directly).
void—public virtual void Reload()
Begin reloading. Routed to the host, which runs it authoritatively. Override `Sandbox.BaseCombatWeapon.OnReloadStarted` and friends for presentation rather than this.
void—public virtual void SecondaryAttack()
Fire the secondary attack. Base does nothing - override it. Same contract as `Sandbox.BaseCombatWeapon.PrimaryAttack`: runs once, on whoever controls the weapon.
void—public void SetNextFire(float delay)
Put both triggers on cooldown for `delay` seconds - for weapons where a shot blocks primary and secondary alike.
| Parameter | Type | Description |
|---|---|---|
| delay | float | — |
void—public void SetNextPrimaryFire(float delay)
Put primary fire on cooldown for `delay` seconds.
| Parameter | Type | Description |
|---|---|---|
| delay | float | — |
void—public void SetNextSecondaryFire(float delay)
Put secondary fire on cooldown for `delay` seconds.
| Parameter | Type | Description |
|---|---|---|
| delay | float | — |
void—public bool TakePrimaryAmmo(int amount = 1)
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).
| Parameter | Type | Description |
|---|---|---|
| amount = 1 | int | — |
bool—protected virtual int TakeReserveAmmo(Sandbox.BaseAmmoResource ammoType, int amount)
Take up to `amount` reserve ammo of the given type from the owning inventory's pool, returning how much was actually taken. Pairs with `Sandbox.BaseCombatWeapon.GetReserveAmmo(Sandbox.BaseAmmoResource)`.
| Parameter | Type | Description |
|---|---|---|
| ammoType | BaseAmmoResource | — |
| amount | int | — |
int—public bool TakeSecondaryAmmo(int amount = 1)
| Parameter | Type | Description |
|---|---|---|
| amount = 1 | int | — |
bool—protected virtual void Think()
Runs every frame before attack handling - continuous logic (spin-up, charge, ...). Base does nothing.
void—protected virtual void UpdateBodyAnimations(Sandbox.SkinnedModelRenderer body)
Drive the holder's body animation for this weapon. Runs every frame while deployed, on every peer, with the holder's renderer. Base sets the hold type; override to drive aiming, leaning and any other body parameters.
| Parameter | Type | Description |
|---|---|---|
| body | SkinnedModelRenderer | — |
void—protected virtual bool WantsPrimaryAttack()
Is the player asking to fire primary this frame? Held when automatic, pressed otherwise.
bool—protected virtual bool WantsReload()
Is the player asking to reload this frame?
bool—protected virtual bool WantsSecondaryAttack()
Is the player asking to fire secondary this frame?
bool—No results match this filter.
Properties57
Showing 57 properties
public virtual Ray Sandbox.BaseCombatWeapon.AimRay { get; set; }
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`.
public int Sandbox.BaseCombatWeapon.Ammo1 { get; set; }
Reserve ammo available to primary fire - the holder's pool of `Sandbox.BaseCombatWeapon.PrimaryAmmoType` (GMod's Ammo1).
int—public int Sandbox.BaseCombatWeapon.Ammo2 { get; set; }
Reserve ammo available to secondary fire (GMod's Ammo2).
int—protected virtual Sandbox.GameObject Sandbox.BaseCombatWeapon.Attacker { get; set; }
The GameObject credited for this weapon's damage - the holding player, or the weapon itself when unheld. Override to credit someone else (e.g. the driver of a mounted weapon).
public Sandbox.SoundEvent Sandbox.BaseCombatWeapon.AttackSound { get; set; }
Sound played when the weapon attacks - the gunshot, swing, launch. Played by the base `Sandbox.BaseCombatWeapon.OnShootEffects(Sandbox.BaseCombatWeapon.ShotEffect)`, so it reaches every peer that sees the shot.
public bool Sandbox.BaseCombatWeapon.AutoReload { get; set; }
Start a reload automatically when the trigger is pulled on an empty magazine.
bool—public Sandbox.BaseCombatWeapon.BallisticConfig Sandbox.BaseCombatWeapon.Ballistics { get; set; }
How the default `Sandbox.BaseCombatWeapon.PrimaryAttack` shoots - damage, pellets, spread and reach.
public bool Sandbox.BaseCombatWeapon.CanCancelReload { get; set; }
Can the reload be cancelled (e.g. by firing) part-way through?
bool—public int Sandbox.BaseCombatWeapon.Clip1 { get; set; }
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(System.Int32)`), whose count is the truth.
int—public int Sandbox.BaseCombatWeapon.Clip2 { get; set; }
Rounds currently in the secondary magazine, or -1 when unused (GMod's Clip2). Host authoritative.
int—public int Sandbox.BaseCombatWeapon.ClipMaxSize { get; set; }
Primary magazine size.
int—protected Color Sandbox.BaseCombatWeapon.CrosshairCanShoot { get; set; }
Crosshair colour for a weapon that's ready to fire.
protected Color Sandbox.BaseCombatWeapon.CrosshairNoShoot { get; set; }
Crosshair colour for a weapon that can't fire - empty, reloading, cooling down.
public virtual Vector2 Sandbox.BaseCombatWeapon.CurrentSpread { get; set; }
The current spread cone in degrees - the base cone widened by recent firing. Override to modify it (e.g. narrow while aiming down sights).
public float Sandbox.BaseCombatWeapon.DeployTime { get; set; }
Seconds after deploying (switching to) this weapon before it can fire.
float—public Sandbox.SoundEvent Sandbox.BaseCombatWeapon.DryFireSound { get; set; }
Sound played when the trigger is pulled with no ammo.
public float Sandbox.BaseCombatWeapon.FirstShellReloadTime { get; set; }
Extra delay after the first round before the rest (e.g. a longer first insert). Incremental only.
float—public Sandbox.BaseCombatWeapon.WeaponHandedness Sandbox.BaseCombatWeapon.Handedness { get; set; }
Which hand(s) the holder carries this in - drives the holder animgraph's "holdtype_handedness" parameter alongside `Sandbox.BaseCombatWeapon.HoldType`. Only some hold types support it (e.g. pistol, holditem).
public string Sandbox.BaseCombatWeapon.HoldBone { get; set; }
The bone on the holder's renderer to attach the world model to.
string—public Sandbox.SkinnedModelRenderer Sandbox.BaseCombatWeapon.HolderRenderer { get; set; }
The body renderer the world model attaches to - the holder's renderer.
public string Sandbox.BaseCombatWeapon.HoldType { get; set; }
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.
string—public bool Sandbox.BaseCombatWeapon.IncrementalReloading { get; set; }
Load one round at a time instead of the whole magazine (shotgun-style).
bool—public bool Sandbox.BaseCombatWeapon.IsHeld { get; set; }
True while held by a player.
bool—public bool Sandbox.BaseCombatWeapon.IsReloading { get; set; }
True while a reload is in progress. Host authoritative, synced so every peer can animate.
bool—public int Sandbox.BaseCombatWeapon.MaxReserveAmmo { get; set; }
Most reserve ammo the holder can carry for primary fire (from the ammo type).
int—protected Sandbox.TimeUntil Sandbox.BaseCombatWeapon.NextPrimaryFire { get; set; }
Time until primary fire is off cooldown. Not synced - the firing side gates itself (GMod's GetNext/SetNextPrimaryFire). The host doesn't enforce the rate; a hardened game rate-checks incoming shot claims instead (see `Sandbox.BaseCombatWeapon.OnValidateShotClaim(Sandbox.BaseCombatWeapon.ShotClaim@)`).
protected Sandbox.TimeUntil Sandbox.BaseCombatWeapon.NextSecondaryFire { get; set; }
Time until secondary fire is off cooldown.
public Sandbox.BaseCombatWeapon.NpcUsage Sandbox.BaseCombatWeapon.Npc { get; set; }
How an NPC fights with this weapon.
public Sandbox.PlayerController Sandbox.BaseCombatWeapon.Owner { get; set; }
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`). Derived from the hierarchy.
public Sandbox.BaseAmmoResource Sandbox.BaseCombatWeapon.PrimaryAmmoType { get; set; }
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.
public bool Sandbox.BaseCombatWeapon.PrimaryAutomatic { get; set; }
When true primary fire keeps firing while the button is held; when false it fires once per press (GMod's `Primary.Automatic`).
bool—public int Sandbox.BaseCombatWeapon.PrimaryClipSize { get; set; }
Magazine size for primary fire, or -1 when it feeds straight from reserve (GMod's Primary.ClipSize). Derived from `Sandbox.BaseCombatWeapon.UsesAmmo` / `Sandbox.BaseCombatWeapon.UsesClips` / `Sandbox.BaseCombatWeapon.ClipMaxSize`.
int—public float Sandbox.BaseCombatWeapon.PrimaryDelay { get; set; }
Seconds between primary shots - the fire rate (GMod's `Primary.Delay`).
float—protected virtual int Sandbox.BaseCombatWeapon.ReloadFillTarget { get; set; }
How full a reload fills the primary magazine. Defaults to `Sandbox.BaseCombatWeapon.PrimaryClipSize` - override for +1-in-the-chamber style reloads (e.g. `ClipMaxSize + (Clip1 > 0 ? 1 : 0)`). Read once when the reload starts.
int—public float Sandbox.BaseCombatWeapon.ReloadStartTime { get; set; }
Delay before the first round goes in. Zero uses `Sandbox.BaseCombatWeapon.ReloadTime`.
float—public float Sandbox.BaseCombatWeapon.ReloadTime { get; set; }
How long a (full) reload takes, in seconds. For incremental reloads, the time per round.
float—public Sandbox.BaseAmmoResource Sandbox.BaseCombatWeapon.SecondaryAmmoType { get; set; }
public bool Sandbox.BaseCombatWeapon.SecondaryAutomatic { get; set; }
When true secondary fire is full-auto while held.
bool—public int Sandbox.BaseCombatWeapon.SecondaryClipSize { get; set; }
Magazine size for secondary fire, or -1 when it doesn't use one (GMod's Secondary.ClipSize). Set directly - unlike `Sandbox.BaseCombatWeapon.PrimaryClipSize`, it isn't derived from the clip settings.
int—public int Sandbox.BaseCombatWeapon.SecondaryDefaultClip { get; set; }
Rounds loaded into the secondary magazine when first given. -1 fills it.
int—public float Sandbox.BaseCombatWeapon.SecondaryDelay { get; set; }
Seconds between secondary shots.
float—public virtual bool Sandbox.BaseCombatWeapon.ShouldAvoid { get; set; }
Avoid auto-switching to a gun with nothing left to fire or load (see `Sandbox.BaseInventoryItem.ShouldAvoid`).
bool—protected float Sandbox.BaseCombatWeapon.SpreadBloom { get; set; }
How bloomed the spread is - 0 settled, 1 right after a shot.
float—public float Sandbox.BaseCombatWeapon.SpreadScale { get; set; }
Runtime multiplier on the spread cone - 1 is the configured ballistics. NPCs set this to the weapon's `Sandbox.BaseCombatWeapon.Npc` spread scale times their own skill when they equip it.
float—public int Sandbox.BaseCombatWeapon.StartingAmmo { get; set; }
Reserve ammo granted on first pickup, seeded into the holder's pool.
int—protected Sandbox.TimeSince Sandbox.BaseCombatWeapon.TimeSinceShoot { get; set; }
Time since the last shot - drives spread bloom.
protected virtual Ray Sandbox.BaseCombatWeapon.UnheldAimRay { get; set; }
The aim ray to use when this weapon isn't held by a player - placed in the world, mounted, or controlled from a seat. Base fires from the muzzle; override for camera-targeted aim.
public bool Sandbox.BaseCombatWeapon.UsableByNpcs { get; set; }
Can NPCs fight with this weapon at all?
bool—public bool Sandbox.BaseCombatWeapon.UsesAmmo { get; set; }
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.
bool—public bool Sandbox.BaseCombatWeapon.UsesClips { get; set; }
Feed primary fire from a magazine (true) or straight from the reserve pool (false).
bool—public bool Sandbox.BaseCombatWeapon.UsesPrimaryClip { get; set; }
True when primary fire feeds from a magazine rather than straight from reserve.
bool—public bool Sandbox.BaseCombatWeapon.UsesSecondaryClip { get; set; }
True when secondary fire feeds from a magazine.
bool—public Sandbox.GameObject Sandbox.BaseCombatWeapon.ViewModel { get; set; }
The spawned view model instance, or null. Owner-only and not networked - each client makes its own.
public Sandbox.GameObject Sandbox.BaseCombatWeapon.ViewModelPrefab { get; set; }
First-person view model prefab. Spawned only on the client holding this item.
public Sandbox.BaseWeaponModel Sandbox.BaseCombatWeapon.WeaponModel { get; set; }
The `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.
public Sandbox.GameObject Sandbox.BaseCombatWeapon.WorldModel { get; set; }
The spawned world model instance, or null. Not networked - each peer makes its own.
public Sandbox.GameObject Sandbox.BaseCombatWeapon.WorldModelPrefab { get; set; }
Third-person world model prefab, attached to the holder's hand bone. Seen by everyone.
No results match this filter.