How to make an egg hatching system in Roblox (Luau)

-- ModuleScript: ReplicatedStorage > EggConfig
-- One source of truth for the server roll AND the odds the client shows.
local EggConfig = {}

EggConfig.Eggs = {
	StarterEgg = {
		price = 100,
		currency = "Coins",
		pets = {
			{ name = "Puffer", rarity = "Common", weight = 60 },
			{ name = "Clownfish", rarity = "Rare", weight = 30 },
			{ name = "GhostJelly", rarity = "Epic", weight = 9 },
			{ name = "BatRay", rarity = "Legendary", weight = 1 },
		},
	},
}

-- Weights -> percentages for the egg stand UI (they always sum to 100)
function EggConfig.getOdds(eggName: string)
	local egg = EggConfig.Eggs[eggName]
	local total = 0
	for _, pet in egg.pets do
		total += pet.weight
	end
	local odds = {}
	for _, pet in egg.pets do
		table.insert(odds, { name = pet.name, rarity = pet.rarity, percent = pet.weight / total * 100 })
	end
	return odds
end

return EggConfig

-- Script: ServerScriptService > HatchService
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local DataStoreService = game:GetService("DataStoreService")
local MarketplaceService = game:GetService("MarketplaceService")
local HttpService = game:GetService("HttpService")

local EggConfig = require(ReplicatedStorage:WaitForChild("EggConfig"))
local store = DataStoreService:GetDataStore("PlayerData_v1")

local hatchRemote = Instance.new("RemoteFunction")
hatchRemote.Name = "HatchEgg"
hatchRemote.Parent = ReplicatedStorage

local TRIPLE_HATCH_PASS = 0 -- your game pass ID
local MAX_PETS = 200
local COOLDOWN = 1 -- seconds between hatches per player
local MAX_DISTANCE = 15 -- studs from the egg stand

local rng = Random.new()
local sessions = {} -- [Player] = { coins, pets }
local lastHatch = {} -- [Player] = os.clock()
local hasTriple = {} -- [Player] = boolean

local function rollPet(egg)
	local total = 0
	for _, pet in egg.pets do
		total += pet.weight
	end
	local roll = rng:NextNumber(0, total)
	local running = 0
	for _, pet in egg.pets do
		running += pet.weight
		if roll < running then
			return pet
		end
	end
	return egg.pets[#egg.pets] -- roll == total (edge case)
end

local function load(player: Player)
	local ok, data = pcall(function()
		return store:GetAsync(tostring(player.UserId))
	end)
	if not ok then
		player:Kick("Could not load your data. Please rejoin.")
		return
	end
	sessions[player] = data or { coins = 500, pets = {} }
	player:SetAttribute("Coins", sessions[player].coins)

	local passOk, owns = pcall(function()
		return MarketplaceService:UserOwnsGamePassAsync(player.UserId, TRIPLE_HATCH_PASS)
	end)
	hasTriple[player] = passOk and owns
end

local function save(player: Player)
	local data = sessions[player]
	if not data then
		return
	end
	local ok, err = pcall(function()
		store:UpdateAsync(tostring(player.UserId), function()
			return data
		end)
	end)
	if not ok then
		warn("Save failed for", player.UserId, err)
	end
end

hatchRemote.OnServerInvoke = function(player: Player, eggName: unknown, count: unknown)
	local data = sessions[player]
	local egg = if typeof(eggName) == "string" then EggConfig.Eggs[eggName] else nil
	if not data or not egg then
		return { ok = false, reason = "Unknown egg" }
	end
	if count ~= 1 and count ~= 3 then
		return { ok = false, reason = "Bad count" }
	end
	if count == 3 and not hasTriple[player] then
		return { ok = false, reason = "Triple hatch needs the game pass" }
	end

	local now = os.clock()
	if lastHatch[player] and now - lastHatch[player] < COOLDOWN then
		return { ok = false, reason = "Too fast" }
	end

	local stand = workspace:FindFirstChild("Eggs") and workspace.Eggs:FindFirstChild(eggName)
	local root = player.Character and player.Character:FindFirstChild("HumanoidRootPart")
	if not stand or not root or (root.Position - stand:GetPivot().Position).Magnitude > MAX_DISTANCE then
		return { ok = false, reason = "Too far from the egg" }
	end

	local cost = egg.price * count
	if data.coins < cost then
		return { ok = false, reason = "Not enough coins" }
	end
	if #data.pets + count > MAX_PETS then
		return { ok = false, reason = "Inventory full" }
	end

	lastHatch[player] = now
	data.coins -= cost
	local results = {}
	for _ = 1, count do
		local pet = rollPet(egg)
		local entry = { id = HttpService:GenerateGUID(false), name = pet.name, rarity = pet.rarity }
		table.insert(data.pets, entry)
		table.insert(results, entry)
	end
	player:SetAttribute("Coins", data.coins)
	return { ok = true, pets = results }
end

Players.PlayerAdded:Connect(load)
for _, player in Players:GetPlayers() do
	task.spawn(load, player)
end

Players.PlayerRemoving:Connect(function(player)
	save(player)
	sessions[player] = nil
	lastHatch[player] = nil
	hasTriple[player] = nil
end)

game:BindToClose(function()
	for _, player in Players:GetPlayers() do
		save(player)
	end
end)

-- LocalScript: StarterPlayer > StarterPlayerScripts > HatchClient
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local TweenService = game:GetService("TweenService")

local player = Players.LocalPlayer
local hatchRemote = ReplicatedStorage:WaitForChild("HatchEgg")
local EggModels = ReplicatedStorage:WaitForChild("EggModels")
local PetModels = ReplicatedStorage:WaitForChild("PetModels")

local gui = Instance.new("ScreenGui")
gui.IgnoreGuiInset = true
gui.ResetOnSpawn = false
gui.Parent = player:WaitForChild("PlayerGui")

local flash = Instance.new("Frame")
flash.Size = UDim2.fromScale(1, 1)
flash.BackgroundColor3 = Color3.new(1, 1, 1)
flash.BackgroundTransparency = 1
flash.Parent = gui

local busy = false

local function localCopy(template: Model): Model
	local model = template:Clone()
	for _, part in model:GetDescendants() do
		if part:IsA("BasePart") then
			part.Anchored = true
			part.CanCollide = false
		end
	end
	model.Parent = workspace
	return model
end

-- Slot i of n: a row in front of the camera, turned to face it
local function slot(i: number, n: number): CFrame
	local x = (i - (n + 1) / 2) * 4
	return workspace.CurrentCamera.CFrame * CFrame.new(x, -1, -8) * CFrame.Angles(0, math.pi, 0)
end

local function playHatch(eggName: string, pets)
	local n = #pets
	local eggs = {}
	for i = 1, n do
		eggs[i] = localCopy(EggModels[eggName])
	end

	-- 1. shake: wobble grows for 1.5 seconds
	local elapsed = 0
	while elapsed < 1.5 do
		local strength = math.rad(4 + elapsed * 12)
		for i, egg in eggs do
			egg:PivotTo(slot(i, n) * CFrame.Angles(0, 0, math.sin(elapsed * 30) * strength))
		end
		elapsed += task.wait()
	end

	-- 2. crack: white flash, eggs vanish
	local flashIn = TweenService:Create(flash, TweenInfo.new(0.15), { BackgroundTransparency = 0 })
	flashIn:Play()
	flashIn.Completed:Wait()
	for _, egg in eggs do
		egg:Destroy()
	end

	-- 3. reveal: pets pop in with a spin, flash fades out
	local shown = {}
	local grow = Instance.new("NumberValue")
	for i, entry in pets do
		shown[i] = localCopy(PetModels[entry.name])
		shown[i]:ScaleTo(0.01)
		shown[i]:PivotTo(slot(i, n))
	end
	grow.Changed:Connect(function(t)
		for i, pet in shown do
			pet:ScaleTo(math.max(t, 0.01))
			pet:PivotTo(slot(i, n) * CFrame.Angles(0, (1 - t) * math.pi * 2, 0))
		end
	end)
	TweenService:Create(flash, TweenInfo.new(0.4), { BackgroundTransparency = 1 }):Play()
	local pop = TweenService:Create(grow, TweenInfo.new(0.6, Enum.EasingStyle.Back, Enum.EasingDirection.Out), { Value = 1 })
	pop:Play()
	pop.Completed:Wait()

	task.wait(1.5) -- show the name and rarity in your UI here
	for _, pet in shown do
		pet:Destroy()
	end
	grow:Destroy()
end

local function hatch(eggName: string, count: number): boolean
	if busy then
		return false
	end
	busy = true
	local result = hatchRemote:InvokeServer(eggName, count)
	if result.ok then
		playHatch(eggName, result.pets)
	else
		warn(result.reason) -- show it in your UI
	end
	busy = false
	return result.ok
end

-- Wire this to your egg stand: a ProximityPrompt or a "Hatch" / "Hatch 3" button
-- hatch("StarterEgg", 1)

-- Auto hatch: repeat single hatches until the player turns it off or a hatch fails
local autoHatching = false
local function setAutoHatch(on: boolean, eggName: string)
	autoHatching = on
	while autoHatching and hatch(eggName, 1) do
		task.wait(0.2)
	end
	autoHatching = false
end

-- Server: check before offering eggs bought with Robux or paid currency
local PolicyService = game:GetService("PolicyService")

local function canUsePaidRandomItems(player: Player): boolean
	local ok, policy = pcall(function()
		return PolicyService:GetPolicyInfoForPlayerAsync(player)
	end)
	-- if the check fails, treat the player as restricted
	return ok and not policy.ArePaidRandomItemsRestricted
end