Merge branch 'main' into Fraktality-patch-1

Author: IgnisRBX

content/en-us/assets/engine-api/classes/Camera/DeviceSafeAreaVsFullscreen.png

@@ -238,6 +238,11 @@ properties:
       viewport to its opposite corner) the camera can view. See
       `Class.Camera.FieldOfView|FieldOfView` for a more general explanation of
       field of view.
+
+      Note that `DiagonalFieldOfView` represents the field of view that is 
+      visible by the `Class.Camera` rendering into the fullscreen area which 
+      may be occluded by notches or screen cutouts on some devices. See `Class.
+      Camera.ViewportSize|ViewportSize` for more information.
     code_samples:
     type: float
     tags:
@@ -271,6 +276,11 @@ properties:
         using binoculars.
       - Increasing FOV when the player is "sprinting" to give the impression of
         a lack of control.
+
+      Note that `FieldOfView` represents the field of view that is visible by 
+      the `Class.Camera` rendering into the fullscreen area which may be 
+      occluded by notches or screen cutouts on some devices. See `Class.Camera.
+      ViewportSize|ViewportSize` for more information.
     code_samples:
     type: float
     tags: []
@@ -534,15 +544,36 @@ properties:
     writeCapabilities: []
   - name: Camera.ViewportSize
     summary: |
-      Describes the dimensions, in pixels, of the client's viewport.
+      The dimensions of the device safe area on a Roblox client.
     description: |
-      **ViewportSize** describes the dimensions, in pixels, of the client's
-      viewport.
-
-      This property ignores the GUI inset applied by the top bar, meaning the
-      center of the screen can be found at precisely at 50% of the viewport in
-      both directions. You can find the position of a `Datatype.Vector3` in the
-      world on the viewport using `Class.Camera:WorldToViewportPoint()`.
+      `Class.Camera.ViewportSize|ViewportSize` returns the dimensions of the
+      device safe area on the current screen. This area is a rectangle which
+      includes the Roblox top bar area but does not include any device notches
+      or screen cutouts. The units of `Class.Camera.ViewportSize|ViewportSize` are Roblox
+      UI offset units which may be different from native display pixels.
+
+      <img src="../../../assets/engine-api/classes/Camera/DeviceSafeAreaVsFullscreen.png" width="840" alt="Mobile device screen with cutout showing device safe area." />
+
+      As noted above, `Class.Camera.ViewportSize|ViewportSize` is not equal to the fullscreen
+      area size on displays with cutouts or
+      notches. To obtain the fullscreen area size on all displays, you can query the
+      `Class.ScreenGui.AbsoluteSize|AbsoluteSize` property of a `Class.ScreenGui` with
+      `Class.ScreenGui.ScreenInsets|ScreenInsets` set to `Enum.ScreenInsets.None|None`. See
+      `Enum.ScreenInsets` for a more information about how screen areas are defined.
+
+      Finally, note that `Class.Camera.ViewportSize|ViewportSize` is not the actual viewport size
+      the camera uses for rendering (the camera renders in the fullscreen area). Also, the
+      `Class.Camera.FieldOfView` and `Class.Camera.DiagonalFieldOfView` properties are
+      based on the fullscreen area, not `Class.Camera.ViewportSize|ViewportSize`.
+
+      ##### Camera Updates
+      
+      Only the `Class.Camera` currently referred to by `Class.Workspace.
+      CurrentCamera` has its `Class.Camera.ViewportSize|ViewportSize` updated each 
+      frame during the `Class.RunService.PreRender|PreRender` step. The
+      `Class.Camera.ViewportSize|ViewportSize` of all other cameras in your 
+      experience won't be updated, including those used for
+      `Class.ViewportFrame|ViewportFrames`.
     code_samples:
     type: Vector2
     tags:
@@ -1158,26 +1189,45 @@ methods:
     summary: |
       Creates a unit `Datatype.Ray` from a position on the viewport (in pixels),
       at a given depth from the `Class.Camera`, orientated in the camera's
-      direction. Does not account for the GUI inset.
+      direction. Does not account for the `Enum.ScreenInsets|CoreUISafeInsets` inset.
     description: |
-      This function creates a unit `Datatype.Ray` from a 2D position on the
-      viewport (defined in pixels). This position does **not** account for the
-      GUI inset. The `Datatype.Ray` originates from the `Datatype.Vector3`
-      equivalent of the 2D position in the world at the given depth (in studs)
-      away from the `Class.Camera`.
-
-      As this function does not acknowledge the GUI inset, the viewport position
-      given is not equivalent to the screen position used by GUI elements. If
-      you are not using `Class.ScreenGui.IgnoreGuiInset` and need an otherwise
-      identical function that accounts for the GUI offset, use
+      This function creates a unit `Datatype.Ray` from a 2D position in device 
+      safe viewport coordinates, defined in pixels. The ray originates from the
+      `Datatype.Vector3` equivalent of the 2D position in the world at the
+      given depth (in studs) away from the `Class.Camera`.
+      
+      As illustrated below, `(0, 0)` corresponds to the top‑left point of the Roblox
+      top bar. This means that the input 2D position does **not** account for the 
+      `Enum.ScreenInsets|CoreUISafeInsets` inset, but it does account for any
+      `Enum.ScreenInsets|DeviceSafeInsets`.
+
+      <img src="../../../assets/engine-api/classes/Camera/ViewportPointToRayOrigin.png" width="840" alt="Diagram showing the origin of the device safe area viewport coordinate system." />
+
+      Note that UI instances use a different coordinate system
+      (`Class.GuiObject.AbsolutePosition` uses the
+      `Enum.ScreenInsets|CoreUISafeInsets` viewport coordinate system 
+      while this function uses the `Enum.ScreenInsets|DeviceSafeInsets`
+      viewport coordinate system). If you 
+      would like to specify position in core UI coordinates, please use
       `Class.Camera:ScreenPointToRay()`.
 
+      Also note that this function only works for the `Class.Workspace.
+      CurrentCamera` camera.
+      Other cameras, such as those you create for a `Class.ViewportFrame`, have 
+      an initial viewport size of `(1, 1)` and are only updated after you set 
+      them to `Class.Workspace.CurrentCamera|CurrentCamera`. The mismatch in 
+      viewport size causes the camera to return a ray with an incorrect 
+      `Datatype.Ray.Direction`.
+
       This function can be used in conjunction with the
-      `Class.Camera.ViewportSize` property to create a ray from the centre of
+      `Class.Camera.ViewportSize|ViewportSize` property to create a ray from the centre of
       the screen, for example:
 
       ```lua
-      local camera = workspace.CurrentCamera
+      local Workspace = game:GetService("Workspace")
+      
+      local camera = Workspace.CurrentCamera
+      
       local viewportPoint = camera.ViewportSize / 2
       local unitRay = camera:ViewportPointToRay(viewportPoint.X, viewportPoint.Y, 0)
       ```
@@ -1186,33 +1236,30 @@ methods:
       create a longer ray, you can do the following:
 
       ```lua
-      local camera = workspace.CurrentCamera
+      local Workspace = game:GetService("Workspace")
+      
+      local camera = Workspace.CurrentCamera
+      
       local length = 500
       local unitRay = camera:ScreenPointToRay(100, 100)
       local extendedRay = Ray.new(unitRay.Origin, unitRay.Direction * length)
       ```
-
-      This function only works for the current Workspace camera. Other cameras,
-      such as those you create for a `Class.ViewportFrame`, have an initial
-      viewport size of `(1, 1)` and are only updated after you set them to
-      `Class.Workspace.CurrentCamera`. The mismatch in viewport size causes the
-      camera to return a ray with an incorrect `Datatype.Ray.Direction`.
     code_samples:
     parameters:
       - name: x
         type: float
         default:
         summary: |
-          The position on the X axis, in pixels, of the viewport point at which
-          to originate the `Datatype.Ray`. This position does not account for
-          the GUI inset.
+          The position on the **X** axis, in pixels, of the viewport point at 
+          which to originate the `Datatype.Ray`, in device safe area 
+          coordinates.
       - name: 'y'
         type: float
         default:
         summary: |
-          The position on the Y axis, in pixels, of the viewport point at which
-          to originate the `Datatype.Ray`. This position does not account for
-          the GUI inset.
+          The position on the **Y** axis, in pixels, of the viewport point at 
+          which to originate the `Datatype.Ray`, in device safe area 
+          coordinates.
       - name: depth
         type: float
         default: 0

content/en-us/assets/engine-api/classes/Camera/ViewportPointToRayOrigin.png

@@ -1,10 +1,10 @@
 name: Axes
 type: datatype
 summary: |
-  The `Datatype.Axes` data type is for the `Class.ArcHandles` class to control
+  The `Axes` data type is for the `Class.ArcHandles` class to control
   which rotation axes are currently enabled.
 description: |
-  The `Datatype.Axes` data type is for the `Class.ArcHandles` class to control
+  The `Axes` data type is for the `Class.ArcHandles` class to control
   which rotation axes are currently enabled.
 code_samples:
 tags: []

content/en-us/reference/engine/classes/Camera.yaml

@@ -175,27 +175,27 @@ The following is a list of common tags in the MicroProfiler, grouped by category
     <td>Reduce the number of visible adorned objects, such as `Class.BillboardGui|BillboardGuis`, `Class.Humanoid` name/health labels, etc.</td>
   </tr>
   <tr>
-    <td>Prepare/Pass2D</td>
+    <td>Prepare/Pass2d</td>
     <td>Readies 2D UI rendering (both player and Roblox UI).</td>
     <td>Reduce the amount or complexity of UI elements.</td>
   </tr>
   <tr>
-    <td>Prepare/UpdateInvalidParts</td>
+    <td>Prepare/UpdatePrepare/updateInvalidParts</td>
     <td>Updates parts that had some property changed or added.</td>
     <td>Reduce the amount of properties changes on the world. If a script updates a large set of object properties, break it down across frames.</td>
   </tr>
   <tr>
-    <td>Prepare/UpdateInvalidateFastClusters</td>
+    <td>Prepare/UpdatePrepare/updateInvalidatedFastClusters</td>
     <td>Prepares geometry, typically "FastClusters" used to render `Class.Humanoid|Humanoids`. Sub-markers specify the number of parts, vertices, and size of vertices.</td>
     <td>Reduce the use of 'Humanoids' under objects that are not `Class.Humanoid|Humanoids`. This should not be used to shorten draw calls as FastClusters consume much more memory.</td>
   </tr>
   <tr>
-    <td>Prepare/UpdateDynamicParts</td>
+    <td>Prepare/UpdatePrepare/updateDynamicParts</td>
     <td>Updates positions for `Class.Humanoid|Humanoids`, vehicles and other moving instances for rendering.</td>
     <td>Reduce the number or complexity of moving `Class.Humanoid|Humanoids` or vehicles visible. Combining parts of the same material and color into a union or MeshPart can help with this.</td>
   </tr>
   <tr>
-    <td>Prepare/updateInstancedClusters</td>
+    <td>Prepare/UpdatePrepare/updateInstancedClusters</td>
     <td>Prepares static geometry that uses instanced rendering (parts and mesh parts). Labels "Clusters" and "Instances" indicate the number updated.</td>
     <td>Use less overall mesh and material variation. You can also create clusters by using objects that have similar appearances - size, color, material. </td>
   </tr>
@@ -335,22 +335,22 @@ The following is a list of common tags in the MicroProfiler, grouped by category
     <td>Reduce the amount of joints being created or destroyed.</td>
   </tr>
   <tr>
-    <td>Simulation/physicsStepped</td>
+    <td>Simulation/physicsSteppedTotal/physicsStepped</td>
     <td>Runs the physics simulation.</td>
     <td>Reduce the amount and complexity of physically simulated bodies.</td>
   </tr>
   <tr>
-    <td>physicsStepped/SpacialFilter/filterStep</td>
+    <td>Simulation/physicsSteppedTotal/physicsStepped/SpacialFilter/filterStep</td>
     <td>Updates simulation islands, arranging parts according to network ownership, local simulation. Islands are non-interacting groups of parts which can be simulated independently.</td>
     <td>Avoid setting network ownership frequently. Keep groups of parts far enough away from each other so they can be simulated separately.</td>
   </tr>
   <tr>
-    <td>physicsStepped/worldStep/stepContacts</td>
+    <td>Simulation/physicsSteppedTotal/physicsStepped/worldStep/stepContacts</td>
     <td>Updates contacts between objects.</td>
     <td>Reduce the amount of bodies colliding at once, or use simpler collision boxes. Cubes are better than complex meshes.</td>
   </tr>
   <tr>
-    <td>physicsStepped/worldStep/stepWorld OR stepWorldThrottled</td>
+    <td>Simulation/physicsSteppedTotal/physicsStepped/worldStep/stepWorld **OR** stepWorldThrottled</td>
     <td>Solves physics equations relating to connectors, buoyancy and `Class.Humanoid|Humanoids`. When the engine is overloaded and unable to simulate everything in real time, some steps may be throttled (stepWorldThrottled) and only "real time assemblies" such as `Class.Humanoid|Humanoids` are simulated.</td>
     <td>Depends on where the time is going based on the following three phases: stepContacts: narrow phase collision detection geometry tests. Solver step: integrate time and resolve collisions and other constraints updateBroadphase: update positions of assemblies in collision detection system and find possibly colliding narrow phase pairs.</td>
   </tr>
@@ -360,7 +360,7 @@ The following is a list of common tags in the MicroProfiler, grouped by category
     <td></td>
   </tr>
   <tr>
-    <td>Simulation/InterpolateNetworkedAssemblies</td>
+    <td>Simulation/physicsSteppedTotal/physicsStepped/interpolateNetworkedAssemblies</td>
     <td>Interpolates assemblies not controlled by this network peer.</td>
     <td>Set the network owner of parts to this peer to reduce this; although this will usually cause more physics work to be done elsewhere.</td>
   </tr>
@@ -370,7 +370,7 @@ The following is a list of common tags in the MicroProfiler, grouped by category
     <td>Lower the destroy height or reduce the amount of parts that fall to the destroy height.</td>
   </tr>
   <tr>
-    <td>Heartbeat/HeartbeatInternal/updateVisuallySleeping</td>
+    <td>Heartbeat/heartbeatInternal/workspaceOnHeartbeat/updateVisuallySleeping</td>
     <td>Second part of NotifyMovingAssemblies.</td>
     <td></td>
   </tr>