Creating and Firing Projectiles with Lua in RollingQuest

--- @param projectileProperties { ... }
--- @return Projectile
function Level.createProjectile(projectileProperties)

--- Create in a named section
--- @param sectionId string
--- @param projectileProperties { ... }
--- @return Projectile
function Level.createProjectile(sectionId, projectileProperties)

--- Constructors
function ProjectileRequest.new(): ProjectileRequest
function ProjectileRequest.new(skin: string): ProjectileRequest
function ProjectileRequest.new(skin: string, origin: Vector3, rotation: Quaternion): ProjectileRequest

local req = ProjectileRequest.new("fireball_skin")
req.origin    = Vector3.new(10, 2, 5)
req.rotation  = Quaternion.identity        -- point forward
req.speed     = 8.0
req.lifetime  = 6.0
req.homingStrength  = 2.5
req.maxHomingRange  = 20.0
req.autoFire  = true
req.explodeOnCollideWithBalls = true

req.onExplode = function(projectile)
    Dialog.createTemporary("Direct hit!", 1.5, Color.red)
end

local proj = Level.createProjectile(req)

--- Returns a table of skin ID strings for the main section
function Level.getAvailableProjectileSkins(): table

--- Returns skins for a specific section
function Level.getAvailableProjectileSkins(sectionId: string): table

-- Print all available skins to the log (useful during development)
local skins = Level.getAvailableProjectileSkins()
for _, skinId in ipairs(skins) do
    print("Skin available: " .. skinId)
end

-- Fire from the projectile's current origin and rotation
function Projectile:fire(): any

-- Fire with a specific initial speed override
function Projectile:fire(initialSpeed: number): any

-- Fire from a specific world position
function Projectile:fire(position: Vector3): any

-- Fire with a specific rotation
function Projectile:fire(rotation: Quaternion): any

-- Fire from a position and rotation
function Projectile:fire(position: Vector3, rotation: Quaternion): any

-- Fire with full override: position, rotation, and speed
function Projectile:fire(position: Vector3, rotation: Quaternion, initialSpeed: number): any

-- Explode immediately at current position
function Projectile:explode(): any

-- Explode with a specific rotation (for directional explosion effects)
function Projectile:explode(rotation: Quaternion): any

---@param self Ball
---@param projectile Projectile
function OnProjectileCollide(self, projectile)
    -- 'projectile' is the Projectile that struck this entity
    if projectile.tag == "enemy_shot" then
        Dialog.createTemporary("Ouch! You were hit!", 2.0, Color.red)
    end
end

-- Enemy script: homing_shooter

local FIRE_INTERVAL = 4.0   -- seconds between shots
local PROJECTILE_SKIN = "enemy_fireball"

local cooldown = FIRE_INTERVAL  -- start ready to fire on spawn

function OnSpawn(self)
    -- Nothing special needed on spawn; cooldown starts at max
end

function OnUpdate(self, deltaTime)
    cooldown = cooldown - deltaTime

    if cooldown <= 0 then
        cooldown = FIRE_INTERVAL
        fireAtBall(self)
    end
end

function fireAtBall(enemy)
    local ball = Level.currentBall
    if ball == nil or not ball.isAlive then
        return
    end

    -- Calculate direction from enemy to ball
    local enemyPos = enemy.position
    local ballPos  = ball.position

    local dx = ballPos.x - enemyPos.x
    local dy = ballPos.y - enemyPos.y
    local dz = ballPos.z - enemyPos.z

    -- Use Quaternion.lookRotation to face the ball
    local direction = Vector3.new(dx, dy, dz).normalized
    local shotRotation = Quaternion.lookRotation(direction, Vector3.up)

    Level.createProjectile({
        skin     = PROJECTILE_SKIN,
        origin   = Vector3.new(enemyPos.x, enemyPos.y, enemyPos.z),
        rotation = shotRotation,
        tag      = "enemy_shot",
        speed    = 6.0,
        lifetime = 8.0,
        homingStrength = 3.0,
        maxHomingRange = 25.0,
        autoFire = true,
        explodeOnCollideWithBalls   = true,
        explodeOnCollideWithBlocks  = true,

        onFire = function(projectile)
            -- Optional: play a visual cue (not shown — use engine events)
        end,

        onExplode = function(projectile)
            -- If the projectile is near the ball when it explodes, lose a life
            local proj  = projectile
            local bPos  = Level.currentBall.position
            local dist  = Vector3.distance(proj.position, bPos)
            if dist < 1.5 then
                Level.loseLives(1)
                Dialog.createTemporary("You were hit!", 2.0, Color.red)
            end
        end,
    })
end

function OnDeath(self)
    -- Enemy died; nothing to clean up since projectiles have their own lifetime
end