update Open Source Docs from Roblox internal teams

Author: rbx-open-source-docs[bot]

content/en-us/assets/optimization/microprofiler/micro-studio-flame.png

@@ -11,7 +11,7 @@ A **developer product** is an item or ability that a user can purchase more than
    For items or abilities that a user should only purchase **once**, such as a special weapon or a permanent power-up, see [Passes](../../production/monetization/game-passes.md).
 </Alert>
 
-## Create developer products
+## Create a developer product
 
 <Alert severity="warning">
    Before creating a developer product, make sure your experience has been [published](../../production/publishing/publish-experiences-and-places.md) and is accessible on Roblox.
@@ -28,10 +28,10 @@ To create a developer product:
 7. Click **Create Developer Product**.
 
 <Alert severity="info">
-   If you want to use the developer product as a randomized reward, review the [randomized virtual item policy](./randomized-virtual-items-policy.md).
+   If you want to use the developer product as a randomized reward, review the [randomized virtual item policy](./virtual-items.md).
 </Alert>
 
-## Get developer product IDs
+## Get the developer product ID
 
 To use scripting, you need a developer product ID. To get the product ID:
 
@@ -41,15 +41,29 @@ To use scripting, you need a developer product ID. To get the product ID:
 
    <img src="../../assets/creator-dashboard/Developer-Product-Copy-Asset-ID.png" width="400" />
 
-## Sell developer products
+## Sell a developer product
 
 <Alert severity="info">
 If you're using [price optimization](./price-optimization.md), make sure to place the script inside a `Class.LocalScript` so that users see personalized product prices.
 </Alert>
 
+Before selling developer products, make sure you are properly processing sales receipts and granting users their purchased products. To do so, you must:
+
+- Use the `Class.MarketplaceService.ProcessReceipt|ProcessReceipt` API to check purchase receipts. `ProcessReceipt` automatically reads and acknowledges that a user has purchased a product outside of the experience.
+- Validate each receipt for `User ID`, `Developer Product ID`, and the receipt status.
+- If the receipt has a status of **Open**, grant the user the developer items they have purchased.
+- Respond to the `ProcessReceipt` API with a message acknowledging the receipt and validating that the purchased items were granted.
+
+You can sell developer products in two ways:
+
+- [Inside your experience](#inside-your-experience)
+- [Outside your experience](#outside-your-experience)
+
+### Inside your experience
+
 To implement and sell a developer product inside an experience, call `Class.MarketplaceService|MarketplaceService` functions.
 
-Use `Class.MarketplaceService:GetProductInfo()|GetProductInfo()` to retrieve information about a developer product, like name and price, and then to display that product to users. You can sell the product inside your experience's marketplace, for example. For developer products, the second parameter must be `Enum.InfoType.Product`.
+Use `Class.MarketplaceService:GetProductInfo()|GetProductInfo` to retrieve information about a developer product, like name and price, and then to display that product to users. You can sell the product inside your experience's marketplace, for example. For developer products, the second parameter must be `Enum.InfoType.Product`.
 
 ```lua
 local MarketplaceService = game:GetService("MarketplaceService")
@@ -70,7 +84,7 @@ if success and productInfo then
 end
 ```
 
-Use `Class.MarketplaceService:GetDeveloperProductsAsync()|GetDeveloperProductsAsync()` to retrieve all developer products associated with your experience. This function returns a `Class.Pages|Pages` object that you can inspect and filter to build things like an in-experience store or product list GUI.
+Use `Class.MarketplaceService:GetDeveloperProductsAsync()|GetDeveloperProductsAsync` to retrieve all developer products associated with your experience. This function returns a `Class.Pages|Pages` object that you can inspect and filter to build things like an in-experience store or product list GUI.
 
 ```lua
 local MarketplaceService = game:GetService("MarketplaceService")
@@ -88,7 +102,7 @@ if success and developerProducts then
 end
 ```
 
-Use `Class.MarketplaceService:PromptProductPurchase()|PromptProductPurchase()` to prompt product purchases inside your experience. You can call this function when a user performs actions like pressing a button or talking to a vendor NPC.
+Use `Class.MarketplaceService:PromptProductPurchase()|PromptProductPurchase` to prompt product purchases inside your experience. You can call this function when a user performs actions like pressing a button or talking to a vendor NPC.
 
 ```lua
 local MarketplaceService = game:GetService("MarketplaceService")
@@ -143,9 +157,57 @@ button.MouseButton1Click:Connect(function()
 end)
 ```
 
-## Handle developer product purchases
+### Outside your experience
+
+To enable developer product purchases outside your experience, you must work with the `Class.MarketplaceService.ProcessReceipt|ProcessReceipt` API. After a user makes a purchase in the Store tab of your experience details page, you must use `ProcessReceipt` to confirm their purchase and grant them their items once they enter your experience.
+
+<Alert severity="warning">
+Do **not** use the `Class.MarketplaceService:PromptProductPurchaseFinished|PromptProductPurchaseFinished` event to process purchases. You must use the `ProcessReceipt` callback instead.
+
+The firing of `PromptProductPurchaseFinished` does not mean that a user has successfully purchased an item.
+</Alert>
+
+#### Test mode
+
+The **test mode** feature helps you validate your purchase flow by simulating a developer product purchase outside your experience. You should use test mode to make sure that you have implemented `ProcessReceipt` correctly before enabling external developer product sales.
+
+The developer products you put up for sale in test mode can only be seen by you and by members of your group. They are not visible to users.
+
+To test your implementation:
+
+1. In the **Creator Hub**, go to **Monetization** > **Developer Products**.
+2. Click the **&vellip;** menu and select **External Purchase Settings**.
+3. In the **External Purchase Settings** page, click **Enable test mode**.
+4. Once test mode is active, return to the **Developer Products** page and select a product to test.
+5. In the **Basic Settings** page, select the **Allow external purchases** checkbox and save your changes.
+6. Go to the **Store** tab of the experience details page and purchase the product you made available for sale.
+7. Enter the experience and confirm that you have received the product you purchased. The receipt status of the `ProcessReceipt` API should update to **Closed**.
+
+After you test your implemention, Roblox verifies that the test has been successfully completed and allows you to fully activate the feature to sell developer products outside your experiences.
+
+For more information about the `ProcessReceipt` API and its implementation, see the `Class.MarketplaceService.ProcessReceipt|ProcessReceipt` page.
+
+#### Enable external sales
+
+<Alert severity="info">
+You can only enable external sales after you have used test mode to validate your purchase flow.
+</Alert>
+
+To enable external sales:
+
+1. Go to the **External Purchase Settings** page.
+2. Turn on **External Purchases**.
+3. Return to the **Developer Products** page and select the products you want to sell outside of your experience.
+4. In the **Basic Settings** page, select the **Allow external purchases** checkbox and save your changes.
+5. Confirm that the products are now available for purchase in the **Store** tab of the experience details page.
+
+To disable the external sale of a developer product, select the product on the **Developer Products** page and clear the **Allow external purchases** checkbox.
+
+## Handle a developer product purchase
+
+After a user purchases a developer product, you must handle and record the transaction. To do this, use a `Class.Script` within `Class.ServerScriptService` using the `ProcessReceipt` function.
 
-After a user purchases a developer product, you must handle and record the transaction. To do this, use a `Class.Script` within `Class.ServerScriptService` using the `Class.MarketplaceService.ProcessReceipt()|ProcessReceipt()` function.
+For more information about the `ProcessReceipt` API and its implementation, see the `Class.MarketplaceService.ProcessReceipt|ProcessReceipt` page.
 
 ```lua
 local MarketplaceService = game:GetService("MarketplaceService")
@@ -218,7 +280,7 @@ The functions for handling each product ID must return `true` for the transactio
 Although Roblox itself does **not** record the purchase history of developer products by specific users, you can request to [download sales data](../../production/analytics/analytics-dashboard.md#sales-data). If you want to track user-specific purchase history, it's your responsibility to [store the data](../../cloud-services/data-stores/index.md).
 </Alert>
 
-## Developer Product analytics
+## Developer product analytics
 
 Use developer product analytics to analyze the success of individual products, identify trends, and forecast potential future earnings.
 

content/en-us/assets/optimization/task-scheduler/scheduler-priority.png

@@ -9,7 +9,7 @@ description: Passes let you charge users a one-time Robux fee to access privileg
    For items that a player might purchase multiple times, such as potions, temporary power-ups, or in-experience currency, see [Developer Products](../../production/monetization/developer-products.md).
 </Alert>
 
-## Create passes
+## Create a pass
 
 <Alert severity="warning">
    Before creating a pass, make sure your experience has been [published](../../production/publishing/publish-experiences-and-places.md) and is accessible on Roblox.
@@ -40,10 +40,10 @@ To create a pass:
 </GridContainer>
 
 <Alert severity="info">
-   If you want to use the pass as a randomized reward, review the [Randomized Virtual Item Policy](./randomized-virtual-items-policy.md).
+   If you want to use the pass as a randomized reward, review the [Randomized Virtual Item Policy](./virtual-items.md).
 </Alert>
 
-## Get pass IDs
+## Get the pass ID
 
 To use scripting, you need a pass ID. To get the pass ID:
 
@@ -53,27 +53,18 @@ To use scripting, you need a pass ID. To get the pass ID:
 
    <img src="../../assets/creator-dashboard/Pass-Copy-Asset-ID.png" width="400" />
 
-## Sell passes
+## Sell a pass
 
 <Alert severity="info">
 If you're using [price optimization](./price-optimization.md), make sure to place the script inside a `Class.LocalScript` so that users see personalized pass prices.
 </Alert>
 
-You can sell passes outside or inside an experience.
+You can sell passes in two ways:
 
-### Outside an experience
+- [Inside your experience](#inside-your-experience)
+- [Outside your experience](#outside-your-experience)
 
-To sell a pass in an experience's **Store** page:
-
-1. Go to **Monetization** &rang; **Passes**.
-2. Hover over the pass and click the **&ctdot;** menu.
-3. Select the pass you want to sell.
-4. Select **Sales**.
-5. Enable to **Item for Sale** toggle.
-6. In the **Price in Robux** field, enter the amount of Robux you want to charge users for the pass. The price you enter affects how much Robux you earn per sale. The price you enter affects how much Robux you earn per sale. The minimum price is 1 Robux, and the maximum price is 1 billion Robux.
-7. Click **Save Changes**. The pass populates in the experience's **Store** page.
-
-### Inside an experience
+### Inside your experience
 
 To implement and sell a pass inside an experience, call `Class.MarketplaceService|MarketplaceService` functions.
 
@@ -162,6 +153,18 @@ MarketplaceService.PromptGamePassPurchaseFinished:Connect(onPromptPurchaseFinish
 Although Roblox itself does **not** record the purchase history of developer products by specific users, you can request to [download sales data](../../production/analytics/analytics-dashboard.md#sales-data). If you want to track user-specific purchase history, it's your responsibility to [store the data](../../cloud-services/data-stores/index.md).
 </Alert>
 
+### Outside your experience
+
+To sell a pass on the **Store** tab of the experience details page:
+
+1. Go to **Monetization** > **Passes**.
+2. Hover over the pass and click the **&ctdot;** menu.
+3. Select the pass you want to sell.
+4. Select **Sales**.
+5. Enable to **Item for Sale** toggle.
+6. In the **Price in Robux** field, enter the amount of Robux you want to charge users for the pass. The price you enter affects how much Robux you earn per sale. The price you enter affects how much Robux you earn per sale. The minimum price is 1 Robux, and the maximum price is 1 billion Robux.
+7. Click **Save Changes**. The pass populates in the **Store** tab of the experience details page.
+
 ## Assign pass privileges
 
 You must manually assign pass privileges to users that purchase your passes. To do this, use `Class.Players.PlayerAdded|PlayerAdded` when a user joins your experience to check if they already own the pass and to assign them the pass privileges.
@@ -212,7 +215,7 @@ With analytics, you can:
 To access pass analytics:
 
 1. Go to [Creations](https://create.roblox.com/dashboard/creations) and select an experience.
-2. Go to **Monetization** &rang; **Passes**.
+2. Go to **Monetization** > **Passes**.
 3. Select the **Analytics** tab.
 
 <img src="../../assets/monetization/game-passes/passes-analytics-2.png" width="100%" />

content/en-us/production/monetization/developer-products.md

@@ -3,7 +3,7 @@ title: MicroProfiler
 description: The MicroProfiler is a Studio and client tool for optimizing your experience.
 ---
 
-The **MicroProfiler** is an optimization tool available in Roblox Studio and the Roblox client that provides detailed timing information for [task scheduler](../../studio/microprofiler/task-scheduler.md) tasks called **tags**.
+The **MicroProfiler** is a performance optimization and troubleshooting tool available in Roblox Studio and the Roblox client. It provides detailed timing information for [task scheduler](../../studio/microprofiler/task-scheduler.md) tasks called **tags**.
 
 - For a list of common tasks, refer to the [tag reference](../../studio/microprofiler/tag-table.md).
 - For a step-by-step example of using the MicroProfiler to identify a performance issue, see the [MicroProfiler walkthrough](../../studio/microprofiler/use-microprofiler.md).
@@ -16,7 +16,7 @@ When open, a menu bar is visible at the top of the 3D viewport. In the default m
 
 <img alt="The Microprofiler frame graph, showing blue frames and detailed frame information." src="../../assets/optimization/microprofiler/micro-frame.png" width="440px" />
 
-Bars should generally be around the middle of the graph, but you might see sudden spikes (rapid increases in value). Spikes indicate that more time was taken to perform some task, usually because of an increased workload. For instance, creating a lot of moving parts requires more work from the physics simulation, which then needs more time to process motion and part contacts. The following image shows an example of a spike:
+Bars should generally be around the middle of the graph, but you might see sudden spikes (rapid increases in values). Spikes indicate that more time was taken to perform some task, usually because of an increased workload. For instance, creating a lot of moving parts requires more work from the physics simulation, which then needs more time to process motion and part contacts. The following image shows an example of a spike:
 
 <img alt="The Microprofiler with several bars higher than others." src="../../assets/optimization/microprofiler/micro-spike.png" width="300px" />
 
@@ -34,7 +34,7 @@ There are three main thread types:
 
 - **Main/Render**: Perhaps unintuitively, runs on the CPU. Processes input, `Class.Humanoid|Humanoids`, animations/tweening, physics ownership, sound, and waiting script resumes. Also updates Studio interfaces and coordinates the other threads.
 
-- **Worker** ("RBX Worker"): Helps the main thread with networking, physics, and pathfinding. Due to the number of cores in modern CPUs, you likely have many worker threads.
+- **Worker** ("RBX Worker"): Helps the main thread with networking, physics, and pathfinding. Due to the number of cores in modern CPUs, you likely have many worker threads, most of which are in a sleep state at any given time.
 
 - **Render** ("GPU"): Follows a "prepare, perform, present" logic. Communicates with the graphics processing unit (GPU) of the device.
 
@@ -48,7 +48,7 @@ If your scripts are running complicated tasks, you can profile critical portions
 
 ```lua title="HardWorkScript"
 debug.profilebegin("Hard Work")
--- Here is where the code to be profiled should be
+-- Code to be profiled
 debug.profileend()
 ```
 
@@ -135,9 +135,13 @@ In general, the MicroProfiler web UI works similarly to [detailed mode](./modes.
   - Lighter portions of the preview bar and lighter labels on the timeline indicate portions of the frame with higher memory allocation.
   - In X-ray mode, press <kbd>C</kbd> to show the total size of the memory allocations rather than the number of allocations.
 
-- Use the **Export** menu to export a CPU or memory flame graph, a specialized visualization that aggregates all of the call stacks included in the dump. The flame graph is especially useful for identifying tasks that don't take particularly long to run (and are therefore hard to notice), but run so often that their processing time becomes significant.
+- Use the **Export** menu to export a CPU or memory flame graph, a specialized visualization that aggregates all of the call stacks included in the dump, maintains the parent-child hierarchy, and sizes them based on duration. Flame graphs are especially useful for identifying tasks that don't take particularly long to run (and are therefore hard to notice), but run so often that their processing time becomes significant.
 
-  <img alt="The MicroProfiler flame graph." src="../../assets/optimization/microprofiler/micro-flame.png" />
+  <img alt="The MicroProfiler flame graph in the web UI." src="../../assets/optimization/microprofiler/micro-flame.png" />
+
+  You can also create flame graphs in Studio, although only for scripts (execution time and memory allocations). Compared to the web-based flame graphs, the ones in Studio are top-down rather than bottom-up and support dramatically longer capture times.
+
+  <img alt="The MicroProfiler flame graph in Studio." src="../../assets/optimization/microprofiler/micro-studio-flame.png" />
 
 - Drag and drop a second dump file into the web UI to generate a diff flame graph, which can help you identify improvements or regressions to your experience's performance over time. Click **Combine & Compare** to export a new HTML file.
 

content/en-us/production/monetization/game-passes.md

@@ -5,6 +5,10 @@ description: A list of tags for the MicroProfiler.
 
 The following is a list of common tags in the MicroProfiler, grouped by category. Understanding these tags can help you identify problematic code in your experience. The tables contain tag label, descriptions and performance advice for improving performance and optimizing your experience.
 
+## Sleep
+
+When threads aren't actively performing tasks, they enter a sleep state, with tags to indicate how long the thread was sleeping. At any given time, it's extremely common for most worker threads to be in a sleep state.
+
 ## AI/navigation
 
 <table>

content/en-us/studio/microprofiler/index.md

@@ -31,8 +31,7 @@ The most direct way to add frame-by-frame game tasks is through the following me
 
 The task scheduler categorizes and completes tasks in the following order. Some tasks may not perform work in a frame, while others may run multiple times.
 
-<img src="../../assets/optimization/task-scheduler/scheduler-priority.png"
-   width="80%" />
+<img src="../../assets/optimization/task-scheduler/scheduler-priority.png" />
 
 ## Best practices