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).

The aim_pitch and aim_yaw parameters control a positional offset of the weapon when looking up/down (or left/right relative to the center of the screen). This can be used to make weapons not aim at the exact center of the screen — Bungie games do this!

Parameters specific to certain weapons

v_m4a1

weapon_pose (🔢 int) should be set to 1 if the handguard covers bodygroup is active.

v_m700

On this sniper rifle, you can trigger a bolt action by sending b_reload_bolt (☑️ bool, ♻️ self-resets). This can be done at any time. The firing pin (striker) will be sent back to its ready position only after using this parameter.

v_recoillessrifle

On this rocket launcher, you can set deploy_type & reload_type to 1 for faster variants.

v_spaghellim4

On this shotgun, b_reload is NOT self-resetting. Toggle it on to start reloading, toggle it off to end. For more advanced control, there are additional parameters.

b_reloading (☑️ bool) activates a sort of "reloading stance", during which you can fireb_reloading_shell (☑️ bool ♻️ self-resets) at the rhythm that you desire. 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.

v_toolgun

Because the toolgun is not a "conventional" weapon, it needs to be able to "fire" without that actually being an attack. So there's trigger_press (🎚️ float, 0.0↔1.0) for making the hand visually squeeze the trigger.

b_joystick (☑️ bool) activates a "joystick stance" during which you can make the right thumb control the joystick with joystick_x and joystick_y (🎚️ floats, -1.0↔1.0). 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.

Tags

Most weapons will send Tags back to the game in order to inform the code that some things need to happen (for example, changing bodygroups).

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.