Builder/BuilderProp.cs

Component on a single placed building block. Stores the recipe (catalog piece id or custom shape, size and shape parameters) as synced properties, rebuilds the model from `BuilderModelCache` when the recipe or geometry version changes, applies material overrides and loads pending workshop materials asynchronously. Also has the static `Spawn`/`Create` helpers that instantiate blocks with permission, limit and undo bookkeeping.

namespace Sandbox;

/// <summary>
/// Recreates the model locally on every peer and after loading a save/dupe.
/// Only the recipe is persistent; runtime model resource names are not portable.
/// </summary>
[Title( "Builder Piece" ), Category( "Game" )]
public sealed class BuilderProp : Component
{
	/// <summary>
	/// Every building block weighs the same, so huge blocks don't make physics work out enormous masses.
	/// </summary>
	public const float Mass = 2500f;

	/// <summary>A spawn menu catalog piece. When set, it's used instead of the custom recipe.</summary>
	[Property, Sync( SyncFlags.FromHost )] public string PieceId { get; set; }

	/// <summary>The custom recipe: <see cref="Shape"/> stretched to fill <see cref="Size"/>, with its <see cref="Parameters"/>.</summary>
	[Property, Sync( SyncFlags.FromHost )] public BuilderCatalog.Shape Shape { get; set; }
	[Property, Sync( SyncFlags.FromHost )] public Vector3 Size { get; set; }

	/// <summary>The shape's own settings by name, like <c>angle=90;thickness=6</c>. See <see cref="BuilderShapes"/>.</summary>
	[Property, Sync( SyncFlags.FromHost )] public string Parameters { get; set; }

	[Property] public ModelRenderer Renderer { get; set; }
	[Property] public ModelCollider Collider { get; set; }

	/// <summary>A workshop material still downloading; the block wears <see cref="BuilderMaterials.Downloading"/> until it arrives.</summary>
	[Property] public string PendingMaterial { get; set; }

	string _builtPieceId;
	BuilderCatalog.Shape _builtShape;
	Vector3 _builtSize;
	string _builtParameters;
	int _builtGeometryVersion;
	Model _applied;
	BuilderShapeKey? _leased;
	int _leaseGeneration;
	BuilderShapeKey? _queued;
	BuilderRecipe _parsedRecipe;
	BuilderShapeKey? _parsedKey;

	public BuilderRecipe Recipe => new( PieceId, Shape, Size, Parameters );

	/// <summary>The key the current model was built from, without parsing the recipe again. Null until it's built.</summary>
	public BuilderShapeKey? BuiltKey => _leased;

	/// <summary>
	/// The model key for the current recipe. False when the recipe is invalid, e.g. an unknown piece or a tampered dupe.
	/// </summary>
	public bool TryGetKey( out BuilderShapeKey key ) => Recipe.TryGetKey( out key );

	/// <summary>Like <see cref="TryGetKey"/>, but only parses the recipe again once it changes.</summary>
	bool TryGetRecipeKey( out BuilderShapeKey key )
	{
		var recipe = Recipe;
		if ( recipe != _parsedRecipe )
		{
			_parsedRecipe = recipe;
			_parsedKey = recipe.TryGetKey( out var parsed ) ? parsed : null;
		}

		key = _parsedKey ?? default;
		return _parsedKey is not null;
	}

	/// <summary>
	/// Build and assign the model right now, even on a proxy. Use before rendering something immediately (dupe icons).
	/// </summary>
	public void Rebuild()
	{
		if ( !Renderer.IsValid() || !Collider.IsValid() ) return;
		if ( !TryGetKey( out var key ) ) return;

		Apply( key );
	}

	protected override void OnStart()
	{
		Refresh();
		if ( !IsProxy && !string.IsNullOrEmpty( PendingMaterial ) ) LoadPendingMaterial();
	}

	async void LoadPendingMaterial()
	{
		var path = PendingMaterial;
		var placeholder = BuilderMaterials.Downloading;
		if ( Renderer.IsValid() && Renderer.MaterialOverride is null ) Renderer.MaterialOverride = placeholder;

		var material = await BuilderMaterials.LoadAsync( path );
		if ( !this.IsValid() || !Renderer.IsValid() || PendingMaterial != path ) return;

		PendingMaterial = null;
		if ( Renderer.MaterialOverride != placeholder ) return;

		if ( material is null || material.IsError )
		{
			var owner = GetComponent<Ownable>()?.Owner;
			Log.Warning( $"Builder: couldn't load material '{path}' for {owner?.DisplayName}, using the default" );
			if ( owner is not null ) Sandbox.UI.Notices.SendLocalizedNotice( owner, "warning", Color.Orange, "#builder.material_failed", null, 3 );
			material = Material.Load( BuilderCatalog.DefaultMaterial );
		}

		Renderer.MaterialOverride = material;
		GameObject.Network?.Refresh();
	}

	protected override void OnUpdate() => Refresh();

	protected override void OnDestroy()
	{
		if ( _leased is { } key ) BuilderModelCache.Release( key, _leaseGeneration );
		_leased = null;
	}

	void Refresh()
	{
		if ( !Renderer.IsValid() || !Collider.IsValid() ) return;

		if ( _applied is not null && Renderer.Model == _applied && Collider.Model == _applied
			&& _builtPieceId == PieceId && _builtShape == Shape && _builtSize == Size && _builtParameters == Parameters
			&& _builtGeometryVersion == BuilderGeometry.GeometryVersion )
			return;

		if ( !TryGetRecipeKey( out var key ) ) return;

		if ( IsProxy && !BuilderModelCache.Contains( key ) )
		{
			if ( _queued == key ) return;

			_queued = key;
			BuilderBuildQueue.Get( Scene )?.Enqueue( key );

			if ( Renderer.Model is { IsError: true } ) Renderer.Model = null;
			return;
		}

		Apply( key );
	}

	void Apply( BuilderShapeKey key )
	{
		var model = BuilderModelCache.Acquire( key );
		if ( _leased is { } old ) BuilderModelCache.Release( old, _leaseGeneration );

		_leased = key;
		_leaseGeneration = BuilderModelCache.Generation;
		_queued = null;
		_applied = model;
		_builtPieceId = PieceId;
		_builtShape = Shape;
		_builtSize = Size;
		_builtParameters = Parameters;
		_builtGeometryVersion = BuilderGeometry.GeometryVersion;

		Renderer.Model = model;
		Collider.Model = model;
	}

	/// <summary>
	/// Create a building block for <paramref name="owner"/> the way the Builder tool does: checks their permission and
	/// building block limit, counts it towards that limit and adds it to their undo history. Host only; null when the
	/// recipe is invalid or the owner isn't allowed. With no owner it's a server-owned block: no permission, limit or undo.
	/// <paramref name="material"/> is a mounted path or a workshop ident. Remove a block with <see cref="GameObject.Destroy"/>. <paramref name="tint"/> colours its renderer.
	/// </summary>
	public static GameObject Spawn( BuilderRecipe recipe, Transform transform, Connection owner, string material = null, Surface surface = null, bool collisions = true, bool frozen = true, Color? tint = null )
	{
		if ( !Networking.IsHost || recipe is null || !recipe.TryGetKey( out var key ) ) return null;

		var limits = LimitsSystem.Current;
		if ( owner is not null )
		{
			if ( !BuilderPolicy.CheckCanBuild( owner ) ) return null;
			if ( limits is not null && !limits.CheckBuilderLimit( owner, 1 ) ) return null;
		}

		var loaded = BuilderMaterials.LoadLocal( material );
		var pieceId = string.IsNullOrEmpty( recipe.PieceId ) ? null : recipe.PieceId;
		var go = Create( key, pieceId, transform, loaded, surface, collisions, frozen, owner, loaded is null ? material : null, tint );

		if ( owner is not null )
		{
			limits?.TrackNow( owner, new List<GameObject> { go } );

			if ( Player.FindForConnection( owner ) is { } player && player.IsValid() )
			{
				var undo = player.Undo.Create();
				undo.Name = "#tool.undo.builder";
				undo.Icon = "🧱";
				undo.Add( go );
			}
		}

		return go;
	}

	/// <summary>
	/// Create a networked building block on the host without any checks, tracking or undo (see <see cref="Spawn"/>).
	/// Pass a catalog <paramref name="pieceId"/>, or null to use the custom recipe in <paramref name="key"/>. With no
	/// <paramref name="material"/> yet, pass a workshop ident as <paramref name="pendingMaterial"/>.
	/// </summary>
	public static GameObject Create( BuilderShapeKey key, string pieceId, Transform transform, Material material, Surface surface, bool collisions, bool frozen, Connection owner, string pendingMaterial = null, Color? tint = null )
	{
		var go = new GameObject( false, pieceId ?? $"Builder {key.Shape}" );
		go.Tags.Add( "removable" );
		if ( !collisions ) go.Tags.Add( GameManager.NoPropCollisionsTag );
		go.WorldTransform = transform;

		var prop = go.AddComponent<BuilderProp>();
		if ( pieceId is not null )
		{
			prop.PieceId = pieceId;
		}
		else
		{
			prop.Shape = key.Shape;
			prop.Size = key.Size;
			prop.Parameters = BuilderShapes.Format( key );
		}

		prop.Renderer = go.AddComponent<ModelRenderer>();
		prop.Renderer.MaterialOverride = material ?? (pendingMaterial is not null ? BuilderMaterials.Downloading : null);
		if ( tint is { } color ) prop.Renderer.Tint = color;
		prop.PendingMaterial = material is null ? pendingMaterial : null;
		prop.Collider = go.AddComponent<ModelCollider>();
		if ( surface is not null ) prop.Collider.Surface = surface;
		prop.Rebuild();

		var body = go.AddComponent<Rigidbody>();
		body.MassOverride = Mass;
		body.MotionEnabled = !frozen;

		if ( owner is not null ) Ownable.Set( go, owner );
		go.NetworkSpawn( true, null );
		return go;
	}
}