Builder/BuilderShapes.cs

Static registry for the Builder tool's shapes. Holds each shape's up axis, its own parameters (with defaults, ranges and discrete choices), kept proportions, validation hooks, flat-face flags and bounds, plus parsing and formatting of the saved parameter string used by BuilderShapeKey.

namespace Sandbox;

/// <summary>
/// The shape-local axis that points along the surface a block is built on.
/// </summary>
public enum BuilderUpAxis
{
	Y,

	Z
}

/// <summary>
/// A setting of its own that a shape (or some of its subtypes) has, like a pipe's wall thickness.
/// Saved by <see cref="Name"/>, so parameters can be added or reordered without breaking saves.
/// </summary>
public sealed record BuilderParameter( string Name, float Default, float Min, float Max, float[] Choices = null )
{
	/// <summary>
	/// The value to build with: one of <see cref="Choices"/> when there are any, otherwise clamped to the range.
	/// False for anything that isn't a usable number or choice.
	/// </summary>
	public bool TryNormalize( float value, out float result )
	{
		result = Default;
		if ( !float.IsFinite( value ) ) return false;

		if ( Choices is not null )
		{
			foreach ( var choice in Choices )
			{
				if ( MathF.Abs( choice - value ) > 0.01f ) continue;
				result = choice;
				return true;
			}

			return false;
		}

		result = Math.Clamp( value, Min, Max );
		return true;
	}
}

/// <summary>
/// Everything that differs between shapes besides their geometry: which way is up, their own parameters, and the
/// proportions Shift keeps. Add a shape here, give it parameters here, and read them in <see cref="BuilderGeometry"/>.
/// </summary>
public sealed class BuilderShapeDefinition
{
	/// <summary>The shape axis that follows the surface normal.</summary>
	public BuilderUpAxis Up { get; init; } = BuilderUpAxis.Z;

	/// <summary>The shape's own settings, at most <see cref="BuilderShapes.MaxParameters"/>.</summary>
	public BuilderParameter[] Parameters { get; init; } = [];

	/// <summary>
	/// Shape-local X:Y:Z proportions that Shift keeps while drawing, so subtypes can differ (a 180° bend is 2:1).
	/// A zero leaves that side free (a half pipe's length). Null means 1:1:1.
	/// </summary>
	public Func<BuilderShapeKey, Vector3> Proportions { get; init; }

	/// <summary>
	/// Last say over a recipe: adjust it to what will really be built (so equal meshes share a key), or return null if
	/// this shape can't be built at that size. Null hook accepts everything.
	/// </summary>
	public Func<BuilderShapeKey, BuilderShapeKey?> Validate { get; init; }

	public int IndexOf( string name )
	{
		for ( int i = 0; i < Parameters.Length; i++ )
		{
			if ( string.Equals( Parameters[i].Name, name, StringComparison.OrdinalIgnoreCase ) ) return i;
		}

		return -1;
	}

	public Vector3 GetProportions( BuilderShapeKey key ) => Proportions?.Invoke( key ) ?? Vector3.One;

	public Func<BuilderShapeKey, BuilderFaces> FlatFaces { get; init; }

	public BuilderFaces GetFlatFaces( BuilderShapeKey key ) => FlatFaces?.Invoke( key ) ?? BuilderFaces.All;

	/// <summary>How the Builder tool draws this shape.</summary>
	public BuilderPlacementMode Placement { get; init; } = BuilderPlacementMode.Box;

	public bool FitsBox { get; init; } = true;

	/// <summary>The model's bounds in the block's frame, for shapes that aren't centred on their size. Null hook or result means a centred box.</summary>
	public Func<BuilderShapeKey, BBox?> Bounds { get; init; }

	public BBox GetBounds( BuilderShapeKey key ) => Bounds?.Invoke( key ) ?? BBox.FromPositionAndSize( Vector3.Zero, key.Size );
}

/// <summary>
/// How the Builder tool draws a shape.
/// </summary>
public enum BuilderPlacementMode
{
	/// <summary>Two corners of a footprint on a surface, then a height.</summary>
	Box,

	/// <summary>A start point, an end point on any surface, then the tube radius (bent pipes).</summary>
	Path
}

/// <summary>
/// Sides of a shape's local box.
/// </summary>
[Flags]
public enum BuilderFaces
{
	None = 0,
	PositiveX = 1,
	NegativeX = 2,
	PositiveY = 4,
	NegativeY = 8,
	PositiveZ = 16,
	NegativeZ = 32,

	Caps = PositiveZ | NegativeZ,
	All = 63
}

/// <summary>
/// The definition of every <see cref="BuilderCatalog.Shape"/>.
/// </summary>
public static class BuilderShapes
{
	/// <summary>How many parameters a shape can have; the slots in <see cref="BuilderShapeKey"/>.</summary>
	public const int MaxParameters = 8;

	public const string Radius = "radius";
	public const string Thickness = "thickness";

	static readonly BuilderParameter WallThickness = new( Thickness, 6, 1, 256 );

	static readonly BuilderShapeDefinition[] Definitions = Create();

	/// <summary>The face flag for shape axis <paramref name="axis"/> (0 X, 1 Y, 2 Z) on side <paramref name="sign"/>.</summary>
	public static BuilderFaces Face( int axis, int sign ) => (BuilderFaces)(1 << (axis * 2 + (sign < 0 ? 1 : 0)));

	public static BuilderShapeDefinition Get( BuilderCatalog.Shape shape )
	{
		var index = (int)shape;
		return index >= 0 && index < Definitions.Length ? Definitions[index] : null;
	}

	static BuilderShapeDefinition[] Create()
	{
		var shapes = Enum.GetValues<BuilderCatalog.Shape>();
		var definitions = new BuilderShapeDefinition[shapes.Length];

		foreach ( var shape in shapes )
		{
			definitions[(int)shape] = shape switch
			{
				BuilderCatalog.Shape.Triangle or BuilderCatalog.Shape.Carved => new()
				{
					Up = BuilderUpAxis.Y,
					FlatFaces = _ => BuilderFaces.Caps
				},

				BuilderCatalog.Shape.BoxFrame => new()
				{
					Parameters = [WallThickness],
					Validate = key => ClampThickness( key, 0, MathF.Min( key.Size.x, MathF.Min( key.Size.y, key.Size.z ) ) / 2 )
				},

				BuilderCatalog.Shape.Trapezium or BuilderCatalog.Shape.Parallelogram => new()
				{
					Up = BuilderUpAxis.Y,
					FlatFaces = _ => BuilderFaces.Caps
				},

				BuilderCatalog.Shape.Pentagon => new()
				{
					Up = BuilderUpAxis.Y,
					FlatFaces = _ => BuilderFaces.Caps
				},

				BuilderCatalog.Shape.HalfPipe => new()
				{
					Proportions = _ => new Vector3( 2, 1, 0 ),
					Up = BuilderUpAxis.Y,
					Parameters = [WallThickness],
					Validate = key => ClampThickness( key, 0, MathF.Min( key.Size.x / 2, key.Size.y ) ),
					FlatFaces = _ => BuilderFaces.NegativeY | BuilderFaces.Caps
				},

				BuilderCatalog.Shape.Tube => new()
				{
					Parameters = [WallThickness],
					Validate = key => ClampThickness( key, 0, MathF.Min( key.Size.x, key.Size.y ) / 2 ),
					FlatFaces = _ => BuilderFaces.Caps
				},

				BuilderCatalog.Shape.PlateHole => new()
				{
					Parameters = [WallThickness],
					Validate = key => ClampThickness( key, 0, MathF.Min( key.Size.x, key.Size.y ) / 2 )
				},

				BuilderCatalog.Shape.Dome => new()
				{
					Proportions = _ => new Vector3( 1, 1, 0.5f ),
					Parameters = [WallThickness],
					Validate = key => ClampThickness( key, 0, MathF.Min( MathF.Min( key.Size.x, key.Size.y ) / 2, key.Size.z ) ),
					FlatFaces = _ => BuilderFaces.NegativeZ
				},

				BuilderCatalog.Shape.QuarterDome => new()
				{
					Proportions = _ => new Vector3( 2, 1, 1 ),
					Parameters = [WallThickness],
					Validate = key => ClampThickness( key, 0, MathF.Min( MathF.Min( key.Size.x / 2, key.Size.y ), key.Size.z ) ),
					FlatFaces = _ => BuilderFaces.NegativeZ | BuilderFaces.NegativeY
				},

				BuilderCatalog.Shape.Bend => new()
				{
					Placement = BuilderPlacementMode.Path,
					FitsBox = false,
					Parameters =
					[
						WallThickness,
						new( Radius, 8, 0.5f, 1024 ),
						new( "endx", 0, -BuilderShapeKey.MaxSize, BuilderShapeKey.MaxSize ),
						new( "endy", 0, -BuilderShapeKey.MaxSize, BuilderShapeKey.MaxSize ),
						new( "endz", 0, -BuilderShapeKey.MaxSize, BuilderShapeKey.MaxSize ),
						new( "endnx", 0, -BuilderPipe.NormalScale, BuilderPipe.NormalScale ),
						new( "endny", 0, -BuilderPipe.NormalScale, BuilderPipe.NormalScale ),
						new( "endnz", 0, -BuilderPipe.NormalScale, BuilderPipe.NormalScale )
					],
					Validate = BuilderPipe.Validate,
					Bounds = key => key.Fit && BuilderPipe.TryFromKey( key, out var pipe ) ? pipe.Bounds : null,
					FlatFaces = key => key.Fit ? BuilderFaces.None : CatalogBendFaces( key )
				},

				BuilderCatalog.Shape.Ring => new() { FlatFaces = _ => BuilderFaces.Caps },
				BuilderCatalog.Shape.Cone => new() { FlatFaces = _ => BuilderFaces.NegativeZ },
				BuilderCatalog.Shape.MirroredCone or BuilderCatalog.Shape.Sphere => new() { FlatFaces = _ => BuilderFaces.None },

				BuilderCatalog.Shape.Stairs => new()
				{
					FlatFaces = _ => BuilderFaces.NegativeZ | BuilderFaces.PositiveX | BuilderFaces.PositiveY | BuilderFaces.NegativeY
				},

				_ => new()
			};

			if ( definitions[(int)shape].Parameters.Length > MaxParameters )
				throw new InvalidOperationException( $"{shape} has more than {MaxParameters} builder parameters" );
		}

		return definitions;
	}

	/// <summary>The end faces of a catalog bend piece, whose first parameter is its angle.</summary>
	static BuilderFaces CatalogBendFaces( BuilderShapeKey key ) => key.Parameter( 0 ) >= 180 ? BuilderFaces.NegativeY : BuilderFaces.NegativeY | BuilderFaces.NegativeX;

	static BuilderShapeKey? ClampThickness( BuilderShapeKey key, int slot, float radius )
	{
		if ( radius < 1f ) return null;

		var thickness = MathF.Min( key.Parameter( slot ), radius * 0.95f );
		return key.WithParameter( slot, thickness );
	}

	/// <summary>
	/// Read a saved parameter string like <c>angle=90;thickness=6</c> into values in definition order.
	/// Missing names use their default, unknown names are ignored, anything unusable fails.
	/// </summary>
	public static bool TryParse( BuilderShapeDefinition definition, string text, Span<float> values )
	{
		if ( values.Length < definition.Parameters.Length ) return false;

		for ( int i = 0; i < definition.Parameters.Length; i++ )
			values[i] = definition.Parameters[i].Default;

		if ( string.IsNullOrWhiteSpace( text ) ) return true;
		if ( text.Length > 256 ) return false;

		foreach ( var part in text.Split( ';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries ) )
		{
			var equals = part.IndexOf( '=' );
			if ( equals <= 0 ) return false;

			var index = definition.IndexOf( part[..equals].Trim() );
			if ( index < 0 ) continue;

			if ( !float.TryParse( part[(equals + 1)..].Trim(), System.Globalization.NumberStyles.Float, System.Globalization.CultureInfo.InvariantCulture, out var value ) )
				return false;

			if ( !definition.Parameters[index].TryNormalize( value, out values[index] ) ) return false;
		}

		return true;
	}

	/// <summary>
	/// A small buildable example of a shape with these parameters, sized by its proportions (free sides get a quarter).
	/// Stretched over a box the shape can't fill, it still shows what was being drawn.
	/// </summary>
	public static bool TryGetSample( BuilderCatalog.Shape shape, ReadOnlySpan<float> parameters, out BuilderShapeKey key )
	{
		key = default;
		if ( Get( shape ) is not { } definition || parameters.Length < definition.Parameters.Length ) return false;

		var probe = new BuilderShapeKey( shape, 16, 16, 16, true );
		for ( int i = 0; i < definition.Parameters.Length; i++ )
			probe = probe.WithParameter( i, parameters[i] );

		var p = definition.GetProportions( probe );
		var size = new Vector3( p.x > 0 ? p.x : 0.25f, p.y > 0 ? p.y : 0.25f, p.z > 0 ? p.z : 0.25f ) * 64;
		return BuilderShapeKey.TryCustom( shape, size, parameters, out key );
	}

	/// <summary>The parameter string for a key, the inverse of <see cref="TryParse"/>.</summary>
	public static string Format( BuilderShapeKey key )
	{
		var definition = Get( key.Shape );
		if ( definition is null || definition.Parameters.Length == 0 ) return null;

		var text = new System.Text.StringBuilder();
		for ( int i = 0; i < definition.Parameters.Length; i++ )
		{
			if ( i > 0 ) text.Append( ';' );
			text.Append( definition.Parameters[i].Name ).Append( '=' ).Append( key.Parameter( i ).ToString( "0.####", System.Globalization.CultureInfo.InvariantCulture ) );
		}

		return text.ToString();
	}
}