Facepunch provides some ready-to-use first-person weapons for you!

➡️ https://sbox.game/facepunch/sboxweapons

These first-person weapons are "open-source", and if downloaded from the editor, they will come bundled with their VMDL, FBX, and Animgraph source files.

How to use our weapons

You may be familiar with the classic Source 1 setup of bonemerging separate weapon models onto a single common arms model. However, our weapon assets require the opposite.

Our first-person arms can be found bundled in with the game files, at the following path: models\first_person\first_person_arms.vmdl. Note that these arms are also "open-source", and that's where all the shared animations and subgraphs used by all of our weapons are currently stored. The actual true path is:\game\addons\citizen\Assets\models\first_person\first_person_arms.vmdl

Common animgraph parameters

Now that you've bonemerged arms onto our weapons, you can send animgraph inputs to the weapon just like you would with any other model.

Movement

Parameters	Type & values	Description
b_grounded	☑️ bool	Behaves like on characters; can be replicated as-is from third-person to first-person.
b_jump	☑️ bool, ♻️ self-resets	Behaves like on characters; can be replicated as-is from third-person to first-person.
b_sprint	☑️ bool	Controls sprinting stance. I recommend to set to true only if sprint key held and player is moving.
move_bob	🎚️ float, 0.0↔1.0	Intensity of movement animations sway/bob (equivalent to move_groundspeed in 3P).
move_bob_cycle_control	🎚️ float, 0.0↔1.0	Manual control of movement animation phase. Think of it like scrubbing through the animation yourself. Active if ≠ 0.0. If = 0.0, auto-resumes normal behaviour after 100ms.
move_x, move_y, move_z	🎚️ float, -1.0↔1.0	Normalized movement input; unused but reserved for future, and should ideally be set anyway.

Weapon mechanics, actions, and states

Parameters	Type & values	Description
b_attack	☑️ bool, ♻️ self-resets	Plays the gun's fire animation, or throws a punch.
b_attack_dry	☑️ bool	Use this instead of b_attack when the gun is empty.
b_attack_hit	☑️ bool	Set to true if the attack connects (used for melee hit/miss animation variation).
attack_hold	🎚️ float, 0.0↔1.0	Staggered recoil for continuous fire; blend toward 1 when holding fire and continuously firing.
b_reload	☑️ bool, ♻️ self-resets	Triggers reload animation.
b_empty	☑️ bool	Set to true if magazine/clip is empty; is used to switch to different reload animations and affect weapon visuals (e.g. slide pulled back).
ironsights	🗂️ enum, 1 = ADS	Trigger "aim down sights" stance. The animation is only in charge of aligning the gun in its default state, additional offsets (for attachments) are up to you in code.
ironsights_fire_scale	🎚️ float, 0.0↔1.0	Scale down strength of fire animations while aiming down sights.
firing_mode	🗂️ enum	Reflects firing mode selector on the weapon. Values vary. Usually: 0 = safety/off, 1 = single, 2 = burst, 3 = auto.
b_deploy_skip	☑️ bool	Skip the deploy animation when animgraph initializes.
b_twohanded	☑️ bool	Toggle between one-handed and two-handed animation sets. Only supported by some weapons.
b_lower_weapon	☑️ bool	Aim the weapon away from center and lower it (HL2-style ally-friendly aim posture).
b_holster	☑️ bool	Holster the weapon. The graph doesn't recover from this; you should fully reset the graph from code if you redeploy the same weapon.
weapon_pose	🗂️ enum	Adjust pose for attachments. Used by some weapons; refer to the section below.
b_grab	☑️ bool	Trigger the "grab stance" (left hand ready, towards the center of the screen)
grab_action	🗂️ enum, ♻️ self-resets	Trigger a "grab gesture". 1 = sweep down, 2 = sweep right, 3 = sweep left, 4 = push button.
deploy_type, reload_type	🗂️ enum	Used by some weapons; refer to the section below.

Speed scaling

You can change these 🎚️ floats at any time, including in the middle of the animations they affect!

Parameters	What's affected
speed_reload	Reload animations
speed_deploy	Deploy & holster animations
speed_ironsights	Ironsight transitions
speed_grab	Grab stance & grab gestures

Aim modifiers

The aim_pitch_inertia and aim_yaw_inertia parameters (🎚️ floats, exploitable range of -45↔45) control an animated, bouncy "lag" of the weapon when looking around (or other parts, e.g. the left arm when "grab stance" is active).

Parameters & behaviours specific to certain weapons

v_m4a1 (assault rifle)

• weapon_pose (🔢 int) should be set to 1 if the handguard covers bodygroup is active.
• reload_type (🗂️ enum) can be set to 1 for a "pull" animation, instead of tossing the magazine.
• deploy_type (🗂️ enum) can be set to 1 for a faster variant.

v_m700 (sniper rifle)

• b_reload_bolt (☑️ bool, ♻️ self-resets) triggers a bolt action. This can be done at any time. The firing pin (striker) will be sent back to its ready position only after using this parameter.
• deploy_type (🗂️ enum) can be set to 1 for a faster variant.

v_mp5 (submachine gun)

• deploy_type (🗂️ enum) can be set to 1 for a faster variant.

v_physgun

• b_button (☑️ bool) makes the right hand push down the big button on the iron part.
• brake (🎚️ float, 0.0↔1.0) makes the left hand squeeze the bicycle brake.
• stylus (🎚️ float, -1.0↔1.0) makes the record player stylus needles go in/out.

v_recoillessrifle (rocket launcher)

• deploy_type & reload_type (🗂️ enums) can be set to 1 for faster variants.

v_spaghellim4 (shotgun, automatic)

• b_reload is NOT self-resetting. Toggle it on to start reloading, toggle it off to end. This is the "simple" way to handle reloads. See below for advanced controls.
• b_reloading (☑️ bool) activates a "reloading stance".
  • During this, you can fire b_reloading_shell (☑️ bool ♻️ self-resets) at any pace.
• The animation for inserting the first shell through the carrier can be triggered with b_reloading_first_shell (☑️ bool ♻️ self-resets) regardless of the other parameters.

↳ You can trigger these parameters in (mostly) any order, at (mostly) the pace that you want.

• deploy_type (🗂️ enum) can be set to 1 for a faster variant.

v_toolgun

• b_twohanded (☑️ bool) is supported.
• trigger_press (🎚️ float, 0.0↔1.0) will make the hand visually squeeze the trigger. This is because the toolgun is not a "conventional" weapon, and it needs to be able to "fire" without that actually being an "attack".
• b_joystick (☑️ bool) activates a "joystick stance".
  • During this, use joystick_x and joystick_y (🎚️ floats, -1.0↔1.0) to make the right thumb control the joystick. with Note that diagonal directions would be roughly ±0.71 in both axises (because the joystick is a circle, not a square).
• firing_mode is assigned to the state of the side switch. 0 = middle, 1 = up, 2 = down.

v_usp (pistol)

• b_twohanded (☑️ bool) is supported.
• deploy_type (🗂️ enum) can be set to 1 for a different animation, without the safety being turned off.

Tags

All animgraphs have their "Internal Tags" for various purposes — but most weapons will also send "Event Tags" back to the game code in order to inform of various events. The most common example is changing the bodygroup of a mesh mid-reload animation, so that a held empty magazine becomes full again.

See OnAnimTagEvent. Tags are passed as a string, as-is; they are effectively "hints" for the code, they don't contain any other data than their name.

Camera bone

The camera is animated through the 🦴camera bone. Its position (relative to the first-person 0,0,0) and orientation (relative to +X forwards, +Y left, +Z up) should add onto your in-game camera.

Our animgraphs automatically "weaken" this camera animation by 50% while moving (this is mapped to the use of the move_bob float).

The "positional" part of these animations should always be used. As for rotations, feel free to offer a toggle for players prone to motion sickness, or to simply not play it back.

Replacing our guns with your own

You might want to use your own gun models. You can hide our gun meshes with the provided bodygroups, and then bonemerge your own on top.

To correct the animations, you can use the finger adjustment parameters. They're all floats with a range of -60,60, emulating a CAT-style finger controller setup. The syntax goes like this:

FingerAdjustment_{L|R}{1|2|3|4|5}_{Bend|Curl|Roll|Spread}

For example: FingerAdjustment_L3_Bend will bend the left hand's middle finger.

Technical details

Each weapon contains its own skeleton. There are three separate root hierarchies: the weapon bones, the arms bones, and the camera.

Under 🦴weapon_root, there's 🦴weapon_root_children, and under that one, different bones for every weapon (as the various mechanical bits of every gun are different).

There are two IK bones under 🦴weapon_root, one for each hand.

The control rig used to create animation has these bones constrained to be at the same position and orientation as the hand bones, and this data is baked out during export, when the exporter "flattens" the animation by making every frame a keyframe. This means that the weapon knows where the hands should be relative to itself at any time — and the hands are always corrected back via IK in their animgraphs.

From there, it becomes very easy to apply various layers and additives (like movement bobbing) and have the hands always stick where they should be. Most of the time, only 🦴weapon_root needs to move… and this means a lot of animations can be shared between guns!