Merge branch 'main' into pathfinding-IsCurrentWaypointReached

Author: metricrb

README.md

@@ -2,7 +2,7 @@
 
 This repository holds source code for the creator documentation at [create.roblox.com/docs](https://create.roblox.com/docs).
 
-**Note**: Currently, the repository has guides, tutorials, educational content, and the Engine API reference. Code samples are coming soon.
+**Note**: Currently, the repository has guides, tutorials, educational content, and a read-only version of the Engine API reference.
 
 If you're unfamiliar with the GitHub contribution process, see [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) and the following video.
 
@@ -77,14 +77,14 @@ The Roblox documentation has three main document types:
 
   Guides benefit massively from practical, real-world use cases, images, code snippets, and diagrams. Most task-based content should include a numbered list.
 
-- API reference docs in `.yaml` files in [content/en-us/reference](./content/en-us/reference)
-
-  APIs are entirely reference content and should use functional descriptions, linking to guides where appropriate. More than other content types, reference content should be terse and direct; summaries for properties, methods, events, and callbacks don't need to be full sentences.
-
 - Tutorials in `.md` files in [content/en-us/tutorials](./content/en-us/tutorials)
 
   Compared to task-based guides, tutorials are more self-contained and take you from _nothing_ to _something_. This focus on creating something specific means they're typically much more prescriptive than guides. Tutorials often touch multiple features and concepts at the same time, demonstrating the connections between tools and strategies.
 
+- API reference docs in `.yaml` files in [content/en-us/reference](./content/en-us/reference)
+
+  We provide these files so that you can view the source and use them in your own projects, but we **no longer** accept pull requests on the reference `.yaml` files.
+
 If your contribution doesn't fit within these categories or covers a particularly narrow subject, it might not be a good fit for the documentation. Consider posting it to the [Roblox developer forum](https://devforum.roblox.com/c/resources/71).
 
 ## Contribution Basics

content/en-us/cloud-services/data-stores/versioning-listing-and-caching.md

@@ -123,7 +123,7 @@ You can specify a prefix when listing all data stores or keys, and get back only
   For new experiences, use [listing and prefixes](#listing-and-prefixes) to organize keys in your data store instead of the legacy scopes feature. For existing experiences that use scopes, continue using them.
 </Alert>
 
-Every key in a data store has a default global scope. You can organize keys further by setting a unique string as a scope for the second parameter of `Class.DataStoreService:GetDataStore()|GetDataStore()`. This automatically attaches the scope to the beginning of all keys in all operations done on the data store.
+You can organize keys in a data store further by setting a unique string as a scope for the second parameter of `Class.DataStoreService:GetDataStore()|GetDataStore()`. The default scope (if no scope is given) is `global`. The scope is automatically prepended to the beginning of all keys in all operations done on the data store.
 
 <table>
 <thead>
@@ -148,7 +148,7 @@ Every key in a data store has a default global scope. You can organize keys furt
 </tbody>
 </table>
 
-The combination of data store name, scope, and key uniquely identifies a key. All three values are required to identify a key with a scope. For example, you can read a global key named `User_1234` as:
+The combination of data store name, scope, and key uniquely identifies a key. All three values are required to identify a key with a scope. For example, you can read a `global`-scoped key named `User_1234` as:
 
 ```lua
 local DataStoreService = game:GetService("DataStoreService")
@@ -158,7 +158,7 @@ local success, currentGold = pcall(function()
 end)
 ```
 
-If the key `User_1234` has a scope of gold, though, you can only read it as:
+If the key `User_1234` has a scope of `gold`, though, you can only read it as:
 
 ```lua
 local DataStoreService = game:GetService("DataStoreService")
@@ -184,7 +184,7 @@ local ds = DataStoreService:GetDataStore("DS1", "", options)
 ```
 
 <Alert severity="info">
-  When you use the `Class.DataStoreOptions.AllScopes|AllScopes` property, `Class.DataStore:ListKeysAsync()|ListKeysAsync()` returns every key with their scope as the prefix argument, such as `global/player_data_1234` or `houses/house3`. The default scope is `global`.
+  When you use the `Class.DataStoreOptions.AllScopes|AllScopes` property, `Class.DataStore:ListKeysAsync()|ListKeysAsync()` returns every key with their scope as the prefix argument, such as `global/player_data_1234` or `houses/house3`. Remember that the default scope is `global`.
 </Alert>
 
 If you enable the `Class.DataStoreOptions.AllScopes|AllScopes` property and create a new key in the data store, you must always specify a scope for that key in the format of scope/keyname. If you don't, the APIs throw an error. For example, `gold/player_34545` is acceptable with gold as the scope, but `player_34545` leads to an error.

content/en-us/effects/particle-emitters.md

@@ -204,7 +204,7 @@ Note that changing `Class.ParticleEmitter.Speed|Speed` does not affect active pa
 
 ### Rate
 
-The `Class.ParticleEmitter.Rate|Rate` property sets the number of particles that emit per second. A single particle emitter can create up to 500 particles per second. For best performance, keep the particle rate as low as possible and experiment with [size](#size) and [other properties](#other-properties) to achieve the desired visual effect.
+The `Class.ParticleEmitter.Rate|Rate` property sets the number of particles that emit per second. A single particle emitter can create up to 400 particles per second (100 per second on mobile). For best performance, keep the particle rate as low as possible and experiment with [size](#size) and [other properties](#other-properties) to achieve the desired visual effect.
 
 <Alert severity="warning">
 Particle count can impact performance due to overdraw, especially when particles are overlapping. The more layers of transparent effects on screen, the more costly it is on the GPU.

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

@@ -79,7 +79,8 @@ methods:
       `Class.DataStoreService:GetDataStore()|GetDataStore()` function.
 
       Note that the `Class.DataStore` returned by this function always uses the
-      scope `u`. See [Data stores](../../../cloud-services/data-stores/index.md)
+      scope `u`. See
+      [Versioning, listing, and caching](../../../cloud-services/data-stores/versioning-listing-and-caching.md#scopes)
       for details on scope.
     code_samples:
       - get-a-globaldatastore-instance

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

@@ -8,22 +8,20 @@ memory_category: Instances
 summary: |
   A GlobalDataStore that also allows for ordered data store entries.
 description: |
-  A **OrderedDataStore** is essentially a `Class.GlobalDataStore` with the
-  exception that stored values must be **positive integers**. It exposes a
-  method `Class.OrderedDataStore:GetSortedAsync()|GetSortedAsync()` which allows
-  inspection of the entries in sorted order using a `Class.DataStorePages`
-  object.
+  An **OrderedDataStore** is essentially a `Class.GlobalDataStore` with stored values that are **integers**. 
+  It exposes the `Class.OrderedDataStore:GetSortedAsync()|GetSortedAsync()` method, which allows for the 
+  inspection of entries in sorted order using a `Class.DataStorePages` object.
 
   Ordered data stores do not support versioning and metadata, so
   `Class.DataStoreKeyInfo` is always `nil` for keys in an
   `Class.OrderedDataStore`. If you need versioning and metadata support, use a
   `Class.DataStore`.
 
-  Ordered data stores do not support the optional `userIds` parameter for
+  Ordered data stores also do not support the optional `userIds` parameter for
   `Class.OrderedDataStore:SetAsync()|SetAsync()` or
   `Class.OrderedDataStore:IncrementAsync()|IncrementAsync()`.
 
-  See [Data Stores](../../../cloud-services/data-stores/index.md) for an
+  See [Data stores](../../../cloud-services/data-stores/index.md) for an
   overview on using ordered data stores.
 code_samples:
   - OrderedDataStore-Basics
@@ -44,7 +42,7 @@ methods:
       **minValue**/**maxValue** are optional parameters which filter the
       results.
 
-      See [Data Stores](../../../cloud-services/data-stores/index.md) for
+      See [Error codes and limits](../../../cloud-services/data-stores/error-codes-and-limits.md) for
       request limits and descriptions of the error codes.
     code_samples: []
     parameters:

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

@@ -36,7 +36,7 @@ properties:
       `Class.PackageLink` will be automatically updated to the latest version.
       By default this property will be false upon creation of a package.
 
-      This property would allows you to decide if a given package should be
+      This property would allow you to decide if a given package should be
       automatically updated to the latest version when entering a given place.
       The game will periodically check for new updates while a place is open.
     code_samples: []

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

@@ -631,8 +631,8 @@ methods:
     summary: |
       Returns information about the character appearance of a given user.
     description: |
-      This function returns information about a player's avatar (ignoring gear)
-      on the Roblox website in the form of a dictionary. It is not to be
+      This function returns information about a player's avatar on
+      the Roblox website in the form of a dictionary. It is not to be
       confused with
       `Class.Players:GetCharacterAppearanceAsync()|GetCharacterAppearanceAsync`,
       which actually loads the assets described by this method. You can use