Component that represents what a player is holding, driven by the host. Syncs world/view model paths, holdtype, handedness, offsets and a lowered flag, then builds a world model attached to the body's hold_R bone (or hold_R attachment) and a first-person overlay view model with bone-merged arms. Sets classic animgraph parameters each frame for movement, aim and inertia, provides muzzle transform/flash, and broadcasts animation triggers to all machines with an optional owner skip.
using System;
using System.Linq;
namespace RoleplayFramework.Players;
/// <summary>
/// What a player holds, set by the host from Lua (<c>ply:SetWeaponModels</c>), modelled on Facepunch's sandbox
/// (BaseSandboxWeapon / ViewModel):
/// <list type="bullet">
/// <item><b>World model</b> on the body's <c>hold_R</c> bone object, with a per-model offset/rotation (models aren't
/// authored for the bone; Facepunch keeps the same offsets in its *_wm prefabs).</item>
/// <item><b>Body animation</b>: the human animgraph's <c>holdtype</c> enum (none, pistol, rifle, shotgun, holditem,
/// melee_punch, melee_weapons, rpg, physgun) and <c>holdtype_handedness</c> (2H, RH, LH).</item>
/// <item><b>View model</b> (owner, first person): the weapon's v_ model plus human arms bone-merged onto it (arms
/// bodygroups 21), drawn in the overlay layer, driven with movement/aim/inertia parameters each frame. A view
/// model of <c>"arms"</c> shows the arms alone (fists).</item>
/// </list>
/// Animation triggers (<see cref="PlayAnim"/>) reach every machine; the owner's own predicted ones are played
/// locally (<see cref="AnimLocal"/>), so the host can skip the owner.
/// </summary>
public sealed class RpHeldWeapon : Component
{
[Sync( SyncFlags.FromHost )] public string WorldModel { get; set; } = "";
[Sync( SyncFlags.FromHost )] public string ViewModel { get; set; } = "";
/// <summary>Option name of the animgraph's "holdtype" enum ("none", "pistol", ...).</summary>
[Sync( SyncFlags.FromHost )] public string HoldType { get; set; } = "none";
/// <summary>"2H", "RH" or "LH".</summary>
[Sync( SyncFlags.FromHost )] public string Handedness { get; set; } = "2H";
[Sync( SyncFlags.FromHost )] public Vector3 WorldOffset { get; set; }
[Sync( SyncFlags.FromHost )] public Angles WorldAngles { get; set; }
/// <summary>View model offset in view space (x forward, y left, z up), like Facepunch's ViewModelOffset.</summary>
[Sync( SyncFlags.FromHost )] public Vector3 ViewOffset { get; set; }
/// <summary>Bodygroup mask of the view model (0 = the model's default).</summary>
[Sync( SyncFlags.FromHost )] public ulong ViewBodyGroups { get; set; }
/// <summary>Weapon held low (animgraph b_weapon_lower), e.g. while a menu is open or for passive weapons.</summary>
[Sync( SyncFlags.FromHost )] public bool Lowered { get; set; }
public const string ArmsModel = "models/first_person/v_first_person_arms_human.vmdl";
public const ulong ArmsBodyGroups = 21;
static readonly string[] HoldTypes = { "none", "pistol", "rifle", "shotgun", "holditem", "melee_punch", "melee_weapons", "rpg", "physgun" };
/// <summary>Animgraph hold type for a GMod-style or graph name.</summary>
public static string HoldTypeOf( string name ) => (name ?? "").ToLowerInvariant() switch
{
"pistol" or "revolver" or "duel" => "pistol",
"rifle" or "ar2" or "smg" or "crossbow" => "rifle",
"shotgun" => "shotgun",
"physgun" or "toolgun" => "physgun",
"rpg" => "rpg",
"fist" or "fists" or "punch" or "melee_punch" => "melee_punch",
"melee" or "melee2" or "knife" or "swing" or "melee_weapons" => "melee_weapons",
"item" or "holditem" or "slam" or "grenade" or "camera" or "magic" => "holditem",
_ => "none",
};
public static string HandednessOf( string name ) => (name ?? "").ToLowerInvariant() switch
{
"right" or "rh" => "RH",
"left" or "lh" => "LH",
_ => "2H",
};
public static bool IsHoldType( string name ) => HoldTypes.Contains( name );
PlayerController Controller => Components.Get<PlayerController>();
SkinnedModelRenderer Body => Controller?.Renderer;
bool IsOwnerHere => !IsProxy && (!Networking.IsActive || Network.IsOwner);
bool FirstPersonOwner => IsOwnerHere && Controller is { ThirdPerson: false };
// ------------------------------------------------------------ body animation
string _bodyKey;
float _bodyRetry;
// The citizen body (and Facepunch's view models) run on the classic animgraph; SkinnedModelRenderer.Animation
// (the newer parameter API) reports "no animation graph instance" for them, so the classic setters are used.
// Enum parameters take the option's index.
#pragma warning disable CS0618
static bool TrySet( SkinnedModelRenderer r, string name, int value )
{
if ( r is null ) return false;
try { r.Set( name, value ); return true; }
catch ( InvalidOperationException ) { return false; }
}
static bool TrySet( SkinnedModelRenderer r, string name, bool value )
{
if ( r is null ) return false;
try { r.Set( name, value ); return true; }
catch ( InvalidOperationException ) { return false; }
}
static bool TrySet( SkinnedModelRenderer r, string name, float value )
{
if ( r is null ) return false;
try { r.Set( name, value ); return true; }
catch ( InvalidOperationException ) { return false; }
}
#pragma warning restore CS0618
static int HoldIndex( string name ) { var i = Array.IndexOf( HoldTypes, name ); return i < 0 ? 0 : i; }
static int HandIndex( string name ) => name switch { "RH" => 1, "LH" => 2, _ => 0 };
protected override void OnUpdate()
{
var body = Body;
if ( body is null ) return;
// The body's graph doesn't run while it is hidden (first person, dead): apply when something changed or the
// graph came back, and wait a moment after a failure instead of throwing every frame.
var key = $"{HoldType}|{Handedness}|{Lowered}|{body.GetHashCode()}";
if ( key != _bodyKey && RealTime.Now >= _bodyRetry )
{
if ( TrySet( body, "holdtype", HoldIndex( HoldType ) )
&& TrySet( body, "holdtype_handedness", HandIndex( Handedness ) )
&& TrySet( body, "b_weapon_lower", Lowered ) )
_bodyKey = key;
else _bodyRetry = RealTime.Now + 0.5f;
}
UpdateWorldModel( body );
UpdateViewModel();
UpdateFlash();
}
// ------------------------------------------------------------ world model
GameObject _world;
ModelRenderer _worldRenderer;
string _worldShown;
bool _worldAttached;
global::Transform _offsetShown;
void UpdateWorldModel( SkinnedModelRenderer body )
{
// On the body's "hold_R" bone object the engine moves the weapon with the animated hand in the same frame.
// A new body model gets new bone objects, so the weapon is re-attached when its parent goes away.
bool parentGone = _world.IsValid() && _worldAttached && !_world.Parent.IsValid();
if ( _worldShown != WorldModel || parentGone || (_world is not null && !_world.IsValid()) )
{
_world?.Destroy();
_world = null;
_worldRenderer = null;
_worldShown = WorldModel;
if ( !string.IsNullOrEmpty( WorldModel ) && Model.Load( WorldModel ) is { IsError: false } m )
{
var hand = body.GetBoneObject( "hold_R" );
_world = new GameObject( hand ?? GameObject, true, "held weapon" );
_world.NetworkMode = NetworkMode.Never;
_worldAttached = hand is not null;
_offsetShown = default;
_worldRenderer = _world.Components.Create<ModelRenderer>();
_worldRenderer.Model = m;
}
}
if ( !_world.IsValid() ) return;
// Hidden with the body (ply:SetNoDraw, death) and for the owner in first person (they see the view model).
var hidden = FirstPersonOwner || !body.Enabled || !body.GameObject.Enabled;
if ( _worldRenderer.IsValid() && _worldRenderer.Enabled == hidden ) _worldRenderer.Enabled = !hidden;
var offset = new global::Transform( WorldOffset, WorldAngles.ToRotation(), 1 );
if ( _worldAttached )
{
if ( _offsetShown.Position != offset.Position || _offsetShown.Rotation != offset.Rotation )
{
_offsetShown = offset;
_world.LocalTransform = offset;
}
}
else if ( body.GetAttachment( "hold_R" ) is { } hold ) _world.WorldTransform = hold.ToWorld( offset );
}
// ------------------------------------------------------------ view model
GameObject _view;
SkinnedModelRenderer _viewRenderer;
string _viewShown;
Vector2 _inertia, _lastAim;
bool _inertiaFirst = true;
static void Overlay( SkinnedModelRenderer r )
{
r.RenderType = ModelRenderer.ShadowRenderType.Off;
r.RenderOptions.Game = false;
r.RenderOptions.Overlay = true;
}
void UpdateViewModel()
{
var want = FirstPersonOwner && !string.IsNullOrEmpty( ViewModel ) ? $"{ViewModel}|{ViewBodyGroups}" : null;
if ( _viewShown != want )
{
_view?.Destroy();
_view = null;
_viewRenderer = null;
_viewShown = want;
_inertiaFirst = true;
if ( want is not null ) BuildViewModel();
}
if ( !_viewRenderer.IsValid() ) return;
var pc = Controller;
var eyes = pc.EyeAngles;
ApplyInertia( eyes );
var velocity = pc.Velocity;
var local = eyes.WithPitch( 0 ).ToRotation().Inverse * velocity;
TrySet( _viewRenderer, "b_twohanded", true );
TrySet( _viewRenderer, "b_grounded", !pc.IsAirborne );
TrySet( _viewRenderer, "move_bob", velocity.Length.Remap( 0, pc.RunSpeed * 2f ) );
TrySet( _viewRenderer, "aim_pitch", eyes.pitch );
TrySet( _viewRenderer, "aim_pitch_inertia", _inertia.x * 2f );
TrySet( _viewRenderer, "aim_yaw", eyes.yaw );
TrySet( _viewRenderer, "aim_yaw_inertia", _inertia.y * 2f );
TrySet( _viewRenderer, "move_direction", MathF.Atan2( local.y, local.x ) * 180f / MathF.PI );
TrySet( _viewRenderer, "move_speed", velocity.Length );
TrySet( _viewRenderer, "move_groundspeed", velocity.WithZ( 0 ).Length );
TrySet( _viewRenderer, "move_x", local.x );
TrySet( _viewRenderer, "move_y", local.y );
TrySet( _viewRenderer, "move_z", velocity.z );
TrySet( _viewRenderer, "b_sprint", Input.Down( "Run" ) && velocity.WithZ( 0 ).Length > pc.WalkSpeed + 20 );
foreach ( var (name, value) in _viewParams )
{
if ( value is bool b ) TrySet( _viewRenderer, name, b );
else if ( value is float f )
{
// Graphs have float and int/enum parameters (e.g. "ironsights"); whole numbers are set as both.
TrySet( _viewRenderer, name, f );
if ( f == MathF.Floor( f ) && MathF.Abs( f ) < 1000 ) TrySet( _viewRenderer, name, (int)f );
}
}
if ( _view.Enabled == ViewHidden ) _view.Enabled = !ViewHidden;
}
readonly System.Collections.Generic.Dictionary<string, object> _viewParams = new();
/// <summary>Owner only: hides the view model (e.g. while looking through a scope).</summary>
public bool ViewHidden { get; set; }
/// <summary>A view model parameter set from Lua (e.g. "b_empty"), re-applied every frame and after rebuilds.</summary>
public void SetViewParam( string name, object value )
{
if ( value is null ) _viewParams.Remove( name );
else if ( _viewParams.Count < 32 || _viewParams.ContainsKey( name ) ) _viewParams[name] = value;
}
void BuildViewModel()
{
var armsOnly = ViewModel == "arms";
var vm = armsOnly ? Model.Load( ArmsModel ) : Model.Load( ViewModel );
if ( vm is null || vm.IsError ) return;
_view = new GameObject( true, "viewmodel" );
_view.NetworkMode = NetworkMode.Never;
_viewRenderer = _view.Components.Create<SkinnedModelRenderer>();
_viewRenderer.Model = vm;
_viewRenderer.UseAnimGraph = true;
_viewRenderer.CreateBoneObjects = true;
if ( armsOnly ) _viewRenderer.BodyGroups = ArmsBodyGroups;
else if ( ViewBodyGroups != 0 ) _viewRenderer.BodyGroups = ViewBodyGroups;
Overlay( _viewRenderer );
if ( !armsOnly && Model.Load( ArmsModel ) is { IsError: false } arms )
{
var a = new GameObject( _view, true, "arms" );
a.LocalPosition = new Vector3( 0, 0, 1 );
var ar = a.Components.Create<SkinnedModelRenderer>();
ar.Model = arms;
ar.BodyGroups = ArmsBodyGroups;
ar.BoneMergeTarget = _viewRenderer;
Overlay( ar );
}
TrySet( _viewRenderer, "b_deploy", true );
TrySet( _viewRenderer, "b_deploy_new", true );
PlaceViewModel();
}
// Weapon sway: lag behind fast turns (Facepunch's ViewModel.ApplyInertia).
void ApplyInertia( Angles eyes )
{
var aim = new Vector2( eyes.pitch, eyes.yaw );
if ( _inertiaFirst ) { _lastAim = aim; _inertia = Vector2.Zero; _inertiaFirst = false; return; }
var delta = new Vector2( Angles.NormalizeAngle( aim.x - _lastAim.x ), Angles.NormalizeAngle( _lastAim.y - aim.y ) );
_lastAim = aim;
var dt = Time.Delta;
if ( dt <= 0 ) return;
var target = delta / MathF.Max( dt, 1f / 500f ) * 0.0167f;
target = new Vector2( Math.Clamp( target.x, -15f, 15f ), Math.Clamp( target.y, -15f, 15f ) );
float k = 1f - MathF.Exp( -dt / 0.03f );
_inertia += (target - _inertia) * k;
}
void PlaceViewModel()
{
if ( !_view.IsValid() || Scene.Camera is not { } cam ) return;
_view.WorldTransform = cam.WorldTransform;
if ( !ViewOffset.IsNearlyZero() ) _view.WorldPosition = cam.WorldPosition + cam.WorldRotation * ViewOffset;
// View model arms reach back past the camera; a near plane of more than ~1 unit cuts them open.
if ( cam.ZNear > 1f ) cam.ZNear = 1f;
}
protected override void OnPreRender()
{
PlaceViewModel();
}
protected override void OnDestroy()
{
_world?.Destroy();
_view?.Destroy();
_flash?.Destroy();
}
// ------------------------------------------------------------ muzzle, flash, animations
/// <summary>The muzzle in world space: the view model's in first person, else the world model's, else the eyes.</summary>
public global::Transform MuzzleTransform()
{
if ( _viewRenderer.IsValid() && _viewRenderer.Enabled && _viewRenderer.GetAttachment( "muzzle" ) is { } vm ) return vm;
if ( _worldRenderer.IsValid() && _worldRenderer.Model is { } m )
{
var att = m.Attachments.All.FirstOrDefault( x => x.Name == "muzzle" );
if ( att is not null ) return _world.WorldTransform.ToWorld( att.LocalTransform );
}
var pc = Controller;
return pc is null ? WorldTransform : new global::Transform( pc.EyePosition, pc.EyeAngles.ToRotation() );
}
public bool HasMuzzle =>
(_viewRenderer.IsValid() && _viewRenderer.GetAttachment( "muzzle" ).HasValue)
|| (_worldRenderer.IsValid() && _worldRenderer.Model is { } m && m.Attachments.All.Any( x => x.Name == "muzzle" ));
GameObject _flash;
float _flashUntil;
void Flash()
{
if ( !HasMuzzle ) return;
if ( !_flash.IsValid() )
{
_flash = new GameObject( true, "muzzle flash" ) { NetworkMode = NetworkMode.Never };
var light = _flash.Components.Create<PointLight>();
light.LightColor = new Color( 1f, 0.75f, 0.4f ) * 3f;
light.Radius = 160;
light.Shadows = false;
}
_flash.WorldPosition = MuzzleTransform().Position;
_flash.Enabled = true;
_flashUntil = RealTime.Now + 0.05f;
}
void UpdateFlash()
{
if ( _flash.IsValid() && _flash.Enabled && RealTime.Now >= _flashUntil ) _flash.Enabled = false;
}
static bool IsBodyParam( string param ) => param is "b_attack" or "b_reload" or "b_deploy";
/// <summary>Plays an animgraph trigger here only (the owner's predicted shot, reload, ...).</summary>
public void AnimLocal( string param )
{
if ( string.IsNullOrEmpty( param ) || param.Length > 32 ) return;
if ( IsBodyParam( param ) ) TrySet( Body, param, true );
if ( _viewRenderer.IsValid() )
{
if ( !TrySet( _viewRenderer, param, true ) ) TrySet( _viewRenderer, param, 1 );
if ( param == "b_reload" ) TrySet( _viewRenderer, "speed_reload", 1f );
}
if ( param == "b_attack" ) Flash();
}
[Rpc.Broadcast( NetFlags.HostOnly )]
void Anim( string param ) => AnimLocal( param );
/// <summary>Host: plays a trigger on every machine, optionally not on the owner (who predicted it).</summary>
public void PlayAnim( string param, bool skipOwner )
{
if ( !Networking.IsActive ) { if ( !skipOwner ) AnimLocal( param ); return; }
var owner = Network.Owner;
if ( skipOwner && owner is not null )
{
using ( Rpc.FilterExclude( c => c == owner ) ) Anim( param );
}
else Anim( param );
}
}