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

• b_grounded and b_jump (self-resets) should behave just like on characters, and can be replicated as-is from third-person to first-person.
• b_sprint controls the "sprinting stance". I would recommend to set it to true IF you hold the sprinting key AND if you're also moving, but this specific detail is up to you.
• move_groundspeed or move_speed from our characters are replaced here with move_bob (float, 0-1), which controls the intensity of the swaying/bobbing from side to side.
  • move_bob_cycle_control (float, range 0,1) lets you control the cycle (phase) of this animation, and take control over it. Think of it as "scrubbing through the animation" yourself. This mode of playback is toggled on if this float is any other value than 0.00. To return to the normal behaviour, leave this parameter on 0.00 for more than 100ms.
• move_x, move_y, move_z are floats normalized to a range of -1,1. These aren't actually used by any of our graphs yet, but they might be one day, so it wouldn't hurt to set them.

Weapon mechanics, actions, and states

• b_attack: will make a gun play its fire animation, or cause a punch to be thrown.
• b_attack_dry: use this one instead of the regular attack if a gun is supposed to be empty.
• b_attack_hit: should be set to true if the attack connects. This is used in melee weapons, because we want to play different animations based on whether you hit or miss.
• attack_hold: 0,1 float. A sort of "staggered recoil" intended for continuous fire. Should be blending to 1 if you are holding down the fire button (and firing is actually happening).
• b_reload: self-resets. Exactly what it says on the tin.
• b_empty: set to true if the magazine, clip, etc. is empty. Some animgraphs will reflect this visually on the weapon, and play a different reload animation when set to true.
• ironsights is an enum (not a bool!) that should be set to 1 when you want an ADS stance.
• ironsights_fire_scale: lets you scale down the strength of fire animations during ironsights (float, 0,1)
• firing_mode: enum, varies per weapon. Set to visually reflect the firing mode on whatever knob or selector a gun might have. Usually, 0 = safety/off, 1 = single, 2 = burst, 3 = auto.
• b_deploy_skip: instantly set this to true if you want to skip the deploy animation (the weapon coming up from off-screen) that plays when the animgraph gets initialized.
• b_twohanded: some weapons (like the USP pistol) support switching between a one-handed and a two-handed animation set through this parameter.
• b_lower_weapon: aim the weapon away from the center of the screen, and lower it, similar to what happens in Half-Life 2 while aiming at allies.
• b_holster: will put the weapon away. The graphs don't come back from this gracefully, so you should completely reset the weapon state/graph if you are going to deploy the same weapon again.
• weapon_pose: enum, varies per weapon. Used to adjust the hand pose when some attachments are active (e.g. M4A1 handguard covers).
• b_grab: will make the left hand reach out towards the center of the screen (think L4D-style when aiming at an item that can be picked up)
• grab_action: self-resets. Trigger an animation related to the "grab stance". 1 = sweep down, 2 = sweep right, 3 = sweep left, 4 = push button (recommend you freeze camera/position during that one). Animations can be triggered without grab stance, in which case I strongly recommend you immediately set b_grab to true.

Speed scaling

• speed_reload lets you scale the speed of reload animations.
• speed_deploy lets you scale the speed of deploy & holster animations.
• speed_ironsights lets you scale the speed of ironsight transitions.
• speed_grab lets you scale the speed of "grab stance" transitions & actions.

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 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 (self-resets). This can be done at any time. Only this parameter will set the firing pin (striker) back to its ready position.

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 (not self-resetting!) activates a sort of "reloading stance", during which you can fireb_reloading_shell (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 (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, range 0,1) for making the hand visually squeeze the trigger.

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