arena.lua

--!strict

--[[

Arena Server System
Author: dtblinux

Purpose
-------
Server authoritative team arena controller responsible for:

• Player queueing
• Pad interaction
• Team assignment
• Teleportation
• Weapon distribution
• Score tracking
• Match lifecycle
• Cleanup

Design Goals
------------
1. Server authoritative gameplay
2. Predictable lifecycle state machine
3. Clear separation of runtime state
4. Defensive programming against player disconnects
5. Maintainable and reviewable architecture

State Machine
-------------
WAITING → COUNTDOWN → IN_PROGRESS → RESET

]]

--------------------------------------------------------------------
-- SERVICES
--------------------------------------------------------------------

local ServerStorage = game:GetService("ServerStorage")
local Players = game:GetService("Players")
local RunService = game:GetService("RunService")
local CollectionService = game:GetService("CollectionService")

--------------------------------------------------------------------
-- MODULES
--------------------------------------------------------------------

local Modules = ServerStorage:WaitForChild("Modules")

local Janitor = _G.Require("Janitor")
local Zone = require(Modules.Zone)

--------------------------------------------------------------------
-- CONSTANTS
--------------------------------------------------------------------

local ARENA_TAG = "BaseArena"

local THUMBNAIL_TYPE = Enum.ThumbnailType.HeadShot
local THUMBNAIL_SIZE = Enum.ThumbnailSize.Size420x420

local DEFAULT_ICON = "rbxassetid://9319891706"
local EMPTY_NAME = "..."

local PAD_EMPTY_COLOR = Color3.new(1,1,1)
local PAD_OCCUPIED_COLOR = Color3.new(1,0,0)

local STATUS_WAITING = "Waiting..."
local STATUS_STARTING = "Starting in: "
local STATUS_ACTIVE = "In Progress..."

local CLASSIC_SWORD = "ClassicSword"

--------------------------------------------------------------------
-- TYPE DEFINITIONS
--------------------------------------------------------------------

type WaitingPlayer = {
	Player: Player,
	PadIndex: number
}

type ArenaSettings = {
	MaxPlayers: number,
	StartCountDown: number,
	GameDuration: number,
	WinCondition: number
}

--------------------------------------------------------------------
-- CLASS DECLARATION
--------------------------------------------------------------------

local Arena = {}
Arena.__index = Arena

Arena.CachedArenas = {}

--------------------------------------------------------------------
-- INTERNAL UTILITIES
--------------------------------------------------------------------

local function getHumanoid(player: Player): Humanoid?
	local character = player.Character
	if not character then
		return nil
	end

	return character:FindFirstChildOfClass("Humanoid")
end

local function getRoot(player: Player): BasePart?
	local character = player.Character
	if not character then
		return nil
	end

	return character.PrimaryPart
end

--------------------------------------------------------------------
-- UI HELPERS
--------------------------------------------------------------------

local function getPadFrame(zone)
	return zone.container.Board.SurfaceGui.Frame
end

local function resetPadVisual(zone)

	local frame = getPadFrame(zone)

	frame.PlayerIcon.Image = DEFAULT_ICON
	frame.PlayerName.Text = EMPTY_NAME

	zone.container.Union.Color = PAD_EMPTY_COLOR
	zone.HasPlayer = false
end

local function setPadVisual(zone, player, thumbnail)

	local frame = getPadFrame(zone)

	frame.PlayerIcon.Image = thumbnail
	frame.PlayerName.Text = player.Name

	zone.container.Union.Color = PAD_OCCUPIED_COLOR
	zone.HasPlayer = true
end

--------------------------------------------------------------------
-- PLAYER LOOKUP
--------------------------------------------------------------------

function Arena:_findWaitingPlayer(player: Player)

	for i,data in ipairs(self.PlayersWaiting) do

		if data.Player == player then
			return i,data.PadIndex
		end

	end

	return nil,nil
end

--------------------------------------------------------------------
-- CONSTRUCTOR
--------------------------------------------------------------------

function Arena.new(folder: Folder)

	local self = setmetatable({},Arena)

	self.Folder = folder
	self.Janitor = Janitor.new()

	self.Settings = folder:GetAttributes() :: ArenaSettings

	self.InProgress = false
	self.Countdown = false
	self.TimerRunning = true

	self.Zones = {}
	self.Teleports = {}

	self.PlayersWaiting = {} :: {WaitingPlayer}

	self.Team1 = {}
	self.Team2 = {}

	self.Team1Score = 0
	self.Team2Score = 0

	self:_validate()
	self:_registerPads()
	self:_connectEvents()

	Arena.CachedArenas[folder] = self

	return self
end

--------------------------------------------------------------------
-- VALIDATION
--------------------------------------------------------------------

function Arena:_validate()

	local max = self.Settings.MaxPlayers

	assert(max >= 2,"MaxPlayers must be >= 2")
	assert(max % 2 == 0,"MaxPlayers must be even")

end

--------------------------------------------------------------------
-- PAD REGISTRATION
--------------------------------------------------------------------

function Arena:_registerPads()

	local pads = self.Folder:WaitForChild("Pads")
	local teleports = self.Folder:WaitForChild("Teleports")

	for i=1,self.Settings.MaxPlayers do

		local pad = pads:FindFirstChild(tostring(i))
		local tp = teleports:FindFirstChild(tostring(i))

		assert(pad,"Missing pad "..i)
		assert(tp,"Missing teleport "..i)

		local zone = Zone.new(pad)
		zone.HasPlayer = false

		table.insert(self.Zones,zone)
		table.insert(self.Teleports,tp)

	end

end

--------------------------------------------------------------------
-- ZONE EVENTS
--------------------------------------------------------------------

function Arena:_connectEvents()

	for i,zone in ipairs(self.Zones) do

		self.Janitor:Add(
			zone.playerEntered:Connect(function(player)
				self:_playerEntered(player,i,zone)
			end)
		)

		self.Janitor:Add(
			zone.playerExited:Connect(function(player)
				self:_playerExited(player,i,zone)
			end)
		)

	end

	Players.PlayerRemoving:Connect(function(player)
		self:_playerLeaving(player)
	end)

end

--------------------------------------------------------------------
-- ZONE ENTRY
--------------------------------------------------------------------

function Arena:_playerEntered(player: Player,index: number,zone)

	if self.InProgress then
		return
	end

	if zone.HasPlayer then
		return
	end

	if #self.PlayersWaiting >= self.Settings.MaxPlayers then
		return
	end

	local exists = self:_findWaitingPlayer(player)
	if exists then
		return
	end

	table.insert(self.PlayersWaiting,{
		Player = player,
		PadIndex = index
	})

	local thumb = DEFAULT_ICON

	local ok,result = pcall(function()
		return Players:GetUserThumbnailAsync(player.UserId,THUMBNAIL_TYPE,THUMBNAIL_SIZE)
	end)

	if ok then
		thumb = result
	end

	setPadVisual(zone,player,thumb)

	if #self.PlayersWaiting == self.Settings.MaxPlayers then
		self:_startCountdown()
	end

end

--------------------------------------------------------------------
-- TEAM ASSIGNMENT
--------------------------------------------------------------------

function Arena:_assignTeams()

	table.sort(self.PlayersWaiting,function(a,b)
		return a.PadIndex < b.PadIndex
	end)

	local mid = #self.PlayersWaiting / 2

	for i=1,mid do
		table.insert(self.Team1,self.PlayersWaiting[i])
	end

	for i=mid+1,#self.PlayersWaiting do
		table.insert(self.Team2,self.PlayersWaiting[i])
	end

end

--------------------------------------------------------------------
-- TELEPORT
--------------------------------------------------------------------

function Arena:_teleportPlayers()

	for _,data in ipairs(self.PlayersWaiting) do

		local root = getRoot(data.Player)
		local spawn = self.Teleports[data.PadIndex]

		if root then
			root.CFrame = spawn.CFrame
		end

	end

end

--------------------------------------------------------------------
-- COUNTDOWN
--------------------------------------------------------------------

function Arena:_startCountdown()

	self.Countdown = true

	for i=self.Settings.StartCountDown,1,-1 do

		self:_setStatus(STATUS_STARTING..i)

		task.wait(1)

		if #self.PlayersWaiting < self.Settings.MaxPlayers then
			self:_setStatus(STATUS_WAITING)
			self.Countdown = false
			return
		end

	end

	self:_startMatch()

end

--------------------------------------------------------------------
-- MATCH START
--------------------------------------------------------------------

function Arena:_startMatch()

	self.InProgress = true

	self:_assignTeams()
	self:_teleportPlayers()

	self:_setStatus(STATUS_ACTIVE)

end

--------------------------------------------------------------------
-- STATUS UI
--------------------------------------------------------------------

function Arena:_setStatus(text)

	self.Folder.MainBoard.SurfaceGui.Frame.Status.Text = text

end

--------------------------------------------------------------------
-- RESET
--------------------------------------------------------------------

function Arena:Reset()

	for _,data in ipairs(self.PlayersWaiting) do

		local player = data.Player

		if player and player.Parent then
			player:LoadCharacter()
		end

	end

	self.PlayersWaiting = {}
	self.Team1 = {}
	self.Team2 = {}

	self.Team1Score = 0
	self.Team2Score = 0

	self.InProgress = false
	self.Countdown = false

	self:_setStatus(STATUS_WAITING)

	for _,zone in ipairs(self.Zones) do
		resetPadVisual(zone)
	end

end

--------------------------------------------------------------------
-- ARENA MANAGER
--------------------------------------------------------------------

local function init()

	for _,arenaFolder in ipairs(CollectionService:GetTagged(ARENA_TAG)) do

		if arenaFolder:IsDescendantOf(workspace) then
			Arena.new(arenaFolder)
		end

	end

end

init()

return Arena