Game Events Reference#

All script event handlers use camelCase — but the engine matches them case-insensitively, so both onDeath and ondeath work. Use camelCase for readability.

Player Script Events#

Player events are defined in player script classes (e.g. player_events.js). The player instance is always this, not a player parameter. Think of each player as running the script themselves.

function onDeath() {
    this.chat = `I died! My name is: ${this.name}`;
}

onLogin#

Called when the player logs in.

function onLogin() { }

onDeath#

Called when the player dies.

function onDeath(killer) {
    if (killer.type == 'player')
        this.say(`I was killed by ${killer.name}!`);
}

killer — the entity that dealt the killing blow

onKill#

Called when this player kills another player.

function onKill(victim, rejectReason) {
    if (!rejectReason)
        this.say(`I defeated ${victim.name}!`);
}

victim — the killed player
rejectReason:string — "sameip", "playerland", "clanland", or null if kill was counted

onRevive#

Called when the player revives after dying.

function onRevive() { }

onEnterMap#

Called when the player enters a new map or warps.

function onEnterMap(map, template, oldpos) {
    echo(`${this.name} came from ${oldpos.map}`);
}

map:object — map object (see Map Reference)
template:string — map template name
oldpos:object — previous position {x, y, map, template}

onEnvironmentZone#

Called when the player moves into a different environment zone.

function onEnvironmentZone(oldEnvironment, newEnvironment) {
    if (newEnvironment && newEnvironment.zone === "cave")
        this.setambient(0.2, 0.2, 0.4);
}

oldEnvironment:object|null — previous zone object (contains .zone, .map, .weather, .x, .y, etc.)
newEnvironment:object|null — new zone object

onPvPZoneChange#

Called when the player enters or exits a PvP zone.

function onPvPZoneChange(isPvP) {
    if (isPvP) this.showmessage('You entered a PvP zone!');
}

isPvP:boolean — true if now in a PvP zone

onHurt#

Called when the player takes damage.

function onHurt(attacker, damage) { }

attacker — the entity dealing damage
damage:number — damage amount
Return {cancelled: true} to block the damage

onDamage#

Called when the player deals damage to another entity.

function onDamage(target, damage) {
    return {damage: damage * 2}; // double damage
}

target — the entity receiving damage
damage:number — damage amount
Return {damage: newValue, cancelled: bool} to modify or cancel

onWeaponChange#

Called when the player equips a different weapon.

function onWeaponChange(oldWeapon, newWeapon) { }

oldWeapon:object — previous weapon object
newWeapon:object — new weapon object

onCustomUpload#

Called when a player uploads a custom graphic.

function onCustomUpload(fileName, customType) {
    this.echo(`Uploaded custom ${customType}: ${fileName}`)
}

fileName:string — the filename of the uploaded graphic
customType:string — the type of custom (e.g., "head", "body", "shield", etc.)

onCustomChecked#

Called when a staff member approves, rejects, or refunds a custom graphic.

function onCustomChecked(fileName, customType, uploaderUserID, status, reason) {
    this.echo(uploaderUserID + "'s custom " + customType + " was " + status);
}

fileName:string — the filename of the checked custom graphic
customType:string — the type of custom graphic
uploaderUserID:number — the ID of the player who uploaded it
status:string — "approved", "rejected", or "refunded"
reason:string — the reason provided (if rejected)

onPickupItem#

Called when the player picks up an item from the ground.

function onPickupItem(itemid) { }

onSoldItems#

Called when the player sells items.

function onSoldItems(price, itemid, item, itemnr) { }

price:number — total sale price
itemid:string — item ID sold
item — item config object
itemnr:number — quantity sold

onItemPurchase#

Called when the player purchases an item.

function onItemPurchase(price, itemid, item) { }

onJobDone#

Called when the player completes a job (e.g. harvesting, digging).

function onJobDone(jobname) { }

onSays#

Called when the player sends a chat message. Use this.chat to read it.

function onSays() {
    if (this.chat == 'hello')
        this.say('Hi!');
}

onNameChange#

Called when the player changes their display name.

function onNameChange(oldName, newName) { }

onOnlineHour#

Called each hour the player is online.

function onOnlineHour(newHours) {
    this.say(`You've been online for ${newHours} hours!`);
}

onLikeSent#

Called when this player likes another player.

function onLikeSent(likedUserId) { }

onLikeReceived#

Called when another player likes this player.

function onLikeReceived(senderUserId) { }

onSparWin#

Called when the player wins a spar.

function onSparWin(loserUserid, loserInfo) { }

onSparLost#

Called when the player loses a spar.

function onSparLost() { }

onClanJoin#

Called when the player joins a clan.

function onClanJoin(clan) { }

onClanCapture#

Called when the player's clan captures a building.

function onClanCapture(buildingname) { }

onStoryPublish#

Called when the player publishes a story.

function onStoryPublish(story) { }

onEquipPet#

Called when the player equips a pet.

function onEquipPet(item) { }

onTradeFinished#

Called for both players when a trade has been completed.

function onTradeFinished(otherPlayer, myCoins, myItems, otherCoins, otherItems) {
    this.showmessage(`Trade with ${otherPlayer.name} done!`);
}

otherPlayer — the trade partner
myCoins, myItems — what this player gave, otherCoins, otherItems — what the partner gave

onAttackTriggered#

Called when the player triggers an attack.

function onAttackTriggered(currentTime, lastAttackTime) { }

onTransferAccount#

Called when an admin transfers an account with /transferaccount, before the data is merged. Use it to transfer script data (e.g. DB tables).

function onTransferAccount(fromUserid, toUserid) { }

Car Events#

Fired on the player script classes for cars (mounts with mounttype: "car"), e.g. for taxi or escort jobs.

onCarEnter#

Called when the player gets into a car.

function onCarEnter(itemid) { }

onCarExit#

Called when the player gets out of a car.

function onCarExit(itemid) { }

onCarTaken#

Called when the player takes over a parked car or an NPC car (can be disabled with enablecarjacking: false in main.json).

function onCarTaken(parkedByUserid, itemid) {
    if (parkedByUserid)
        this.showmessage("You stole someone's car!");
}

parkedByUserid — user id of the player who left the car there, or null

Related: player.cardamage, player.repaircar(), player.escortpassenger (see Player Reference).

Payment Events#

onLoadPaymentPackages#

Called when the client requests the coin packages; answer with player.sendpaymentpackages(data).

function onLoadPaymentPackages(platform, minCoins) { }

onCompletePayment#

Called after a purchase if completepaymentbyscript is enabled in main.json, instead of adding the coins automatically.

function onCompletePayment(productid, isValid, isTest) { }

Item / Weapon Events#

onEquip#

Called on an item or weapon script when equipped.

// Server-side item scripts:
function onEquip(player, autoequip) { }

// Client-side weapon scripts:
function onEquip(player) { }

autoequip:boolean — true if auto-equipped on pickup

onUnequip#

Called when the item/weapon is unequipped.

function onUnequip(player) { }

Effect Events#

onEffectStart#

Called when a status effect is applied to the player.

function onEffectStart(effectType) { }

onEffectEnd#

Called when a status effect ends.

function onEffectEnd(effectType) { }

Console Events#

These only fire for players with admin access who have the console open.

onConsoleOpen#

function onConsoleOpen() { }

onConsoleClose#

function onConsoleClose() { }

onConsoleChat#

Called when the admin types in the console. Return true to suppress the default output.

function onConsoleChat(message) {
    if (message == 'hello') {
        this.echo('Hi from script!');
        return true;
    }
}

Client-Side Display Events#

These events fire on the client (in player_events.js or a client script class) when specific player properties change visually.

onCoinsChange#

Called when the player's coin count changes.

function onCoinsChange() {
    // this.coins holds the new value
}

onBodyChange#

Called when the player's equipped body item changes.

function onBodyChange() { }

onHatChange#

Called when the player's hat changes.

function onHatChange() { }

onHeadChange#

Called when the player's head item changes.

function onHeadChange() { }

onShieldChange#

Called when the player's shield changes.

function onShieldChange() { }

Custom / Scheduled Events#

onEVENT (custom)#

Triggered by this.scheduleevent(delay, "eventname", ...params).

this.scheduleevent(2, 'myEvent', 42);

function onMyEvent(value) {
    this.say(`Triggered with: ${value}`);
}

onTimeout#

Triggered after this.settimeout(seconds).

this.settimeout(3);

function onTimeout() {
    this.say('3 seconds passed!');
}

onStoryEnd#

Triggered when a non-looping story finishes (via setstory).

function onStoryEnd(storyid) { }