update Open Source Docs from Roblox internal teams

rbx-open-source-docs[bot] · rbx-open-source-docs[bot] · commit 2631756e3ebe · 2024-12-13T19:28:39.000Z
diff --git a/content/en-us/assets/studio/explorer/Part-Attachment-BillboardGui-ImageLabel.png b/content/en-us/assets/studio/explorer/Part-Attachment-BillboardGui-ImageLabel.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bbd4356606194a3ff49987b2b37ba5533e99f6c504226db94f4ad361e89d4359
+size 39782
diff --git a/content/en-us/assets/studio/explorer/Part-BillboardGui-ImageLabel.png b/content/en-us/assets/studio/explorer/Part-BillboardGui-ImageLabel.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:97f294433b6fd4f49a4af2ca5fd01cb86797b9caa045af37d26755919ce66209
+size 38938
diff --git a/content/en-us/assets/studio/explorer/Part-SurfaceGui-ImageLabel.png b/content/en-us/assets/studio/explorer/Part-SurfaceGui-ImageLabel.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c3aa19b63a5615d124b94b87c0ba88fdeb752e1467b7d94b0525be600d2b952f
+size 28976
diff --git a/content/en-us/assets/studio/explorer/StarterGui-SurfaceGui.png b/content/en-us/assets/studio/explorer/StarterGui-SurfaceGui.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6941a717e62081a191be602c4fce8db713e8dffba2c36d76bede9b88ed54bda8
+size 35983
diff --git a/content/en-us/assets/studio/properties/SurfaceGui-Adornee-Face.png b/content/en-us/assets/studio/properties/SurfaceGui-Adornee-Face.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:13e42463862fcbf9c3a6db661d17590be80dc56f57aef4bc248575735cfdc296
+size 39247
diff --git a/content/en-us/assets/studio/properties/SurfaceGui-Face-Top.png b/content/en-us/assets/studio/properties/SurfaceGui-Face-Top.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7ee64e2d6342d6ac87eacbbb7eab97a55a77c1665ed293d1e03020ed216aee11
+size 23760
diff --git a/content/en-us/assets/ui/in-experience/BillboardGui-Diagram.jpg b/content/en-us/assets/ui/in-experience/BillboardGui-Diagram.jpg
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:cb1978a0841f57fed2398daa4f3f32999f59f46b2944fb9b42220fb9b745d6eb
-size 223146
+oid sha256:b304e5f3f38ba8d8a9afae1542cf338d74d5162f760ad5653a2c88c73726bdf8
+size 276027
diff --git a/content/en-us/assets/ui/in-experience/BillboardGui-LightInfluence-0.jpg b/content/en-us/assets/ui/in-experience/BillboardGui-LightInfluence-0.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f109b60bb1db6f16a70423e98278557b1912c2c1430fb69499a23afdbe1b3835
+size 223582
diff --git a/content/en-us/assets/ui/in-experience/BillboardGui-LightInfluence-1.jpg b/content/en-us/assets/ui/in-experience/BillboardGui-LightInfluence-1.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:81e154d53706911f18ff4f6c85cac164580bf7c8b155448aa05b52d71ddaa6d1
+size 219520
diff --git a/content/en-us/assets/ui/in-experience/BillboardGui-Sizing-Positioning.mp4 b/content/en-us/assets/ui/in-experience/BillboardGui-Sizing-Positioning.mp4
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:841be61c7b0bdc703aacae7bcbe699c74cb6fba1368c5daa7e7f3c6807290086
+size 7444255
diff --git a/content/en-us/assets/ui/in-experience/Showcase.mp4 b/content/en-us/assets/ui/in-experience/Showcase.mp4
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:7cc51691b2e5cc4db99892e81e45723b6ad021f5b14dae10cb65b393959095b6
-size 11145294
+oid sha256:45c173911aab56aca26b3b7b8c59af04c2ae60f3501ff2d4d3b575e04170ead1
+size 10256715
diff --git a/content/en-us/assets/ui/in-experience/SurfaceGui-Brightness-0.jpg b/content/en-us/assets/ui/in-experience/SurfaceGui-Brightness-0.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1ff592c37fbba81ec0ef58faee83ca8347b3d2eae7aab11a7c701e75973b3132
+size 264120
diff --git a/content/en-us/assets/ui/in-experience/SurfaceGui-Brightness-10.jpg b/content/en-us/assets/ui/in-experience/SurfaceGui-Brightness-10.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ccc248cc57c281d7a356ed5259c930936197646085af27d29ab5b18d5703acb5
+size 283985
diff --git a/content/en-us/assets/ui/in-experience/SurfaceGui-Diagram.jpg b/content/en-us/assets/ui/in-experience/SurfaceGui-Diagram.jpg
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:78e3dfd91552fe53248d0c690e0f8d5bfa2781e8c4a98747ea753c391a13e215
-size 228682
+oid sha256:309c9e7aee332c50611fee43d2cbfd707a4d21c92ceaf52bda316c59a6b81cb7
+size 274200
diff --git a/content/en-us/assets/ui/in-experience/SurfaceGui-Sizing.mp4 b/content/en-us/assets/ui/in-experience/SurfaceGui-Sizing.mp4
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1a828486d40005fd50b04cf76c75b1ee97d0b81d5a507f0d95d256349532405a
+size 2125497
diff --git a/content/en-us/reference/engine/classes/BillboardGui.yaml b/content/en-us/reference/engine/classes/BillboardGui.yaml
diff --git a/content/en-us/reference/engine/classes/GuiObject.yaml b/content/en-us/reference/engine/classes/GuiObject.yaml
@@ -36,11 +36,9 @@ properties:
     summary: |
       Determines whether this UI element sinks input.
     description: |
-      This property determines whether this `Class.GuiObject` will sink input to
+      This property determines whether the `Class.GuiObject` will sink input to
       3D space, such as underlying models with a `Class.ClickDetector` class
-      such as `Class.DragDetector`. In other words, if the player attempts to
-      click the detector with the mouse hovering over an active UI element, the
-      UI will block the input from reaching the detector.
+      like `Class.DragDetector`.
 
       For `Class.GuiButton` objects (`Class.ImageButton` and
       `Class.TextButton`), this property determines whether
diff --git a/content/en-us/reference/engine/classes/SurfaceGui.yaml b/content/en-us/reference/engine/classes/SurfaceGui.yaml
@@ -5,21 +5,35 @@ memory_category: Instances
 summary: |
   Container for GuiObjects that are rendered on the surface of a part.
 description: |
-  Allows for the rendering of GUI elements onto a part's surface in the 3D
-  world, while allowing for basic user interaction to occur. SurfaceGuis must be
-  descendants of PlayerGui in order to know which player is interacting with it.
+  `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.
 
-  ##### Caching static UI for performance improvements
+  <img src="/assets/ui/in-experience/SurfaceGui-Diagram.jpg" width="800" alt="SurfaceGui on a 3D part in the place with an ImageLabel child to depict a screen console." />
 
-  A Gui's appearance is cached until one of the following events occurs:
+  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`.
 
-  - A descendant is added to the Gui.
-  - A descendant is removed from the Gui.
-  - A property of a descendant of the Gui changes.
-  - A property of the Gui changes.
+  See [In-Experience UI](../../../ui/in-experience-containers.md#surface-ui) for a guide on working with `Class.SurfaceGui` containers.
 
-  If any of these events occur, the Gui's appearance will be recomputed the next
-  frame it gets rendered.
+  ##### 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
@@ -28,22 +42,21 @@ deprecation_message: ''
 properties:
   - name: SurfaceGui.AlwaysOnTop
     summary: |
-      Determines whether the SurfaceGui will always be rendered on top of other
-      3D objects.
+      Determines whether the `Class.SurfaceGui` will always be rendered on top
+      of other 3D objects.
     description: |
-      Determines whether the SurfaceGui will render over top of 3D content, or
-      be occluded by it.
-
-      When set to false, the SurfaceGui will render like other 3D content, and
-      will be occluded by other 3D objects.
-
-      When set to true, it always renders on top of 3D content, and the
-      appearance changes significantly:
+      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` is treated as though it was 0.
-      - `Class.SurfaceGui.Brightness` has no effect.
+      - `Class.SurfaceGui.LightInfluence|LightInfluence` is treated as though it's `0`.
+      - `Class.SurfaceGui.Brightness|Brightness` has no effect.
     code_samples:
     type: bool
     tags: []
@@ -61,25 +74,22 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.Brightness
     summary: |
-      Determines the factor by which the GUI's light is scaled when
-      `Class.SurfaceGui.LightInfluence|LightInfluence` is 0.
+      Determines the factor by which the `Class.SurfaceGui` container's light is
+      scaled when `Class.SurfaceGui.LightInfluence|LightInfluence` is `0`.
     description: |
-      **Brightness** determines the factor by which the GUI's emitted light is
-      scaled. By default, this property is 1 and can be set to any number on the
-      range [0, 1000].
-
-      By modifying this property, the apparent brightness of a GUI can be better
-      matched to its environment. For instance, a video billboard like those
-      found in Times Square can be made brighter to be clearly visible on a
-      bright day.
+      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`.
 
-      This property won't produce any effect in the following scenarios wherein
-      the GUI does not emit light.:
-
-      - When `Class.SurfaceGui.AlwaysOnTop|AlwaysOnTop` is true, the color of
-        each pixel is the color shown on-screen.
-      - When `Class.SurfaceGui.LightInfluence|LightInfluence` is 1, all light
-        from the GUI is reflected from the environment instead of being emit.
+      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: []
@@ -97,11 +107,11 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.CanvasSize
     summary: |
-      The size of a 'virtual screen', in 'virtual pixels', which makes
-      SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
+      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
-      SurfaceGuis pixel-to-pixel compatible with ScreenGuis.
+      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: []
@@ -119,14 +129,15 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.ClipsDescendants
     summary: |
-      When set to true, portions of GuiObjects that fall outside of the
-      SurfaceGui's canvas borders will not be drawn.
+      Whether portions of `Class.GuiObject|GuiObjects` that fall outside of the
+      `Class.SurfaceGui` canvas borders will be drawn.
     description: |
-      When set to true, portions of GuiObjects that fall outside of the
-      SurfaceGui's canvas borders will not be drawn.
+      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, objects that are completely outside of
-      the canvas of the SurfaceGui will not render.
+      Even when this property is `false`, `Class.GuiObject|GuiObjects` that are
+      **completely** outside of the canvas will not render.
     code_samples:
     type: bool
     tags: []
@@ -144,11 +155,9 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.LightInfluence
     summary: |
-      Controls how much the SurfaceGui is influenced by the lighting in the game
-      world.
+      Controls how much the `Class.SurfaceGui` is influenced by environmental lighting.
     description: |
-      Controls how much the SurfaceGui is influenced by the lighting in the game
-      world.
+      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: []
@@ -166,28 +175,18 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.MaxDistance
     summary: |
-      Controls how far away the SurfaceGui can be displayed before it stops
-      rendering.
+      Controls how far away the `Class.SurfaceGui` can be displayed before it
+      stops rendering.
     description: |
-      Controls how far away the SurfaceGui can be displayed before it stops
-      rendering. A value of 0 means there is no limit, and it will render
-      infinitely far away.
-
-      For experiences with many SurfaceGuis, it's recommended to set this to an
-      appropriate value for each SurfaceGui. The default value when inserting a
-      SurfaceGui in Studio is 1000, which should be fine for most usages.
-
-      For UIs that are outdoors, you should set the MaxDistance far enough away
-      so that the UI is small on the screen when it pops out, around 10 pixels
-      across. This makes it less noticeable when it pops in or out.
+      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.
 
-      You can reduce the pop in effect even more by adding a similar looking
-      decal underneath the SurfaceGui, or by changing the part color to match
-      the background color of your UI.
-
-      For indoor spaces, the MaxDistance should be set slightly larger than the
-      size of the room, so that the UI won't render when the player is in a
-      different room.
+      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: []
@@ -205,21 +204,22 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.PixelsPerStud
     summary: |
-      Determines the number of screen-space pixels per world-space stud used to
-      render the contents of the SurfaceGui.
+      Determines the density of pixels used for each world-space stud to render
+      the contents of the `Class.SurfaceGui`.
     description: |
-      **PixelsPerStud** determines the density of pixels used for each
-      world-space stud to render the contents of the SurfaceGui.
-
-      Higher values will cause the various `Class.GuiObject` within to appear
-      smaller if they are kept the same size. Conversely, lower values will
-      cause objects to appear larger. However, if the GuiObjects are scaled
-      proportionally (either by using a `Class.UIScale` or modifying
-      `Class.GuiObject.Size|Size` or `Class.TextLabel.TextSize` etc.), 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 SurfaceGui.
-      Be mindful that a large pixel density could negatively affect performance
-      if the face of the adorned part is large enough.
+      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: []
@@ -237,15 +237,17 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.SizingMode
     summary: |
-      Determines whether SurfaceGui will render at fixed size or scale with its
-      size in studs.
+      Determines whether the `Class.SurfaceGui` will render at a fixed size or
+      scale with its size in studs.
     description: |
-      When set to `Enum.SurfaceGuiSizingMode.FixedSize`, SurfaceGui renders with
-      a fixed size set using `Class.SurfaceGui.CanvasSize`.
+      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.PixelsPerStud`, SurfaceGui renders
-      with a variable size based on `Class.SurfaceGui.PixelsPerStud` and the
-      SurfaceGui'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: []
@@ -263,12 +265,13 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.ToolPunchThroughDistance
     summary: |
-      Sets the distance left clicking starts acting on the surface gui instead
-      of the held tool.
+      Sets the distance in which left clicking starts acting on the
+      `Class.SurfaceGui` instead of for the held `Class.Tool`.
     description: |
-      Sets the distance left clicking starts acting on the surface gui instead
-      of the held tool. If a character is within this distance of the surface
-      gui, then the tool will not activate on click.
+      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: []
@@ -286,11 +289,12 @@ properties:
     writeCapabilities: []
   - name: SurfaceGui.ZOffset
     summary: |
-      Offsets the SurfaceGui relative to the normal of the surface it is
-      attached to.
+      Layers this `Class.SurfaceGui` in relation to other
+      `Class.SurfaceGui|SurfaceGuis` on the same face.
     description: |
-      Offsets the SurfaceGui relative to the normal of the surface it is
-      attached to.
+      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: []
diff --git a/content/en-us/reference/engine/classes/SurfaceGuiBase.yaml b/content/en-us/reference/engine/classes/SurfaceGuiBase.yaml
diff --git a/content/en-us/resources/feature-packages/bundles.md b/content/en-us/resources/feature-packages/bundles.md
diff --git a/content/en-us/resources/feature-packages/missions.md b/content/en-us/resources/feature-packages/missions.md
diff --git a/content/en-us/tutorials/use-case-tutorials/ui/creating-hud-meters.md b/content/en-us/tutorials/use-case-tutorials/ui/creating-hud-meters.md
diff --git a/content/en-us/ui/in-experience-containers.md b/content/en-us/ui/in-experience-containers.md
diff --git a/content/en-us/ui/index.md b/content/en-us/ui/index.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+version https://git-lfs.github.com/spec/v1`
	`2`	`+oid sha256:841be61c7b0bdc703aacae7bcbe699c74cb6fba1368c5daa7e7f3c6807290086`
	`3`	`+size 7444255`