Getting Started

Step 1: Install the Plugin

Download the RBLX Essentials Plugin from Itch.io and drag the .rbxm file into Studio. It installs automatically to your Plugins folder. Restart Studio once.

The plugin appears as RBLX Essentials in the Plugins toolbar.

Step 2: Drag a Pack into Studio

1. Download any pack .rbxm from Itch.io.
2. Drag the file into your Studio Workspace (it lands there temporarily).
3. Open the plugin (Plugins → RBLX Essentials).

The plugin will detect the pack and show both Ecosystem Core and the pack in its list.

Note: Ecosystem Core is bundled inside every pack, you do not download it separately. It will always appear in the plugin list when you drag in any pack.

Step 3: Install the Packs

Always install Ecosystem Core first, then the pack you dragged in.

1. Click Ecosystem Core in the pack list and click Move & Install.
2. Once done, select your pack and click Move & Install.

Repeat Step 2 and Step 3 for each additional pack. Follow this install order when combining packs:

1. Ecosystem Core: always first (bundled, install before anything else).
2. Datastore & Purchase System: no other dependencies.
3. Sound System: no other dependencies.
4. General UI Kit: requires Ecosystem Core (already installed). Sound System is optional.
5. Easy Pet System: requires Datastore & Purchase System. Sound System is optional.

Step 4: Enable API Services

If you are using the Datastore & Purchase System, go to:

Game Settings → Security → Enable Studio Access to API Services

Without this, player data will not save in Studio playtests.

Step 5: Configure

Select any installed pack in the plugin to open its settings panel. Change values directly in the panel, no script editing required.

Typical things to configure:

• Easy Pet System: egg prices, drop rates, pet multipliers, gamepass IDs.
• Datastore & Purchase System: auto-save interval, DataStore name.
• Sound System: which Music Player template to use, enable/disable Music Player.

Step 6: Press Play

Hit Play in Studio. All packs initialise automatically. No bootstrap code, no wiring required.

Uninstalling a Pack

Select the pack in the plugin and click Uninstall Pack. The pack's deployed code is removed from all services. The pack template stays in ServerStorage so you can reinstall at any time.

Uninstalling Ecosystem Core does not clean up any packs that depend on it. Remove dependent packs manually first.

Plugin

The plugin is the package manager for the RBLX Essentials ecosystem. It handles discovery, deployment, configuration, and removal of packs, all within Studio without touching any project files manually.

How It Works

The plugin has three core systems. These run internally and are not visible in the UI, but understanding them helps if you want to know what happens under the hood.

Scanner reads ServerStorage.RBLXEssentials looking for _manifest folders. Each manifest identifies a pack (PackId, Version, DisplayName). This is how the plugin knows which packs are present in the project.

Verifier compares the pack's source in ServerStorage against the deployed code in the actual game services (StarterGui, ServerScriptService, ReplicatedStorage, etc.). This produces a status for each pack.

Installer copies pack code from ServerStorage into the target services on demand, and removes it on uninstall.

Pack Statuses

Registry and Update Checks

On each refresh the plugin fetches a remote registry that lists all available packs and their latest versions. This powers two features:

1. Catalogue listing: packs not yet downloaded appear in a separate "More from RBLX Essentials" section so you can discover them.
2. Plugin update banner: if a newer version of the plugin itself is available, a banner appears at the top of the plugin UI.

The registry fetch is non-blocking: the plugin renders local packs immediately, then updates the list when the fetch completes.

Ecosystem Core Requirement

No pack can be installed unless Ecosystem Core is already deployed. The plugin enforces this by checking Verifier status for Ecosystem Core before allowing any install action. The install button shows "Install Ecosystem Core first" and is disabled until EC is deployed.

Settings Panel

Selecting an installed pack opens a settings panel on the right side of the plugin. The panel reads the pack's Settings folder from ServerStorage and renders each value as an editable field. Changes are applied directly to the ServerStorage instances and take effect on the next Play session.

PackId: EcosystemCore  ·  Version: 1.0.7  ·  Dependencies: None

What It Does

Ecosystem Core is the shared UI foundation for the RBLX Essentials ecosystem. It must be installed before any pack that uses the tag-based UI system.

It provides:

• A central GUI manager that discovers and controls all UI_Panel and UI_Button elements across your game.
• GUIBridge: a cross-pack handler registry that lets each pack register its own button actions without knowing about the others.
• Panel animations, image preloading, tooltip hover effects, and effect icon management, shared across all installed packs.

You don't need to know any of this to use RBLX Essentials packs. Everything runs automatically once installed. However, if you want to use Ecosystem Core's APIs in your own code, the full reference is below.

GUIBridge API

GUIBridge lives in ReplicatedStorage.RBLXEssentials.EcosystemCore. Require it from any LocalScript.

local GUIBridge = require(ReplicatedStorage.RBLXEssentials.EcosystemCore.GUIBridge)

GUIBridge.registerHandlers(handlers)

Registers a table of action handlers. Call this once per pack during initialisation.

GUIBridge.registerHandlers({
    OpenShop = function(button)
        -- open the shop panel
    end,
    BuyItem = function(button)
        -- handle purchase
    end,
})

RBLX Essentials packs use unique action names by design, so conflicts between them won't happen. If you register your own custom actions and run into a conflict with an existing one, remove the duplicate entry from your script.

GUIBridge.dispatch(action, button)

Calls the registered handler for action. Called automatically by the GUIManager for every UI_Button click. You do not need to call this manually.

GUIBridge.getPanel(panelId)

Returns the UI_Panel GuiObject with the given PanelId attribute, searching the local PlayerGui. Returns nil if not found.

local shopPanel = GUIBridge.getPanel("Shop")

Only call this inside a running LocalScript after the GUI has loaded.

Tag System

Ecosystem Core's GUIManager discovers elements by CollectionService tag. Apply tags in Studio via the Tag Editor or via script.

Built-in Button Actions

These actions are handled by the GUIManager itself and do not need a GUIBridge handler:

Notes

• Sound playback is silent if Sound System is not installed.

PackId: DatastorePurchaseSystem  ·  Version: 1.0.6  ·  Dependencies: None

What It Does

The Datastore & Purchase System is the data and monetisation backbone of RBLX Essentials. It handles:

• Loading and saving player data automatically on join/leave.
• An in-memory cache so all reads mid-session are instant.
• Game pass ownership checks with caching.
• Developer product purchase callbacks with receipt history to prevent duplicate grants.
• Automatic retry with exponential backoff to handle Roblox DataStore throttling.

All other RBLX Essentials packs that need to persist data (e.g. Easy Pet System) read and write through this system. There is only one DataStore per game, no duplicate stores or conflicting keys.

This pack can also be used on its own. You don't need any other RBLX Essentials pack installed to use it in your game.

Plugin Configuration

All settings are managed directly from the plugin, no script editing needed.

Datastore Settings

• AutoSaveInterval: how often (in seconds) player data is saved automatically. Default is 90.
• DataStoreVersion: the DataStore key version used in production. Increment this to reset all player data (e.g. for a game wipe).
• StudioDataStoreVersion: same as above but only applies in Studio, so you can wipe test data without affecting live players.
• Wipe Studio Data: clears all locally stored Studio test data immediately.

Default Data

Defines the default data structure for new players. Data is organised into groups (e.g. Stats, Pets, Meta), each containing variables with a default value. You can add, remove, and rename groups and variables freely. This structure is what every new player starts with on their first join.

Add a new Variable

Clicking + New Variable shows a row where you write the variable name and select its type:

• Num: a number (e.g. Cash, XP).
• Str: a string of text.
• Bool: a true/false value.
• List: an array (e.g. for storing a list of owned items).

Add a new Group

Clicking + New Group shows a field to enter the group name:

Purchase Settings

• FreeMode: when ON, all game pass checks return true for all players. Useful for testing without real purchases.
• Purchases: the list of game passes and developer products registered in the system. Each entry has a name, a type (gamepass or product), and the Roblox asset ID. Add your passes here so the system can handle ownership checks and purchase callbacks.

Uninstalling

Removes the pack's deployed folders from all service locations. The pack template stays in ServerStorage so you can reinstall at any time.

DataStoreManager API

Require from any Script or ModuleScript in ServerScriptService.

local ManagerProvider = require(ServerScriptService.RBLXEssentials.DatastorePurchaseSystem.ManagerProvider)
local Manager = ManagerProvider.get()

Manager:Get(player)

Returns the player's complete data table. The first call loads from DataStore and caches the result; subsequent calls return the cache instantly.

local data = Manager:Get(player)
print(data.Stats.Cash)

Manager:Update(player, mutator)

Applies a mutation function to the player's data and queues a save. The mutator receives the data table directly.

Manager:Update(player, function(data)
    data.Stats.Cash += 100
end)

PurchaseManager API

local PurchaseManager = require(ServerScriptService.RBLXEssentials.DatastorePurchaseSystem.PurchaseManager)

PurchaseManager.HasPass(player, passId)

Returns true if the player owns the game pass. Checks the cache first, then DataStore, then MarketplaceService. Returns true in FreeMode (for Studio testing).

if PurchaseManager.HasPass(player, 123456789) then
    -- grant perk
end

PurchaseManager.registerHandler(productId, callback)

Registers a handler for a developer product. The callback receives (player, receiptInfo) and must return true to confirm the purchase. Returning false or erroring will cause Roblox to retry the receipt.

PurchaseManager.registerHandler(987654321, function(player, receipt)
    Manager:Update(player, function(data)
        data.Stats.Cash += 1000
    end)
    return true
end)

PurchaseManager.InvalidatePass(player, passId)

Clears the cached ownership result for a pass, forcing a fresh check on the next HasPass call. This is called automatically when a player purchases a pass mid-session, you only need to call it manually if you have an external reason to force a re-check.

PurchaseManager.GrantProduct(player, productId)

Directly invokes a registered product handler without a real purchase. Only works in FreeMode. Useful for testing reward flows in Studio.

Default Player Data Schema

{
    Meta = {
        SchemaVersion = 1
    },
    Stats = {
        Cash = 0
    },
    Pets = {
        Equipped = {},
        Owned    = {}
    },
    Purchases = {
        Gamepasses = {}
    }
}

Missing keys return their default values automatically. Existing players receive new defaults on their next load, no migration needed. New keys and entirely new top-level groups can be added either via the Settings > Default Data folder in the plugin, or directly in DefaultData.lua. Both approaches are equivalent: on load, the system merges the player's saved data with the current defaults and fills in anything missing.

Configuration

Settings live in ServerStorage.RBLXEssentials.DatastorePurchaseSystem.Settings and are editable via the plugin.

PackId: EasyPetSystem  ·  Version: 1.0.16  ·  Dependencies: Datastore & Purchase Sound System (optional)

What It Does

Easy Pet System is a complete, production-ready pet system for Roblox. Players hatch pets from eggs, collect them across rarity tiers, merge duplicates into rarer versions, equip pets that follow them around the map, and earn multiplier bonuses.

• Weighted rarity rolls for egg hatching.
• Auto-hatch gamepass support.
• Triple-hatch gamepass support.
• Extra Pet Space gamepass support.
• Pets follow and orbit the player with smooth animations.
• Merge 3 pets of the same type into the next rarity tier.
• Merge All: auto-merges all eligible sets in one call.
• Equip Best: automatically equips the highest-multiplier combination.
• Multiplier API: sum or product of all equipped pet multipliers, accessible from any server script.
• 28 included pet models across 5 rarities (fully replaceable).
• ScreenGui egg hatching animations.

Plugin Configuration

All settings are managed directly from the plugin, no script editing needed.

Purchase Settings

Lists the game passes used by the pack. Each entry has a warning to replace the default ID with your own from the Roblox Creator Dashboard.

• ExtraPetSpace: allows players to equip a 4th pet.
• AutoHatch: allows players to auto-hatch eggs continuously.
• TripleHatch: allows players to hatch 3 eggs at once.

Pet Data

• MaxOwned: maximum number of pets a player can have in their inventory.
• MaxEquipped: maximum number of pets a player can have equipped at once (increased to 4 with the ExtraPetSpace pass).
• MergeCount: number of pets of the same type required to perform a merge.
• ProximityDistance: how close players need to be to an egg for the hatch prompt to appear.
• FollowMode: how pets follow the player. Ground keeps pets on the floor; other modes may orbit or float.

Rarities

Rarities are defined in ReplicatedStorage > RBLXEssentials > EasyPetSystem > PetData > Rarities. You can add, remove, and rename rarities freely. Pets reference rarities by name.

The colours of pet cards in the Pets menu and in the hatch toast are not driven by these values. They are baked into each [Rarity]PetTemplate frame (gradient and UIStroke) and read from there at runtime.

Pet Card Templates

The actual pet cards rendered inside the Pets menu use rarity-specific UI templates located in:

MenusGUI > Menus > Pets > Container > PetContainer > Container

Each template is a Frame named [Rarity]PetTemplate (e.g. CommonPetTemplate, EpicPetTemplate) and tagged in CollectionService with the same name. When a pet card is rendered, the system resolves the correct template by tag:

CollectionService:GetTagged(petDef.rarity .. "PetTemplate")

The matching template is cloned and populated with the pet's data. Colours, gradients, and border styles are baked directly into each template and are not applied dynamically at runtime.

To add a new rarity, create a new Frame in the container, name it [NewRarity]PetTemplate, and apply the CollectionService tag [NewRarity]PetTemplate to it.

Pets

The full list of pets in the game. Each pet has a preview image (the 3D model), a name, a rarity, and a multiplier value. You can add new pets, delete existing ones, or change any of their properties here.

Eggs

Defines all eggs available in the game. Each egg has a name, a price, a currency (Cash or Robux), and a drop percentage table listing which pets can be hatched from it and at what probability. The total must add up to 100%.

At the bottom you can create a new Cash Egg or a Robux Egg.

Robux Eggs

Robux eggs use robuxPrice (the display price in Robux) and a productId (the Developer Product ID from the Roblox Creator Dashboard) instead of a cash price.

Uninstalling

Removes the pack's deployed folders from all service locations. The pack template stays in ServerStorage so you can reinstall at any time.

PetService API

Require from any Script or ModuleScript in ServerScriptService.

local PetService = require(ServerScriptService.RBLXEssentials.EasyPetSystem.PetSystem.PetService)

PetService.GetTotalMultiplier(player, multiply?)

Returns the combined multiplier of all equipped pets.

-- Sum all equipped multipliers (e.g. 1 + 1.5 + 2 = 4.5)
local total = PetService.GetTotalMultiplier(player)

-- Multiply all equipped multipliers (e.g. 1 * 1.5 * 2 = 3.0)
local product = PetService.GetTotalMultiplier(player, true)

-- Apply to a reward
local reward = baseCash * PetService.GetTotalMultiplier(player)

PetService.HatchEgg(player, eggId, count, isAuto?)

Hatches one or three pets from the specified egg. Returns a result table.

local result = PetService.HatchEgg(player, "Tier1Egg", 1)
if result.ok then
    for _, pet in result.pets do
        print(pet.id, pet.rarity, pet.multiplier)
    end
end

Parameters:

• eggId (string): must match a key in the Eggs configuration.
• count (number): 1 for single hatch, 3 for triple (requires TripleHatch pass).
• isAuto (bool, optional): true for auto-hatch (requires AutoHatch pass).

Failure reasons: "invalid_egg", "insufficient_funds", "inventory_full", "need_triple_pass", "need_auto_pass", "cooldown".

Each pet in result.pets has: uid, id, rarity, multiplier, createdAt.

PetService.EquipPet(player, uid)

Equips a pet by its unique ID. Players can have up to 3 pets equipped (4 with the ExtraPetSpace pass).

PetService.UnequipPet(player, uid)

Unequips a pet by its unique ID.

PetService.DeletePet(player, uid)

Deletes a pet from the player's inventory. The pet must be unequipped first.

PetService.MergePets(player, petId)

Merges 3 non-equipped pets of the same type into one pet of the next rarity tier.

local result = PetService.MergePets(player, "Cat")
if result.ok then
    print("Merged into:", result.pet.rarity)
end

Failure reasons: "no_next_tier", "not_enough", "invalid_pet".

PetService.MergeAll(player)

Merges all eligible pet sets in a single call.

local result = PetService.MergeAll(player)
print("Merges performed:", result.mergeCount)

PetService.EquipBest(player)

Unequips all current pets and re-equips the combination with the highest total multiplier, up to the equip limit.

Configuration

All configuration is data-driven. No code changes are needed to add pets, eggs, or rarities.

Key Settings

Gamepasses

Included Pets

28 pets across 5 rarities sourced from a Roblox asset pack. All pet models are fully replaceable, you can add, remove, or swap them at any time without code changes.

PackId: SoundSystem  ·  Version: 1.0.13  ·  Dependencies: None

What It Does

Sound System is a centralised audio playback system for Roblox. It provides clean client and server APIs for playing sound effects, from simple UI sounds to positional 3D audio at a world location.

It integrates with Roblox SoundGroup for volume control and respects a global SFX toggle, so players can mute sound effects independently of music.

Other RBLX Essentials packs (Easy Pet System, General UI Kit, Ecosystem Core) use Sound System for their audio feedback. If Sound System is not installed, there will be no audio at all.

Plugin Configuration

All settings are managed directly from the plugin, no script editing needed.

Sound Settings

• SFXEnabled: enables or disables all sound effects globally. When OFF, no sounds will play regardless of what other packs request.

Music Player

• Template: which Music Player UI template to use. The templates are located in ServerStorage > RBLXEssentials > SoundSystem > Templates.
• MusicPlayerEnabled: enables or disables the Music Player UI entirely.

There are 6 built-in templates to choose from (MusicPlayer_Template_1 through MusicPlayer_Template_6). You can also modify any of them freely in Studio to match your game's visual style.

Uninstalling

Removes the pack's deployed folders from all service locations. The pack template stays in ServerStorage so you can reinstall at any time.

Sound Storage

Sounds are split into two folders under SoundService > RBLXEssentials > SoundSystem:

• SFX: sound effects, looked up by name and played via the API.
• Music: music tracks played by the Music Player.

Add sounds to the relevant folder in Studio to make them available.

Client API

Require from any LocalScript.

local SFX = require(ReplicatedStorage.RBLXEssentials.SoundSystem.SFXSystem)

SFX:Play(name)

Plays a sound by name. If the sound is already playing, it restarts from the beginning.

SFX:Play("ButtonClick")

SFX:PlayOverlap(name)

Clones the sound and plays the clone. Multiple instances can overlap simultaneously. Each clone destroys itself when playback ends.

SFX:PlayOverlap("Coin")

Use PlayOverlap for sounds that can trigger rapidly (e.g. collecting coins, rapid button presses).

Server API

Require from any Script in ServerScriptService.

local SFX = require(ServerScriptService.RBLXEssentials.SoundSystem.SFXSystem)

SFX:PlayAt(name, position, range?)

Plays a sound for all clients at a world position. With a range, the sound has 3D rolloff (quieter with distance). Without a range, it plays globally at full volume for everyone.

-- Global sound (no rolloff)
SFX:PlayAt("Explosion", workspace.Part.Position)

-- 3D positional sound (audible within 40 studs)
SFX:PlayAt("Explosion", workspace.Part.Position, 40)

SFX:PlayAtForPlayer(player, name, position, range?)

Same as PlayAt but only plays for one specific player.

SFX:PlayAtForPlayer(player, "LevelUp", player.Character.HumanoidRootPart.Position)

Notes

• Positional sounds use RollOffMode.LinearSquare.
• An invisible Part is created at the position to host the sound and is destroyed when playback ends.
• The global SFX toggle (SFXEnabled BoolValue) is set by the Bootstrap script and affects all playback.

PackId: GeneralUIKit  ·  Version: 1.0.12  ·  Dependencies: Ecosystem Core Sound System (optional)

What It Does

General UI Kit is a tag-based UI framework for Roblox. UI behaviour is declared through CollectionService tags and Instance Attributes, with no hardcoded paths or script modifications needed to add new panels or buttons.

It provides:

• Panel management (open/close, exclusive mode, animated transitions).
• Universal button sounds and tooltip hover effects.
• Decorative UI animations (rotation, hover bob).
• Effect icon system with tooltip descriptions.
• TextBox typing sounds.
• Dispatch integration with Ecosystem Core's GUIBridge for cross-pack button handling.

How It Works

The GUIManager (a LocalScript) discovers all tagged elements in PlayerGui at runtime. Tags declare what an element is; Attributes declare how it behaves. You tag a Frame as UI_Panel and set PanelId = "Shop", and GUIManager handles the rest.

Button actions are dispatched through GUIBridge.dispatch(). To handle an action in your own code, call GUIBridge.registerHandlers() with a table of action functions.

Plugin Configuration

All panel and button configuration is managed directly from the plugin. No script editing or manual attribute assignment needed.

Panels and Buttons

The Navigation Manager lets you configure every panel and its associated button from a single visual panel in Studio. Each panel row shows a live thumbnail preview alongside its settings.

• Exclusive: when enabled, opening this panel automatically closes all other open panels.
• Animation: select the open/close animation for this panel (Bounce, SpinReveal, etc.).
• Button assignment: assign which button in your GUI toggles this panel.
• Add New Panel & Button: creates a new panel and a linked button in one click.

Tag Reference

UI_Panel

A toggleable menu panel (Frame or ScreenGui).

UI_Button

A clickable button (TextButton or ImageButton) that dispatches an action.

UI_Animated

A decorative UI element with a looping animation.

UI_Tooltip

A Frame that appears on hover for an adjacent UI_Button or UI_EffectIcon.

UI_EffectIcon

An icon representing a buff or game effect, with an automatic tooltip.

UI_TypeSound

Apply to a TextBox to play a typing sound on each character input. No attributes required.

Registering Button Handlers

Call GUIBridge.registerHandlers from a LocalScript that runs after the GUI loads.

local GUIBridge = require(ReplicatedStorage.RBLXEssentials.EcosystemCore.GUIBridge)

GUIBridge.registerHandlers({
    OpenShop = function(button)
        GUIBridge.getPanel("Shop").Visible = true
    end,

    BuyItem = function(button)
        local productId = button:GetAttribute("ProductId")
        game:GetService("MarketplaceService"):PromptProductPurchase(
            game.Players.LocalPlayer, productId
        )
    end,
})

Built-in Actions

These actions are handled by GUIManager directly. Do not register handlers for them.

Notes

• Image preloading is batched (2 images per frame) to avoid frame hitches on startup.
• Sound playback (button clicks, hover effects) is silent if Sound System is not installed.
• Tooltips are throttled at 16ms intervals to avoid layout thrashing.
• All GUIManager connections are cleaned up via Trove when the GUI is destroyed (respawn/reload safe).

PackId: EasyLeaderstatsSystem  ·  Version: 1.0.4  ·  Dependencies: Datastore & Purchase System

What It Does

Easy Leaderstats & Leaderboards System adds two related features to your game:

• Leaderstats: the in-game stat list shown in the Tab/escape menu. Values are read directly from player data (provided by the Datastore & Purchase System) and kept in sync automatically.
• Global Leaderboards: physical in-world boards that display the all-time top players for any stat, stored in Roblox OrderedDataStores and refreshed on a configurable interval.

Both features are fully configuration-driven from the plugin. No script editing is needed to add or remove stats and leaderboards.

Plugin Configuration

Selecting the pack in the plugin opens a settings panel with two sections: Leaderstats and Leaderboards.

Leaderstats

Each stat entry corresponds to one row in the Tab menu. Entries are grouped by the data group they belong to (e.g. Stats).

Display fields compose left-to-right: Prefix + formatted value + Suffix.

+ Add Stat creates a new entry. The DataKey is selected from the existing variables in your Datastore Default Data, so stats must be defined there first.

Leaderboards

Global Settings

Leaderboards

Each entry drives one physical in-world leaderboard board. Boards are discovered via the CollectionService tag ELS_Leaderboard: any Model in workspace with that tag and an ELS_LeaderboardId attribute appears here automatically. Models can be placed anywhere in the workspace hierarchy.

+ Add Leaderboard clones the first template from ServerStorage/.../Templates/, places it in workspace.EasyLeaderstatsSystem, assigns a GUID, and creates the corresponding Settings entry. The new model is selected in Studio automatically.

Delete Leaderboard removes both the Settings entry and the workspace model.

Duplicating a Board in Studio

If you duplicate a leaderboard Model in Studio, the plugin detects the duplicate GUID and automatically assigns the clone a new unique ID and a new Settings entry.

Uninstalling

Removes the pack's deployed folders from all service locations. The pack template stays in ServerStorage so you can reinstall at any time.

How It Works

Leaderstats

On server start, a Bootstrap script creates a leaderstats folder under each player as they join, then creates one IntValue per configured stat entry inside it. The value is read from PlayerData using the DataKey dot-path (e.g. Stats.Cash) and a Changed signal keeps the leaderstat in sync automatically throughout the session.

Global Leaderboards

Stats are written to OrderedDataStores in three situations:

1. On join: once the player's data is loaded and all configured stat values are non-nil, their stats are written. This happens automatically, even for players who were already in-game when the server started.
2. On leave: stats are written immediately when the player disconnects.
3. Periodically: every 5 minutes, all current players' stats are written to keep leaderboard data fresh for long sessions.

Board UI is refreshed every RefreshInterval seconds. The first refresh runs 5 seconds after server start to allow player data to load. During each refresh, the top MaxEntries players are read from the OrderedDataStore and the SurfaceGui list on the in-world board is rebuilt. A countdown timer on each board shows when the next refresh will occur.

OrderedDataStore Naming

Store names are derived automatically from the stat path: GlobalLeaderboard_ followed by the dot-path with dots replaced by underscores.

-- e.g. Stats.Cash → GlobalLeaderboard_Stats_Cash

Dummy Avatars

The top 3 players on each board have their Roblox avatar applied to Dummy1, Dummy2, and Dummy3 models placed beside the board. Avatars are scaled down and play looping emote animations. Avatar application is skipped for a rank if the same player holds that rank after a refresh; only changed ranks trigger a new GetHumanoidDescriptionFromUserId call.

In-World Board Setup

Each board is a Model anywhere in workspace tagged with ELS_Leaderboard (CollectionService). New boards are cloned from ServerStorage.RBLXEssentials.EasyLeaderstatsSystem.LeaderboardTemplate and placed inside workspace.EasyLeaderstatsSystem when you click + Add Leaderboard.

The system locates UI elements by ELS_Role attribute, not by path, so the internal hierarchy of the model can vary between templates.

[StatPath leaf] Leaderboard  [Model]
├── BoardModel
│   ├── BoardBase  [Part]
│   │   └── Leaderboard  [SurfaceGui]
│   │       ├── Rank   [TextLabel, header]  ELS_Role = HeaderRank
│   │       ├── Name   [TextLabel, header]  ELS_Role = HeaderName
│   │       ├── Value  [TextLabel, header]  ELS_Role = HeaderValue  (shows VariableNameText)
│   │       └── List   [ScrollingFrame]     ELS_Role = List
│   │           └── Template  [Frame, cloned per entry, must stay hidden]
│   │               └── Frame
│   │                   ├── Rank, Name, Value  [TextLabel]
│   │                   └── Icon  [ImageLabel]
│   └── TopPart  [Part]
│       └── Leaderboard  [SurfaceGui]
│           └── TextLabel  ELS_Role = TitleLabel  (shows TitleLabelText)
├── Dummy1 / Dummy2 / Dummy3  [Model, R15 rigs for top-3 avatars]
└── Timer  [Part]
    └── GUI  [SurfaceGui]
        └── Label  [TextLabel, shows "Refresh in: Xs"]

Each board Model also carries these attributes (managed by the plugin):

Requirements

• Datastore & Purchase System must be installed and providing PlayerData for each player.
• API Services must be enabled (Game Settings → Security → Enable Studio Access to API Services) for OrderedDataStores to work in Studio.

Roulette System

PackId: RouletteSystem  ·  Version: 1.0.0  ·  Dependencies: Datastore & Purchase System Easy Pet System (optional)

What It Does

Roulette System adds a spin-to-win wheel to your game. Players spend spins to land on rewards, earn free spins on a cooldown timer, and can purchase extra spins via developer products. Everything is configurable without touching code: reward types, amounts, weights, icons, and product IDs are all set through the plugin settings panel.

• Weighted random reward selection (Cash, Diamonds, extra Spins, or custom).
• Free spin cooldown: timer starts when the player hits 0 spins, auto-grants a spin when it expires.
• Developer product integration: +1, +3, and +10 spin purchases wired up from plugin settings.
• Up to 8 reward slots, each with a DisplayName, Icon, Type, Amount, and Weight.
• Custom reward support: drop a ModuleScript with a .Grant(player, d) function into CustomRewards/ to define any reward (e.g. grant a pet).
• Live settings panel: changing a reward's DisplayName or Icon updates the in-game GUI without restarting.
• Safety timeout: if the client never fires AnimationComplete, the server grants the reward after 10 seconds.

Plugin Configuration

Selecting the pack in the plugin opens a settings panel with three sections: General, DevProducts, and Rewards.

General

DevProducts

Rewards

Up to 8 reward slots (Reward1–Reward8). Each slot has:

For custom reward types, set Type to the exact name of a ModuleScript placed in ServerStorage > RBLXEssentials > RouletteSystem > Settings > CustomRewards. The module must return a table with a Grant(player, d) function.

Uninstalling

Removes the pack's deployed folders from all service locations. The pack template stays in ServerStorage so you can reinstall at any time.

Player Data

On player join, Bootstrap initialises the Roulette key in the player's datastore entry if it doesn't exist yet. No changes to the DS default data module are required — RouletteSystem writes its own keys via Manager:Update on PlayerAdded.

d.Roulette = d.Roulette or {}
d.Roulette.Spins        -- number of spins available
d.Roulette.LastSpinTime -- os.time() when spins hit 0 (0 = timer not running)

RouletteManager API

Require from any Script in ServerScriptService.

local RouletteManager = require(ServerScriptService.RBLXEssentials.RouletteSystem.RouletteManager)

RouletteManager.addSpins(player, amount)

Adds spins to the player's balance, capped by MaxSpins (0 = no cap).

RouletteManager.addSpins(player, 5)

RouletteManager.canSpin(player)

Returns true if the player has at least one spin available. Returns false, reason otherwise.

RouletteManager.processSpin(player)

Deducts one spin, picks a weighted random reward, stores it as a pending reward, and returns it to the caller. The reward is not granted yet — it's held until AnimationComplete fires (or the 10-second safety timeout).

local success, result = RouletteManager.processSpin(player)
if success then
    print(result.Type, result.Amount) -- e.g. "Cash", 500
end

RouletteManager.grantPendingReward(player)

Applies the pending reward to the player's data. Called automatically by the AnimationComplete RemoteEvent or the safety timeout. Also called on PlayerRemoving to prevent loss if the player leaves mid-spin.

Custom Rewards

Place a ModuleScript inside ServerStorage > RBLXEssentials > RouletteSystem > Settings > CustomRewards. The module must return a table with a Grant function:

local MyReward = {}

function MyReward.Grant(player, d)
    -- d is the live datastore table inside Manager:Update
    -- modifications here are persisted automatically
    d.Stats = d.Stats or {}
    d.Stats.Gems = (d.Stats.Gems or 0) + 1
end

return MyReward

In the plugin settings panel, set a reward slot's Type to the exact name of the ModuleScript (e.g. "MyReward"). The Amount field controls how many times Grant is called per spin.

A GrantPet example module is included out of the box — edit the PET_ID constant at the top to change which pet is granted.

Configuration

All settings are configured through the plugin's Settings panel. No code changes needed.

General

DevProducts

Rewards (up to 8 slots)

Each reward slot (Reward1–Reward8) has:

Default Rewards

The fallback Rewards.lua module (used when the Settings/Rewards folder is empty) ships with 7 reward slots:

Remotes

Created automatically at runtime in ReplicatedStorage > RBLXEssentials > RouletteSystem > Remotes:

Config Replication

FreeSpinCooldown is replicated to ReplicatedStorage > RBLXEssentials > RouletteSystem > Config > FreeSpinCooldown so the client can display the timer without a remote call.

Changelog

Version history for all packs and the plugin.