Player Weight Match

Quick setup

Install Player Weight Match from Creator Store, then open it from Studio’s Plugins toolbar. Use a separate published test experience, saved progression records and Studio API access. Installing a supplied .rbxmx? See local installation.

1. Connect your stats

Open Stats → Fetch DataStores. Choose each stat’s store and use Browse to select its saved value. Check the key and UserId with Test read. Delete unused examples and set importance to total 100%. More detail.

2. Check the result

Open Simulator and try New, Mid and Top. Adjust importance until the 1–100 weight feels right. This preview does not change player data.

3. Deploy and save a test weight

Select Deploy System, then start a server playtest with a player who has saved progression. Wait for a calculated weight and verify a successful matchmaking save before stopping. A default value of 1 alone is not proof. How to check.

4. Create the Roblox attribute

In Creator Dashboard → your experience → Configure → Custom Matchmaking → Attributes, create a Player Attribute. Copy every connection field from the plugin’s Matchmaking tab, then Save Changes.

5. Add and preview the signal

Under Configuration → Add Custom Signal, create PlayerWeightSimilarity using your attribute, Player Numerical, Average, and Differences beyond = 20.

For the proof test, use importance 50, Occupancy 1, Latency 1, and unrelated signals 0. In Preview and Test, use player value 50 with server averages 10, 48 and 90. Keep other inputs equal: 48 should win. Tune production importance after this test.

6. Apply it and join again

Save Configuration → select your playable places → save again. Publish the generated runtime. Join, let a weight save, leave, then rejoin so Roblox can use it when selecting a server.

Setup complete. If something does not match, jump to Troubleshooting. The rest of this page contains the detailed walkthrough and reference—you do not need to read it all to get started.

Before you start

Player Weight Match 1.0 combines saved progression into one 1–100 player weight for Roblox Custom Matchmaking. The supplied package uses 0.6.0 as its internal build identifier. Build numbers in generated metadata and Repair / Update diagnostics are separate from the public release version.

The plugin configures the system in Studio. Its generated server runtime reads saved progression, calculates weight and writes a dedicated matchmaking record. Roblox reads that saved weight before choosing a server on a subsequent join. The running server also exposes the current value as a Player attribute.

It measures progression, not character mass. It does not replace your save system, automatically move players between servers, expose a client matchmaking remote or guarantee strict progression brackets.

Requirements and safe testing

• Use an experience you can publish and configure in Creator Dashboard.
• Have a populated standard DataStore containing saved progression. A leaderboard display, in-memory profile or OrderedDataStore alone is not the input workflow for this build.
• Know a test user’s numeric UserId, the record key format and the nested fields your save system writes.
• Use a separate published test experience with test records before enabling Studio API access. Another place in the same experience is not an independent DataStore sandbox.
• Back up the place and keep progression inputs separate from the plugin’s matchmaking and top-index output stores.

The source picker in this build uses the global progression scope. If your game uses custom source scopes or a private save abstraction, check compatibility first; selecting a matching store name alone is not enough.

Installation

Install from the official Player Weight Match listing, enable the installed plugin and open it from Studio’s Plugins toolbar.

If GoldAstro supplied a licensed .rbxmx package directly:

1. Open a test place while not playtesting.
2. Use Studio’s local model import command, such as Insert from File in Explorer, to import the supplied package. Locate the imported PlayerWeightPro Script.
3. Select that Script and use Save as Local Plugin from the Plugins menu or Script context menu, depending on your Studio layout.
4. Save the local plugin, then open Player Weight Match from the Plugins toolbar. Reload the plugin or restart Studio if it does not appear immediately.
5. Keep the original package as a backup. The imported Script is installation material; do not treat it as the generated game runtime or publish an extra copy as game logic.

The plugin Script expects Studio’s plugin context. Running it as an ordinary game Script does not install the runtime. The live system is created later with Deploy System.

Expected result: the plugin interface opens with Stats, Simulator, Matchmaking, Settings and documentation available. Use Settings > Reset window location if the floating panel is out of view.

Setup overview

The built-in Documentation > Setup page has six expandable cards. Follow them in order; the sections below add examples and checkpoints to that workflow.

There are three separate saves: local plugin settings, published generated scripts, and player matchmaking records. A local configuration save does not publish the runtime or persist a player’s weight.

Connect progression

Fetch and select the stores

Open Stats and select Fetch DataStores on first use. Once a list exists, the action is labelled Refresh DataStores. Fetch lists populated standard store names without reading every player’s record. The list is cached for 300 seconds.

If nothing appears, confirm publishing, Studio API access and that your save system has written at least one record. An unused store name is not a populated store.

The starting Power, Currency and Rebirths entries are examples, not connected data. Configure each one or remove it with Delete this stat. Removing a plugin stat does not delete progression records. Use long-term values that generally increase, such as lifetime power, earnings, rebirths, wins or playtime.

Remove unused stats instead of merely setting their importance to zero. The runtime still checks configured values and tops, so a missing unused input can prevent a new calculation.

Expand a stat and select its store from the fetched list. Smart Fill inspects a sample record and suggests plausible numeric or BigNum fields, key templates and test users. It can select a strong candidate or open the browser when several are plausible. Review the result rather than assuming the first similar field name is correct.

Browse the exact saved value

Use Browse / Browse saved data, open nested groups with +, and Select the intended numeric or BigNum child. The plugin builds the value path from your selection.

For example:

{
    Stats = {
        Power = "20Oc",
        Coins = "5Qa",
        Rebirths = 125,
    },
}

The corresponding paths are Stats.Power, Stats.Coins and Stats.Rebirths. Your plugin display name can be Currency while the saved source is Stats.Coins; the label does not rename a saved field.

Use exact spelling and capitalization. Select the underlying value when a stat is inside a larger object. An arbitrary table is not automatically a supported BigNum representation.

Verify the record key and test user

The key template determines which player’s record is read. With an example UserId of 12345678:

Match your existing save system. {UserId} is required; a username or display name is not a substitute. Smart Fill can infer a key format, but verify it against a known record.

Open Advanced & test, confirm the numeric test UserId and select Test read. Studio may prefill your own account, which still needs a saved record in this experience. The operation reads that record and follows the value path without writing progression.

Expected result: the status reports that the stat was found. Compare the value with your save system. For a BigNum object, inspect its fields in the saved-data browser rather than expecting every status message to format it as a number.

Set Minimum and Importance

Minimum is the low reference point for the curve, normally 0 or 1. Importance controls relative influence: Power at 50 has twice the influence of Rebirths at 25. The example configuration uses Power 50, Currency 30 and Rebirths 20.

Keep total importance around 100% for readability. At least one stat and a positive total are required. Review confirmations when changing sources, key formats or important curve settings.

Stage complete: every retained stat has a real source, correct key template, exact value path, valid minimum and intentional importance. Do not point a source at the plugin’s output stores.

Simulate player weights

Open Simulator and try New, 25%, Mid, 75% and Top. These generated samples do not modify player records.

Check the individual scores, contributions and final weight. Raise one stat at a time to confirm its influence. A low-importance stat should not dominate the result.

Preview Top is a pretend best value for the simulator. Set it above Minimum and use it to explore the progression range you expect. It is not a fixed runtime maximum and does not seed the live top index. Runtime uses observed saved progression.

Preset percentages represent positions along the scoring curve, not necessarily percentages of the raw progression number. Logarithmic scoring compresses large ranges.

Stage complete: New-to-Top progression feels reasonable and every configured stat calculates successfully. You do not need to understand the formula to finish setup.

Deploy and test

Generate the server system

Select Deploy System in the setup guide, or Deploy Player Weight System on the Matchmaking page. If a generated system already exists, review the replacement confirmation first.

The generated folder is:

ServerScriptService
└── PlayerWeightSystem
    ├── Server
    ├── Runtime
    ├── Config
    └── API

Server starts the runtime. Runtime handles reads, top tracking, scoring and saves. Config contains generated settings, and API exposes server integration helpers. Keep them together in ServerScriptService. No client Script or RemoteEvent is required.

Deployment validates the configuration, including key templates, missing inputs and collisions between progression, matchmaking and top-index store names. Resolve the reported problem instead of substituting guessed values.

Run a server playtest

Publish the test experience. Enable Experience Settings > Security > Enable Studio Access to API Services for Studio DataStore testing. Start a server playtest with a user whose progression record exists.

The default initial delay is five seconds, but reads and budget delays can take longer. Use the server Command Bar, not the client context:

local player = game.Players:GetPlayers()[1]
if player then
    print("Player:", player.Name, "UserId:", player.UserId)
    print(player:GetAttribute("PlayerWeight"))
else
    warn("Start a server playtest with a player first.")
end

Use the configured attribute name if you changed it. Studio multiplayer test users may not have the UserIds or saved records of real accounts. A missing test record does not prove the calculation is broken.

Verify the first saved weight

A visible attribute proves there is a current value, not necessarily a persisted matchmaking record. A value of 1 may also be the first-join default. Check Output and runtime status for successful reads and saves.

After progression loads, this optional server diagnostic recalculates and explicitly requests a matchmaking save:

local API = require(game.ServerScriptService.PlayerWeightSystem.API)
local player = game.Players:GetPlayers()[1]
if player then
    local weight = API:Recalculate(player)
    if weight then
        print("Calculated weight:", weight)
        print("Weight saved:", API:SaveWeight(player))
    else
        warn("Progression or its top is not ready. Check server output.")
    end
end

SaveWeight returns a boolean. False can indicate unavailable state, low request budget or a failed operation. Do not retry it in a tight loop.

The built-in setup guide has you stop the playtest after a real weight appears. The runtime also attempts departure and shutdown saves, but verify success where possible. The dedicated weight store needs a written record before selecting it in Creator Dashboard.

Stage complete: the generated system exists, a real player’s progression calculates and a matchmaking record has been saved.

Matchmaking connection

Create the Player Attribute

1. Go to Creator Dashboard > Creations > your experience > Configure > Custom Matchmaking.
2. Open Attributes, select Create Attribute, and choose Player Attribute.
3. Keep the plugin’s Matchmaking page or Documentation > Setup > Create the Roblox attribute card open beside the dashboard.
4. Copy the exact attribute name, type, default, DataStore, scope, key template and value path.
5. Select Save Changes.

The supplied defaults are below. If you intentionally changed the plugin connection, copy the changed values instead:

The DataStore here is the plugin’s dedicated output, not the source progression store. The value path must point to the numeric weight, not the entire record. For example, a saved table with PlayerWeight = 52 uses the path PlayerWeight.

The runtime’s Player instance attribute and the dashboard’s Custom Matchmaking Player Attribute are separate. Seeing the former in a playtest does not automatically configure the latter.

Stage complete: the dashboard attribute is saved with the exact deployed connection. If you change a connection field later, update both the plugin deployment and dashboard before retesting.

Create the matchmaking signal

Create a configuration

1. In Custom Matchmaking, open Configuration and create a new configuration.
2. Select Add Custom Signal.
3. Name it PlayerWeightSimilarity and select the PlayerWeight attribute, or the name you configured.
4. Use a Player Numerical signal and Average aggregation.
5. For the first proof test, set Differences beyond = 20, then create the signal.

Average compares the joining player’s weight with the average player weight in each candidate server. Differences beyond controls how quickly dissimilar servers lose preference. It does not create a hard admission limit.

Use the exact proof-test values

The plugin recommends deliberately strong diagnostic settings:

These settings make the progression effect easy to see. They are not a universal production recommendation; latency and occupancy still matter.

Open Preview and Test. Set Player Value = 50 for all three mock servers and enter:

Keep other mock-server inputs comparable. Server B, with average 48, should clearly win when this progression signal dominates the test. The preview uses fake values and does not modify player data.

If it does not prefer B, recheck the attribute, Player Numerical type, Average aggregation, difference setting and signal importance. Check that unrelated signals are not outweighing the progression test.

Apply and live test

1. Select Save Configuration.
2. Select the playable Place or Places that should use it.
3. Save/apply again. Saving a configuration without assigning it to the intended place is not enough.
4. Publish the experience with the generated runtime included.
5. Join normally with an account that has saved progression. Let a real weight calculate and save, then leave.
6. Join again. Roblox can now read the saved weight before selecting a server.
7. Once the end-to-end test works, tune other signal weights for your game and repeat the preview and live tests.

A first-time player without a saved matchmaking record uses the dashboard default, normally 1. The current session prepares information for a later join; it cannot change which server was selected before the session began.

A small game may have only one suitable server. Capacity, latency, other signals and Roblox’s selection process affect the outcome. A single mixed-progression server is not proof that the signal failed.

Repeat dashboard setup when changing the matchmaking connection or creating a new configuration. For normal importance changes, update plugin settings, redeploy and publish, then let new weights calculate and save.

How scoring works

The runtime compares each configured stat with its Minimum and highest observed saved value. Logarithmic magnitudes keep enormous progression values useful without constructing every full number.

For ordinary non-negative values, the curve uses log10(value + 1). It scales and clamps each score into 1–100, multiplies by importance, combines the results, divides by total importance, then rounds and clamps the final weight.

For example, suppose the already calculated stat scores are Power 80, Currency 40 and Rebirths 20, with importance 50, 30 and 20:

(80 × 50 + 40 × 30 + 20 × 20) ÷ 100 = 56

Those example numbers are scores, not raw progression. The simulator shows both values and contributions.

Automatic top and established games

When the runtime observes a larger saved value, it updates that stat’s top. Servers share the managed index through PlayerWeightPro_TopIndex and refresh periodically, so they converge rather than necessarily updating simultaneously.

There is no historical scan of every player key. Existing games warm up as stronger players are observed. A historical best player who has not been observed since installation may not be represented yet.

The top is a highest-observed reference, not a promise to decrease when a player spends currency or a season resets. Prefer long-term progression values and plan migrations deliberately. Do not delete managed records simply to make a preview look different.

If a configured value or top is missing or invalid, the runtime can decline to calculate a new weight and keep the previous/default state. A partly connected setup is not a reliable partial-weight system.

Large number formats

The supplied parser supports:

Recognized suffixes include K, M, B, T, Qa, Qi, Sx, Sp, Oc, No and Dc, case-insensitively. Custom abbreviations from another number library are not automatically supported.

Common mantissa/exponent aliases and some value wrappers are recognized. Arbitrary serialized BigNum formats may require adaptation in your own save system. Verify the actual saved representation with Test read and the simulator.

Preserve extremely large values as strings or supported structures. If a value has overflowed into math.huge, its original magnitude has already been lost. Correct negative, malformed, missing or unsupported inputs rather than assuming they will become a normal low score.

Runtime API

Call the API from server code. Let the generated Server Script start Runtime; do not expose a client RemoteEvent that lets players set their own weights.

local API = require(game.ServerScriptService.PlayerWeightSystem.API)
local player = game.Players:GetPlayers()[1]

if player then
    print(API:GetWeight(player))
    print(API:Recalculate(player))
    print(API:SaveWeight(player))
end

Inspect the known top

local API = require(game.ServerScriptService.PlayerWeightSystem.API)
local top = API:GetKnownTop("power")
if top then
    print("Observed value:", top.Raw)
    print("Observed user:", top.UserId)
    print("Updated at:", top.UpdatedAt)
end

power is the default stat ID, not a promise that every display name can be passed directly. Use the configured ID. Known-top data also contains LogMagnitude.

Refresh after your own save completes

Your server integration can request API:Refresh(player) after its progression save succeeds. This queues a fresh read; calling GetWeight immediately afterwards may still return the previous value. Observe the eventual runtime status or attribute change instead of assuming synchronous completion.

Recalculate does not request fresh DataStore data. SaveWeight skips ordinary interval/delta conditions for that request, but still checks budgets and can fail. Do not poll these methods every frame or on every small progression increment.

Data freshness and safety

Which stores can change?

Do not reuse a store for multiple roles. Deployment validates these separations. The API has no progression editing, incrementing or deletion methods.

Why a weight can lag behind gameplay

The normal progression cache is 300 seconds. Your own system must save a change before Player Weight Match can observe it. Unsaved private profile data is not available to this DataStore-only workflow.

The runtime groups stale reads, checks budgets and delays work when needed. It cannot reuse unrelated scripts’ GetAsync calls. Low budgets or service failures can extend refresh time beyond the normal cache interval.

The supplied runtime uses BatchGetAsync for grouped progression reads. Failed batches are reported and requeued; do not assume this build falls back to individual reads. If grouped reads repeatedly fail in your environment, capture the server error and contact GoldAstro before releasing the configuration to players.

Normal periodic saves respect the save interval and minimum weight change. Initial, departure, shutdown and explicit saves can take different paths; request-budget checks still apply. No DataStore operation is guaranteed simply because a timer elapsed.

Settings reference

Runtime defaults

Use the exposed controls rather than editing generated Config fields. Not every runtime field is an editable UI control in this release. Runtime changes require redeployment and publishing before new production servers use them.

Appearance and local saves

Settings includes solid and animated themes, toolbar density, Compact/Comfortable stat editors, font and weight choices, text size and stroke, UI motion, automatic simulator preview, status-text visibility and remembering the open page.

Configuration is saved locally with an experience-specific key. The status area shows the last successful local save time. This is not a replacement for publishing generated scripts and should not be assumed to synchronize to a teammate’s computer.

Reset window location repositions the panel. Reset settings restores local appearance and progression configuration after confirmation; it does not delete records or the existing deployed system. Verify the setup before deploying after a reset.

Repair and update

Choose the correct operation

• Deploy / Redeploy uses the plugin’s current configuration. Use it after intentional configuration changes.
• Repair / Update recovers the existing generated setup before regenerating it. Use it to preserve an installed configuration while repairing or updating generated files.

Repair is not a way to apply a different local setup. Recovery can replace the plugin’s current settings with the recovered deployment configuration.

Repair workflow

1. Back up the place and review any custom changes to generated scripts.
2. Open Settings > System repair & updates.
3. Review Installed build and Latest build. The supplied package may show 0.6.0 here because these are internal build values; the public release is 1.0.
4. Select Repair deployed system or Repair / Update deployed system.
5. Review the confirmation: recovery preserves progression sources and the matchmaking connection, then replaces only ServerScriptService > PlayerWeightSystem.
6. If recovery or validation fails, stop and verify Stats and connection settings. Do not force replacement with guessed values.
7. After repair succeeds, repeat the server calculation/save test and publish the repaired place when ready.

Recovery uses generated configuration and metadata attributes where available. Objects include role, build, configuration and safety metadata; a repaired folder also records repair information such as the previous build and repair time.

The updater does not delete, reset or rewrite progression, matchmaking or top-index records. When the repaired runtime runs, its normal reads and writes resume. Regeneration overwrites custom edits inside generated scripts, so keep integration code in separate server scripts using the API.

Runtime compares its metadata with Config. Do not change a Build, schema or connection attribute merely to hide an error. Use the supported deploy or repair workflow and retest.

Troubleshooting

The plugin does not open

Confirm it is installed and enabled as a Studio plugin. An imported Script left in the place is not an installation. Reload Studio if necessary, inspect plugin errors in Output and reset the window location if the panel is off-screen.

No DataStores are listed

Check the experience, publishing, Studio API access and whether a standard global-scope store contains records. Fetch does not create progression. A new test experience needs its own sample saves.

Smart Fill selected the wrong field

Use Browse to choose the exact child. Check capitalization, wrappers and whether a similarly named field is a current balance or lifetime value. Verify the final path with a known UserId and Test read.

Test read returns nil or a missing-path error

Verify the key template, numeric UserId, store and exact nested path. Confirm that the account has played and saved in this experience. A visible leaderboard does not prove that the chosen record contains that value.

Deployment is refused

Read the validation message. Typical causes are no stats, zero total importance, unconnected default stats, invalid minimums, missing {UserId} placeholders or a store being reused for input and output.

PlayerWeight is missing or stays at 1

Confirm the generated Server Script is running under ServerScriptService. Use the configured attribute name and wait for the initial delay. Inspect missing records, invalid BigNums, batch failures and budget warnings. New or genuinely low-progression players can correctly have weight 1.

Recalculate returns nil

The runtime state or a configured value/top is not ready. Check every stat, including unused examples. Recalculate cannot create missing progression records or bypass a failed read.

The current weight is stale

Confirm your save system persisted the progression change. The normal cache lasts five minutes, with queue delays possible. Refresh can request new reads after a successful save; Recalculate uses existing inputs.

SaveWeight returns false

Check whether a weight exists and whether Output reports low budgets or failed operations. Allow normal retries. Repeated forced saves can consume budget without fixing the cause.

The dashboard cannot find the matchmaking store

Run the generated system and verify a successful weight save first. A configured but empty store may not be discoverable. Choose the same experience and dedicated output store, not a progression source.

All mock servers score alike

Recheck the attribute, numerical signal, Average, difference setting and signal importance. Use Player Value 50 for all mock servers and averages 10, 48 and 90. Keep other inputs comparable; the 48 server should win this proof test.

Preview works but normal joins seem unchanged

Confirm the configuration was applied to the correct playable places, the runtime was published and a weight was saved in an earlier session. Consider server availability and other signals. The current session does not retroactively change its own server assignment.

Runtime reports a metadata mismatch

Use Repair / Update or Redeploy with the correct configuration. Keep generated files together and check for unintended old systems. Do not patch matching-looking attributes merely to silence validation.

Seasonal resets produce surprising weights

The top index is highest-observed data, not a full rescan of current player values. Test progression-model changes deliberately and keep backups. Contact GoldAstro for a migration plan rather than deleting records blindly.

Launch checklist

• Every configured stat has been verified against saved test data.
• Unused examples are removed and importance values are intentional.
• Progression, matchmaking and top-index stores are separate.
• New, Mid and Top simulator cases work as intended.
• Generated files are in ServerScriptService and a real server test calculates a weight.
• A dedicated matchmaking record has been saved successfully.
• Dashboard attribute values exactly match the deployed connection.
• The proof test prefers average 48 for player value 50.
• The configuration is applied to the intended playable places.
• A subsequent normal join has been tested after saving a weight.
• Production signals balance progression with latency and occupancy.
• The published place contains the final runtime and a backup is retained.

For current dashboard terminology, see Roblox’s matchmaking configuration guide. Return to the Player Weight Match product page for pricing and release information, or contact GoldAstro with your build identifier and the relevant server error. Remove private player records and credentials before sharing diagnostics.