example.lua

--[[
	Example: wiring HookRegistry into a combat system.

	This mirrors a common shape — attacker-side hooks gate on the
	attacker's owned ability, receiver-side hooks gate on the victim's,
	and a wildcard entry always runs. None of this is built into the
	module; it's just one way to use the gateResolver.

	Written as plain tables (not Roblox Player instances) so this file
	is a runnable demonstration on its own, independent of Roblox.
]]

local HookRegistry = require(script.Parent.src)

local Registry = HookRegistry.new({
	"OnHitDealt",
	"OnHitReceived",
})

-- Your own ownership check — HookRegistry has no opinion on how
-- abilities are stored. Here it's a stand-in for however your game
-- tracks "does this player have this ability equipped".
local function playerOwnsAbility(player, abilityName)
	return player.EquippedAbility == abilityName
end

-- A resolver tailored to this game's ctx shape: attacker-side hooks
-- check ctx.attacker, receiver-side hooks check ctx.victim.
local function gateResolver(gateKey, ctx)
	local subject = ctx.attacker
	if ctx.__gateSide == "victim" then
		subject = ctx.victim
	end
	if not subject then
		return false
	end
	return playerOwnsAbility(subject, gateKey)
end

-- Register a passive for "Thorns" that only fires for players who own it.
Registry:Register("OnHitReceived", "Thorns", function(ctx)
	print(ctx.victim.Name .. " reflects some damage back!")
	ctx.reflectedDamage = (ctx.dmg or 0) * 0.2
end, 50)

-- Register a wildcard logger that always runs, regardless of ability.
Registry:Register("OnHitDealt", "*", function(ctx)
	print(("%s hit for %d"):format(ctx.attacker.Name, ctx.dmg or 0))
end, 10) -- lower priority number = runs first

-- Fire the hooks for real, so this example is a runnable demonstration.
local attacker = { Name = "Aria", EquippedAbility = "Thorns" }
local victim = { Name = "Bram", EquippedAbility = "Thorns" }

Registry:Fire("OnHitDealt", { attacker = attacker, dmg = 25 })
Registry:Fire("OnHitReceived", { victim = victim, dmg = 25, __gateSide = "victim" }, gateResolver)

return Registry