-- Snapshot memory usage across a frame
local function measureFrame(frameFunc)
    collectgarbage("stop")           -- pause automatic GC temporarily
    local before = collectgarbage("count")  -- returns KB used as float

    frameFunc()                      -- run your game logic

    local after = collectgarbage("count")
    collectgarbage("restart")        -- resume automatic GC

    return after - before            -- KB allocated this frame
end

-- Usage: log over 100 frames to find spikes in a hot path
for i = 1, 100 do
    local allocated = measureFrame(function() entity:doTheThing(dt) end)
    if allocated > 10 then           -- threshold: tune to your budget
        print(string.format("Frame %d: %.2f KB allocated", i, allocated))
    end
end

-- Runs every frame, for every entity:
function onEntityMoved(entity)
    local event = {              -- new table allocated here
        id     = entity.id,
        type   = "move",
        x      = entity.x,
        y      = entity.y
    }
    eventBus:dispatch(event)     -- event lives briefly, then becomes garbage
end

-- Pool size: base on your expected max entities, plus a safety buffer.
-- If your entity budget is 256, a 25% buffer gives 320 slots.

local MAX_ENTITIES  = 256
local POOL_SIZE     = math.ceil(MAX_ENTITIES * 1.25)  -- 320; adjust to your cap
local _pool         = {}
local _poolIndex    = 0

-- Initialize the pool once at startup--not per frame
for i = 1, POOL_SIZE do
    _pool[i] = { id = 0, type = "", x = 0.0, y = 0.0 }
end

-- Reuse a slot instead of allocating a new table
local function getPooledEvent(entity, eventType)
    -- Wrap index: when we hit POOL_SIZE, cycle back to 1
    _poolIndex = (_poolIndex % POOL_SIZE) + 1

    local event = _pool[_poolIndex]  -- grab existing table

    -- Overwrite fields; no new table is created
    event.id   = entity.id
    event.type = eventType
    event.x    = entity.x
    event.y    = entity.y

    return event
end

eventBus:dispatch(getPooledEvent(entity, "move"))

-- Before: global lookup on every iteration
function updateProjectiles(dt)
    for i = 1, #projectiles do
        local p = projectiles[i]
        -- math.cos and math.sin are resolved via _ENV each call
        p.x = p.x + math.cos(p.angle) * p.speed * dt
        p.y = p.y + math.sin(p.angle) * p.speed * dt
    end
end

-- After: one lookup per function call, register access in the loop
function updateProjectiles(dt)
    local cos = math.cos   -- resolved once, stored in register
    local sin = math.sin
    local ps  = projectiles  -- local ref to the global table too

    for i = 1, #ps do
        local p = ps[i]
        p.x = p.x + cos(p.angle) * p.speed * dt
        p.y = p.y + sin(p.angle) * p.speed * dt
    end
end

-- Each call to Enemy.new() allocates new function objects for every method
function Enemy.new(enemyType, maxHealth)
    local self = { type = enemyType, health = maxHealth }

    -- New function object allocated here for each instance:
    function self:takeDamage(amount)
        -- Also worth a note that : syntax desugars to function(self, amount), the self shadows the outer local.
        -- The inner self is the call-site receiver, not the constructor's self. This is a common source of confusion and bugs.
        self.health = math.max(0, self.health - amount)
    end

    function self:isAlive()
        return self.health > 0
    end

    return self
end
-- 500 enemies = 1,000 function allocations, none shared

-- Enemy is a table acting as a "class" (prototype)
local Enemy = {}

-- __index: when a field isn't found on an instance, look here next.
-- This is Lua's mechanism for prototype-based inheritance.
Enemy.__index = Enemy

function Enemy.new(enemyType, maxHealth)
    -- setmetatable(table, meta): attaches a metatable to a table.
    -- When Lua can't find a key on the returned instance, it follows
    -- __index to Enemy and finds methods there instead.
    local instance = setmetatable({}, Enemy)

    instance.type      = enemyType
    instance.health    = maxHealth
    instance.maxHealth = maxHealth

    return instance
end

-- Methods live on Enemy--not copied per instance
function Enemy:takeDamage(amount)
    -- 'self' is the instance; colon syntax is shorthand for
    -- function Enemy.takeDamage(self, amount)
    self.health = math.max(0, self.health - amount)
end

function Enemy:isAlive()
    return self.health > 0
end

function Enemy:getHealthPercent()
    return self.health / self.maxHealth
end

-- 500 enemies share the same three function objects on Enemy

local Character = {}
Character.__index = Character

function Character.new(name, health)
    -- Base constructor: creates a Character instance
    return setmetatable({ name = name, health = health }, Character)
end

function Character:takeDamage(amount)
    self.health = math.max(0, self.health - amount)
end

function Character:isAlive()
    return self.health > 0
end

-- Enemy inherits from Character.
-- setmetatable on Enemy itself (not an instance): when Enemy doesn't
-- have a key, look at Character. This chains the prototype lookup.
local Enemy = setmetatable({}, { __index = Character })
Enemy.__index = Enemy

function Enemy.new(name, health, experienceValue)
    -- Call Character.new to set up the base fields--
    -- this is Lua's equivalent of super() in other languages.
    -- We then re-setmetatable the result to point to Enemy,
    -- so Enemy's methods shadow Character's where defined.
    local instance = Character.new(name, health)
    instance.experienceValue = experienceValue
    return setmetatable(instance, Enemy)  -- re-bind metatable to Enemy
end

function Enemy:takeDamage(amount)
    -- Override with armor mitigation, then call the base:
    local mitigated = math.max(0, amount - (self.armor or 0))
    -- Explicit super call: Character.takeDamage(self, ...) bypasses
    -- Enemy's __index and calls Character's version directly.
    Character.takeDamage(self, mitigated)
end

function Enemy:getExperience()
    return self.experienceValue
end

-- This creates a new string every call:
local function makeKey(entityId, category)
    return entityId .. "_" .. category  -- fresh allocation each time
end

-- Called 10,000 times? 10,000 new strings.

-- Cache: stores the constructed key string so subsequent calls return
-- the existing interned value instead of re-concatenating.
local _keyCache = {}

local function getCachedKey(entityId, category)
    -- Two-level index: _keyCache[entityId] is a sub-table per entity
    local byEntity = _keyCache[entityId]
    if not byEntity then
        byEntity = {}
        _keyCache[entityId] = byEntity
    end

    local key = byEntity[category]
    if not key then
        -- Build the string once, store for reuse
        key = entityId .. "_" .. category
        byEntity[category] = key
    end

    return key  -- same string object on every subsequent call
end

-- Pre-compute at module load; no concatenation at runtime
local Keys = {
    ENEMY_MOVE    = "enemy_move",
    ENEMY_ATTACK  = "enemy_attack",
    ENEMY_DEATH   = "enemy_death",
    PLAYER_MOVE   = "player_move",
}

-- Usage in hot path: no allocation, just a table lookup
eventBus:dispatch(Keys.ENEMY_MOVE, entity)