Skip to content

Souvik-223/agent-skills-agentic-tools / .agents/skills/game-development/roblox-games

roblox-game

Verified

Expert Roblox game development companion — Luau, Roblox Studio, MCP integration, simulator, tycoon, obby, RPG, horror, battle royale, game design, security, performance.

FileKindSize
.gitignoreother9 B
README.mdmarkdown5.2 KB
SKILL.mdskill md5.1 KB
docs/plans/2026-03-04-roblox-game-skill-design.mdmarkdown11.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/_index.mdmarkdown5.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-001-create-directory-structure.mdmarkdown753 B
docs/plans/2026-03-04-roblox-game-skill-plan/task-002-write-skill-router.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-003-luau-mastery.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-004-architecture-patterns.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-005-mcp-orchestration.mdmarkdown2.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-006-security-hardening.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-007-datastore-persistence.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-008-gui-systems.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-009-performance-optimization.mdmarkdown2.2 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-010-monetization-systems.mdmarkdown2.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-011-combat-systems.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-012-inventory-systems.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-013-game-design-roblox.mdmarkdown2.1 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-014-tooling-ecosystem.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-015-animation-vfx.mdmarkdown2.0 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-016-multiplayer-networking.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-017-testing-patterns.mdmarkdown1.9 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-018-sharp-edges.mdmarkdown2.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-019-game-scaffold.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-020-genre-simulator.mdmarkdown1.8 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-021-genre-tycoon.mdmarkdown1.3 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-022-genre-obby.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-023-genre-rpg.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-024-genre-horror.mdmarkdown1.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-025-genre-battle-royale.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-026-workflow-new-game.mdmarkdown1.6 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-027-workflow-debug-loop.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-028-workflow-performance-audit.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-029-workflow-security-audit.mdmarkdown1.4 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-030-workflow-publish-checklist.mdmarkdown1.7 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-031-workflow-monetization-audit.mdmarkdown1.5 KB
docs/plans/2026-03-04-roblox-game-skill-plan/task-032-workflow-code-review.mdmarkdown1.6 KB
references/animation-vfx.mdmarkdown38.4 KB
references/architecture-patterns.mdmarkdown32.2 KB
references/combat-systems.mdmarkdown42.0 KB
references/datastore-persistence.mdmarkdown31.6 KB
references/game-design-roblox.mdmarkdown34.9 KB
references/gui-systems.mdmarkdown46.2 KB
references/inventory-systems.mdmarkdown51.7 KB
references/luau-mastery.mdmarkdown42.9 KB
references/mcp-orchestration.mdmarkdown16.4 KB
references/monetization-systems.mdmarkdown24.4 KB
references/multiplayer-networking.mdmarkdown50.0 KB
references/performance-optimization.mdmarkdown17.7 KB
references/security-hardening.mdmarkdown35.2 KB
references/sharp-edges.mdmarkdown40.3 KB
references/testing-patterns.mdmarkdown29.6 KB
references/tooling-ecosystem.mdmarkdown29.2 KB
templates/game-scaffold.mdmarkdown57.6 KB
templates/genre-battle-royale.mdmarkdown44.2 KB
templates/genre-horror.mdmarkdown49.9 KB
templates/genre-obby.mdmarkdown26.0 KB
templates/genre-rpg.mdmarkdown43.2 KB
templates/genre-simulator.mdmarkdown48.7 KB
templates/genre-tycoon.mdmarkdown50.9 KB
workflows/code-review.mdmarkdown10.3 KB
workflows/debug-loop.mdmarkdown7.8 KB
workflows/monetization-audit.mdmarkdown11.3 KB
workflows/new-game.mdmarkdown19.6 KB
workflows/performance-audit.mdmarkdown7.6 KB
workflows/publish-checklist.mdmarkdown9.6 KB
workflows/security-audit.mdmarkdown9.1 KB

templates/genre-battle-royale.md

View on GitHub
# Genre Template: Battle Royale

## 1. Genre Overview

**Core Loop:** Drop --> Loot --> Survive --> Fight --> Win

Players deploy from a high point above the map, choose a landing spot, scavenge for weapons
and items, and fight to be the last player (or squad) standing while a shrinking safe zone
forces encounters.

**Key Pillars:**
- **Tension Curve** — Early game is looting and positioning; mid game is rotating to safe zone;
  late game is intense close-quarters combat.
- **Fair Starts** — Everyone drops with nothing. No permanent power advantages.
- **Emergent Gameplay** — Random loot placement and zone movement ensure no two matches feel the same.
- **High Stakes** — One life per match. Elimination is permanent (spectate or return to lobby).

**Roblox Examples:**
- BIG Paintball (arena variant with respawns, but loot/loadout loop applies)
- Arsenal (fast-paced weapon rotation, arena BR hybrid)
- Island Royale (classic BR format on Roblox)

**Typical Match Flow:**
1. Players gather in lobby while queue fills (30-60s)
2. Countdown begins once minimum player count reached
3. All players teleport to drop vehicle/sky platform
4. Free-fall with parachute to choose landing spot
5. Loot weapons, armor, consumables from spawn points
6. Storm/zone begins shrinking on a timer
7. Players eliminate each other; eliminated players spectate
8. Last player/squad alive wins
9. XP/rewards distributed, return to lobby

---

## 2. Architecture Blueprint

```
ServerScriptService/
  BattleRoyale/
    MatchManager.lua          -- State machine, round lifecycle
    StormSystem.lua           -- Zone shrink logic, damage ticks
    LootSpawner.lua           -- Item distribution across map
    EliminationTracker.lua    -- Kill feed, placements, stats
    DropSystem.lua            -- Sky deploy, parachute, landing
    SpectatorSystem.lua       -- Camera follow on elimination
    WeaponManager.lua         -- Weapon stats, rarity scaling
    InventoryManager.lua      -- Per-match inventory (not persistent)
    AntiCheat.lua             -- Server-side hit validation

ReplicatedStorage/
  BattleRoyale/
    Config.lua                -- Match settings, zone timings, loot tables
    WeaponDefs.lua            -- Weapon definitions and rarity stats
    Remotes/                  -- Folder of RemoteEvents/RemoteFunctions
      MatchState.lua          -- Replicate match phase to clients
      ZoneUpdate.lua          -- Broadcast zone position/radius
      KillFeed.lua            -- Broadcast eliminations
      SpectatorTarget.lua     -- Spectator camera target changes
      DropInput.lua           -- Player deploy/parachute input

StarterPlayerScripts/
  BattleRoyale/
    HUDController.lua         -- Health, kill count, alive count, zone timer
    MinimapController.lua     -- Minimap with zone overlay
    SpectatorController.lua   -- Spectator camera input
    DropController.lua        -- Parachute input and camera during drop
    LootPickupUI.lua          -- Proximity prompts for item pickup

StarterGui/
  BattleRoyaleHUD/
    KillFeed.gui              -- Kill feed overlay
    Minimap.gui               -- Minimap with storm circle
    MatchInfo.gui             -- Alive count, placement, zone timer
    Inventory.gui             -- Current loadout display
    VictoryScreen.gui         -- Winner announcement
    SpectatorHUD.gui          -- Spectating player info
```

**Module Responsibilities:**

| Module | Responsibility | Runs On |
|---|---|---|
| MatchManager | State machine, phase transitions, win detection | Server |
| StormSystem | Zone center, radius, shrink schedule, damage ticks | Server |
| LootSpawner | Place weapons/items at spawn points on match start | Server |
| EliminationTracker | Kill credit, placement tracking, kill feed broadcasts | Server |
| DropSystem | Sky teleport, free-fall physics, parachute deploy | Server + Client |
| SpectatorSystem | Camera assignment on elimination, player cycling | Server + Client |
| WeaponManager | Damage calculation, rarity stat scaling, hit validation | Server |
| InventoryManager | Per-match loadout, pickup/drop, ammo tracking | Server |

---

## 3. Core Systems (Luau Code)

### 3.1 Match Lifecycle State Machine

The match flows through discrete phases. A single `MatchState` value drives all systems.

```
Lobby --> Waiting --> Countdown --> Deploying --> InProgress --> Victory --> Cleanup --> Lobby
```

```luau
--!strict
-- ServerScriptService/BattleRoyale/MatchManager.lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local Config = require(ReplicatedStorage.BattleRoyale.Config)
local StormSystem = require(script.Parent.StormSystem)
local LootSpawner = require(script.Parent.LootSpawner)
local EliminationTracker = require(script.Parent.EliminationTracker)
local DropSystem = require(script.Parent.DropSystem)
local SpectatorSystem = require(script.Parent.SpectatorSystem)

local MatchStateRemote = ReplicatedStorage.BattleRoyale.Remotes.MatchState

export type MatchPhase =
	"Lobby"
	| "Waiting"
	| "Countdown"
	| "Deploying"
	| "InProgress"
	| "Victory"
	| "Cleanup"

local MatchManager = {}
MatchManager.__index = MatchManager

function MatchManager.new()
	local self = setmetatable({}, MatchManager)
	self._phase = "Lobby" :: MatchPhase
	self._alivePlayers = {} :: { [Player]: boolean }
	self._matchStartTime = 0
	self._countdownRemaining = Config.COUNTDOWN_DURATION
	self._winner = nil :: Player?
	return self
end

function MatchManager:GetPhase(): MatchPhase
	return self._phase
end

function MatchManager:GetAlivePlayers(): { Player }
	local alive = {}
	for player, isAlive in self._alivePlayers do
		if isAlive and player.Parent then
			table.insert(alive, player)
		end
	end
	return alive
end

function MatchManager:GetAliveCount(): number
	return #self:GetAlivePlayers()
end

function MatchManager:_setPhase(newPhase: MatchPhase)
	local oldPhase = self._phase
	self._phase = newPhase
	print(`[MatchManager] Phase: {oldPhase} -> {newPhase}`)
	MatchStateRemote:FireAllClients(newPhase)
end

function MatchManager:_transitionTo(phase: MatchPhase)
	local handlers: { [MatchPhase]: () -> () } = {
		Lobby = function()
			self:_setPhase("Lobby")
			-- Reset all systems
			self._alivePlayers = {}
			self._winner = nil
			EliminationTracker:Reset()
			SpectatorSystem:Reset()
		end,

		Waiting = function()
			self:_setPhase("Waiting")
			-- Wait for minimum players
			while self._phase == "Waiting" do
				local playerCount = #Players:GetPlayers()
				if playerCount >= Config.MIN_PLAYERS then
					self:_transitionTo("Countdown")
					return
				end
				task.wait(1)
			end
		end,

		Countdown = function()
			self:_setPhase("Countdown")
			self._countdownRemaining = Config.COUNTDOWN_DURATION

			for i = Config.COUNTDOWN_DURATION, 1, -1 do
				if self._phase ~= "Countdown" then return end
				self._countdownRemaining = i
				MatchStateRemote:FireAllClients("Countdown", i)

				-- If players drop below minimum during countdown, abort
				if #Players:GetPlayers() < Config.MIN_PLAYERS then
					self:_transitionTo("Waiting")
					return
				end
				task.wait(1)
			end

			self:_transitionTo("Deploying")
		end,

		Deploying = function()
			self:_setPhase("Deploying")

			-- Register all current players as alive
			for _, player in Players:GetPlayers() do
				self._alivePlayers[player] = true
			end

			-- Spawn loot across the map before players land
			LootSpawner:SpawnAllLoot()

			-- Teleport players to sky and begin drop sequence
			DropSystem:DeployAllPlayers(self:GetAlivePlayers())

			-- Wait for deploy phase duration (players are free-falling)
			task.wait(Config.DEPLOY_DURATION)

			self:_transitionTo("InProgress")
		end,

		InProgress = function()
			self:_setPhase("InProgress")
			self._matchStartTime = os.clock()

			-- Start the storm system
			StormSystem:Start()

			-- Main match loop: check for winner
			while self._phase == "InProgress" do
				local aliveCount = self:GetAliveCount()

				if aliveCount <= 1 then
					local alivePlayers = self:GetAlivePlayers()
					if #alivePlayers == 1 then
						self._winner = alivePlayers[1]
					end
					self:_transitionTo("Victory")
					return
				end

				-- Tick storm system
				StormSystem:Tick()

				task.wait(0.5)
			end
		end,

		Victory = function()
			self:_setPhase("Victory")

			-- Announce winner
			if self._winner then
				MatchStateRemote:FireAllClients("Victory", self._winner.Name)
				print(`[MatchManager] Winner: {self._winner.Name}`)
			else
				MatchStateRemote:FireAllClients("Victory", nil)
				print("[MatchManager] No winner (draw or all eliminated)")
			end

			-- Award XP / rewards here
			EliminationTracker:FinalizeResults(self._winner)

			-- Show victory screen for a few seconds
			task.wait(Config.VICTORY_SCREEN_DURATION)
			self:_transitionTo("Cleanup")
		end,

		Cleanup = function()
			self:_setPhase("Cleanup")

			-- Stop storm
			StormSystem:Stop()

			-- Despawn remaining loot
			LootSpawner:DespawnAllLoot()

			-- Reset drop system
			DropSystem:Reset()

			-- Teleport remaining players back to lobby spawn
			for _, player in Players:GetPlayers() do
				local lobbySpawn = workspace.LobbySpawn
				if player.Character and lobbySpawn then
					player.Character:PivotTo(lobbySpawn.CFrame + Vector3.new(0, 5, 0))
				end
			end

			task.wait(Config.CLEANUP_DURATION)
			self:_transitionTo("Lobby")
		end,
	}

	local handler = handlers[phase]
	if handler then
		handler()
	else
		warn(`[MatchManager] Unknown phase: {phase}`)
	end
end

function MatchManager:EliminatePlayer(player: Player, killer: Player?)
	if not self._alivePlayers[player] then return end

	self._alivePlayers[player] = false
	local placement = self:GetAliveCount() + 1

	EliminationTracker:RecordElimination(player, killer, placement)
	SpectatorSystem:BeginSpectating(player, self:GetAlivePlayers())

	print(`[MatchManager] {player.Name} eliminated (#{placement}). {self:GetAliveCount()} remain.`)
end

-- Handle player disconnect during match
function MatchManager:OnPlayerRemoving(player: Player)
	if self._alivePlayers[player] then
		self._alivePlayers[player] = nil
		EliminationTracker:RecordDisconnect(player, self:GetAliveCount() + 1)
	end
end

function MatchManager:Start()
	-- Listen for player disconnects
	Players.PlayerRemoving:Connect(function(player)
		self:OnPlayerRemoving(player)
	end)

	-- Begin the match cycle
	while true do
		self:_transitionTo("Lobby")
		task.wait(Config.LOBBY_INTERMISSION)
		self:_transitionTo("Waiting")
		-- Waiting will chain into Countdown -> Deploying -> InProgress -> Victory -> Cleanup -> Lobby
		task.wait(1)
	end
end

return MatchManager
```

**Config module (referenced above):**

```luau
--!strict
-- ReplicatedStorage/BattleRoyale/Config.lua

local Config = {
	-- Player counts
	MIN_PLAYERS = 4,
	MAX_PLAYERS = 50,

	-- Phase durations (seconds)
	LOBBY_INTERMISSION = 10,
	COUNTDOWN_DURATION = 10,
	DEPLOY_DURATION = 15,
	VICTORY_SCREEN_DURATION = 8,
	CLEANUP_DURATION = 5,

	-- Storm / Zone
	ZONE_INITIAL_RADIUS = 500,      -- studs
	ZONE_DAMAGE_PER_TICK = 5,
	ZONE_TICK_INTERVAL = 1.0,       -- seconds between damage ticks
	ZONE_PHASES = {
		{ waitTime = 60, shrinkTime = 30, radiusFraction = 0.6 },
		{ waitTime = 45, shrinkTime = 25, radiusFraction = 0.35 },
		{ waitTime = 30, shrinkTime = 20, radiusFraction = 0.15 },
		{ waitTime = 20, shrinkTime = 15, radiusFraction = 0.05 },
		{ waitTime = 10, shrinkTime = 10, radiusFraction = 0.0 },
	},

	-- Loot
	LOOT_SPAWN_TAG = "LootSpawn",
	RARITY_WEIGHTS = {
		Common = 40,
		Uncommon = 30,
		Rare = 18,
		Epic = 9,
		Legendary = 3,
	},

	-- Drop system
	DROP_HEIGHT = 500,               -- studs above map center
	PARACHUTE_DEPLOY_HEIGHT = 100,   -- auto-deploy parachute below this
	FALL_SPEED = 80,                 -- studs/sec during free fall
	PARACHUTE_SPEED = 30,            -- studs/sec with parachute

	-- Spectator
	SPECTATOR_CYCLE_COOLDOWN = 0.5,  -- seconds between switching targets
}

return Config
```

---

### 3.2 Shrinking Zone / Storm System

The zone is a circle on the XZ plane. Each phase picks a new smaller circle inside the
current safe area. The zone interpolates from current to target over the shrink duration.
Players outside take periodic damage.

```luau
--!strict
-- ServerScriptService/BattleRoyale/StormSystem.lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local Config = require(ReplicatedStorage.BattleRoyale.Config)
local ZoneUpdateRemote = ReplicatedStorage.BattleRoyale.Remotes.ZoneUpdate

local StormSystem = {}
StormSystem.__index = StormSystem

export type ZoneState = {
	centerX: number,
	centerZ: number,
	radius: number,
}

function StormSystem.new()
	local self = setmetatable({}, StormSystem)

	-- Current visible zone (what players see and what deals damage)
	self._currentZone = {
		centerX = 0,
		centerZ = 0,
		radius = Config.ZONE_INITIAL_RADIUS,
	} :: ZoneState

	-- Target zone the current zone is shrinking toward
	self._targetZone = {
		centerX = 0,
		centerZ = 0,
		radius = Config.ZONE_INITIAL_RADIUS,
	} :: ZoneState

	self._phaseIndex = 0
	self._isShrinking = false
	self._running = false
	self._damageTickAccumulator = 0

	-- Map bounds (set based on your map dimensions)
	self._mapCenterX = 0
	self._mapCenterZ = 0

	return self
end

-- Check if a world position is inside the current safe zone
function StormSystem:IsInsideZone(position: Vector3): boolean
	local dx = position.X - self._currentZone.centerX
	local dz = position.Z - self._currentZone.centerZ
	local distSquared = dx * dx + dz * dz
	return distSquared <= self._currentZone.radius * self._currentZone.radius
end

-- Pick a random point inside the current zone for the next smaller zone center
function StormSystem:_pickNextCenter(currentZone: ZoneState, nextRadius: number): (number, number)
	-- The new center must be placed so the new circle fits inside the old one
	local maxOffset = math.max(0, currentZone.radius - nextRadius)

	if maxOffset <= 0 then
		return currentZone.centerX, currentZone.centerZ
	end

	local angle = math.random() * 2 * math.pi
	local distance = math.random() * maxOffset
	local newCenterX = currentZone.centerX + math.cos(angle) * distance
	local newCenterZ = currentZone.centerZ + math.sin(angle) * distance

	return newCenterX, newCenterZ
end

-- Broadcast current zone state to all clients (for minimap rendering)
function StormSystem:_broadcastZone()
	ZoneUpdateRemote:FireAllClients(
		self._currentZone.centerX,
		self._currentZone.centerZ,
		self._currentZone.radius,
		self._targetZone.centerX,
		self._targetZone.centerZ,
		self._targetZone.radius,
		self._isShrinking
	)
end

-- Apply damage to all players outside the safe zone
function StormSystem:_applyStormDamage()
	for _, player in Players:GetPlayers() do
		local character = player.Character
		if not character then continue end

		local humanoid = character:FindFirstChildOfClass("Humanoid")
		local rootPart = character:FindFirstChild("HumanoidRootPart") :: BasePart?
		if not humanoid or not rootPart then continue end
		if humanoid.Health <= 0 then continue end

		if not self:IsInsideZone(rootPart.Position) then
			-- Scale damage by phase for increasing urgency
			local damageMultiplier = math.max(1, self._phaseIndex)
			local damage = Config.ZONE_DAMAGE_PER_TICK * damageMultiplier
			humanoid:TakeDamage(damage)
		end
	end
end

-- Run a single shrink phase: wait, then interpolate zone to target
function StormSystem:_runPhase(phaseConfig: { waitTime: number, shrinkTime: number, radiusFraction: number })
	local nextRadius = Config.ZONE_INITIAL_RADIUS * phaseConfig.radiusFraction
	local nextCenterX, nextCenterZ = self:_pickNextCenter(self._currentZone, nextRadius)

	self._targetZone = {
		centerX = nextCenterX,
		centerZ = nextCenterZ,
		radius = nextRadius,
	}

	-- Phase 1: Wait period (zone is static, target is shown on minimap)
	self._isShrinking = false
	self:_broadcastZone()
	print(`[StormSystem] Phase {self._phaseIndex}: waiting {phaseConfig.waitTime}s before shrink`)

	local waitElapsed = 0
	while waitElapsed < phaseConfig.waitTime and self._running do
		task.wait(1)
		waitElapsed += 1
	end

	if not self._running then return end

	-- Phase 2: Shrink period (interpolate current zone toward target)
	self._isShrinking = true
	self:_broadcastZone()
	print(`[StormSystem] Phase {self._phaseIndex}: shrinking over {phaseConfig.shrinkTime}s`)

	local startZone: ZoneState = {
		centerX = self._currentZone.centerX,
		centerZ = self._currentZone.centerZ,
		radius = self._currentZone.radius,
	}

	local shrinkElapsed = 0
	while shrinkElapsed < phaseConfig.shrinkTime and self._running do
		local dt = task.wait()
		shrinkElapsed += dt

		local alpha = math.clamp(shrinkElapsed / phaseConfig.shrinkTime, 0, 1)
		-- Smooth ease-in-out interpolation
		local smoothAlpha = alpha * alpha * (3 - 2 * alpha)

		self._currentZone.centerX = startZone.centerX + (self._targetZone.centerX - startZone.centerX) * smoothAlpha
		self._currentZone.centerZ = startZone.centerZ + (self._targetZone.centerZ - startZone.centerZ) * smoothAlpha
		self._currentZone.radius = startZone.radius + (self._targetZone.radius - startZone.radius) * smoothAlpha

		self:_broadcastZone()
	end

	-- Snap to target at end of shrink
	self._currentZone.centerX = self._targetZone.centerX
	self._currentZone.centerZ = self._targetZone.centerZ
	self._currentZone.radius = self._targetZone.radius
	self._isShrinking = false
	self:_broadcastZone()
end

-- Called every match tick from MatchManager
function StormSystem:Tick()
	if not self._running then return end

	self._damageTickAccumulator += 0.5 -- called every 0.5s from MatchManager
	if self._damageTickAccumulator >= Config.ZONE_TICK_INTERVAL then
		self._damageTickAccumulator -= Config.ZONE_TICK_INTERVAL
		self:_applyStormDamage()
	end
end

function StormSystem:Start()
	self._running = true
	self._phaseIndex = 0
	self._damageTickAccumulator = 0

	-- Reset zone to full size
	self._currentZone = {
		centerX = self._mapCenterX,
		centerZ = self._mapCenterZ,
		radius = Config.ZONE_INITIAL_RADIUS,
	}
	self._targetZone = {
		centerX = self._mapCenterX,
		centerZ = self._mapCenterZ,
		radius = Config.ZONE_INITIAL_RADIUS,
	}

	self:_broadcastZone()

	-- Run zone phases in sequence on a separate thread
	task.spawn(function()
		for i, phaseConfig in Config.ZONE_PHASES do
			if not self._running then break end
			self._phaseIndex = i
			self:_runPhase(phaseConfig)
		end

		-- After all phases: zone is fully closed, max damage
		print("[StormSystem] All phases complete. Zone fully closed.")
	end)
end

function StormSystem:Stop()
	self._running = false
end

return StormSystem
```

**Client-side minimap zone rendering (outline):**

```luau
--!strict
-- StarterPlayerScripts/BattleRoyale/MinimapController.lua (zone portion)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ZoneUpdateRemote = ReplicatedStorage.BattleRoyale.Remotes.ZoneUpdate

-- References to minimap UI circles (Frame objects with UICorner for circle shape)
local minimapFrame = script.Parent:WaitForChild("Minimap")
local currentZoneIndicator = minimapFrame:WaitForChild("CurrentZone")   -- ImageLabel, circle
local targetZoneIndicator = minimapFrame:WaitForChild("TargetZone")     -- ImageLabel, circle, dashed

local MINIMAP_SCALE = 0.5  -- studs-to-pixels ratio for your minimap

local function worldToMinimap(worldX: number, worldZ: number): (number, number)
	-- Convert world XZ to minimap pixel position relative to minimap center
	local minimapCenterX = minimapFrame.AbsoluteSize.X / 2
	local minimapCenterY = minimapFrame.AbsoluteSize.Y / 2
	return minimapCenterX + worldX * MINIMAP_SCALE, minimapCenterY + worldZ * MINIMAP_SCALE
end

local function updateZoneCircle(indicator: GuiObject, centerX: number, centerZ: number, radius: number)
	local px, py = worldToMinimap(centerX, centerZ)
	local pixelRadius = radius * MINIMAP_SCALE
	local diameter = pixelRadius * 2

	indicator.Position = UDim2.fromOffset(px - pixelRadius, py - pixelRadius)
	indicator.Size = UDim2.fromOffset(diameter, diameter)
end

ZoneUpdateRemote.OnClientEvent:Connect(function(
	curCenterX: number, curCenterZ: number, curRadius: number,
	tgtCenterX: number, tgtCenterZ: number, tgtRadius: number,
	isShrinking: boolean
)
	updateZoneCircle(currentZoneIndicator, curCenterX, curCenterZ, curRadius)
	updateZoneCircle(targetZoneIndicator, tgtCenterX, tgtCenterZ, tgtRadius)

	-- Show target zone indicator only when zone will shrink next
	targetZoneIndicator.Visible = (tgtRadius < curRadius)

	-- Visual feedback: change zone border color when shrinking
	if isShrinking then
		currentZoneIndicator.ImageColor3 = Color3.fromRGB(255, 80, 80)  -- red when moving
	else
		currentZoneIndicator.ImageColor3 = Color3.fromRGB(80, 160, 255) -- blue when static
	end
end)
```

---

### 3.3 Loot Spawning

```luau
--!strict
-- ServerScriptService/BattleRoyale/LootSpawner.lua

local CollectionService = game:GetService("CollectionService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ServerStorage = game:GetService("ServerStorage")

local Config = require(ReplicatedStorage.BattleRoyale.Config)
local WeaponDefs = require(ReplicatedStorage.BattleRoyale.WeaponDefs)

local LootSpawner = {}

local spawnedLoot: { Instance } = {}

-- Select a rarity tier using weighted random
function LootSpawner:_rollRarity(): string
	local totalWeight = 0
	for _, weight in Config.RARITY_WEIGHTS do
		totalWeight += weight
	end

	local roll = math.random() * totalWeight
	local cumulative = 0
	for rarity, weight in Config.RARITY_WEIGHTS do
		cumulative += weight
		if roll <= cumulative then
			return rarity
		end
	end
	return "Common"
end

-- Pick a random weapon definition of the given rarity
function LootSpawner:_pickWeapon(rarity: string): string?
	local candidates = {}
	for weaponName, def in WeaponDefs do
		if def.rarity == rarity then
			table.insert(candidates, weaponName)
		end
	end
	if #candidates == 0 then return nil end
	return candidates[math.random(#candidates)]
end

function LootSpawner:SpawnAllLoot()
	self:DespawnAllLoot()

	local spawnPoints = CollectionService:GetTagged(Config.LOOT_SPAWN_TAG)
	print(`[LootSpawner] Spawning loot at {#spawnPoints} points`)

	for _, spawnPoint in spawnPoints do
		if not spawnPoint:IsA("BasePart") then continue end

		local rarity = self:_rollRarity()
		local weaponName = self:_pickWeapon(rarity)
		if not weaponName then continue end

		-- Clone weapon model from ServerStorage
		local weaponTemplate = ServerStorage:FindFirstChild("Weapons")
			and ServerStorage.Weapons:FindFirstChild(weaponName)
		if not weaponTemplate then continue end

		local lootItem = weaponTemplate:Clone()
		lootItem:PivotTo(spawnPoint.CFrame + Vector3.new(0, 1, 0))

		-- Attach metadata
		local rarityValue = Instance.new("StringValue")
		rarityValue.Name = "Rarity"
		rarityValue.Value = rarity
		rarityValue.Parent = lootItem

		-- Add proximity prompt for pickup
		local prompt = Instance.new("ProximityPrompt")
		prompt.ActionText = "Pick Up"
		prompt.ObjectText = `{weaponName} ({rarity})`
		prompt.HoldDuration = 0.15
		prompt.MaxActivationDistance = 8
		prompt.Parent = lootItem.PrimaryPart or lootItem:FindFirstChildWhichIsA("BasePart")

		lootItem.Parent = workspace.LootFolder

		table.insert(spawnedLoot, lootItem)
	end

	print(`[LootSpawner] Spawned {#spawnedLoot} items`)
end

function LootSpawner:DespawnAllLoot()
	for _, item in spawnedLoot do
		if item.Parent then
			item:Destroy()
		end
	end
	table.clear(spawnedLoot)
end

return LootSpawner
```

**Weapon definitions with rarity stat scaling:**

```luau
--!strict
-- ReplicatedStorage/BattleRoyale/WeaponDefs.lua

export type WeaponDef = {
	rarity: string,
	baseDamage: number,
	fireRate: number,     -- rounds per second
	magSize: number,
	reloadTime: number,   -- seconds
	range: number,        -- max effective range in studs
	weaponType: string,   -- "AR" | "Shotgun" | "SMG" | "Sniper" | "Pistol"
}

-- Rarity multipliers applied to base damage
local RARITY_DAMAGE_SCALE = {
	Common = 1.0,
	Uncommon = 1.15,
	Rare = 1.3,
	Epic = 1.5,
	Legendary = 1.75,
}

local WeaponDefs: { [string]: WeaponDef } = {
	-- Assault Rifles
	AssaultRifle_Common     = { rarity = "Common",    baseDamage = 18, fireRate = 5.5, magSize = 30, reloadTime = 2.2, range = 200, weaponType = "AR" },
	AssaultRifle_Uncommon   = { rarity = "Uncommon",  baseDamage = 21, fireRate = 5.5, magSize = 30, reloadTime = 2.0, range = 200, weaponType = "AR" },
	AssaultRifle_Rare       = { rarity = "Rare",      baseDamage = 23, fireRate = 5.5, magSize = 30, reloadTime = 1.8, range = 200, weaponType = "AR" },
	AssaultRifle_Epic       = { rarity = "Epic",      baseDamage = 27, fireRate = 6.0, magSize = 35, reloadTime = 1.6, range = 220, weaponType = "AR" },
	AssaultRifle_Legendary  = { rarity = "Legendary", baseDamage = 32, fireRate = 6.0, magSize = 35, reloadTime = 1.4, range = 240, weaponType = "AR" },

	-- Shotguns
	Shotgun_Common    = { rarity = "Common",    baseDamage = 70,  fireRate = 1.0, magSize = 5,  reloadTime = 4.5, range = 30,  weaponType = "Shotgun" },
	Shotgun_Rare      = { rarity = "Rare",      baseDamage = 85,  fireRate = 1.0, magSize = 5,  reloadTime = 4.0, range = 35,  weaponType = "Shotgun" },
	Shotgun_Legendary = { rarity = "Legendary", baseDamage = 110, fireRate = 1.1, magSize = 6,  reloadTime = 3.5, range = 40,  weaponType = "Shotgun" },

	-- SMGs
	SMG_Common   = { rarity = "Common",   baseDamage = 12, fireRate = 10.0, magSize = 25, reloadTime = 1.8, range = 80,  weaponType = "SMG" },
	SMG_Uncommon = { rarity = "Uncommon", baseDamage = 14, fireRate = 10.0, magSize = 30, reloadTime = 1.6, range = 90,  weaponType = "SMG" },
	SMG_Epic     = { rarity = "Epic",     baseDamage = 18, fireRate = 11.0, magSize = 35, reloadTime = 1.4, range = 100, weaponType = "SMG" },

	-- Snipers
	Sniper_Rare      = { rarity = "Rare",      baseDamage = 90,  fireRate = 0.5, magSize = 5, reloadTime = 3.0, range = 500, weaponType = "Sniper" },
	Sniper_Epic      = { rarity = "Epic",      baseDamage = 105, fireRate = 0.5, magSize = 5, reloadTime = 2.8, range = 550, weaponType = "Sniper" },
	Sniper_Legendary = { rarity = "Legendary", baseDamage = 130, fireRate = 0.5, magSize = 5, reloadTime = 2.5, range = 600, weaponType = "Sniper" },

	-- Pistols
	Pistol_Common   = { rarity = "Common",   baseDamage = 22, fireRate = 3.5, magSize = 12, reloadTime = 1.5, range = 120, weaponType = "Pistol" },
	Pistol_Uncommon = { rarity = "Uncommon", baseDamage = 25, fireRate = 3.5, magSize = 15, reloadTime = 1.4, range = 130, weaponType = "Pistol" },
}

return WeaponDefs
```

---

### 3.4 Elimination Tracking

```luau
--!strict
-- ServerScriptService/BattleRoyale/EliminationTracker.lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local KillFeedRemote = ReplicatedStorage.BattleRoyale.Remotes.KillFeed

export type EliminationRecord = {
	victim: string,
	killer: string?,
	placement: number,
	timestamp: number,
}

local EliminationTracker = {}

local killCounts: { [Player]: number } = {}
local placements: { [Player]: number } = {}
local eliminations: { EliminationRecord } = {}

function EliminationTracker:Reset()
	table.clear(killCounts)
	table.clear(placements)
	table.clear(eliminations)
end

function EliminationTracker:RecordElimination(victim: Player, killer: Player?, placement: number)
	-- Track placement
	placements[victim] = placement

	-- Track kill count
	if killer and killer ~= victim then
		killCounts[killer] = (killCounts[killer] or 0) + 1
	end

	-- Log the elimination
	local record: EliminationRecord = {
		victim = victim.Name,
		killer = if killer and killer ~= victim then killer.Name else nil,
		placement = placement,
		timestamp = os.clock(),
	}
	table.insert(eliminations, record)

	-- Broadcast kill feed to all clients
	local killerName = record.killer or "The Storm"
	KillFeedRemote:FireAllClients(killerName, victim.Name, placement)

	-- Drop victim's inventory at their death location
	self:_dropInventory(victim)
end

function EliminationTracker:RecordDisconnect(player: Player, placement: number)
	placements[player] = placement

	local record: EliminationRecord = {
		victim = player.Name,
		killer = nil,
		placement = placement,
		timestamp = os.clock(),
	}
	table.insert(eliminations, record)

	KillFeedRemote:FireAllClients("Disconnect", player.Name, placement)
end

function EliminationTracker:GetKillCount(player: Player): number
	return killCounts[player] or 0
end

function EliminationTracker:GetPlacement(player: Player): number?
	return placements[player]
end

function EliminationTracker:_dropInventory(player: Player)
	-- Clone the player's held tools/weapons to the ground at their death position
	local character = player.Character
	if not character then return end

	local rootPart = character:FindFirstChild("HumanoidRootPart") :: BasePart?
	if not rootPart then return end

	local dropPosition = rootPart.CFrame

	-- Move backpack tools to workspace as loot
	for _, tool in player.Backpack:GetChildren() do
		if tool:IsA("Tool") then
			tool.Parent = workspace.LootFolder
			local handle = tool:FindFirstChild("Handle") :: BasePart?
			if handle then
				handle.CFrame = dropPosition * CFrame.new(
					math.random(-3, 3), 1, math.random(-3, 3)
				)
			end
		end
	end
end

function EliminationTracker:FinalizeResults(winner: Player?)
	print("[EliminationTracker] Match Results:")
	if winner then
		placements[winner] = 1
		print(`  1st: {winner.Name} ({self:GetKillCount(winner)} kills)`)
	end

	-- Sort and print top placements
	local sorted: { { player: string, placement: number } } = {}
	for player, placement in placements do
		table.insert(sorted, { player = player.Name, placement = placement })
	end
	table.sort(sorted, function(a, b) return a.placement < b.placement end)

	for _, entry in sorted do
		print(`  #{entry.placement}: {entry.player}`)
	end

	-- TODO: Award XP based on placement and kills
	-- XP formula example: base XP + (kills * 50) + (placement bonus)
end

return EliminationTracker
```

---

### 3.5 Spectator System

```luau
--!strict
-- ServerScriptService/BattleRoyale/SpectatorSystem.lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local SpectatorTargetRemote = ReplicatedStorage.BattleRoyale.Remotes.SpectatorTarget

local SpectatorSystem = {}

-- Map of spectating player -> currently watched player
local spectatorTargets: { [Player]: Player } = {}
-- Map of spectating player -> index in alive list (for cycling)
local spectatorIndex: { [Player]: number } = {}

function SpectatorSystem:Reset()
	table.clear(spectatorTargets)
	table.clear(spectatorIndex)
end

function SpectatorSystem:BeginSpectating(eliminated: Player, alivePlayers: { Player })
	if #alivePlayers == 0 then return end

	-- Pick first alive player as initial target
	local targetIndex = 1

	-- Prefer the player's killer if they're still alive
	spectatorIndex[eliminated] = targetIndex
	spectatorTargets[eliminated] = alivePlayers[targetIndex]

	-- Tell the eliminated player's client to enter spectator mode
	SpectatorTargetRemote:FireClient(
		eliminated,
		"StartSpectating",
		alivePlayers[targetIndex]
	)
end

function SpectatorSystem:CycleTarget(spectator: Player, direction: number, alivePlayers: { Player })
	if #alivePlayers == 0 then return end
	if not spectatorIndex[spectator] then return end

	local currentIdx = spectatorIndex[spectator]
	local newIdx = ((currentIdx - 1 + direction) % #alivePlayers) + 1

	spectatorIndex[spectator] = newIdx
	spectatorTargets[spectator] = alivePlayers[newIdx]

	SpectatorTargetRemote:FireClient(
		spectator,
		"SwitchTarget",
		alivePlayers[newIdx]
	)
end

function SpectatorSystem:GetTarget(spectator: Player): Player?
	return spectatorTargets[spectator]
end

return SpectatorSystem
```

**Client-side spectator camera controller:**

```luau
--!strict
-- StarterPlayerScripts/BattleRoyale/SpectatorController.lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local UserInputService = game:GetService("UserInputService")
local RunService = game:GetService("RunService")

local SpectatorTargetRemote = ReplicatedStorage.BattleRoyale.Remotes.SpectatorTarget
local Config = require(ReplicatedStorage.BattleRoyale.Config)

local camera = workspace.CurrentCamera
local isSpectating = false
local currentTarget: Player? = nil
local cameraOffset = Vector3.new(0, 8, 12)
local renderConnection: RBXScriptConnection? = nil

local function followTarget()
	if not currentTarget then return end
	local character = currentTarget.Character
	if not character then return end
	local rootPart = character:FindFirstChild("HumanoidRootPart") :: BasePart?
	if not rootPart then return end

	camera.CameraType = Enum.CameraType.Scriptable
	local targetCF = CFrame.new(rootPart.Position + cameraOffset, rootPart.Position)
	camera.CFrame = camera.CFrame:Lerp(targetCF, 0.1)
end

local function startSpectating(target: Player)
	isSpectating = true
	currentTarget = target

	-- Disconnect any existing render loop
	if renderConnection then
		renderConnection:Disconnect()
	end

	renderConnection = RunService.RenderStepped:Connect(followTarget)
end

local function stopSpectating()
	isSpectating = false
	currentTarget = nil
	if renderConnection then
		renderConnection:Disconnect()
		renderConnection = nil
	end
	camera.CameraType = Enum.CameraType.Custom
end

SpectatorTargetRemote.OnClientEvent:Connect(function(action: string, target: Player?)
	if action == "StartSpectating" and target then
		startSpectating(target)
	elseif action == "SwitchTarget" and target then
		currentTarget = target
	elseif action == "StopSpectating" then
		stopSpectating()
	end
end)

-- Cycle targets with left/right arrow or Q/E keys
local lastCycleTime = 0
UserInputService.InputBegan:Connect(function(input, gameProcessed)
	if gameProcessed or not isSpectating then return end
	if os.clock() - lastCycleTime < Config.SPECTATOR_CYCLE_COOLDOWN then return end

	local direction = 0
	if input.KeyCode == Enum.KeyCode.E or input.KeyCode == Enum.KeyCode.Right then
		direction = 1
	elseif input.KeyCode == Enum.KeyCode.Q or input.KeyCode == Enum.KeyCode.Left then
		direction = -1
	end

	if direction ~= 0 then
		lastCycleTime = os.clock()
		-- Fire to server to get next valid target
		ReplicatedStorage.BattleRoyale.Remotes.SpectatorTarget:FireServer("CycleTarget", direction)
	end
end)
```

---

### 3.6 Drop / Spawn System

```luau
--!strict
-- ServerScriptService/BattleRoyale/DropSystem.lua

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Config = require(ReplicatedStorage.BattleRoyale.Config)
local DropRemote = ReplicatedStorage.BattleRoyale.Remotes.DropInput

local DropSystem = {}

local deployedPlayers: { [Player]: boolean } = {}

function DropSystem:DeployAllPlayers(players: { Player })
	table.clear(deployedPlayers)

	-- Determine map center for the drop position
	local mapCenter = Vector3.new(0, Config.DROP_HEIGHT, 0)

	for i, player in players do
		if not player.Character then continue end

		local humanoid = player.Character:FindFirstChildOfClass("Humanoid")
		local rootPart = player.Character:FindFirstChild("HumanoidRootPart") :: BasePart?
		if not humanoid or not rootPart then continue end

		-- Spread players along a line in the sky
		local offset = Vector3.new((i - #players / 2) * 6, 0, 0)
		local spawnCF = CFrame.new(mapCenter + offset)
		player.Character:PivotTo(spawnCF)

		-- Disable default movement during drop
		humanoid.PlatformStand = true

		deployedPlayers[player] = true

		-- Notify client to begin free-fall camera
		DropRemote:FireClient(player, "BeginDrop", spawnCF.Position)
	end

	-- Server-side drop physics (simplified: move characters downward)
	task.spawn(function()
		while true do
			local anyDropping = false
			for player, isDropping in deployedPlayers do
				if not isDropping then continue end
				if not player.Character then continue end

				local rootPart = player.Character:FindFirstChild("HumanoidRootPart") :: BasePart?
				if not rootPart then continue end

				local height = rootPart.Position.Y
				local speed: number

				if height > Config.PARACHUTE_DEPLOY_HEIGHT then
					speed = Config.FALL_SPEED
				else
					speed = Config.PARACHUTE_SPEED
					-- Notify client to deploy parachute visual (once)
				end

				-- Ground check: stop drop when near ground
				local rayResult = workspace:Raycast(
					rootPart.Position,
					Vector3.new(0, -5, 0),
					RaycastParams.new()
				)
				if rayResult or height <= 5 then
					-- Player has landed
					local humanoid = player.Character:FindFirstChildOfClass("Humanoid")
					if humanoid then
						humanoid.PlatformStand = false
					end
					deployedPlayers[player] = false
					DropRemote:FireClient(player, "Landed")
					continue
				end

				-- Move downward
				rootPart.CFrame = rootPart.CFrame - Vector3.new(0, speed * 0.03, 0)
				anyDropping = true
			end

			if not anyDropping then break end
			task.wait()
		end
	end)
end

-- Allow client to send lateral movement input during drop
DropRemote.OnServerEvent:Connect(function(player, action, direction: Vector3?)
	if action ~= "MoveInput" then return end
	if not deployedPlayers[player] then return end
	if not direction then return end

	local rootPart = player.Character and player.Character:FindFirstChild("HumanoidRootPart") :: BasePart?
	if not rootPart then return end

	-- Clamp lateral movement speed
	local lateralSpeed = 40
	local clampedDir = Vector3.new(
		math.clamp(direction.X, -1, 1),
		0,
		math.clamp(direction.Z, -1, 1)
	).Unit * lateralSpeed * 0.03

	rootPart.CFrame = rootPart.CFrame + clampedDir
end)

function DropSystem:Reset()
	table.clear(deployedPlayers)
end

return DropSystem
```

---

## 4. Progression Design

Battle royale progression must never grant permanent power advantages. All combat is
skill-based with equal access to loot on the ground.

### XP and Leveling

| Action | XP Reward |
|---|---|
| Survive to top 50% | +50 XP |
| Survive to top 25% | +100 XP |
| Survive to top 10% | +200 XP |
| Victory Royale (1st) | +500 XP |
| Per elimination | +50 XP |
| Damage dealt (per 100) | +10 XP |
| Match completed | +25 XP |

### Cosmetic Unlocks

- **Level milestones** unlock free cosmetic items (skins, emotes, trails).
- **Seasonal ranks** (Bronze/Silver/Gold/Diamond/Champion) based on placement consistency.
- **Lifetime stats** tracked: total wins, total kills, K/D ratio, matches played.

### Battle Pass Integration

Each season (6-8 weeks) offers a battle pass with 100 tiers:
- **Free track:** ~25 free rewards spread across tiers (basic skins, sprays, small currency).
- **Premium track:** unlocked via Robux purchase, adds rewards at every tier.
- Progression is XP-based, not pay-to-skip (or offer limited tier-buy for late joiners).

---

## 5. Monetization Strategy

**Core principle:** No pay-to-win. All purchasable items are cosmetic only.

### Revenue Streams

| Product | Pricing (Robux) | Type |
|---|---|---|
| Battle Pass (seasonal) | 499-799 | Seasonal content |
| Character Skins | 100-500 | Cosmetic |
| Weapon Skins | 50-250 | Cosmetic (visual only) |
| Emotes / Dances | 75-200 | Cosmetic |
| Glider / Parachute Skins | 100-300 | Cosmetic |
| Drop Trail Effects | 50-150 | Cosmetic |

### Gamepass Ideas

| Gamepass | Price | Benefit |
|---|---|---|
| VIP | 499 | 2x XP, exclusive lobby area, VIP badge |
| Stat Tracker | 199 | Detailed match stats, heatmaps, leaderboard access |
| Emote Pack | 299 | Bundle of 10 emotes |

### Anti-P2W Safeguards

- Weapon skins never modify stats (damage, fire rate, accuracy stay identical).
- No purchasable weapons, ammo, or armor.
- XP boosts are acceptable but must not gate gameplay content.
- Matchmaking never considers spend amount.

---

## 6. Performance Considerations

### Many Players in One Server

- **Server tick budget:** Target 30Hz server heartbeat. Profile with `debug.profilebegin()`.
- **Player cap:** Start with 30-50 players. Stress test before going higher.
- **Character replication:** Use `StreamingEnabled = true` to only replicate nearby characters.
- **StreamingIntegrity:** Set to `Enum.StreamingIntegrity.Minimum` for BR maps.
- **StreamingTargetRadius:** 256-512 studs depending on map size.

### Weapon / Projectile Optimization

```luau
-- Use raycasts for hitscan weapons, NOT physical Part projectiles
local function fireHitscan(origin: Vector3, direction: Vector3, maxRange: number): RaycastResult?
    local params = RaycastParams.new()
    params.FilterType = Enum.RaycastFilterType.Exclude
    params.FilterDescendantsInstances = { player.Character }

    return workspace:Raycast(origin, direction.Unit * maxRange, params)
end
-- For visual bullet trails, use Beams or tweened Attachments (client-side only)
```

- **Hitscan weapons:** One `workspace:Raycast()` per shot. Cheap and accurate.
- **Projectile weapons (rockets, grenades):** Simulate trajectory with math on server,
  use client-side visual parts that get cleaned up.
- **Never create physical Part projectiles** for every bullet. This kills server performance.

### Map Optimization

- **Part count:** Keep under 10,000 unique parts. Use MeshParts over Unions.
- **Texture budget:** Reuse materials. Use Roblox PBR materials where possible.
- **LOD:** Place distant scenery as low-poly Decals or MeshParts with minimal collision.
- **Destroy loot items** immediately on pickup (do not just hide them).
- **Workspace cleanup:** Remove dead player ragdolls after 5 seconds.

### Distant Player Rendering

```luau
-- Reduce render fidelity for distant players on the client
RunService.Heartbeat:Connect(function()
    local myPos = localPlayer.Character and localPlayer.Character.PrimaryPart
    if not myPos then return end

    for _, otherPlayer in Players:GetPlayers() do
        if otherPlayer == localPlayer then continue end
        local otherChar = otherPlayer.Character
        if not otherChar then continue end

        local dist = (otherChar:GetPivot().Position - myPos.Position).Magnitude
        -- Beyond 200 studs: hide accessories, simplify rendering
        for _, accessory in otherChar:GetChildren() do
            if accessory:IsA("Accessory") then
                accessory:FindFirstChildWhichIsA("BasePart").LocalTransparencyModifier =
                    if dist > 200 then 1 else 0
            end
        end
    end
end)
```

### Network Optimization

- Batch zone updates: broadcast once per second, not every frame.
- Kill feed uses `FireAllClients` sparingly (only on elimination events).
- Loot pickups: use ProximityPrompt server validation, do not replicate all loot state every frame.

---

## 7. Launch Checklist

### Zone / Storm Balance
- [ ] Zone timing tested with minimum player count (does final zone close before match drags)
- [ ] Zone timing tested with maximum player count (enough time to loot and rotate)
- [ ] Zone damage per phase escalates appropriately (early = warning, late = lethal)
- [ ] Zone center randomization stays within map bounds
- [ ] Zone visual indicator is clear on minimap at all phases

### Loot Distribution
- [ ] Every landing area has at least 2-3 loot spawn points
- [ ] Rarity distribution tested over 100+ matches (Legendary < 5% of drops)
- [ ] No "dead zones" where players land with zero loot access
- [ ] High-tier loot areas balanced by higher risk (more exposed, central)
- [ ] Weapon balance: no single weapon dominates all ranges

### Player Count
- [ ] Minimum player count starts a match correctly (tested with 4 players)
- [ ] Maximum player count does not cause server lag (profiled at 50 players)
- [ ] Server FPS stays above 25 at max player count
- [ ] Lobby handles players joining mid-countdown gracefully
- [ ] Players disconnecting mid-match do not break match state

### Spectator Mode
- [ ] Eliminated player camera transitions smoothly to spectator view
- [ ] Cycling between alive players works with Q/E keys
- [ ] Spectator cannot interact with game world (no input leaks)
- [ ] Spectator UI shows target player name, health, kill count
- [ ] Spectating ends and returns to lobby on match end

### Progression and Rewards
- [ ] XP awarded correctly based on placement and kills
- [ ] Battle pass tiers increment with XP
- [ ] Cosmetic items apply correctly in lobby and in-match
- [ ] Leaderboard updates after each match

### Security
- [ ] All damage calculations are server-authoritative
- [ ] Loot pickup validated server-side (proximity check, item exists, not already taken)
- [ ] Remote events rate-limited (especially weapon fire and movement)
- [ ] Kill credit cannot be spoofed via client
- [ ] Zone damage cannot be bypassed by client exploits
- [ ] Inventory manipulation impossible from client (server owns inventory state)

### Mobile and Performance
- [ ] Touch controls for drop, aiming, looting tested on mobile
- [ ] Frame rate acceptable on low-end devices with StreamingEnabled
- [ ] UI scales correctly on small screens
- [ ] Part count under budget at all match phases

### Pre-Launch Stress Test
- [ ] Run 10+ full matches with target player count
- [ ] Monitor server memory (should not climb across matches -- check for leaks)
- [ ] Verify cleanup phase removes all loot, resets all systems
- [ ] Test rapid back-to-back matches (no state bleed between rounds)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 196kUpdated Claude CodeCodexVerifiedInstall