# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: SurfaceGui type: class memory_category: Instances summary: | Container for GuiObjects that are rendered on the surface of a part. description: | `Class.SurfaceGui` allows for the rendering of UI objects onto a part's surface in the 3D world while also allowing for basic user interaction to occur. Similar to `Class.Decal|Decals` and `Class.Texture|Textures`, UI objects such as `Class.TextLabel|TextLabels` and `Class.ImageLabel|ImageLabels` parented to a `Class.SurfaceGui` face the same direction as the surface they're on, editable through the `Class.SurfaceGui.Face|Face` property. SurfaceGui on a 3D part in the place with an ImageLabel child to depict a screen console. Note that interactive UI elements like `Class.ImageButton|ImageButtons` and `Class.TextButton|TextButtons` inside a `Class.SurfaceGui` will only receive user input if they are parented to the `Class.PlayerGui`, typically via placing the `Class.SurfaceGui` inside `Class.StarterGui` (the `Class.SurfaceGui.Adornee|Adornee` property can be used to target a part in the 3D world while the `Class.SurfaceGui` itself remains in the `Class.PlayerGui`). Additionally, the part's `Class.BasePart.CanQuery|CanQuery` property must be `true` for the interactive UI element to receive input. See [In-Experience UI](../../../ui/in-experience-containers.md#surface-ui) for a guide on working with `Class.SurfaceGui` containers. ##### Caching Behavior To help improve performance, the appearance of a `Class.SurfaceGui` is cached until one of the following occurs, after which its appearance will be recomputed on the next rendering frame. - A descendant is added to or removed from the `Class.SurfaceGui`. - A property of a descendant of the `Class.SurfaceGui` changes. - A property of the `Class.SurfaceGui` itself changes. code_samples: [] inherits: - SurfaceGuiBase descendants: [] tags: [] deprecation_message: '' properties: - name: SurfaceGui.AlwaysOnTop summary: | Determines whether the `Class.SurfaceGui` will always be rendered on top of other 3D objects. description: | This property determines whether the `Class.SurfaceGui` will always render on top of other 3D objects. When set to `false` (default), the `Class.SurfaceGui` renders like other 3D content and is occluded by other 3D objects. When set to `true`, the `Class.SurfaceGui` always renders on top of 3D content and the appearance changes significantly: - Colors match how they appear inside a `Class.ScreenGui`. - Text may appear sharper on high DPI devices. - `Class.SurfaceGui.LightInfluence|LightInfluence` is treated as though it's `0`. - `Class.SurfaceGui.Brightness|Brightness` has no effect. code_samples: [] type: boolean tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.Brightness summary: | Determines the factor by which the `Class.SurfaceGui` container's light is scaled when `Class.SurfaceGui.LightInfluence|LightInfluence` is `0`. description: | This property determines the factor by which the `Class.SurfaceGui` container's light is scaled when `Class.SurfaceGui.LightInfluence|LightInfluence` is `0`. By default, this property is `1` and can be set to any number between `0` and `1000`. By modifying this property, the apparent brightness of a `Class.SurfaceGui` can be better matched to its environment. For instance, a video billboard can be brightened inside a dark room by increasing `Class.SurfaceGui.Brightness|Brightness` to `10`. Note that `Class.SurfaceGui.Brightness|Brightness` is inaccessible in Studio and has no effect when either `Class.SurfaceGui.LightInfluence|LightInfluence` is `1` or `Class.SurfaceGui.AlwaysOnTop|AlwaysOnTop` is `true`. code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.CanvasSize summary: | The size of a "virtual screen" in "virtual pixels" which makes `Class.SurfaceGui|SurfaceGuis` pixel-to-pixel compatible with `Class.ScreenGui|ScreenGuis`. description: | The size of a "virtual screen" in "virtual pixels" which makes `Class.SurfaceGui|SurfaceGuis` pixel-to-pixel compatible with `Class.ScreenGui|ScreenGuis`. code_samples: [] type: Vector2 tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Sizing serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.ClipsDescendants summary: | Whether portions of `Class.GuiObject|GuiObjects` that fall outside of the `Class.SurfaceGui` canvas borders will be drawn. description: | When set to `true` (default), portions of `Class.GuiObject|GuiObjects` that fall outside of the `Class.SurfaceGui` canvas borders will not be drawn. Even when this property is `false`, `Class.GuiObject|GuiObjects` that are **completely** outside of the canvas will not render. code_samples: [] type: boolean tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Behavior serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.LightInfluence summary: | Controls how much the `Class.SurfaceGui` is influenced by environmental lighting. description: | Controls how much the `Class.SurfaceGui` is influenced by environmental lighting, in a range from `0` to `1`. Setting this to `1` means that surrounding lighting has complete control over the appearance, while setting it to `0` means that the lighting has no effect. code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.MaxDistance summary: | Controls how far away the `Class.SurfaceGui` can be displayed before it stops rendering. description: | This property controls how far from the camera the `Class.SurfaceGui` will be displayed before it stops rendering. A value of `0` means there is no limit and it will render infinitely far away. The default value of `1000` works fine for most cases. For `Class.SurfaceGui|SurfaceGuis` that appear outdoors, it's recommended that `Class.SurfaceGui.MaxDistance|MaxDistance` is high enough to ensure that the container's UI is sufficiently small on the screen when it appears or disappears, minimizing the sudden pop‑in/out effect. code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.PixelsPerStud summary: | Determines the density of pixels used for each world-space stud to render the contents of the `Class.SurfaceGui`. description: | This property determines the density of pixels used for each world-space stud to render the contents of the `Class.SurfaceGui`. Higher values will cause the various `Class.GuiObject|GuiObjects` within to appear smaller if they are kept the same size. Conversely, lower values will cause objects to appear larger. However, if the `Class.GuiObject|GuiObjects` are scaled proportionally through use of `Class.UIScale`, `Class.GuiObject.Size`, `Class.TextLabel.TextSize`, or similar, this property allows for higher definition to be used. It's important to select a value based on how far away you expect a player to view the `Class.SurfaceGui`. Also be mindful that a large pixel density could negatively affect performance if the face of the adorned part is large enough. code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Sizing serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.SizingMode summary: | Determines whether the `Class.SurfaceGui` will render at a fixed size or scale with its size in studs. description: | When set to `Enum.SurfaceGuiSizingMode.PixelsPerStud` (default), the `Class.SurfaceGui` renders with a variable size based on `Class.SurfaceGui.PixelsPerStud|PixelsPerStud` and the surface's size in studs. When set to `Enum.SurfaceGuiSizingMode.FixedSize`, the `Class.SurfaceGui` renders with a fixed size set through `Class.SurfaceGui.CanvasSize|CanvasSize`. code_samples: [] type: SurfaceGuiSizingMode tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Sizing serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.ToolPunchThroughDistance summary: | Sets the distance in which left clicking starts acting on the `Class.SurfaceGui` instead of for the held `Class.Tool`. description: | Sets the distance in which left clicking starts acting on the `Class.SurfaceGui` instead of for the held `Class.Tool`. If a character is within this distance of the `Class.SurfaceGui`, the `Class.Tool` will not activate on click. code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: true can_save: true capabilities: - UI - name: SurfaceGui.ZOffset summary: | Layers this `Class.SurfaceGui` in relation to other `Class.SurfaceGui|SurfaceGuis` on the same face. description: | Layers this `Class.SurfaceGui` in relation to others on the same face (changing this does not visually "lift" or "sink" a `Class.SurfaceGui` from the surface). code_samples: [] type: float tags: [] deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Appearance serialization: can_load: true can_save: true capabilities: - UI methods: [] events: [] callbacks: []