Builder mode for the toolgun. Draws a box or path shape on a hovered face with grid snapping and alignment guides, previews it with a debug model, and places it through an owner-only host RPC that checks build policy, limits, recipe validity, reach and path lengths before creating the prop and an undo entry. Also holds a radial shape menu and a cached HUD status line.
using Sandbox.UI;
[Icon( "🧱" )]
[Title( "#tool.name.builder" )]
[ClassName( "builder" )]
[Group( "#tool.group.building" )]
public sealed class BuilderTool : ToolMode
{
const string ShapeGroup = "#tool.setting.group.shape";
const string MaterialGroup = "#tool.setting.group.material";
const string PhysicsGroup = "#tool.setting.group.physics";
[Property, Group( ShapeGroup ), Order( 0 ), Title( "#tool.setting.builder.shape" ), Description( "#tool.setting.builder.shape.description" )]
public BuilderCatalog.Shape Shape { get; set; } = BuilderCatalog.Shape.Box;
[Property, Group( ShapeGroup ), Order( 1 ), BuilderParameter( BuilderShapes.Thickness ), Range( 1, 256 ), Step( 1 ), Title( "#tool.setting.builder.thickness" ), Description( "#tool.setting.builder.thickness.description" )]
public float Thickness { get; set; } = 6;
[Property, Group( ShapeGroup ), Order( 2 ), Range( BuilderPlacement.MinGrid, BuilderPlacement.MaxGrid ), Step( BuilderPlacement.GridStep ), Title( "#tool.setting.builder.grid" ), Description( "#tool.setting.builder.grid.description" )]
public int GridSize { get; set; } = 16;
[Property, Group( ShapeGroup ), Order( 3 ), Title( "#tool.setting.builder.adjacent" ), Description( "#tool.setting.builder.adjacent.description" )]
public bool SnapToAdjacentLines { get; set; } = true;
[Property, Group( ShapeGroup ), Order( 4 ), Title( "#tool.setting.builder.symmetry" ), Description( "#tool.setting.builder.symmetry.description" )]
public bool Symmetrical { get; set; }
[Property, Group( MaterialGroup ), Order( 10 ), ResourceSelect( Extension = "material", AllowPackages = true, Popup = true ), Title( "#tool.setting.material" )]
public string MaterialPath { get; set; } = BuilderCatalog.DefaultMaterial;
[Property, Group( MaterialGroup ), Order( 11 ), ResourceSelect( Extension = "surface", Popup = true ), Title( "#tool.setting.builder.surface" ), Description( "#tool.setting.builder.surface.description" )]
public string SurfacePath { get; set; } = "surfaces/plastic.surface";
[Property, Group( MaterialGroup ), Order( 12 ), Title( "#tool.setting.tint" )]
public Color Tint { get; set; } = Color.White;
[Property, Group( PhysicsGroup ), Order( 20 ), Title( "#tool.setting.builder.collisions" ), Description( "#tool.setting.builder.collisions.description" )]
public bool Collisions { get; set; } = true;
[Property, Group( PhysicsGroup ), Order( 21 ), Title( "#tool.setting.freeze" ), Description( "#tool.setting.builder.frozen.description" )]
public bool SpawnFrozen { get; set; } = true;
const int MaxPathLength = 256;
const float ReachTolerance = 256f;
const float PreviewRebuildInterval = 0.1f;
const float MinPlaceInterval = 0.1f;
const float StickyMargin = 4f;
RealTimeSince _sinceLastPlace = 1;
BuilderCatalog.Shape _cachedShape;
Vector3 _cachedSize;
BuilderShapeKey _cachedKey;
readonly float[] _cachedValues = new float[BuilderShapes.MaxParameters];
bool _cachedValid;
bool _hasCache;
BuilderBoxFlow _boxFlow;
BuilderPathFlow _pathFlow;
BuilderFlow _drawingFlow;
BuilderPlane _hoverPlane;
(BuilderPlane Plane, Vector2 Point, SelectionPoint Hit)? _hoverStart;
bool _placeThisFrame;
bool _primaryQueued;
BuilderFaceRef? _stickyFace;
SnapGrid _grid;
BuilderSnapMarkers _markers;
readonly BuilderAlignment _alignment = new();
Model _previewModel;
Vector3 _previewSize;
BuilderShapeKey _previewKey;
RealTimeSince _sincePreviewBuilt;
Material _previewMaterial;
ToolStatus? _status;
int _statusGrid;
string _statusDimensions;
string _statusHint;
string _statusLanguage;
public override string Description => "#tool.hint.builder.description";
public override string SnapAction => "#tool.hint.builder.offgrid";
protected override IEnumerable<ToolHint> ExtraHints => Flow.SupportsSymmetry
? [new( Symmetrical ? "#tool.hint.builder.symmetry_on" : "#tool.hint.builder.symmetry_off", ["Symmetry"] )]
: [];
public override bool AbsorbMouseInput => ShapeMenu.IsOpen || (_drawingFlow?.AbsorbsMouse ?? false);
internal BuilderShapeDefinition Definition => BuilderShapes.Get( Shape ) ?? BuilderShapes.Get( BuilderCatalog.Shape.Box );
internal bool OffGrid => Input.Down( "snap" );
internal bool Aligning => SnapToAdjacentLines;
internal bool KeepProportions => Input.Down( "run" );
/// <summary>The flow that draws the current shape, whether or not a drawing is in progress.</summary>
BuilderFlow Flow => Definition.Placement switch
{
BuilderPlacementMode.Path => _pathFlow ??= new BuilderPathFlow( this ),
_ => _boxFlow ??= new BuilderBoxFlow( this )
};
protected override void OnStart()
{
base.OnStart();
RegisterAction( ToolInput.Primary, () => _drawingFlow?.PrimaryHint ?? Flow.StartHint, OnPrimary );
RegisterAction( ToolInput.Secondary, () => _drawingFlow?.SecondaryHint, OnSecondary );
RegisterAction( ToolInput.Reload, () => Flow.GetReloadHint( _drawingFlow is not null ), OnReload );
}
/// <summary>The radial shape menu, held open on the tool menu button. <see cref="BuilderRadialMenu"/> draws it.</summary>
public BuilderShapeMenu ShapeMenu { get; } = new();
public override string MenuAction => "#tool.hint.builder.shapes";
static bool IsOtherMenuOpen => SpawnMenuHost.IsOpen || ChatBox.IsOpen || Inventory.IsOpen || Input.Down( "score" );
bool UpdateShapeMenu()
{
var menu = ShapeMenu;
if ( !menu.IsOpen )
{
if ( !Input.Pressed( "ToolMenu" ) || IsOtherMenuOpen ) return false;
menu.Open();
}
HideGrid();
_markers?.Hide();
_hoverStart = null;
_primaryQueued = false;
Inventory.ConsumeMouseWheel();
if ( IsOtherMenuOpen )
{
menu.Close();
return true;
}
var hovered = menu.Hovered;
menu.Move( Input.AnalogLook );
if ( menu.Hovered is not null && menu.Hovered != hovered ) Sound.Play( MenuHoverSound );
if ( Input.Down( "ToolMenu" ) && !Input.Pressed( "attack1" ) ) return true;
if ( menu.Hovered is { } shape )
{
Shape = shape;
Sound.Play( MenuSelectSound );
}
menu.Close();
return true;
}
const string MenuHoverSound = "sounds/ui/ui.hover.sound";
// The same sound as undoing an action
const string MenuSelectSound = "sounds/ui/ui.undo.sound";
protected override void OnDisabled()
{
base.OnDisabled();
ShapeMenu.Close();
_drawingFlow = null;
_hoverStart = null;
_primaryQueued = false;
_placeThisFrame = false;
_grid?.Destroy();
_grid = null;
_markers?.Destroy();
_markers = null;
}
public override void OnControl()
{
if ( UpdateShapeMenu() ) return;
base.OnControl();
_previewMaterial ??= Material.Load( "materials/effects/duplicator_override.vmat" );
if ( _drawingFlow is not null && _drawingFlow != Flow ) _drawingFlow = null;
if ( Input.Pressed( "Symmetry" ) && Flow.SupportsSymmetry ) Symmetrical = !Symmetrical;
AdjustGridSize();
ScrollDrawing();
_placeThisFrame = true;
}
protected override void OnPreRender()
{
if ( !_placeThisFrame ) return;
_placeThisFrame = false;
_markers ??= new BuilderSnapMarkers();
_markers.Begin( Scene.SceneWorld );
_alignment.BeginFrame( Aligning );
UpdatePlacement();
if ( _primaryQueued )
{
_primaryQueued = false;
ApplyPrimary();
}
foreach ( var guide in _alignment.Guides )
_markers.AddGuide( guide.From, guide.To, guide.Direction, guide.Extend, Player.EyeTransform.Position );
_markers.End();
DrawPreview();
}
void AdjustGridSize()
{
var wheel = Input.MouseWheel.y;
if ( !Input.Down( "run" ) || MathF.Abs( wheel ) < 0.001f ) return;
GridSize = BuilderPlacement.ClampGrid( GridSize + MathF.Sign( wheel ) * BuilderPlacement.GridStep );
Inventory.ConsumeMouseWheel();
}
void ScrollDrawing()
{
var wheel = Input.MouseWheel.y;
if ( _drawingFlow is null || MathF.Abs( wheel ) < 0.001f ) return;
var steps = (int)MathF.Round( wheel );
_drawingFlow.Scroll( steps != 0 ? steps : MathF.Sign( wheel ) );
Inventory.ConsumeMouseWheel();
}
void UpdatePlacement()
{
var grid = BuilderPlacement.ClampGrid( GridSize );
var eyes = Player.EyeTransform.ForwardRay;
_hoverStart = null;
if ( _drawingFlow is not null )
{
_drawingFlow.Update( eyes, grid );
IsValidState = _drawingFlow.IsValid;
return;
}
if ( !TryResolveStart( eyes, out var plane, out var point, out var hit ) )
{
IsValidState = false;
HideGrid();
return;
}
var start = PlacePoint( plane, point, grid );
IsValidState = true;
_hoverPlane = plane;
_hoverStart = (plane, start, hit);
DrawSnapPoints( plane );
ShowGrid( plane, grid, plane.ToWorld( point ), plane.ToWorld( start ) );
}
void OnPrimary() => _primaryQueued = true;
void ApplyPrimary()
{
if ( _drawingFlow is null )
{
if ( _hoverStart is not { } hover ) return;
_drawingFlow = Flow;
_previewModel = null;
_drawingFlow.Begin( hover.Plane, hover.Point );
ShootEffects( hover.Hit );
return;
}
if ( !_drawingFlow.Advance() ) return;
var flow = _drawingFlow;
_drawingFlow = null;
Place( flow.Transform.Position, flow.Transform.Rotation, flow.Key.Size, Shape, BuilderShapes.Format( flow.Key ), MaterialPath, SurfacePath, Tint, Collisions, SpawnFrozen );
}
void OnSecondary()
{
if ( _drawingFlow is not null && !_drawingFlow.Back() ) _drawingFlow = null;
}
void OnReload() => Flow.Reload( _hoverPlane, _drawingFlow is not null );
internal bool TryResolveStart( Ray eyes, out BuilderPlane plane, out Vector2 point, out SelectionPoint hit )
{
hit = TraceSelect();
var found = BuilderPlacement.TryGetPlane( hit, eyes.Forward, out plane, out point, out var face );
if ( found && face is not null )
{
_stickyFace = face;
return true;
}
if ( _stickyFace is { } sticky && BuilderPlacement.TryGetFacePlane( sticky, out var stickyPlane )
&& Vector3.Dot( eyes.Forward, stickyPlane.Normal ) < 0
&& BuilderPlacement.TryProject( stickyPlane, eyes, out var onFace ) && stickyPlane.Contains( onFace, StickyMargin ) )
{
var facePoint = stickyPlane.ToWorld( onFace );
var blocked = hit.IsValid() && hit.GameObject.Root != sticky.Object.Root
&& hit.WorldPosition().Distance( eyes.Position ) < facePoint.Distance( eyes.Position ) - 1f;
if ( !blocked )
{
plane = stickyPlane;
point = onFace;
if ( !hit.IsValid() || hit.GameObject.Root != sticky.Object.Root )
hit = new SelectionPoint { GameObject = sticky.Object, LocalTransform = sticky.Object.WorldTransform.ToLocal( new Transform( facePoint, Rotation.LookAt( stickyPlane.Normal ) ) ) };
return true;
}
}
_stickyFace = null;
return found;
}
internal void GetSettings( Span<float> values )
{
var parameters = Definition.Parameters;
for ( int i = 0; i < parameters.Length; i++ )
values[i] = parameters[i].Name == BuilderShapes.Thickness ? Thickness : parameters[i].Default;
}
internal bool TryValidate( Vector3 size, ReadOnlySpan<float> values, out BuilderShapeKey key )
{
var count = Definition.Parameters.Length;
if ( !_hasCache || _cachedShape != Shape || _cachedSize != size || !values[..count].SequenceEqual( _cachedValues.AsSpan( 0, count ) ) )
{
_hasCache = true;
_cachedShape = Shape;
_cachedSize = size;
values[..count].CopyTo( _cachedValues );
_cachedValid = BuilderShapeKey.TryCustom( Shape, size, values, out _cachedKey );
}
key = _cachedKey;
return _cachedValid;
}
internal void DrawSnapPoints( in BuilderPlane plane )
{
if ( !plane.HasFace || OffGrid ) return;
_markers?.Add( plane, Player.EyeTransform.Position );
}
internal Vector2 PlacePoint( in BuilderPlane plane, Vector2 raw, int grid )
{
var snapped = OffGrid ? raw : plane.Snap( raw, grid );
if ( !Aligning || Scene.Camera is not { } camera ) return snapped;
return _alignment.AlignPoint( Scene, camera, plane, raw, snapped );
}
internal Vector2 PlaceProportional( in BuilderPlane plane, Vector2 start, Vector2 raw, Vector2 ratio, int grid )
{
var snapped = BuilderPlacement.Proportional( start, raw, ratio, OffGrid ? 0 : grid );
if ( !Aligning || Scene.Camera is not { } camera ) return snapped;
var free = BuilderPlacement.Proportional( start, raw, ratio, 0 );
var direction = free - start;
if ( direction.Length < 0.01f ) return snapped;
return _alignment.AlignOnRay( Scene, camera, plane, start, direction.Normal, free, snapped );
}
internal bool TryAlignHeight( Vector3 center, Vector3 normal, out float height )
{
height = 0;
return Aligning && Scene.Camera is { } camera && _alignment.TryAlignHeight( Scene, camera, center, normal, out height );
}
internal void ShowGrid( in BuilderPlane plane, int grid, Vector3 aim, Vector3 snapped, Vector3? cursor = null )
{
if ( OffGrid )
{
HideGrid();
_markers?.AddCursor( cursor ?? snapped, plane.Right, plane.Forward, Player.EyeTransform.Position );
return;
}
_grid ??= new SnapGrid();
_grid.UpdatePlane( Scene.SceneWorld, plane.Origin, plane.Right, plane.Forward, plane.Normal, grid, aim, snapped );
}
internal void HideGrid() => _grid?.Hide();
void DrawPreview()
{
var flow = _drawingFlow;
if ( flow is null || !flow.HasBox ) return;
if ( !flow.IsValid )
{
Model model;
Vector3 size;
if ( _previewModel is not null && _previewKey.Shape == Shape && (!flow.StretchesPreview || PreviewHasCurrentParameters()) )
{
model = _previewModel;
size = _previewSize;
}
else if ( !flow.TryGetFallbackPreview( out model, out size ) )
{
return;
}
var box = flow.Transform;
if ( flow.StretchesPreview )
{
box = box.WithScale( flow.Size / size );
box.Position -= box.Rotation * (model.Bounds.Center * box.Scale);
}
DebugOverlay.Model( model, color: Color.Red, transform: box, castShadows: false, materialOveride: _previewMaterial );
return;
}
var rebuild = _previewKey != flow.Key && (!flow.StretchesPreview || _sincePreviewBuilt > PreviewRebuildInterval);
if ( _previewModel is null || _previewKey.Shape != Shape || rebuild )
{
_previewModel = BuilderModelCache.TryGet( flow.Key, out var cached ) ? cached : BuilderGeometry.Create( flow.Key, collision: false );
_previewKey = flow.Key;
_previewSize = flow.Key.Size;
_sincePreviewBuilt = 0;
}
if ( _previewModel is null ) return;
var transform = flow.StretchesPreview ? flow.Transform.WithScale( flow.Size / _previewSize ) : flow.Transform;
DebugOverlay.Model( _previewModel, transform: transform, castShadows: false, materialOveride: _previewMaterial );
}
bool PreviewHasCurrentParameters()
{
Span<float> values = stackalloc float[BuilderShapes.MaxParameters];
GetSettings( values );
var parameters = Definition.Parameters;
for ( int i = 0; i < parameters.Length; i++ )
{
if ( MathF.Abs( _previewKey.Parameter( i ) - values[i] ) > 0.5f ) return false;
}
return true;
}
public override void DrawHud( Painter painter, Vector2 crosshair )
{
// The shape menu covers the middle of the screen
if ( ShapeMenu.IsOpen ) return;
base.DrawHud( painter, crosshair );
}
/// <summary>
/// The grid size, the drawn block's dimensions once it can be built, and the drawing's hint. Rebuilt only when one
/// of them changes.
/// </summary>
public override ToolStatus? Status
{
get
{
var grid = OffGrid ? 0 : BuilderPlacement.ClampGrid( GridSize );
var dimensions = _drawingFlow is { IsValid: true } ? _drawingFlow.Dimensions : null;
var hint = _drawingFlow?.HudHint;
var language = Game.Language.SelectedCode;
if ( _status is null || grid != _statusGrid || !ReferenceEquals( dimensions, _statusDimensions ) || hint != _statusHint || language != _statusLanguage )
{
_statusGrid = grid;
_statusDimensions = dimensions;
_statusHint = hint;
_statusLanguage = language;
var gridText = grid == 0
? Game.Language.GetPhrase( "tool.hint.builder.hud_offgrid" )
: Game.Language.GetPhrase( "tool.hint.builder.hud_grid", new() { { "size", grid.ToString() } } );
_status = new ToolStatus( gridText, dimensions, LocalizedText.Resolve( hint ) );
}
return _status;
}
}
[Rpc.Host( NetFlags.OwnerOnly )]
void Place( Vector3 position, Rotation rotation, Vector3 size, BuilderCatalog.Shape shape, string parameters, string materialPath, string surfacePath, Color tint, bool collisions, bool frozen )
{
var player = Player;
if ( !player.IsValid() ) return;
var owner = player.Network.Owner;
if ( _sinceLastPlace < MinPlaceInterval ) return;
_sinceLastPlace = 0;
if ( !BuilderPolicy.CheckCanBuild( owner ) ) return;
if ( LimitsSystem.Get( Scene ) is { } limits && !limits.CheckBuilderLimit( owner, 1 ) ) return;
if ( !BuilderPlacement.IsFinite( position ) || !IsUsable( rotation ) )
{
Reject( owner, "invalid transform" );
return;
}
if ( !BuilderShapeKey.TryCustom( shape, size, parameters, out var key ) )
{
Reject( owner, $"invalid {shape} recipe" );
return;
}
var transform = new Transform( position, rotation.Normal );
var bounds = BuilderShapes.Get( shape ).GetBounds( key );
var reach = BuilderPlacement.Reach + bounds.Size.Length * 0.5f + ReachTolerance;
if ( transform.PointToWorld( bounds.Center ).Distance( player.EyeTransform.Position ) > reach )
{
Reject( owner, "out of reach" );
return;
}
if ( materialPath?.Length > MaxPathLength || surfacePath?.Length > MaxPathLength )
{
Reject( owner, "path too long" );
return;
}
var surface = string.IsNullOrWhiteSpace( surfacePath ) ? null : ResourceLibrary.Get<Surface>( surfacePath );
if ( !FireToolAction( ToolInput.Primary ) ) return;
var material = BuilderMaterials.LoadLocal( materialPath );
var go = BuilderProp.Create( key, null, transform, material, surface, collisions, frozen, owner, pendingMaterial: material is null ? materialPath : null, tint: ClampTint( tint ) );
Track( go );
var undo = player.Undo.Create();
undo.Name = "#tool.undo.builder";
undo.Icon = "🧱";
undo.Add( go );
PlaceEffects( transform );
FirePostToolAction( ToolInput.Primary );
}
static Color ClampTint( Color tint )
{
static float Channel( float value ) => float.IsFinite( value ) ? Math.Clamp( value, 0f, 1f ) : 1f;
return new Color( Channel( tint.r ), Channel( tint.g ), Channel( tint.b ), Channel( tint.a ) );
}
static bool IsUsable( Rotation rotation )
{
var length = rotation.x * rotation.x + rotation.y * rotation.y + rotation.z * rotation.z + rotation.w * rotation.w;
return float.IsFinite( length ) && length > 0.25f;
}
static void Reject( Connection owner, string reason )
{
Log.Warning( $"Builder: refused a block from {owner?.DisplayName}: {reason}" );
if ( owner is not null ) Notices.SendLocalizedNotice( owner, "block", Color.Red, "#builder.refused", null, 3 );
}
[Rpc.Broadcast( NetFlags.HostOnly )]
void PlaceEffects( Transform target ) => Toolgun?.PlayToolEffects( target );
}