Creating and Firing Projectiles with Lua in RollingQuest

Projectiles are objects that travel through the level and explode when they hit something. You create them with Level.createProjectile, configure their speed, direction, homing behavior, and explosion rules, then fire them — either automatically at creation or manually in your own code. Every projectile can carry onFire, onExplode, and onUpdate callbacks so you have frame-by-frame control over its behavior.

Creating a Projectile

The simplest signature creates a projectile using an inline property table:

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

You can also pass a ProjectileRequest object instead of a table.

Full Property Table

All fields except skin, origin, and rotation are optional.

Field	Type	Description
`skin`	`string`	Skin ID to use (see `Level.getAvailableProjectileSkins()`)
`origin`	`Vector3`	World-space spawn position
`rotation`	`Quaternion`	Initial facing direction
`tag`	`string?`	Arbitrary tag for identification
`power`	`number?`	Damage power of the projectile
`lifetime`	`number?`	Seconds before the projectile auto-explodes
`speed`	`number?`	Initial travel speed
`acceleration`	`number?`	Speed change per second
`homingStrength`	`number?`	How strongly the projectile tracks the ball (0 = none)
`maxHomingRange`	`number?`	Maximum distance at which homing activates
`autoFire`	`boolean?`	If `true`, fire immediately at creation
`explodeOnCollideWithBlocks`	`boolean?`	Explode on block contact
`explodeOnCollideWithItems`	`boolean?`	Explode on item contact
`explodeOnCollideWithEnemies`	`boolean?`	Explode on enemy contact
`explodeOnCollideWithBalls`	`boolean?`	Explode on ball contact
`explodeOnCollideWithDecorations`	`boolean?`	Explode on decoration contact
`onFire`	`function?`	Called when the projectile is fired
`onExplode`	`function?`	Called when the projectile explodes
`onUpdate`	`function?`	Called every frame with `(projectile, deltaTime)`

Using `ProjectileRequest`

ProjectileRequest is a class alternative to the inline table. It is useful when you want to build the configuration incrementally or reuse a base configuration.

local req = ProjectileRequest.new("fireball_skin")
req.origin    = Vector3.new(10, 2, 5)
req.rotation  = Quaternion.identity
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)

Querying Available Skins

function Level.getAvailableProjectileSkins(): table

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

The `Projectile` Object

Level.createProjectile returns a Projectile. You can read and write its properties after creation, and call methods to fire or detonate it manually.

Key Properties

Property	Type	R/W	Description
`isActive`	`boolean`	R	`true` while the projectile is in flight
`isHoming`	`boolean`	R	`true` when `homingStrength > 0`
`position`	`Vector3`	R/W	Current world position
`rotation`	`Quaternion`	R/W	Current rotation
`forward`	`Vector3`	R	Forward direction vector
`velocity`	`Vector3`	R	Current velocity vector
`speed`	`number`	R/W	Travel speed
`lifetime`	`number`	R/W	Remaining lifetime
`homingStrength`	`number`	R/W	Homing tracking strength

Fire and Explode

function Projectile:fire()
function Projectile:fire(initialSpeed)
function Projectile:fire(position)
function Projectile:fire(position, rotation)
function Projectile:fire(position, rotation, initialSpeed)

function Projectile:explode()
function Projectile:explode(rotation)

The `OnProjectileCollide` Hook

Any entity script can define OnProjectileCollide to react when a projectile hits it:

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

Complete Example — Enemy That Fires a Homing Projectile

local FIRE_INTERVAL = 4.0
local PROJECTILE_SKIN = "enemy_fireball"
local cooldown = FIRE_INTERVAL

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

    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

    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,

        onExplode = function(projectile)
            local bPos = Level.currentBall.position
            local dist = Vector3.distance(projectile.position, bPos)
            if dist < 1.5 then
                Level.loseLives(1)
                Dialog.createTemporary("You were hit!", 2.0, Color.red)
            end
        end,
    })
end

Get Started

Core Concepts

Recipes

Creating and Firing Projectiles with Lua in RollingQuest

Creating a Projectile

Full Property Table

Using `ProjectileRequest`

Querying Available Skins

The `Projectile` Object

Key Properties

Fire and Explode

The `OnProjectileCollide` Hook

Complete Example — Enemy That Fires a Homing Projectile

​Creating a Projectile

​Full Property Table

​Using ProjectileRequest

​Querying Available Skins

​The Projectile Object

​Key Properties

​Fire and Explode

​The OnProjectileCollide Hook

​Complete Example — Enemy That Fires a Homing Projectile

Creating a Projectile

Full Property Table

Using `ProjectileRequest`

Querying Available Skins

The `Projectile` Object

Key Properties

Fire and Explode

The `OnProjectileCollide` Hook

Complete Example — Enemy That Fires a Homing Projectile