combat-system

Battlegrounds-Style Hitbox (GetPartBoundsInBox)

```lua

-- Most common method for melee games like The Strongest Battlegrounds

local function createHitbox(cframe, size, ignoreList, callback)

local params = OverlapParams.new()

params.FilterDescendantsInstances = ignoreList

params.FilterType = Enum.RaycastFilterType.Exclude

local parts = workspace:GetPartBoundsInBox(cframe, size, params)

local hitCharacters = {}

for _, part in ipairs(parts) do

local character = part.Parent

local humanoid = character:FindFirstChildOfClass("Humanoid")

if humanoid and not hitCharacters[character] then

hitCharacters[character] = true

callback(humanoid, part)

end

end

return hitCharacters

end

-- Usage with lingering hitbox (active for multiple frames)

local function meleeAttack(attacker, damage, knockback)

local hitTargets = {}

local duration = 0.2 -- Hitbox active for 200ms

local startTime = os.clock()

while os.clock() - startTime < duration do

local hitboxCFrame = attacker.HumanoidRootPart.CFrame * CFrame.new(0, 0, -3)

local hitboxSize = Vector3.new(4, 6, 4)

createHitbox(hitboxCFrame, hitboxSize, {attacker}, function(humanoid, hitPart)

if not hitTargets[humanoid.Parent] then

hitTargets[humanoid.Parent] = true

applyDamage(humanoid, damage, knockback, attacker)

end

end)

task.wait()

end

end

```

Client-Predicted Hitbox (Validate on Server)

```lua

-- Client: Perform hit detection locally for responsiveness

local function clientHitDetection(attackData)

local hitbox = createHitbox(attackData.cframe, attackData.size, {localPlayer.Character})

for character, _ in pairs(hitbox) do

-- Send hit claim to server

CombatRemote:FireServer("HitClaim", {

targetId = character:GetAttribute("EntityId"),

attackId = attackData.id,

timestamp = workspace:GetServerTimeNow()

})

-- Play hit effect immediately (client prediction)

playHitEffect(character)

end

end

-- Server: Validate hit claims

local function validateHit(player, data)

local attacker = player.Character

local target = getEntityById(data.targetId)

if not attacker or not target then return false end

-- Check distance (with tolerance for latency)

local distance = (attacker.HumanoidRootPart.Position - target.HumanoidRootPart.Position).Magnitude

if distance > MAX_ATTACK_RANGE * 1.5 then return false end

-- Check attack is valid (cooldown, state)

if not canAttack(attacker, data.attackId) then return false end

-- Check target is damageable

if not canBeDamaged(target) then return false end

return true

end

```

Capsule Hitbox (For Character Shapes)

```lua

-- Multiple overlapping spheres for better character detection

local function capsuleOverlap(startPos, endPos, radius, ignoreList)

local params = OverlapParams.new()

params.FilterDescendantsInstances = ignoreList

params.FilterType = Enum.RaycastFilterType.Exclude

local hits = {}

local segments = 5

local direction = (endPos - startPos)

for i = 0, segments do

local t = i / segments

local pos = startPos + direction * t

local parts = workspace:GetPartBoundsInRadius(pos, radius, params)

for _, part in ipairs(parts) do

hits[part] = true

end

end

return hits

end

```

Damage Calculation

```lua

local DamageSystem = {}

function DamageSystem.calculateDamage(baseDamage, attacker, target)

local damage = baseDamage

-- Attacker bonuses

local attackBonus = attacker:GetAttribute("AttackBonus") or 0

damage = damage * (1 + attackBonus / 100)

-- Critical hit

local critChance = attacker:GetAttribute("CritChance") or 5

local critMultiplier = attacker:GetAttribute("CritMultiplier") or 1.5

local isCrit = math.random(100) <= critChance

if isCrit then

damage = damage * critMultiplier

end

-- Target defense

local defense = target:GetAttribute("Defense") or 0

damage = damage * (100 / (100 + defense)) -- Diminishing returns formula

-- Elemental resistances

local element = attacker:GetAttribute("DamageElement")

if element then

local resistance = target:GetAttribute(element .. "Resistance") or 0

damage = damage * (1 - resistance / 100)

end

return math.floor(damage), isCrit

end

function DamageSystem.applyDamage(humanoid, damage, isCrit, source)

-- Check invincibility frames

if humanoid:GetAttribute("Invincible") then return end

humanoid:TakeDamage(damage)

-- Fire damage event for UI/effects

local character = humanoid.Parent

DamageEvent:Fire(character, damage, isCrit, source)

-- Track damage source for kill attribution

character:SetAttribute("LastDamageSource", source and source.Name or "Environment")

character:SetAttribute("LastDamageTime", os.clock())

end

```

Damage Over Time (DoT)

```lua

local DoTManager = {}

DoTManager.activeDoTs = {}

function DoTManager.applyDoT(target, dotData)

local id = HttpService:GenerateGUID()

local dot = {

id = id,

target = target,

damage = dotData.damage,

tickRate = dotData.tickRate or 1,

duration = dotData.duration,

element = dotData.element,

source = dotData.source,

startTime = os.clock(),

lastTick = 0

}

DoTManager.activeDoTs[id] = dot

return id

end

function DoTManager.update()

local currentTime = os.clock()

for id, dot in pairs(DoTManager.activeDoTs) do

-- Check expiration

if currentTime - dot.startTime >= dot.duration then

DoTManager.activeDoTs[id] = nil

continue

end

-- Apply tick damage

if currentTime - dot.lastTick >= dot.tickRate then

dot.lastTick = currentTime

local humanoid = dot.target:FindFirstChildOfClass("Humanoid")

if humanoid and humanoid.Health > 0 then

DamageSystem.applyDamage(humanoid, dot.damage, false, dot.source)

else

DoTManager.activeDoTs[id] = nil

end

end

end

end

```

Stun Handler Module

```lua

local StunHandler = {}

StunHandler.stunnedEntities = {}

-- Stun priorities (higher overrides lower)

local StunPriority = {

Stagger = 1, -- Brief interruption

Stun = 2, -- Standard stun

Knockdown = 3, -- Longer, on ground

Ragdoll = 4, -- Full physics ragdoll

Frozen = 5 -- Highest priority

}

function StunHandler.applyStun(character, stunType, duration)

local current = StunHandler.stunnedEntities[character]

local newPriority = StunPriority[stunType]

-- Only apply if higher or equal priority

if current and StunPriority[current.type] > newPriority then

return false

end

-- Apply stun

local humanoid = character:FindFirstChildOfClass("Humanoid")

if not humanoid then return false end

-- Disable movement

humanoid.WalkSpeed = 0

humanoid.JumpPower = 0

humanoid.AutoRotate = false

StunHandler.stunnedEntities[character] = {

type = stunType,

endTime = os.clock() + duration,

originalWalkSpeed = humanoid:GetAttribute("BaseWalkSpeed") or 16,

originalJumpPower = humanoid:GetAttribute("BaseJumpPower") or 50

}

-- Schedule recovery

task.delay(duration, function()

StunHandler.removeStun(character, stunType)

end)

return true

end

function StunHandler.removeStun(character, expectedType)

local stun = StunHandler.stunnedEntities[character]

if not stun or (expectedType and stun.type ~= expectedType) then return end

local humanoid = character:FindFirstChildOfClass("Humanoid")

if humanoid then

humanoid.WalkSpeed = stun.originalWalkSpeed

humanoid.JumpPower = stun.originalJumpPower

humanoid.AutoRotate = true

end

StunHandler.stunnedEntities[character] = nil

end

function StunHandler.isStunned(character)

return StunHandler.stunnedEntities[character] ~= nil

end

```

Knockback System

```lua

function applyKnockback(character, direction, force, duration)

local hrp = character:FindFirstChild("HumanoidRootPart")

if not hrp then return end

-- Normalize direction and apply force

local knockbackVelocity = direction.Unit * force

-- Use LinearVelocity for consistent knockback

local linearVel = Instance.new("LinearVelocity")

linearVel.Attachment0 = hrp:FindFirstChild("RootAttachment") or Instance.new("Attachment", hrp)

linearVel.VectorVelocity = knockbackVelocity

linearVel.MaxForce = math.huge

linearVel.RelativeTo = Enum.ActuatorRelativeTo.World

linearVel.Parent = hrp

task.delay(duration or 0.2, function()

linearVel:Destroy()

end)

end

```

Combo System State Machine

```lua

local ComboSystem = {}

local ComboData = {

M1 = {

{name = "Jab", damage = 10, duration = 0.3, canCancel = {0.2, 0.3}},

{name = "Cross", damage = 12, duration = 0.35, canCancel = {0.25, 0.35}},

{name = "Hook", damage = 15, duration = 0.4, canCancel = {0.3, 0.4}},

{name = "Uppercut", damage = 20, duration = 0.5, canCancel = nil, finisher = true}

}

}

function ComboSystem.new(character)

return {

character = character,

currentCombo = nil,

comboIndex = 0,

lastAttackTime = 0,

inputBuffer = nil,

comboResetTime = 1.5

}

end

function ComboSystem.attack(self, attackType)

local currentTime = os.clock()

-- Reset combo if too much time passed

if currentTime - self.lastAttackTime > self.comboResetTime then

self.comboIndex = 0

self.currentCombo = nil

end

-- Get combo data

local combo = ComboData[attackType]

if not combo then return end

-- Advance combo

self.comboIndex = self.comboIndex + 1

if self.comboIndex > #combo then

self.comboIndex = 1

end

local attackData = combo[self.comboIndex]

self.currentCombo = attackType

self.lastAttackTime = currentTime

-- Execute attack

return self:executeAttack(attackData)

end

function ComboSystem.executeAttack(self, attackData)

-- Play animation

local animator = self.character:FindFirstChildOfClass("Humanoid"):FindFirstChildOfClass("Animator")

local track = animator:LoadAnimation(attackData.animation)

track:Play()

-- Create hitbox at appropriate frame

task.delay(attackData.hitboxDelay or 0.1, function()

meleeAttack(self.character, attackData.damage, attackData.knockback)

end)

return attackData

end

```

Hitscan Weapon

```lua

function fireHitscan(origin, direction, weaponData)

local params = RaycastParams.new()

params.FilterDescendantsInstances = {localPlayer.Character}

params.FilterType = Enum.RaycastFilterType.Exclude

-- Apply spread

local spread = weaponData.spread * (isADS and 0.3 or 1)

local spreadX = (math.random() - 0.5) * spread

local spreadY = (math.random() - 0.5) * spread

local spreadDir = (CFrame.lookAt(origin, origin + direction) * CFrame.Angles(spreadX, spreadY, 0)).LookVector

local result = workspace:Raycast(origin, spreadDir * weaponData.range, params)

if result then

-- Check if hit character

local character = result.Instance.Parent

local humanoid = character:FindFirstChildOfClass("Humanoid")

if humanoid then

-- Calculate damage falloff

local distance = result.Distance

local falloff = 1 - math.clamp((distance - weaponData.falloffStart) / (weaponData.range - weaponData.falloffStart), 0, 0.5)

local damage = weaponData.baseDamage * falloff

-- Headshot multiplier

if result.Instance.Name == "Head" then

damage = damage * weaponData.headshotMultiplier

end

CombatRemote:FireServer("HitscanHit", {

targetId = character:GetAttribute("EntityId"),

damage = damage,

hitPart = result.Instance.Name

})

end

-- Create impact effect

createImpactEffect(result.Position, result.Normal, result.Material)

end

return result

end

```

Projectile System

```lua

local ProjectileSystem = {}

ProjectileSystem.activeProjectiles = {}

function ProjectileSystem.spawn(data)

local projectile = {

id = HttpService:GenerateGUID(),

position = data.origin,

velocity = data.direction.Unit * data.speed,

gravity = data.gravity or Vector3.new(0, -workspace.Gravity, 0),

damage = data.damage,

owner = data.owner,

lifetime = data.lifetime or 10,

spawnTime = os.clock(),

radius = data.radius or 0.5

}

-- Create visual

projectile.visual = data.visualTemplate:Clone()

projectile.visual.CFrame = CFrame.lookAt(data.origin, data.origin + data.direction)

projectile.visual.Parent = workspace

ProjectileSystem.activeProjectiles[projectile.id] = projectile

return projectile

end

function ProjectileSystem.update(dt)

for id, proj in pairs(ProjectileSystem.activeProjectiles) do

-- Check lifetime

if os.clock() - proj.spawnTime > proj.lifetime then

ProjectileSystem.destroy(id)

continue

end

-- Physics update

proj.velocity = proj.velocity + proj.gravity * dt

local newPos = proj.position + proj.velocity * dt

-- Raycast for collision

local result = workspace:Raycast(proj.position, newPos - proj.position)

if result then

ProjectileSystem.onHit(proj, result)

ProjectileSystem.destroy(id)

continue

end

proj.position = newPos

proj.visual.CFrame = CFrame.lookAt(proj.position, proj.position + proj.velocity)

end

end

function ProjectileSystem.onHit(proj, rayResult)

local character = rayResult.Instance.Parent

local humanoid = character:FindFirstChildOfClass("Humanoid")

if humanoid then

DamageSystem.applyDamage(humanoid, proj.damage, false, proj.owner)

end

-- Spawn explosion/impact

createExplosion(rayResult.Position, proj.explosionRadius)

end

```

Cooldown Management

```lua

local CooldownManager = {}

CooldownManager.cooldowns = {}

function CooldownManager.startCooldown(entity, abilityId, duration)

local key = entity:GetAttribute("EntityId") .. "_" .. abilityId

CooldownManager.cooldowns[key] = os.clock() + duration

end

function CooldownManager.isOnCooldown(entity, abilityId)

local key = entity:GetAttribute("EntityId") .. "_" .. abilityId

local endTime = CooldownManager.cooldowns[key]

return endTime and os.clock() < endTime

end

function CooldownManager.getRemainingCooldown(entity, abilityId)

local key = entity:GetAttribute("EntityId") .. "_" .. abilityId

local endTime = CooldownManager.cooldowns[key]

if not endTime then return 0 end

return math.max(0, endTime - os.clock())

end

```

Ability Base Class

```lua

local Ability = {}

Ability.__index = Ability

function Ability.new(data)

return setmetatable({

id = data.id,

name = data.name,

cooldown = data.cooldown,

manaCost = data.manaCost or 0,

castTime = data.castTime or 0,

onCast = data.onCast,

onChannel = data.onChannel,

onRelease = data.onRelease

}, Ability)

end

function Ability:canCast(caster)

-- Check cooldown

if CooldownManager.isOnCooldown(caster, self.id) then

return false, "On cooldown"

end

-- Check mana

local mana = caster:GetAttribute("Mana") or 0

if mana < self.manaCost then

return false, "Not enough mana"

end

-- Check stun

if StunHandler.isStunned(caster) then

return false, "Stunned"

end

return true

end

function Ability:cast(caster, target)

local canCast, reason = self:canCast(caster)

if not canCast then return false, reason end

-- Consume mana

local currentMana = caster:GetAttribute("Mana")

caster:SetAttribute("Mana", currentMana - self.manaCost)

-- Start cooldown

CooldownManager.startCooldown(caster, self.id, self.cooldown)

-- Execute ability

if self.castTime > 0 then

-- Channeled ability

self:startChannel(caster, target)

else

-- Instant ability

self.onCast(caster, target)

end

return true

end

```