Merge branch 'main' into yusufameri-creator-store-docs

IgnisRBX · web-flow · commit 5dc0d64d7606 · 2024-10-29T11:19:00.000-10:00
diff --git a/content/en-us/cloud/open-cloud/index.md b/content/en-us/cloud/open-cloud/index.md
@@ -5,15 +5,29 @@ description: In addition to using Engine and Studio tools to create experiences
 
 With Open Cloud, you can access Roblox resources through standard REST APIs, which lets you build everything from command line automation tools to complex web apps. The Open Cloud APIs support HTTPS and let you update experiences, restart servers, work with your data stores and memory stores, manage user restrictions, list inventory items, and much, much more.
 
-For the full list of available operations, see the Open Cloud API reference.
-
 <a href="../reference/index.md">
   <Button variant="contained">Open Cloud API Reference</Button>
 </a>
 
+## About the APIs
+
+Roblox has four categories of HTTP REST API:
+
+- [Open Cloud v2](../reference/index.md)
+- [Open Cloud v1](../reference/index.md)
+- [Legacy with API key and/or OAuth 2.0 authentication](../legacy.md)
+- [Legacy with cookie authentication](../legacy.md)
+
+Whenever possible, use the Open Cloud v2 API. This API has the strongest stability guarantees and regularly adds new resources. The Open Cloud v1 API also has strong stability guarantees, but a more limited set of resources.
+
+The legacy APIs, no matter which types of authentication they support, can incorporate breaking changes without notice and have minimal stability guarantees. They are not part of the Open Cloud v1 or v2 APIs, and we don't recommend them for production applications.
+
 ## Getting Started with Open Cloud
 
-1. See the authentication documentation for how to use [API keys](api-keys.md) or [OAuth 2.0](oauth2-overview.md).
+1. Set up authentication for your application.
+
+   See the documentation for how to use [API keys](api-keys.md) or [OAuth 2.0](oauth2-overview.md). API keys are the easiest way to get started.
+
 1. Use a tool like [Postman](https://www.postman.com) or the [OAuth 2.0 sample app](oauth2-sample.md) to test API calls.
 1. Review the [resource guides](experience-notifications.md) for end-to-end walkthroughs of using certain APIs.
-1. See the Open Cloud [reference documentation](../reference/index.md) for the full list of resources, [common API patterns](../reference/patterns.md), and [types](../reference/types.md).
+1. See the Open Cloud [reference documentation](../reference/index.md) for the full list of v1 and v2 resources, [common API patterns](../reference/patterns.md), and [types](../reference/types.md).
diff --git a/content/en-us/production/game-design/ui-ux-design.md b/content/en-us/production/game-design/ui-ux-design.md
@@ -37,11 +37,11 @@ Irrelevant elements can cause confusion and distraction. [_Spellbound RPG_](http
 <GridContainer numColumns="2">
   <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-3.png" alt="A close up view of an unselected circular Items button with a brown book icon. The environment in the background is a brown dirt with a patch of snow." width="100%"/>
-    <figcaption>Items prior to selection in *Spellbound RPG*</figcaption>
+    <figcaption>Items prior to selection in [Spellbound RPG](https://www.roblox.com/games/6468323505/)</figcaption>
   </figure>
   <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-2.png" alt="A close up view of a selected circular Items button with a brown book icon, along with three additional buttons for skills, equipment, and the players deck. The additional buttons only display when the button is selected." width="90%"/>
-    <figcaption>Items after selection in *Spellbound RPG*</figcaption>
+    <figcaption>Items after selection in [Spellbound RPG](https://www.roblox.com/games/6468323505/)</figcaption>
   </figure>
 </GridContainer>
 
@@ -50,19 +50,19 @@ In [_Super Striker League_](https://www.roblox.com/games/3360853050/), player in
 <GridContainer numColumns="2">
   <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-6.png" width="100%"/>
-    <figcaption>Contextual buttons in _Super Striker League_</figcaption>
+    <figcaption>Contextual buttons in [Super Striker League](https://www.roblox.com/games/3360853050/)</figcaption>
   </figure>
   <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-7.png" width="100%"/>
-    <figcaption>Contextual buttons in _Super Striker League_</figcaption>
+    <figcaption>Contextual buttons in [Super Striker League](https://www.roblox.com/games/3360853050/)</figcaption>
   </figure>
 </GridContainer>
 
 In [_The Survival Game,_](https://www.roblox.com/games/11156779721/) players need to be aware of their health and hunger status, and have quick access to their map, inventory, and tools. This information allows them to make decisions and prioritize actions for survival. If this information or tools are hard to find or missing, survival becomes more challenging and needlessly frustrating.
 
 <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-1.png" width="60%"/>
-    <figcaption> HUD features in _The Survival Game_ </figcaption>
+    <figcaption> HUD features in [The Survival Game](https://www.roblox.com/games/11156779721/)</figcaption>
   </figure>
 
 ### Attention
@@ -83,21 +83,21 @@ In [_Jailbreak_](https://www.roblox.com/games/606849621/)'s season pass UI, a st
 
 <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-8.png" width="60%"/>
-    <figcaption> Season pass UI in _Jailbreak_ </figcaption>
+    <figcaption> Season pass UI in [Jailbreak](https://www.roblox.com/games/606849621/)</figcaption>
   </figure>
 
 In [_Dragon Adventures,_](https://www.roblox.com/games/3475397644/) visual priority is given to the highest-value coin bundle by increasing its size and separating it with more padding, to distinguish it from smaller bundles.
 
 <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-9.png" width="60%"/>
-    <figcaption> Coin bundles in _Dragon Adventures_</figcaption>
+    <figcaption> Coin bundles in [Dragon Adventures](https://www.roblox.com/games/3475397644/)</figcaption>
   </figure>
 
 In [_Tower Defense Simulator_](https://www.roblox.com/games/3260590327/), both size and proximity are used to visually group and distinguish Daily Tower Skins from Daily Crates.
 
 <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-10.png" width="60%"/>
-    <figcaption> _Tower Defense Simulator_ shop</figcaption>
+    <figcaption>The shop in [Tower Defense Simulator](https://www.roblox.com/games/3260590327/)</figcaption>
   </figure>
 
 ### Visual language
@@ -128,7 +128,7 @@ Headers and titles containing significant high-level information should be large
 
 <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-13.png" width="40%"/>
-    <figcaption> Clothing Shop in *Winds of Fortune*</figcaption>
+    <figcaption> Clothing Shop in [Winds of Fortune](https://www.roblox.com/games/7714627632/)</figcaption>
   </figure>
 
 Once the visual language has been designed, it can be documented in a _Style Guide_, a set of rules and examples that help everyone on the team understand how to apply the language consistently across the game.
@@ -146,11 +146,11 @@ Given their widespread use, players are typically familiar with such conventions
 <GridContainer numColumns="2">
   <figure>
     <img src="../../assets/game-design/ui-ux-design/ui-ux-design-14.png" width="100%"/>
-    <figcaption>X Close Buttons in *Winds of Fortune*, *Dragon Adventures*, *BotClashSimulator*, and *DOORS*</figcaption>
+    <figcaption>X Close Buttons in [Winds of Fortune](https://www.roblox.com/games/7714627632/), [Dragon Adventures](https://www.roblox.com/games/3475397644/), [BotClash Simulator](https://www.roblox.com/games/9300407930/), and [DOORS](https://www.roblox.com/games/6516141723/)</figcaption>
   </figure>
   <figure>
    <img src="../../assets/game-design/ui-ux-design/ui-ux-design-15.png" width="90%"/>
-    <figcaption>Green "Health" stat consistency in *Arcane Odyssey*</figcaption>
+    <figcaption>Green "Health" stat consistency in [Arcane Odyssey](https://www.roblox.com/games/3272915504/)</figcaption>
   </figure>
 </GridContainer>
 
@@ -245,7 +245,7 @@ For example, to equip an item on an avatar in [Berry Avenue RP](https://www.robl
 
  <figure>
     <video controls src="../../assets/game-design/ui-ux-design/ui-ux-design-18-video.mp4"></video>
-    <figcaption>Avatar customization flow in *Berry Avenue RP*.</figcaption>
+    <figcaption>Avatar customization flow in [Berry Avenue RP](https://www.roblox.com/games/8481844229/)</figcaption>
   </figure>
 
 These steps taken together represent the avatar customization flow. This flow is simple and straightforward, with as few steps as possible needed to equip an item. Because players do not have to perform many actions or think too much about what they need to do, this flow is low in _friction_, a measurement of the effort required to reach a goal.
diff --git a/content/en-us/projects/assets/index.md b/content/en-us/projects/assets/index.md
@@ -260,6 +260,18 @@ if success then
 end
 ```
 
+### rbxgameasset
+
+`rbxgameasset` points to an asset uploaded through the [Asset Manager](../../projects/assets/manager.md). It allows access to assets by a user‑friendly name instead of ID, so if you upload an image named `Potion.png`, you can reference it as:
+
+<span><Chip label='rbxgameasset://Images/Potion' color='primary' size='large' /></span><br />
+
+In the above example, `Images` is the category/folder that appears in the [Asset Manager](../../projects/assets/manager.md) and `Potion` is the asset name, minus its extension.
+
+<Alert severity="warning">
+`rbxgameasset` only works for the current game. If you paste a parent object that utilizes the asset into another game, the asset will not load (or will load a different asset if you've uploaded one with the same name to that other game). If you need an asset to work across multiple games, use `rbxassetid` instead of `rbxgameasset`.
+</Alert>
+
 ### rbxhttp
 
 `rbxhttp` is shorthand for `Class.ContentProvider.BaseUrl`, for example:
diff --git a/content/en-us/reference/engine/classes/AtmosphereSensor.yaml b/content/en-us/reference/engine/classes/AtmosphereSensor.yaml
@@ -4,12 +4,12 @@ category:
 memory_category: Instances
 summary: |
   A `Class.SensorBase` that outputs data about the
-  `Class.AtmosphereSensor.AirDenstiy|AirDenstiy` and
+  `Class.AtmosphereSensor.AirDensity|AirDensity` and
   `Class.AtmosphereSensor.RelativeWindVelocity|RelativeWindVelocity` at the
   sensor's position.
 description: |
   A `Class.SensorBase` that outputs data about the
-  `Class.AtmosphereSensor.AirDenstiy|AirDenstiy` and
+  `Class.AtmosphereSensor.AirDensity|AirDensity` and
   `Class.AtmosphereSensor.RelativeWindVelocity|RelativeWindVelocity` at the
   sensor's position.
 code_samples: []
diff --git a/content/en-us/reference/engine/classes/FluidForceSensor.yaml b/content/en-us/reference/engine/classes/FluidForceSensor.yaml
@@ -2,8 +2,15 @@ name: FluidForceSensor
 type: class
 category:
 memory_category: Instances
-summary: ''
-description: ''
+summary: |
+  A `Class.SensorBase` that outputs `Class.FluidForceSensor.Force|Force`, `Class.FluidForceSensor.Torque|Torque` and `Class.FluidForceSensor.CenterOfPressure|CenterOfPressure`.
+description: |
+  `FluidForceSensor` is a `Class.SensorBase` which outputs the results of fluid
+  force simulation from the last physics frame for the part it is attached to.
+  The sensor outputs the `Class.FluidForceSensor.Force|Force`,
+  `Class.FluidForceSensor.Torque|Torque` and
+  `Class.FluidForceSensor.CenterOfPressure|CenterOfPressure` which were computed
+  by the fluid force simulation on the last physics frame.
 code_samples: []
 inherits:
   - SensorBase
@@ -12,8 +19,12 @@ tags:
 deprecation_message: ''
 properties:
   - name: FluidForceSensor.CenterOfPressure
-    summary: ''
-    description: ''
+    summary: |
+      Assembly center of pressure offset from its center of mass in world
+      coordinates.
+    description: |
+      Assembly center of pressure offset from its center of mass in world
+      coordinates.
     code_samples: []
     type: Vector3
     tags:
@@ -31,8 +42,10 @@ properties:
     capabilities: []
     writeCapabilities: []
   - name: FluidForceSensor.Force
-    summary: ''
-    description: ''
+    summary: |
+      Assembly fluid force in world coordinates.
+    description: |
+      Assembly fluid force in world coordinates.
     code_samples: []
     type: Vector3
     tags:
@@ -50,8 +63,10 @@ properties:
     capabilities: []
     writeCapabilities: []
   - name: FluidForceSensor.Torque
-    summary: ''
-    description: ''
+    summary: |
+      Assembly fluid torque in world coordinates.
+    description: |
+      Assembly fluid torque in world coordinates.
     code_samples: []
     type: Vector3
     tags:
@@ -70,25 +85,36 @@ properties:
     writeCapabilities: []
 methods:
   - name: FluidForceSensor:EvaluateAsync
-    summary: ''
-    description: ''
+    summary: |
+      Asynchronously computes force, torque, and center of pressure for the
+      parent part of a sensor given provided inputs.
+    description: |
+      Asynchronously computes force, torque, and center of pressure for the
+      parent part of a sensor given provided inputs.
     code_samples: []
     parameters:
       - name: linearVelocity
         type: Vector3
         default:
-        summary: ''
+        summary: |
+          Linear velocity in world coordinates.
       - name: angularVelocity
         type: Vector3
         default:
-        summary: ''
+        summary: |
+          Angular velocity in world coordinates.
       - name: cframe
         type: CFrame
         default:
-        summary: ''
+        summary: |
+          `Datatype.CFrame` to be used for evaluation.
     returns:
       - type: Tuple
-        summary: ''
+        summary: |
+          Tuple of `Class.FluidForceSensor.Force|Force`,
+          `Class.FluidForceSensor.Torque|Torque` and
+          `Class.FluidForceSensor.CenterOfPressure|CenterOfPressure` calculated
+          given the input parameters.
     tags:
       - Yields
     deprecation_message: ''
diff --git a/content/en-us/reference/engine/classes/Instance.yaml b/content/en-us/reference/engine/classes/Instance.yaml
@@ -1727,22 +1727,31 @@ events:
     writeCapabilities: []
   - name: Instance.Destroying
     summary: |
-      Fires immediately before the instance is destroyed via
-      `Class.Instance:Destroy()`.
+      Fires immediately before (or is deferred until after) the instance is destroyed via `Class.Instance:Destroy()`.
     description: |
-      The Destroying event fires immediately before the Instance or one of its
-      ancestors is destroyed with `Instance.Destroy()`.
-
-      The Instance will never be deleted from memory while a connected function
-      is still using it. However, if the function yields at any point, the
-      Instance and its descendants will be parented to `nil`.
-
-      When deleting an instance in Studio, such as manually deleting through the
-      Explorer or through a plugin, the instance isn't destroyed. Instead, the
-      parent is set to `nil` which you can track with
-      `Class.Instance.AncestryChanged`.
+      The `Class.Instance` will
+      never be deleted from memory while a connected function is still using it. However,
+      if the function yields at any point, the `Class.Instance` and its descendants will be
+      parented to `nil`.
+
+      If the `Class.Workspace.SignalBehavior` property is set to `Enum.SignalBehavior.Immediate`,
+      this event fires immediately before the `Class.Instance` or one of its ancestors is destroyed
+      with `Class.Instance:Destroy()`.
+
+      If the `Class.Workspace.SignalBehavior` property is set to `Enum.SignalBehavior.Deferred`, this event
+      fires at the next resumption point, which will be after the `Class.Instance` or one of its ancestors is
+      destroyed with `Class.Instance:Destroy()`.
+      
+      With `Enum.SignalBehavior.Deferred|Deferred` behavior, connecting a script to its own
+      `Class.Instance.Destroying` event is problematic, as the script will be destroyed before the callback
+      can be called (meaning it will not execute).
+      
+      When deleting an `Class.Instance` in Studio, such as manually deleting through the
+      [Explorer](../../../studio/explorer.md) or through a plugin, the `Class.Instance` isn't destroyed. Instead,
+      the parent is set to `nil` which you can track with `Class.Instance.AncestryChanged`.
     code_samples:
-      - Instance-Destroying
+      - Instance-Destroying-Immediate
+      - Instance-Destroying-Deferred
     parameters: []
     tags: []
     deprecation_message: ''
diff --git a/content/en-us/reference/engine/classes/Workspace.yaml b/content/en-us/reference/engine/classes/Workspace.yaml
@@ -760,8 +760,16 @@ properties:
     capabilities: []
     writeCapabilities: []
   - name: Workspace.SignalBehavior
-    summary: ''
-    description: ''
+    summary: |
+      Configures when the engine resumes event handlers.
+    description: |
+      This property determines whether event handlers will be resumed immediately when the event fires,
+      or deferred and then resumed at a later resumption point. Resumption points currently include:
+      - `Class.RunService.RenderStepped`
+      - Waiting script resumption such as `Library.task.wait()`, `Library.task.spawn()`, and `Library.task.delay()`
+      - `Class.RunService.Stepped`
+      - `Class.RunService.Heartbeat`
+      - `Class.DataModel.BindToClose`
     code_samples:
     type: SignalBehavior
     tags:
diff --git a/content/en-us/reference/engine/enums/SignalBehavior.yaml b/content/en-us/reference/engine/enums/SignalBehavior.yaml
@@ -1,28 +1,34 @@
 name: SignalBehavior
 type: enum
-summary: ''
-description: ''
+summary: 'Determines when the engine resumes event handlers.'
+description: |
+ Determines when the engine resumes event handlers. At some future point, the default mode will
+ be `Deferred` but opt-out will still be possible through use of `Immediate`.
 code_samples:
 tags: []
 deprecation_message: ''
 items:
   - name: Default
     value: 0
-    summary: ''
+    summary: |
+      The default behavior; currently equivalent to `Immediate` but this will eventually change to `Deferred`.
     tags: []
     deprecation_message: ''
   - name: Immediate
     value: 1
-    summary: ''
+    summary: |
+      Event handlers are resumed immediately when the event occurs.
     tags: []
     deprecation_message: ''
   - name: Deferred
     value: 2
-    summary: ''
+    summary: |
+      All events are deferred and their handlers resumed at specific resumptions points each frame.
     tags: []
     deprecation_message: ''
   - name: AncestryDeferred
     value: 3
-    summary: ''
+    summary: |
+      Equivalent to `Deferred` but only for events triggered by changes in ancestry.
     tags: []
-    deprecation_message: ''
+    deprecation_message: ''
