hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-24 06:34:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update rules

Browse source
This commit is contained in:
Joe 2026-02-02 14:05:11 -06:00
parent 4c390fdd37
commit d5522b2fef
8549 changed files with 11783 additions and 1888 deletions
Download patch file Download diff file Expand all files Collapse all files

96
.cursor/rules/roblox/en-us/matchmaking/analytics.md Normal file
View file

@ -0,0 +1,96 @@
---
title: Matchmaking analytics
description: Use matchmaking analytics to analyze your matchmaking configurations.
---
Use the matchmaking analytics dashboard metrics to analyze the impact of individual matchmaking configurations and monitor signal performance over different periods of time.
## Access the dashboard
To access the matchmaking analytics dashboard:
1. In the **Creator Dashboard**, navigate to **Creations**, then select an experience.
2. In the lefthand navigation, navigate to the **Configure** section, then select **Custom Matchmaking**.
3. In the horizontal navigation, select the **Analytics** tab.
## See metrics for a specific place
The analytics dashboard includes charts for Roblox signals and custom signals. If a matchmaking configuration has one numerical custom signal and one categorical custom signal, data is populated in both the numerical and categorical signal charts. If a configuration has two of the same type of custom signal (as in, two numerical or two categorical), only one of the charts is populated with two lines representing data for both. Categorical charts represent a similarity ratio, while numerical charts represent the difference.
To see matchmaking metrics for a specific place in your experience:
1. In the **Analytics** tab, click the **Date Range** dropdown and select a date range between the previous day and the last 90 days.
2. Click the **Place** dropdown and select the place you want to see metrics for. The **Current Configuration** updates with the name of the matchmaking configuration applied to the place you selected.
<img src="../assets/matchmaking/MatchmakingAnalytics.png" width="80%" alt="Matchmaking analytics charts for several different ratios." />
If the selected place doesn't have a custom matchmaking configuration applied to it, the dashboard shows metrics for the default Roblox matchmaking configuration.
## Filter by percentile values
In the **Analytics** tab, select the **Filter By** menu to swap signal charts between averages and the following percentile values:
- **P90** to filter by the number of values that fall within the 90th percentile.
- **P10** to filter by the number of values that fall within the 10th percentile.
- **P50** to filter by the median, with half of all values falling above it and half below it.
The filter applies to all signal charts.
<Alert severity="info">
Percentile values are calculated smallest to largest, so for metrics where lower numbers are better, P10 represents the "best case" and P90 the "worst case" rather than the other way around.
</Alert>
## Signal charts
The **Analytics** tab includes the following signal charts:
<table>
<thead>
<tr>
<th>**Chart**</th>
<th>**Description**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Occupancy Ratio**</td>
<td>The average/P10/P50/P90 occupancy ratio of the chosen server.</td>
</tr>
<tr>
<td>**Average for Preferred Player Match Ratio**</td>
<td>The average percentage of matchmaking requests that match the joining player to a server with preferred players.</td>
</tr>
<tr>
<td>**Age Difference**</td>
<td>The average/P10/P50/P90 value of the age difference between the joining player and the mean age of all players in the chosen server.</td>
</tr>
<tr>
<td>**Common Language Ratio**</td>
<td>The average/P10/P50/P90 common language ratio of the chosen server. The common language is the language shared between existing players in the server and the joining player.</td>
</tr>
<tr>
<td>**Estimate Ping**</td>
<td>The average/P10/P50/P90 estimate ping value of the chosen server.</td>
</tr>
<tr>
<td>**Voice Chat Ratio**</td>
<td>The average/P10/P50/P90 occupancy ratio of players with voice chat enabled in the chosen server.</td>
</tr>
<tr>
<td>**Common Device Ratio**</td>
<td>The average/P10/P50/P90 common device ratio of the chosen server. The common device is the device type shared between existing players in the server and the joining player.</td>
</tr>
<tr>
<td>**Play History Difference**</td>
<td>The average/P10/P50/P90 value of the play history difference between the joining player and the mean play history of all players in the chosen server.</td>
</tr>
<tr>
<td>**Numerical Custom Signal Difference**</td>
<td>The average/P10/P50/P90 value of the numerical signal difference between the joining player and the server average.</td>
</tr>
<tr>
<td>**Categorical Custom Signal Similarity Ratio**</td>
<td>The average/P10/P50/P90 categorical signal similarity ratio between the joining player and the server average.</td>
</tr>
</tbody>
</table>

426
.cursor/rules/roblox/en-us/matchmaking/attributes-and-signals.md Normal file
View file

@ -0,0 +1,426 @@
---
title: Attributes and signals
description: Attributes and signals define the player and server data used in matchmaking, including both Roblox-provided signals and custom signals you can create.
---
## Existing attributes
The default Roblox matchmaking configuration uses signals based on existing attributes like player location, age group, and latency.
To use data for matchmaking that Roblox doesn't automatically include in its default configuration, you need to create [custom attributes](#custom-attributes) and [custom signals](#custom-signals).
<table>
<thead>
<tr>
<th>**Attribute**</th>
<th>**Type**</th>
<th>**Description**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Estimated Player Latency**</td>
<td>Numerical</td>
<td>The estimated latency of a player in a server.</td>
</tr>
<tr>
<td>**Has Friends**</td>
<td>Categorical</td>
<td>Whether a server has a connection or another player of the same IP address as the joining player.</td>
</tr>
<tr>
<td>**Is Voice Chat Enabled**</td>
<td>Categorical</td>
<td>Whether a player has voice chat enabled.</td>
</tr>
<tr>
<td>**Player Age**</td>
<td>Numerical</td>
<td>The player’s age.</td>
</tr>
<tr>
<td>**Player Device Type**</td>
<td>Categorical</td>
<td>The player’s device type. Can be a mobile device, a computer, a tablet, a console, or a VR device.</td>
</tr>
<tr>
<td>**Player Language**</td>
<td>Categorical</td>
<td>The player’s language.</td>
</tr>
<tr>
<td>**Player Play History**</td>
<td>Numerical</td>
<td>The log-10 number of minutes a player has played in a universe in the past 28 days.</td>
</tr>
<tr>
<td>**Server Occupancy**</td>
<td>Numerical</td>
<td>The number of players in a server.</td>
</tr>
<tr>
<td>**Player Text Chat Group**</td>
<td>Categorical</td>
<td>The player's text chat group where they can text chat together.</td>
</tr>
</tbody>
</table>
## Existing signals
The following are Roblox-defined signals derived based on Roblox attributes:
<table>
<thead>
<tr>
<th>**Signal**</th>
<th>**Description**</th>
</tr>
</thead>
<tbody>
<tr>
<td>[**Age**](#age)</td>
<td>The difference between the average age of players in the server and the joining player’s age, with a maximum relevant difference of 25.</td>
</tr>
<tr>
<td>[**Device Type**](#device-type)</td>
<td>The ratio of players in the server with the same device type as the joining player.</td>
</tr>
<tr>
<td>[**Friends**](#friends)</td>
<td>The number of people in the server who are connections with the joining player or who share an IP address with the joining player. 1 if there is a preferred player, 0 otherwise.</td>
</tr>
<tr>
<td>[**Latency**](#latency)</td>
<td>The estimated player latency for a server, with a max relevant value of 250.</td>
</tr>
<tr>
<td>[**Language**](#language)</td>
<td>The ratio of players in the server with the same language as the joining player</td>
</tr>
<tr>
<td>[**Occupancy**](#occupancy)</td>
<td>The ratio of players in the server compared to the capacity of the server.</td>
</tr>
<tr>
<td>[**Play History**](#play-history)</td>
<td>The difference between the average play history in the server and the joining player’s play history, with a maximum relevant difference of 4.6.</td>
</tr>
<tr>
<td>[**Voice Chat**](#voice-chat)</td>
<td>The ratio of players in the server with voice chat enabled.</td>
</tr>
<tr>
<td>[**Text Chat**](#text-chat)</td>
<td>The ratio of players in the server who can text chat with the joining player together.</td>
</tr>
</tbody>
</table>
### Age
A numerical signal that compares the average ages of players on a server to the joining player's age. This signal has a max relevant difference of 25. The signal score is inversely related to the age difference, meaning lower age differences have higher scores.
$\text{ageDifferenceSignalScore} = 1 - \min(25, \text{ageDifference}) / 25$
where
$\text{ageDifference} = |\text{avgServerAge} - \text{joiningPlayerAge}|$
### Device Type
A categorical signal that measures the ratio of players on the server with the same device type as the joining player. Device types include: Computer, mobile device, tablet, console, and VR device.
$\text{deviceTypeSignalScore} = \text{\# players with same device as joining player} / \text{\# players on the server}$
### Friends
A preferred player is a player who is either connections with the joining player or who shares the same IP address as the joining player. The Friends signal is a categorical signal with a score of 1 when there is a preferred player in the server and a score of 0 when there are no preferred players on the server.
$\text{friendsSignalScore} = \text{hasFriends} \ {?} \ 1 : 0$
The Friends signal can also be considered a numerical signal with a maximum relevant value of 1.
$\text{friendsSignalScore} = \min(\text{\# preferred players in server}, 1) / 1$
### Language
A categorical signal that measures the ratio of players on the server who share the same language setting as the joining player.
$\text{languageSignalScore} = \text{\# players with same language setting as joining player} / \text{\# players on the server}$
### Latency
A numerical signal that measures the estimated ping time in milliseconds of the joining player if they were to play on a server. This signal has a max relevant value of 250 milliseconds. The signal score is inversely related to the ping, meaning lower ping values have higher scores.
$\text{latencySignalScore} = 1 - \min(250, \text{estimatedPingMs}) / 250$
### Occupancy
A numerical signal that measures the ratio of players on the server to the capacity of the server.
$\text{occupancySignalScore} = \text{\# players in server} / \text{serverCapacity}$
### Play History
The Play History attribute value is the log-10 number of minutes a player has played in a universe in the past 28 days. This numerical signal compares the average log-10 Play History value of players in the server to the joining player's Play History value. This signal has a max relevant difference of 4.6. The signal score is inversely related to the play history difference, meaning lower play history differences have higher scores.
$\text{playHistorySignalScore} = 1 - \min(4.6, \text{playHistoryDifference} / 4.6)$, where
$\text{playHistoryDifference} = |\text{avgServerPlayHistory} - \text{joiningPlayerPlayHistory}|$
### Voice Chat
A player can have voice chat enabled or disabled. The Voice Chat signal is a categorical signal that measures the ratio of players with the same voice chat setting as the joining player to the number of players in the server.
If a place has voice chat disabled, the Voice Chat signal's weight is 0.
$\text{voiceChatSignalScore} = \text{\# players with same voice chat setting as joining player} / \text{\# players on the server}$
### Text Chat
A categorical signal that measures the ratio of players on the server who can text chat with the joining player together in common.
$\text{textChatSignalScore} = \text{\# players can text with the joining player in common } / \text{\# players on the server}$
## Custom attributes
Custom attributes give custom signals access to player and server data. For more information about creating your own custom attributes, see [Create a custom attribute](./customize-matchmaking.md#create-a-custom-attribute). For more information about existing Roblox attributes, see [Existing attributes](#existing-attributes).
<table>
<thead>
<tr>
<th>**Attribute**</th>
<th>**Characteristics**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Player**</td>
<td>Persistent <br /><br /> Custom player data that persists in data stores, like a player's level or score inside the experience <br /><br /> Managed using the `Class.DataStore|DataStore` APIs</td>
</tr>
<tr>
<td>**Server**</td>
<td>Not persistent and only last as long as the server is active <br /><br /> Server-specific data like the server level or game mode <br /><br /> Managed using the `Class.MatchmakingService|MatchmakingService` API</td>
</tr>
</tbody>
</table>
```lua title="Player attribute example"
local DataStoreService = game:GetService("DataStoreService")
local eloStore = DataStoreService:GetDataStore("PlayerElo")
function onMatchEnded(players: {Player}, winners: {Player}, losers: {Player})
for _, player in players do
local updatedElo = CalculateUpdatedElo(player, winners, losers)
local success, errorMessage = pcall(function()
eloStore:SetAsync(player.UserId, updatedElo)
end)
end
end
```
```lua title="Server attribute example"
local MatchmakingService = game:GetService("MatchmakingService")
local RunService = game:GetService("RunService")
if RunService:IsStudio() then
-- Sets up initial attributes and schema for testing
MatchmakingService:InitializeServerAttributesForStudio({
Level = "Advanced",
Elo = 123.456,
TrainingMode = true
})
end
-- Retrieves the Level attribute
local currentLevel, errorMessage = MatchmakingService:GetServerAttribute("Level")
if errorMessage then
warn(errorMessage)
else
print("Current level: " .. currentLevel)
end
-- Updates the Level attribute value to Advanced
local success, errorMessage = MatchmakingService:SetServerAttribute("Level", "Advanced")
if not success then
warn("Failed to update server attribute [Level] to [Advanced] due to error: " .. errorMessage)
else
print("Successfully set [Level] to [Advanced]")
end
```
## Custom signals
Custom signals are created and defined by you and can be numerical or categorical:
- Numerical signals are numbers. They compare the difference between the joining player's attribute and the server's aggregated value, with larger differences lowering or increasing the score. For example, the closer the skill level of a player is to the average skill level of the server, the higher the numerical signal's score is. This score is then multiplied by the signal's weight.
- Categorical signals are strings or booleans. They're based on how common the joining player's attribute is when compared to the other players in the server. For example, if a high percentage of the players inside a server have the same preferred language as the joining player, the score increases. This score is then also multiplied by the signal's weight.
For more information about creating your own custom signals, see [Create a custom signal](./customize-matchmaking.md#create-a-custom-signal). For more information about existing Roblox signals, see [Existing signals](#existing-signals).
### Player numerical
<h5>Joining player</h5>
Minimizes the difference between the server's average player attribute and the joining player's attribute. Differences beyond 1000 return a signal score of 0.
```lua title="Joining player formula for player numerical signal"
local diff = math.abs(server_{aggregation_function}_{attribute_name} - joining_player_{attribute_name})
local score = 1 - math.min(diff / max_relevant_difference, 1)
return score
```
```lua title="Joining player example for player numerical signal"
local server_average_Elo = 2000
local joining_player_Elo = 1000
local max_relevant_difference = 1500
local diff = math.abs(server_average_Elo - joining_player_Elo)
local score = 1 - math.min(diff / max_relevant_difference, 1)
return score
```
<h5>Constant value</h5>
Minimizes the difference between the server's average player attribute and a constant value of 500. Differences beyond 1000 return a signal score of 0.
```lua title="Constant value formula for player numerical signal"
local diff = math.abs(server_sum_{attribute_name} + joining_player_{attribute_name} - constant_value)
local score = 1 - math.min(diff / max_relevant_difference, 1)
return score
```
```lua title="Constant value example for player numerical signal"
local server_sum_PowerLevel = 4500
local joining_player_PowerLevel = 9901
local max_relevant_difference = 1500
local constant_value = 5000
local diff = math.abs(server_sum_PowerLevel + joining_player_PowerLevel - constant_value)
local score = 1 - math.min(diff / max_relevant_difference, 1)
```
### Player categorical
<h5>Clustering</h5>
Maximizes the ratio of players in the server who have the same attribute as the joining player's attribute.
```lua title="Clustering formula for player categorical signal"
local score = num_players_same_{attribute_name} / occupancy
return score
```
```lua title="Clustering example for player categorical signal"
local num_players_same_Guild = 15
local occupancy = 19
local score = num_players_same_Guild / occupancy
return score
```
<h5>Diversifying</h5>
Maximizes the ratio of players in the server who have a different attribute than the joining player's attribute.
```lua title="Diversifying formula for player categorical signal"
local score = num_players_same_{attribute_name} / occupancy
return 1 - score
```
```lua title="Diversifying example for player categorical signal"
local num_players_same_RpgClass = 15
local occupancy = 19
local score = num_players_same_RpgClass / occupancy
return score
```
### Server numerical
<h5>Joining player</h5>
Minimizes the difference between the server's attribute and the joining player's attribute. Differences beyond 1000 return a signal score of 0.
```lua title="Joining player formula for server numerical signal"
local diff = math.abs(server_{attribute_name} - joining_player_{attribute_name})
local score = 1 - math.min(diff / max_relevant_difference, 1)
return score
```
```lua title="Joining player example for player numerical signal"
local server_Level = 4500
local joining_player_Level = 9000
local max_relevant_difference = 1500
local diff = math.abs(server_Level - joining_player_Level)
local score = 1 - math.min(diff / max_relevant_difference, 1)
```
<h5>Constant value</h5>
Minimizes the difference between the server's attribute value and a constant value. Differences beyond this constant value return a signal score of 0.
```lua title="Constant value formula for server numerical signal"
local diff = math.abs(server_{attribute_name} - constant_value)
local score = math.min(diff / max_relevant_difference, 1)
return score
```
```lua title="Constant value example for server numerical signal"
local server_GameTime = 500
local max_relevant_difference = 1000
local constant_value = 1000
local diff = math.abs(server_GameTime - constant_value)
local score = math.min(diff / max_relevant_difference, 1)
```
### Server categorical
<h5>Compare to joining player</h5>
The score is 1 when the server's attribute value (for example, Game Mode) is equal to the player's attribute value (for example, Preferred Game Mode). Otherwise, the signal score is 0.
```lua title="Joining player formula for server categorical signal"
if server_{attribute_name} == joining_player_{attribute_name} then
return 1
else
return 0
end
```
```lua title="Joining player example for server categorical signal"
local server_GameMode = "Survival"
local joining_player_GameMode = "Survival"
if server_GameMode == joining_player_GameMode then
return 1
else
return 0
end
```
<h5>Compare to constant value</h5>
The score is 1 when the server's attribute value is equal to a constant value of true. Otherwise, the signal score is 0.
```lua title="Constant value formula for server categorical signal"
if server_{attribute_name} == constant_value then
return 1
else
return 0
end
```
```lua title="Constant value example for server categorical signal"
local server_GameNotStarted = true
if server_GameNotStarted == true then
return 1
else
return 0
end
```

159
.cursor/rules/roblox/en-us/matchmaking/customize-matchmaking.md Normal file
View file

@ -0,0 +1,159 @@
---
title: Customize your matchmaking configuration
description: Use custom matchmaking to match players based on attributes like their skill level, their age and language, and their gameplay preferences.
---
With a custom matchmaking configuration, you can build competitive, cooperative, and unique experiences by matching players to servers based on characteristics like skill level, latency, and gameplay preferences.
By default, Roblox provides you with a matchmaking configuration that uses predefined Roblox signals. To customize matchmaking, you can create new matchmaking configurations by [adjusting the weights of existing Roblox signals](#custom-configuration-with-roblox-signals), [creating new custom signals](#custom-configuration-with-custom-signals), or both. You can then preview your configuration by [previewing server scores with mock servers](#preview-and-test-server-scores).
## Custom configuration with Roblox signals
You can adjust the weights of existing Roblox signals to customize your experience's matchmaking. For more information about Roblox signals and how their formulas are calculated, see [Existing signals](./attributes-and-signals.md#existing-signals).
To create a custom matchmaking configuration using only Roblox signals:
1. In the **Creator Dashboard**, navigate to **Creations**, then select an experience.
2. In the lefthand navigation, navigate to the **Configure** section, then select **Custom Matchmaking**.
3. Select the **Configuration** tab and click **Create Configuration**.
4. In the **Create a Custom Matchmaking Configuration** page, enter a name for your configuration.
5. Change the weights of the Roblox signals you want to update.
6. Click **Save Configuration**.
7. Select the places you want to apply this configuration to.
8. Click **Save Configuration** again.
The new matchmaking configuration shows up in the **Configurations** list of the **Configuration** tab.
<img src="../assets/matchmaking/CustomConfiguration_List.png" alt="The Configurations list of the Configuration tab."/>
## Custom configuration with custom signals
To create a custom matchmaking configuration using custom signals:
1. In the **Creator Dashboard**, navigate to **Creations**, then select an experience.
2. In the lefthand navigation, navigate to the **Configure** section, then select **Custom Matchmaking**.
3. Select the **Configuration** tab and click **Create Configuration**.
4. In the **Create a Custom Matchmaking Configuration** page, enter a name for your configuration.
5. Click **Add Custom Signal** and [create a custom signal](#create-a-custom-signal).
6. Change the weights of the signals you want to update.
7. Click **Save Configuration**.
8. Select the places you want to apply this configuration to.
9. Click **Save Configuration** again.
The new matchmaking configuration shows up in the **Configurations** list of the **Configuration** tab.
### Create a custom signal
<Alert severity="info">
You can create a total of 2 custom signals per experience.
</Alert>
<Alert severity="info">
Custom signals use custom attributes to access player and server data. In order to create a custom signal, you must first create a [custom attribute](#create-a-custom-attribute).
</Alert>
Custom signals can be player numerical, server numerical, player categorical, or server categorical. For more information about custom signals and how their formulas are calculated, see [Custom signals](./attributes-and-signals.md#custom-signals).
To create a custom signal:
1. In the **Create a Custom Matchmaking Configuration** page, click **Add Custom Signal**.
2. Under **Signal Details**, enter a signal name and description.
3. Under **Signal Configuration**:
- For a **player numerical attribute**:
1. Choose the [attribute](#create-a-custom-attribute) you want to reference.
2. Select how you want to aggregate the attribute in each server.
- **Average**: The average of all players' attribute values in the server. Minimizes the difference between the server's average player attribute and the joining player's attribute.
- **Median**: The median of all players' attribute values in the server. Minimizes the difference between the server's median player attribute and the joining player's attribute.
- **Sum**: The sum of all players' attribute values in the server, including the joining player's. Minimizes the difference between the total attribute value of the players in the server, including the joining player, and a constant value.
3. Adjust the values under the aggregation.
- For a **server numerical attribute**:
1. Choose the [attribute](#create-a-custom-attribute) you want to reference.
2. Adjust the values under the attribute.
- For a **player categorical attribute**:
1. Choose the [attribute](#create-a-custom-attribute) you want to reference.
2. Select how you want to distribute the attribute value across servers:
- **Cluster**: Groups players with the same attribute value. Maximizes the ratio of players in the server who have the same attribute value as the joining player.
- **Diversify**: Groups players with different attribute values. Maximizes the ratio of players in the server who have a different attribute value from the joining player.
- For a **server categorical attribute**:
1. Choose the [attribute](#create-a-custom-attribute) you want to reference.
2. Adjust the values under the attribute.
4. **(Optional)** Expand **Preview and Test Signal** to preview the signal score. You can adjust the **Test Signal** values to optimize the preview result.
<img src="../assets/matchmaking/Preview_Custom_Signal.png" width="600" alt="A preview of the signal score in Preview and Test Signal." />
5. Click **Create Signal**.
The new custom signal shows up in the **Configuration** list of the **Create a Custom Matchmaking Configuration** page.
### Create a custom attribute
<Alert severity="info">
You can create a total of 5 server attributes and 5 player attributes per experience.
</Alert>
Attributes are properties associated with players and servers, like skill level and game mode preferences. If you want to create and use custom signals, you must first create custom attributes. You can create player or server attributes.
For more information about the difference between player and server attributes, see [Custom attributes](./attributes-and-signals.md#custom-attributes).
<h5 style={{marginTop: '48px'}}>Player attributes</h5>
To create a player attribute:
1. In the **Custom Matchmaking** page, select the **Attributes** tab and click **Create Attribute**.
2. In the **Create Attribute** page, select **Player Attribute** and enter a unique name for it.
3. Choose a **Data Type** and a **Default Value** for the attribute.
4. Under **Data Store Settings**, select the data store that the attribute data lives in.
5. Enter a **Data Store Key Template** to store the player attribute values. At runtime, the `{UserId}` is replaced by the player's actual user ID.
6. Enter a **Data Store Value Path** so that matchmaking can locate the player attribute value inside a JSON object in the data store you selected.
7. Enter a **Data Store Scope** to specify the scope. If you don't enter a scope, it defaults to global.
8. Click **Save Changes** to save your player attribute.
<img src="../assets/matchmaking/Player_Attribute.png" width="700" alt="The attribute characteristics and data store settings for the creation of a player attribute." />
The new attribute shows up in the **Player Attributes** list of the **Attributes** tab.
<h5 style={{marginTop: '48px'}}>Server attributes</h5>
To create a server attribute:
1. In the **Custom Matchmaking** page, select the **Attributes** tab and click **Create Attribute**.
2. In the **Create Attribute** page, select **Server Attribute** and enter a unique name for it.
3. Choose a **Data Type** and a **Default Value** for the attribute.
4. Click **Save Changes** to save your server attribute.
<img src="../assets/matchmaking/Server_Attribute.png" width="600" alt="The attribute characteristics for the creation of a server attribute." />
The new attribute shows up in the **Server Attributes** list of the **Attributes** tab.
## Preview and test server scores
<Alert severity="warning">
Preview server scores are just examples and don't reflect actual experience servers.
</Alert>
Preview and test server scoring to see how your configured signal weights impact server selection. You can experiment with different weight combinations to optimize your matchmaking configuration.
When you create a preview, the preview mocks server scores and identifies which mock server has the highest total score and is the best match for the player.
To preview and test, click **Preview and Test** in the **Create a Custom Matchmaking Configuration** page. The preview shows you three mock servers with different scores and highlights the winning server. To see details about the formulas used for scoring, hover over each signal score result for each mock server.
<img src="../assets/matchmaking/Matchmaking_Simulation.png" />
For more information about scoring and weights, see [Scoring](./scoring.md).
## Apply a configuration to places
You can apply a matchmaking configuration to as many places as you want inside your experience.
To apply a configuration to places:
1. In the **Custom Matchmaking** page, click **Add to Place**.
2. Select a configuration and the place or places you want to apply it to.
3. Click **Save Configuration**.
The places you selected show up in the **Applied Places** list of the **Configuration** tab. You can also add a configuration to places during the creation of that matchmaking configuration.

115
.cursor/rules/roblox/en-us/matchmaking/glossary.md Normal file
View file

@ -0,0 +1,115 @@
---
title: Matchmaking glossary
description: Glossary of matchmaking terms.
---
<table>
<thead>
<tr>
<th>**General terms**</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>**Joining player**</td>
<td>The player being matched to a server in your experience.</td>
</tr>
<tr>
<td>**Common device**</td>
<td>The device type shared between existing players in the server and the joining player. Can be a mobile device, a desktop, a laptop, a tablet, or a console.</td>
</tr>
<tr>
<td>**Common language**</td>
<td>The language shared between existing players in the server and the joining player.</td>
</tr>
</tbody>
<thead>
<tr>
<th>**Scoring**</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>**Server**</td>
<td>An RCC instance hosting a place.</td>
</tr>
<tr>
<td>**Signal weight**</td>
<td>A non-negative number that describes the importance of a signal relative to other signals.</td>
</tr>
<tr>
<td>**Weighted sum**</td>
<td>The sum of all weighted signal scores for a server. The basis for picking the best server for a player.</td>
</tr>
<tr>
<td>**Server score**</td>
<td>The final matchmaking score for a server, based on the weighted sum of its signals. Players are matched to the server with the highest score.</td>
</tr>
<tr>
<td>**Weighted signal score**</td>
<td>The value after multiplying the signal score by its weight.</td>
</tr>
</tbody>
<thead>
<tr>
<th>**Signals**</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>**Signal**</td>
<td>The processed version of an attribute. A signal is created when an attribute is transformed to fit the matchmaking scoring system.</td>
</tr>
<tr>
<td>**Signal score**</td>
<td>The value of a signal after transformations, ranging between 0 and 1.</td>
</tr>
<tr>
<td>**Weight**</td>
<td>Describes the importance of a signal in the scoring process. Signals with higher weights have a bigger impact in matchmaking.</td>
</tr>
<tr>
<td>**Weighted signal score**</td>
<td>The result of multiplying a signal's score by its weight. Reflects both the value and importance of the signal.</td>
</tr>
<tr>
<td>**Numerical custom signal**</td>
<td>The difference between the joining player's attribute and the server's average.</td>
</tr>
<tr>
<td>**Categorical custom signal**</td>
<td>How common the joining player's attribute is when compared to the other players in the server.</td>
</tr>
</tbody>
<thead>
<tr>
<th>**Attributes**</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td>**Attribute**</td>
<td>A property used in matchmaking scoring. Represents “raw signal values” before they're processed.<br/><br/>
Can be a number or a string.</td>
</tr>
<tr>
<td>**Custom attribute**</td>
<td>A universe-level property defined by creators. Can be a **player attribute** or a **server attribute**.</td>
</tr>
<tr>
<td>**Player attribute**</td>
<td>A characteristic of a player, like their preferred game mode or skill level.</td>
</tr>
<tr>
<td>**Server attribute**</td>
<td>A characteristic of a server, like the server's response time or active game mode.</td>
</tr>
</tbody>
</table>

65
.cursor/rules/roblox/en-us/matchmaking/index.md Normal file
View file

@ -0,0 +1,65 @@
---
title: Matchmaking
description: Match players to servers inside your experience.
---
Matchmaking is the process of matching players to servers based on player characteristics like age, language, skill level, and other gameplay preferences.
<iframe width="800" height="450" src="https://www.youtube-nocookie.com/embed/fUMlnldI53A" title="YouTube video player" frameborder="0" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
## How matchmaking works
When a player tries to join your experience, the matchmaking service finds all eligible servers that the player can join, scores these servers using signals, and matches the player to the server with the highest score.
The matchmaking flow works like this:
1. A player requests to join a place.
2. Matchmaking finds eligible servers that the player can join, filtering out servers that are full, private, reserved, or about to be shut down.
3. Matchmaking scores all eligible servers to determine the most compatible server for the player.
4. Matchmaking matches the player to the server with the highest score.
5. The player joins the winning server.
<figcaption>Roblox default matchmaking</figcaption>
<img src="../assets/matchmaking/Default_Matchmaking.png" alt="The default Roblox matchmaking flow." />
<figcaption>Custom matchmaking</figcaption>
<img src="../assets/matchmaking/Custom_Matchmaking.png" alt="The custom matchmaking flow." />
## Scoring
The matchmaking scoring algorithm uses the weighted sum (WS) of signal values to assign scores to servers.
For more information on scoring, see [Server scoring](./scoring.md).
## Attributes
Attributes are properties used in matchmaking scoring. An attribute can be a number, like a player's age and skill level rating, or a string, like a player's language.
Attributes can be numerical or categorical:
- **Numerical attributes** compare the difference between the joining player's attribute and the server's aggregated value, with larger differences lowering or increasing the score. For example, the closer the skill level of a player is to the average skill level of the server, the higher the numerical signal's score is. This score is then multiplied by the signal's weight.
- **Categorical attributes** are based on how common the joining player's attribute is when compared to the other players in the server. For example, if a high percentage of the players inside a server have the same preferred language as the joining player, the score increases. This score is then also multiplied by the signal's weight.
For a list of all existing attributes, see [Existing attributes](./attributes-and-signals.md#existing-attributes). For more information about custom attributes, see [Custom attributes](./attributes-and-signals.md#custom-attributes).
## Signals
Signals used in server scoring can either be the default ones already provided by Roblox, or custom ones you create yourself.
Roblox signals use existing attributes that Roblox already has access to, like player location, age group, and latency. Custom signals, however, need to use custom attributes to access data from your data stores. In order to create a custom signal, you must first create a custom attribute.
For a list of all existing Roblox signals, see [Existing signals](./attributes-and-signals.md#existing-signals). For more information about custom signals, see [Custom signals](./attributes-and-signals.md#custom-signals).
## Custom matchmaking
When a player joins your experience, matchmaking assigns a score to each running server based on the weighted sum of the server's signal values. You can customize this process by adjusting the weight of each of your signals to change how much each signal matters in the scoring of servers. Increasing the weight of the latency signal, for example, means the matchmaking algorithm prioritizes servers with lower ping for smoother gameplay.
After adjusting signal weights, you can preview the impact of these new weights on matchmaking server selection by evaluating them on mock servers.
For more information about how to customize matchmaking and simulate the results, see [Customize your matchmaking configuration](./customize-matchmaking.md).
## Analytics
Matchmaking analytics helps you track the success of your matchmaking configurations and find opportunities to optimize them.
For more information about matchmaking analytics, see [Analytics](./analytics.md).

380
.cursor/rules/roblox/en-us/matchmaking/scoring.md Normal file
View file

@ -0,0 +1,380 @@
---
title: Server scoring
description: How matchmaking uses scoring to match players to servers.
---
## The scoring formula
Servers are scored using a weighted sum formula. There are four parts to this formula:
- [Attributes](#attributes), which are data that describe players and servers, such as player age or server occupancy.
- [Signals](#signals), which transform attributes into numbers between 0 and 1.
- [Weights](#weights), which describe the relative importance of signals.
- The [server score](#server-score), which measures the server's compatibility with the joining player.
The joining player is matched to the server with the highest server score.
### Attributes
Attributes are data that describe players and servers. An attribute's value can be a number or a string. When an attribute's value is a string, it's called a categorical attribute. When an attribute's value is a number, it's called a numerical attribute.
For a full list of all available Roblox attributes, see [Existing attributes](./attributes-and-signals.md#existing-attributes). For more information about custom attributes, see [Custom attributes](./attributes-and-signals.md#custom-attributes).
<h5 style={{marginTop: '36px'}}>Example: Categorical and numerical attributes</h5>
<table>
<thead>
<tr>
<th>**Categorical attributes**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Has Friends** is a categorical attribute because its value is the string "true" when there is a preferred player on this server, and "false" when there are no preferred players on this server.</td>
</tr>
<tr>
<td>**Language** is a categorical attribute because its value is the player's language setting, such as "Japanese".</td>
</tr>
</tbody>
<thead>
<tr>
<th>**Numerical attributes**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Age** is a numerical attribute because its value is the player's age.</td>
</tr>
<tr>
<td>**Occupancy** is a numerical attribute because its value is the number of players currently in this server.</td>
</tr>
</tbody>
</table>
### Signals
Signals transform attribute values into numbers between 0 and 1, called signal scores. A signal score of 1 predicts high player compatibility, while a signal score of 0 predicts low player compatibility. Depending on the attribute, transformations can include different aggregations, comparisons, and normalizations.
For a full list of existing Roblox signals, see [Existing signals](./attributes-and-signals.md#existing-signals). For more information about custom signals, see [Custom signals](./attributes-and-signals.md#custom-signals).
<h5 style={{marginTop: '36px'}}>Example: Two servers with different signal scores</h5>
The following table calculates Occupancy signal scores for two different server with capacity for 8 players:
<table>
<thead>
<tr>
<th></th>
<th>**Players in server**</th>
<th>**Occupancy score**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Server A**</td>
<td>2</td>
<td>2/8 = 0.25</td>
</tr>
<tr>
<td>**Server B**</td>
<td>6</td>
<td>6/8 = 0.75</td>
</tr>
</tbody>
</table>
The Occupancy signal scores Server B higher and considers it a better fit for the joining player.
### Weights
A signal's weight describes that signal's importance relative to other signals. A higher weight increases the signal's contribution to the server score. The value after multiplying a signal score by its weight is called a **weighted signal**.
Signals can't have negative weights. If a signal's weight is 0, that signal is not considered for scoring.
<h5 style={{marginTop: '36px'}}>Example: Weighting the Occupancy score</h5>
The following table calculates weighted Occupancy signal scores for a place with capacity for 8 players and an Occupancy signal weight of 2:
<table>
<thead>
<tr>
<th></th>
<th>**Players in server**</th>
<th>**Occupancy score**</th>
<th>**Weighted occupancy score**</th>
</tr>
</thead>
<tbody>
<tr>
<td>**Server A**</td>
<td>2</td>
<td>2/8 = 0.25</td>
<td>0.25 * 2 = 0.5</td>
</tr>
<tr>
<td>**Server B**</td>
<td>6</td>
<td>6/8 = 0.75</td>
<td>0.75 * 2 = 1.5</td>
</tr>
</tbody>
</table>
<h5 style={{marginTop: '36px'}}>Example: Two configurations with different weights</h5>
Different weights can also make matchmaking choose different servers. The following table calculates the server scores of two servers with different matchmaking configurations. Configuration 2 has a higher weight for its Occupancy signal, and Server A has a connection of the joining player in it.
<table>
<thead>
<tr>
<th></th>
<th></th>
<th colspan="2">**Friends**</th>
<th colspan="2">**Occupancy**</th>
<th></th>
</tr>
<tr>
<th></th>
<th></th>
<th>**Weight**</th>
<th>**Score**</th>
<th>**Weight**</th>
<th>**Score**</th>
<th>**Total score**</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="2">**Config 1**</td>
<td>**Server A**</td>
<td>1</td>
<td>1</td>
<td>5</td>
<td>0.25</td>
<td>1 * 1 + 5 * 0.25 = 2.25</td>
</tr>
<tr>
<td>**Server B**</td>
<td>1</td>
<td>0</td>
<td>5</td>
<td>0.75</td>
<td>1 * 0 + 5 * 0.75 = 3.75</td>
</tr>
<tr>
<td rowspan="2">**Config 2**</td>
<td>**Server A**</td>
<td>3</td>
<td>1</td>
<td>5</td>
<td>0.25</td>
<td>3 * 1 + 5 * 0.25 = 4.25</td>
</tr>
<tr>
<td>**Server B**</td>
<td>3</td>
<td>0</td>
<td>5</td>
<td>0.75</td>
<td>3 * 0 + 5 * 0.75 = 3.75</td>
</tr>
</tbody>
</table>
### Server score
The server score is calculated by the following weighted sum formula, which sums a server's weighted signal scores:
$\text{ServerScore} = \text{WeightedSignalScore}_1 + \text{WeightedSignalScore}_2 + \ldots + \text{WeightedSignalScore}_n$
$\phantom{\text{ServerScore}} = \text{Weight}_1 \times \text{SignalScore}_1 + \text{Weight}_2 \times \text{SignalScore}_2 + \ldots + \text{Weight}_n \times \text{SignalScore}_n$
### Matchmaking configurations
A matchmaking configuration is the set of signals and weights used to score servers of a place. By default, all servers of all places are scored by the Roblox default configuration, meaning you don't need to customize or enable any settings in order to use it.
The Roblox default configuration includes the following signals and weights:
<table>
<thead>
<tr>
<th>**Signal**</th>
<th>**Weight**</th>
</tr>
</thead>
<tbody>
<tr>
<td>Friends</td>
<td>15</td>
</tr>
<tr>
<td>Latency</td>
<td>3</td>
</tr>
<tr>
<td>Text Chat</td>
<td>3</td>
</tr>
<tr>
<td>Occupancy</td>
<td>2</td>
</tr>
<tr>
<td>Play History</td>
<td>2</td>
</tr>
<tr>
<td>Language</td>
<td>2</td>
</tr>
<tr>
<td>Age</td>
<td>1</td>
</tr>
<tr>
<td>Voice Chat</td>
<td>1</td>
</tr>
<tr>
<td>Device Type</td>
<td>0</td>
</tr>
</tbody>
</table>
In the default Roblox configuration, the Friends signal's weight is greater than the sum of the weights of every other signal. This means that, if available, the joining player is always matched to servers with connections (or players on the same IP address) in them.
The Device Type signal exists in the default configuration but has a weight of 0, so it doesn't affect matchmaking decisions. You can adjust this weight when you [customize matchmaking](./customize-matchmaking.md).
For more information about each Roblox signal, see [Existing signals](./attributes-and-signals.md#existing-signals).
## Advanced concepts
The following are more advanced concepts about the matchmaking process.
### Normalization
Signals normalize attribute values to be numbers between 0 and 1. Numerical signals can be normalized by any positive number, called the **normalizing factor**. If the normalized value is greater than 1, it is clamped down to 1.
<h5 style={{marginTop: '36px'}}>Example: Designing the Age signal</h5>
The Age signal measures the difference between the average age of players in the server and the joining player's age.
$$\text{ageDifference} = |\text{avgServerAge} - \text{joiningPlayerAge}|$$
Servers with age differences beyond 25 are all considered equally incompatible with the player. For example, an age difference of 25 is no worse for a player than an age difference of 26, so both values should take the signal score to 0. In this case, 25 is considered the normalizing factor.
$$\text{normAgeDifference} = \min(1, |\text{avgServerAge} - \text{joiningPlayerAge}| / 25)$$
The signal score is inversely related to the age difference, meaning that the signal score is higher when the age difference is smaller.
$$\text{ageDifferenceSignalScore} = 1 - \text{normAgeDifference}$$
The following table shows Age signal scores with two different normalizing factors:
<table>
<thead>
<tr>
<th>**Age**</th>
<th>**Normalizing factor: 100**</th>
<th>**Normalizing factor: 25**</th>
</tr>
</thead>
<tbody>
<tr>
<td>50</td>
<td>0.5</td>
<td>0</td>
</tr>
<tr>
<td>25</td>
<td>0.75</td>
<td>0</td>
</tr>
<tr>
<td>12</td>
<td>0.88</td>
<td>0.52</td>
</tr>
<tr>
<td>5</td>
<td>0.95</td>
<td>0.8</td>
</tr>
<tr>
<td>0</td>
<td>1</td>
<td>1</td>
</tr>
</tbody>
</table>
The signal with a normalizing factor of 25 considers the 5-year and 12-year age differences to be farther apart. Smaller normalizing factors have the effect of amplifying marginal increases or decreases in age difference.
### Weight magnitudes
A weight indicates the importance of a signal relative to other signals in a configuration. The relative magnitudes of weights determine signal importance, not their absolute magnitudes.
<h5 style={{marginTop: '36px'}}>Example: Relative vs absolute magnitude</h5>
The table below calculates the server scores of two servers with two different matchmaking configurations. Configuration 5 and Configuration 6 have Occupancy weights higher than their respective Friends weights. Server A has a connection of the joining player in it.
<table>
<thead>
<tr>
<th></th>
<th></th>
<th colspan="2">**Friends**</th>
<th colspan="2">**Occupancy**</th>
<th></th>
</tr>
</thead>
<tbody>
<tr>
<td></td>
<td></td>
<td>**Weight**</td>
<td>**Score**</td>
<td>**Weight**</td>
<td>**Score**</td>
<td>**Total score**</td>
</tr>
<tr>
<td rowspan="2">**Config 5**</td>
<td>**Server A**</td>
<td>10,000</td>
<td>1</td>
<td>15,000</td>
<td>0.25</td>
<td>10,000 * 1 + 15,000 * 0.25 = 13,750</td>
</tr>
<tr>
<td>**Server B**</td>
<td>10,000</td>
<td>0</td>
<td>15,000</td>
<td>0.75</td>
<td>10,000 * 0 + 15,000 * 0.75 = 11,250</td>
</tr>
<tr>
<td rowspan="2">**Config 6**</td>
<td>**Server A**</td>
<td>0.01</td>
<td>1</td>
<td>0.05</td>
<td>0.25</td>
<td>0.01 * 1 + 0.05 * 0.25 = 0.0225</td>
</tr>
<tr>
<td>**Server B**</td>
<td>0.01</td>
<td>0</td>
<td>0.05</td>
<td>0.75</td>
<td>0.01 * 0 + 0.05 * 0.75 = 0.0375</td>
</tr>
</tbody></table>
Server A wins with Configuration 5 while Server B wins with Configuration 6. This is because Configuration 5's Occupancy weight is only 1.5x its Friends weight, while Configuration 6's Occupancy weight is 5x its Friends weight.
Despite differences in absolute magnitudes, Configuration 6 prioritizes Occupancy over Friends more than Configuration 5 does.