Skip to main content
The Item class represents any collectible object placed on a side in a RollingQuest level. Scripts attached to an item receive it as self in hooks such as OnCollect and OnRespawn. You can read the item’s state, programmatically collect it for any ball, and toggle its presence in the level. RollingQuest ships with a large library of typed item sub-classes — from simple collectibles like ItemCoin to gameplay modifiers like ItemSlowMotion — all inheriting the properties and methods described here.

​
Properties

​
Identity

PropertyTypeRead-onlyDescription
typeEntityType✅Always EntityType.Item (3).
namestring✅Name derived from the item’s template.
tagstring✅Tag used for categorisation and scripted lookup.

​
Transform

PropertyTypeRead-onlyDescription
positionVector3✅World-space position of the item.
rotationQuaternion✅World-space rotation of the item.
basisBasis✅Local coordinate-system basis of the item.
slotBlockSlot✅Grid slot of the block the item is placed on.
sectionstring✅ID of the level section containing the item.

​
State

PropertyTypeRead-onlyDescription
isEnabledboolean✅true while the item is visible and collectible.
isTreasureboolean✅true when the item counts as a treasure collectible.
isKeyboolean✅true when the item is a key type.
isFruitboolean✅true when the item is a fruit type.
treasureScoreinteger✅Point value awarded when collected as a treasure.
developerModeOnlyboolean✅true when the item only appears in developer mode.
propertiesElementPropertyPool✅Custom property pool attached to the item.
localDataRawLocalData✅Per-instance local data store for this item.

​
Methods

​
collect

--- @param collectorBall Ball
function Item:collect(collectorBall)
Forces the specified ball to collect this item immediately, triggering the normal collection logic.

​
enable / disable

function Item:enable()
function Item:disable()
Show or hide the item. A disabled item is invisible and cannot be collected until re-enabled.

​
Type-cast helpers

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

​
ItemData

ItemData is the raw, mutable representation used when building level data (e.g. in OnLevelLoad). It exposes template, scriptRef, scriptTag, scriptVars, and properties as writable fields, plus isRespawnEnabled and respawnTime which control whether the item reappears after being collected. Call clear() to reset it to defaults.

​
Item Subtypes

All of the following sub-classes inherit every property and method from Item. You receive the most specific type automatically when accessing items at runtime.
Sub-classDescription
ItemKeyA key used to unlock exits or doors within the level.
ItemCoinA basic coin collectible that awards score.
ItemDiamondA premium collectible worth more score than a coin.
ItemFruitA fruit collectible; the level’s fruit trophy item.
ItemGobletA trophy-style collectible.
ItemLetterCollects a letter toward spelling out a bonus word.
ItemBatteryRestores a time bonus or recharges a level timer.
ItemTimePlusAdds time to the level countdown timer.
ItemTimeMinusSubtracts time from the level countdown timer.
ItemLiveUpAwards an extra life.
ItemShieldGrants the ball a temporary protective shield.
ItemSlowMotionActivates slow-motion movement for the ball.
ItemBouncingPillSwitches the ball to bouncing jump mode.
ItemJumpBanPillBans the ball from jumping for a duration.
ItemSleepingPillBriefly immobilises the ball.
ItemPoisonApplies a harmful status effect to the ball.
ItemMirrorActivates mirrored controls for the ball.
ItemGlassesReveals hidden blocks or level elements.
ItemLightBulbIlluminates dark areas or activates light-sensitive elements.
ItemTorchProvides localised light in dark level sections.
ItemHourglassModifies the timer or freezes it temporarily.
ItemGravityArrowRedirects the ball’s gravity to a new face.
ItemFarJumpModifierIncreases the ball’s horizontal jump distance.
ItemMessageDisplays a custom message when collected.
ItemPortalEntranceActivates a portal that teleports the ball on contact.

​
Usage Example

The OnCollect hook fires when a ball collects the item. The example below logs the collector’s name and disables the item for 5 seconds before re-enabling it: 
function OnCollect(self, ball)
    -- self is an Item
    Log.info(ball.name .. " collected item: " .. self.name)

    -- Disable and schedule re-enable using a timer
    self:disable()

    Timer.schedule(5.0, function()
        self:enable()
    end)
end
You can also collect an item manually from another script — for example when a ball steps onto a trigger side: 
function OnBallRoll(self, ball)
    -- self is a Side
    if self.hasItem and self.item.tag == "bonus_coin" then
        self.item:collect(ball)
    end
end