Framework/Players/RpHeldWeapon.cs

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 );
	}
}