S&box Wiki

First Person

BOTH THIS WIKI PAGE AND THE FEATURE ITSELF ARE A WORK-IN-PROGRESS. PLEASE DO NOT TOUCH. THANK YOU! đź‘Ť

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.

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

Basic & advanced animation setups

We can divide the use cases into two broad categories.

Basic

The biggest criteria here is that your held object is going to be driven by one bone. If it has its own animations and/or bones, then they are not bonemerged and happen solely on their own—through, either through an autoplay layer or a sequence sync (a currently hypothetical feature)

These objects are to be bonemerged onto first_person_arms.vmdl, and you would be using existing sequences + adjustment layers to make them work well.

Advanced

*You want to work with complex objects that have more than one bone. *You want to use your own animations and/or your own animgraph. *You want modify the object/hold bones as you wish, and maybe even flip the effective hierarchy so that the held object always drives the arms through IK.

If any of these matches your use case, then what you should be doing is "forking" first_person_arms.vmdl; your new VMDL will store the following:

  • The original standard first person arms skeleton.
  • NOT the original arms mesh. first_person_arms.vmdl will be bonemerged into your VMDL at runtime.
  • The original VMDL prefabs that provide the animations used by the base animgraph.

Standardized parameters

These are features implemented solely through the "base" animgraph, the one that provides base features and standardized animation parameters. (Please refer to the above warning again.)

Parameters

move_x/y/z, move_groundspeed

Same as the Citizen, but this time, it's normalized to a -2,2 range, where 0-1 is "regular movement" and 1-2 is "extra movement" (I actually don't know if this will be useful, maybe not.)

move_cycle_control

In order to sync up the animation to the footsteps (which are themselves driven by the 3rd person character), this cycle control parameter needs to be driven.

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

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

arms_type

As outlined in the first section of this page, there will eventually be other arm variants. On paper, the plan is this: the parameter will apply global additive adjustments to keep proportions intact, using a delta layer computed from [new arm bind pose] subtracted by [male arms bind pose]. (Further adjustments would be made possible through the finger and hold adjustment layers.)

Finger adjustments

FingerAdjustment_[A]_[B]

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.

Hold adjustments

HoldAdjustment_[A]_[B]_[C]

Where A is the hand (RH or LH), B is the type of adjustment (Pos or Rot), and C is the axis (X, Y, Z).

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)