Skip to main content
s&box ships with a library of production-ready assets you can use in any game without building them yourself. These include a fully animated player character, a set of first-person weapons, and a growing collection of models and materials available through the Cloud Browser.

​
The Citizen character

The Citizen is the default player model provided by Facepunch. It comes with a complete skeleton, animgraph, blend shapes, and LOD meshes — everything you need to have a working player character out of the box.
All Citizen source files — VMDLs, FBXs, animgraphs, and more — ship with the game. Find them under addons/citizen/models/citizen in your s&box installation. These files are kept in sync with Facepunch’s source folder, so new files appear automatically when Facepunch adds them.

​
Source files and scale

All Citizen source files are in centimeters. The VMDL applies a ScaleAndMirror modifier with a value of 0.3937 to convert to the engine’s inch-based units. When you create clothing or other bonemerged content, work in centimeters and apply the same modifier in your VMDL.

​
Procedural helper bones

The Citizen uses constraint-driven procedural bones for better limb deformation. You do not need to export animation data for these bones — the engine drives them at runtime.
  • arm_upper_[R/L]_twist[0/1] — shoulder to biceps
  • arm_elbow_helper_[R/L] — extreme elbow angles
  • arm_lower_[R/L]_twist[0/1] — forearm to wrist
  • leg_upper_[R/L]_twist[0/1] — pelvis to thigh
  • leg_knee_helper_[R/L] — extreme knee angles
  • leg_lower_[R/L]_twist[0/1] — calf to foot
  • neck_clothing — reduces neck twist for clothing items
Never skin geometry to the limb bones themselves (arm_upper_R, leg_lower_L, etc.). These are containers. Only skin to the *_twist0 and *_twist1 child bones. Breaking this rule causes height scaling to malfunction.

​
LOD reference

LODTriangles (body)Switch distance
LOD06.6k (+ 7.2k head)—
LOD14.2k (+ 7.2k head)5
LOD21.7k (+ 1.0k head)20
LOD31.0k (+ 0.4k head)40
LOD41.0k (+ 0.2k head)70

​
Adding animations

To add a small number of new animations without forking the full Citizen VMDL, use the Base Model field in ModelDoc and reference citizen.vmdl. You can only add animations this way — you cannot add new meshes, materials, or bones through this feature.
Give your new animations unique names or prefix them. Animation name collisions produce undefined behavior.
For a community-made Citizen control rig, see: https://github.com/Ali3nSystems/Ecodelia-Tools-for-Facepunch-Assets

​
Stretching limbs

The Citizen supports non-uniform limb lengths. Because animations store position offsets in parent-local space, you can author animations where bone offsets differ from the default — effectively stretching or squashing arms and legs without per-bone scale data.

​
First-person weapons

Facepunch provides a ready-to-use first-person weapon pack at: https://sbox.game/facepunch/sboxweapons The pack is open-source. When downloaded through the editor it includes source files: VMDLs, FBXs, animgraphs, and subgraphs.

​
How to attach arms to a weapon

The setup is the reverse of what Source 1 developers may expect:
Bonemerge the arms onto the weapon, not the weapon onto the arms.

​
Animgraph parameters

Once arms are bonemerged onto a weapon, send animgraph parameters to drive animations. Below are the most commonly used parameters.
ParameterTypeDescription
b_groundedboolWhether the player is on the ground.
b_jumpbool (self-resets)Trigger a jump.
b_sprintboolSprinting stance. Set true only when the sprint key is held and the player is moving.
move_bobfloat 0–1Intensity of sway and bob.
move_bob_cycle_controlfloat 0–1Manual scrub of movement animation phase.
ParameterTypeDescription
b_attackbool (self-resets)Fire or punch.
b_attack_dryboolUse when the weapon is empty.
b_reloadbool (self-resets)Trigger reload animation.
b_emptyboolSet when the magazine is empty.
ironsightsenum (1 = ADS)Aim-down-sights stance.
b_holsterboolHolster the weapon.
ParameterWhat it controls
speed_reloadReload animations
speed_deployDeploy and holster animations
speed_ironsightsIron sights transitions
speed_grabGrab stance and gestures

​
Animation event tags

The animgraph fires event tags as strings to your game code via OnAnimTagEvent. Use these instead of hard-coding timings.
TagMeaning
attack_discouragedThe weapon is not ready to fire cleanly yet.
holster_finishedSafe to destroy the weapon GameObject.
reload_bodygroupThe magazine is off-screen — swap bodygroup now.
reload_incrementA mag/clip has been inserted — increment ammo counter.
melee_swingActive across the full melee swing.
melee_hitThe moment of melee impact.

​
Replacing weapon meshes

To use your own art while keeping the weapon’s animgraph, hide the default weapon mesh and bonemerge (or parent) your mesh on top. Adjust hand grip using the FingerAdjustment_* float parameters: 
FingerAdjustment_{L|R}{1|2|3|4|5}_{Bend|Curl|Roll|Spread}
For example, FingerAdjustment_L3_Bend bends the left hand’s middle finger.
The weapons are designed for a maximum horizontal FOV of 80° at 16:9. Higher FOVs are not guaranteed to look correct.

​
Cloud assets

The Cloud Browser gives you access to every asset published on sbox.game. Drag an asset into your scene and s&box downloads and caches it automatically. You can also reference cloud assets directly in code: 
// Reference by ident at compile time (ships with your package)
var model = Cloud.Model( "facepunch.w_usp" );

// Or expose a property in the editor for cloud or local assets
public Model MyModel { get; set; }
For spawnable-prop games or procedurally generated content, mount packages at runtime: 
static async Task<Model> DownloadModel( string packageIdent )
{
    var package = await Package.Fetch( packageIdent, false );
    if ( package == null || package.Revision == null )
        return null;

    await package.MountAsync();

    var primaryAsset = package.GetMeta( "PrimaryAsset", "" );
    return Model.Load( primaryAsset );
}