S&box Wiki

First Person

First-person assets are being actively worked on, and are subject to change.

The goal of the first person base is to help you and provide you with valuable tools and "starter kits", whether you are a beginner or an advanced user.

If you would like to make animations for the first person assets, here are community made control rigs to get you started: https://github.com/Ali3nSystems/Ecodelia-Tools-for-Facepunch-Assets

First person arms

The main model can be found here: addons/citizen/models/first_person/first_person_arms.vmdl

The "base" animgraph implements standard features for the "basic" use cases (see below), and provides you with the setup & parameters the adjustment layers stuff.

Support for Animgraph groups and subgroups (which are groups-as-an-external-file) is being worked on. This base animgraph is planned to be an externally-referenceable file for you to use in your own animgraph.
The current arms are "male," but there will eventually be others (the two most likely ones being "female" and "citizen"). These will probably be implemented through bodygroups, and the change in proportions will be handled through a parameter that applies a delta layer. All animations are planned to be authored on the "male" skeleton, with the delta layer being in charge of the type change.
While everything is being worked out, there is no standard 1st person Animator/Controller yet. You can look at Fists.cs of the official Sandbox gamemode in the meantime.

Animation setup

This entire section needs to be rewritten, but here are the broad strokes for now:

Only one "official weapon" is using first_person_arms.vmdl as-is: the fists.

Weapons, held items, etc. should go live in their own VMDL, and copy the original skeleton over.

The copied skeleton of the arms should ideally be left as-is, no changes, but you are free to add new leaves to it. You have complete free rein over what you want to do under weapon_root & weapon_root_children.

Facepunch's "official weapons" are set up in such a way that the weapon root can be animated independently of anything else, and arms/hands are corrected back to match the original relative position (in weapon_root's space) through the use of IK. This lets us do a ton of cool additive layering, and offer a lot of template "shared animations" that let us test weapons quickly.

You have complete freedom over the hierarchization of the skeleton. The only thing that really matters, in the end, is that the first_person_arms.vmdl bones stay in the same shape and proportions, but you could completely flip their hierarchy if you wanted to. You can link weapon_root under hand_R if you want to. The downside of doing so is that you'll break the common shared weightlists (they assume weapon_root being independent)

Facepunch's "official weapons" rely heavily on additive animation, which may seem a bit unintuitive at first. However, this comes with a ton of benefits with regards to compositing, and lets you reuse animations across different weapons super easily (hence the "shared" template animation set)

Remember that the hierarchization of your animation control rig and of the final output skeleton (what you export out of your 3D software) do not have to be the same.

Standardized parameters

These parameters should ideally be the same between all weapons. Unfortunately there is no way yet to have referenced & shared lists of prefabs and tags between different animgraphs and subgraphs, so as of the time of writing, this is a completely manual process that involves copying and pasting guts of the files manually.


move_x/y/z, move_groundspeed




aim_pitch_inertia, aim_yaw_inertia

Used to create drag and follow-through in the animation. This parameter uses the current angular velocity of the player's aim. NOTE: plans are being made to implement a different damping mode that would bounce and overshoot physically.

aim_pitch aim_yaw

Used for tweaking the weapon pose as you away from the center. (This means only the pitch one is of any real use 99% of the time... unless you implemented a moving crosshair kind of thing.)

insert skeleton delta parameter here


Finger adjustments (from prefab)


Where A is the hand followed by the finger number (R2 is right index, L4 is left ring), and B is the type of adjustment: Bend, Curl, Roll, Spread. This is an arrangement that's very inspired by the CAT rig system in 3ds Max.

Weapon adjustments

These used to be a thing but now they aren't, they need to be replaced

Hand pose adjustments

Not implemented yet.

Exporting parameter values

You have to copy these over by hand. We should include a way to export current parameter values (as previewed) to your clipboard, or even better, as the C# code so you can copy/paste easily to your first person code.

Driving the camera

Through animation

Use the camera bone.

(add code here)

Through code

(add code here)