Skip to main content
The Enemy class represents a hostile entity that roams the game world and can harm or interact with the ball. Scripts attached to an enemy receive it as self in hooks such as OnDeath and OnUpdate. Through the Enemy API you can read its position and orientation, toggle whether it responds to specific level hazards (via EnemyInteraction flags), and kill or disable it programmatically.

​
Properties

​
Identity

PropertyTypeRead-onlyDescription
typeEntityType✅Always EntityType.Enemy (4).
namestring✅Name derived from the enemy’s template.
tagstring✅Tag used for grouping and scripted lookup.

​
Transform

PropertyTypeRead-onlyDescription
positionVector3✅World-space position of the enemy.
rotationQuaternion✅World-space rotation of the enemy.
basisBasis✅Local coordinate-system basis of the enemy.
sectionstring✅ID of the level section the enemy is currently in.
currentGroundSideSide✅The side the enemy is standing on, or nil if airborne.

​
Data

PropertyTypeRead-onlyDescription
propertiesElementPropertyPool✅Custom property pool attached to the enemy.
localDataRawLocalData✅Per-instance local data store for this enemy.

​
Methods

​
enable / disable

function Enemy:enable()
function Enemy:disable()
Activate or deactivate the enemy. A disabled enemy is removed from play until re-enabled.

​
kill

function Enemy:kill()
Destroys the enemy immediately, triggering its death logic.

​
enableInteraction / disableInteraction

--- @param interaction EnemyInteraction
function Enemy:enableInteraction(interaction)

--- @param interaction EnemyInteraction
function Enemy:disableInteraction(interaction)
Toggle whether the enemy responds to a specific EnemyInteraction type.

​
setInteractionEnabled

--- @param interaction EnemyInteraction
--- @param enabled boolean
function Enemy:setInteractionEnabled(interaction, enabled)
A single-call alternative to enableInteraction/disableInteraction.

​
isInteractionEnabled

--- @param interaction EnemyInteraction
--- @return boolean
function Enemy:isInteractionEnabled(interaction)
Returns true when the given interaction is currently active for this enemy.

​
Type-cast helpers

Use these to narrow a generic entity reference to a concrete type. Each throws an error if the cast is invalid. 
function Enemy:asLevel()      -- returns Level
function Enemy:asBlock()      -- returns Block
function Enemy:asSide()       -- returns Side
function Enemy:asItem()       -- returns Item
function Enemy:asEnemy()      -- returns Enemy
function Enemy:asBall()       -- returns Ball
function Enemy:asDecoration() -- returns Decoration

​
EnemyInteraction Enum

The EnemyInteraction enum controls which level hazards and mechanics the enemy reacts to. Use it with the interaction methods above.
MemberValueDescription
Spikes0Enemy is affected by spike sides.
Lasers1Enemy is affected by laser sides.
Teleports2Enemy can be transported by teleport sides.
Buttons3Enemy can activate button sides.
LightSensors4Enemy can trigger light-sensor sides.
DirectionRestrictions5Enemy obeys one-way and multi-way direction limits.
Ice6Enemy is affected by icy surfaces.
Fire7Enemy is affected by fire/flame surfaces.
BreakingBlocks8Enemy interacts with breaking-block mechanics.
TrampsAndVents9Enemy is affected by trampolines and vents.
Magnets10Enemy is affected by magnetic sides.
Rotators11Enemy is affected by rotator sides.
BallShield12Enemy can interact with a ball’s active shield.
InvisibleBlocks13Enemy can collide with invisible blocks.

​
EnemyData

EnemyData is the mutable data representation used when building or modifying level data (e.g. in OnLevelLoad). It exposes template, scriptRef, scriptTag, scriptVars, properties, the read-only initialPosition (BlockLocation), and an interactions array (EnemyInteraction[]). The same four interaction helper methods — enableInteraction, disableInteraction, setInteractionEnabled, isInteractionEnabled — are available on EnemyData for use at design time. Call clear() to reset all fields.

​
Usage Example

The OnDeath hook fires when an enemy is killed. The example below checks whether the ball that killed the enemy has a shield, then disables all spike interactions on a second enemy: 
function OnDeath(self, ball)
    -- self is an Enemy
    Log.info("Enemy killed: " .. self.name)

    if ball ~= nil and ball.hasShield then
        Log.info("Ball used its shield to kill the enemy.")
    end
end
You can also interact with enemies from a side script. The snippet below kills every enemy in the section when the ball rolls onto a specific trigger side: 
function OnBallRoll(self, ball)
    if self.tag ~= "kill_trigger" then return end

    local section = Level.getSection(self.section)
    for _, enemy in ipairs(section:getEnemies()) do
        enemy:kill()
    end
end