Skip to Content
Kinemium

SurfaceGui

Draw a GUI onto a face of a part.

SurfaceGui renders its GUI children onto a surface in the 3D world. Parent it to a part, or set Adornee, and its canvas is painted onto the chosen face.

Getting started

local surface = Instance.new("SurfaceGui")
surface.Face = Enum.NormalId.Front
surface.CanvasSize = Vector2.new(800, 600)
surface.PixelsPerStud = 100
surface.Parent = part

local label = Instance.new("TextLabel")
label.Size = UDim2.fromScale(1, 1)
label.BackgroundTransparency = 1
label.Text = "Harbor"
label.TextScaled = true
label.Parent = surface

Properties

PropertyTypeAccessDefaultDescription
ActivebooleanRead/writetrueWhether the GUI receives input.
AdorneeInstance?Read/writenilPart to draw on when the GUI isn't parented to one.
AlwaysOnTopbooleanRead/writefalseDraw over other geometry.
BrightnessnumberRead/write1Brightness multiplier, clamped to 0 through 1000.
CanvasSizeVector2Read/write(800, 600)Logical canvas size used for layout.
ClipsDescendantsbooleanRead/writetrueClip children to the canvas.
EnabledbooleanRead/writetrueWhether the GUI renders.
FaceEnum.NormalIdRead/writeFrontPart face that receives the GUI.
LightInfluencenumberRead/write0How much scene lighting affects the GUI, clamped to 0 through 1.
MaxDistancenumberRead/write1000Distance at which the GUI stops rendering, clamped to 0 or above.
PixelsPerStudnumberRead/write100Resolution when sizing by pixels per stud, minimum 0.001.
ShapeEnum.SurfaceGuiShapeRead/writeFlatFlat or curved surface layout.
SizingModeEnum.SurfaceGuiSizingModeRead/writePixelsPerStudWhether the canvas is sized in pixels per stud or fixed pixels.
ToolPunchThroughDistancenumberRead/write0Depth allowance for held tools.
ZOffsetnumberRead/write0Depth offset from the surface.

Notes

  • The target is the parent part, or Adornee when set. Without a part target, nothing renders.
  • CanvasSize defines the coordinate space for child layout, so scaled children resolve against it.
  • PixelsPerStud is clamped to a minimum of 0.001; values below that are raised.
  • Brightness clamps rather than raising.
  • The maximum texture dimension is 4096 pixels.
  • Unlike ScreenGui, this object is not a GuiObject; it hosts GUI children directly.

See also

  • Part for the surface that displays the GUI.
  • ScreenGui for screen-space UI.
  • ViewportFrame for 3D content inside a GUI.

On this page