Skip to the content.

Random

local R = require(Packages.Constella.Random)

local chest = R.lootTable({
	{ Value = "Wood Sword", Weight = 60 },
	{ Value = "Star Blade", Weight = 9 },
})
local item = chest:Roll()                   -- uses a private Random.new()
local seeded = chest:Roll(Random.new(1234)) -- deterministic
local lucky = chest:Roll(nil, { Luck = 0.5 })

Roll rewards on the server. Never accept a roll result, luck value or multiplier from a client.

Server-authoritative rewards

The client only says what it wants to open. The price, the odds, the roll and the reward all stay on the server, and the client gets the result to display:

-- Server (inside a service)
local Network = Constella.Network
local Check = Network.Check
local R = Constella.Random

local CHESTS = {
	Basic = {
		Price = 100,
		Loot = R.lootTable({
			{ Value = "Wood Sword", Weight = 60 },
			{ Value = "Star Blade", Weight = 9 },
		}),
	},
}

local server = context.Cleanup:Add(Network.Server.new("Chests"))
local open = server:Function("Open", {
	Schema = { Check.literal("Basic") }, -- only chests that exist
	RateLimit = { Count = 2, Per = 1 },
})

open:SetHandler(function(player, chestId)
	local profile = store:Get(player) -- a Data profile; nil until loaded
	if profile == nil then
		return "NotReady"
	end
	local chest = CHESTS[chestId]
	if profile:Get("Coins") < chest.Price then
		return "NotEnoughCoins"
	end
	-- Pay and roll in the same handler call, before anything yields,
	-- so two quick requests can't both pass the price check.
	profile:Update("Coins", function(coins)
		return coins - chest.Price
	end)
	local item = chest.Loot:Roll()
	profile:Update("Inventory", function(inventory)
		local updated = table.clone(inventory)
		table.insert(updated, item)
		return updated
	end)
	return "Opened", item
end)
-- Client: only shows what the server decided
local ok, status, item = chests:Function("Open", { Timeout = 5 }):Invoke("Basic")

The math

RNG

Every function takes an optional rng. It can be a Roblox Random object, or any table whose NextNumber() returns a number in [0, 1). Values outside that range raise an error. Tests use a fixed-value table so boundaries can be checked exactly.

API

Member Description
R.choose(entries, rng?, modifiers?) Returns a Value. Validates every entry on every call, about 15–20× slower than lootTable:Roll (100 entries). Fine for occasional rolls; for anything rolled often, build a R.lootTable once and roll that
R.chooseIndex(weights, rng?) Returns an index into a plain array of weights
R.lootTable(entries) A validated, immutable table. Rolls without modifiers are O(log n)
loot:Roll(rng?, modifiers?)  
loot:RollMany(count, rng?, modifiers?)  
loot:GetChance(value, modifiers?) Probability in [0, 1]. Sums entries that share a value
loot:GetChances(modifiers?) { { Value, Chance } } in entry order
loot:GetEntries() A copy of the validated entries
R.chance(p, rng?) true with probability p (0..1)
R.shuffle(array, rng?) Shuffled copy (Fisher–Yates). The input isn’t modified