Table of Contents

Events Reference

Here is a list of all the events currently supported by the world server.

Player Status Events

NewPlayer

Triggered by A new player logging in to the world for the first time
Event Parameter None
CancelTransaction N/A

Example

Event( "NewPlayer", "" )
{
    *say Welcome %PLAYER% to our world!
}

PlayerLogin

Triggered by A player logging in to the world
Event Parameter None
CancelTransaction N/A
Notes

Example

Event( "PlayerLogin", "" )
{
    *say %PLAYER% has entered our world!
}

PlayerLoginComplete

Triggered by A player completing the log-in process to the world
Event Parameter None
CancelTransaction N/A
Notes

Example

Event( "PlayerLoginComplete", "" )
{
    *say %PLAYER% has finished entering our world!
}

PlayerLogout

PlayerBirthday

PlayerChangeVehicle

PlayerDeath

PlayerKilled

RobocrowKilled

RobocrowKill

StartFishing

OnFish

PlayerRespawn

PlayerResurrect

OSDSelect

Triggered by Player clicking a scripted OSD item
Event Parameter OSDName:OSDButtonName
CancelTransaction N/A
Notes For details on created scripted UI, see the Scripted OSD Overview


Triggered by A player selecting a customisable menu or button in the main game UI
Event Parameter Menu number :
1 = Custom main menu item linked to F9 (Set with … ?? )
2 = Player list popup button 1
3 = Player list popup button 2
4 = Player list popup button 3
5 = Player list popup button 4
6 = Info screen custom button 1
7 = Info screen custom button 2
8 = Pub custom button 1
9 = Pub custom button 2
10 = Pub custom button 3
11 = Pub custom button 4
12 = Pub custom button 5
CancelTransaction N/A
Notes Most of these events won't appear until you've first set up the particular custom menu option or other settings. (e.g. You must use *scriptedoption 18,[BUTTON_TEXT] to activate the 'Info screen custom button 1'. See the scripting main ui doc for a full list of configurable options and interfaces.)

Example

Event( "MenuOption", "1" )
{
    *notify %PLAYER% You selected a custom menu option
}

ItemDetails

Triggered by Player clicking the custom 'Details' button on the inventory item popup
Event Parameter Item Name
CancelTransaction N/A
Notes This will only be triggered on items that have had a custom details button enabled using *itemdetailstext ItemNum,ButtonText

Example

Event( "ItemDetails", "Bronze Sword" )
{
    osdcreate(OSDLOWER,"SwordOSD", "- Bronze Sword -" ) 
    osdadd(TEXT, 0, 0, 600, 80, "", "The Bronze Sword is a basic weapon, +4 dmg, occupies 1 inventory slot etc." )
    osdactivate()
}

MapClick

Triggered by The player clicking on a tile on the landscape when they're in a vehicle using Control Mode = 34. This is an experimental mode, probably requiring further development, that is intended to let you build scripted games using a different control methodology.
Event Parameter None
CancelTransaction N/A

Example

Event( "MapClick", "" )
{
    $mapX = $gClickX
    $mapY = $gClickY
    *msg %PLAYER% You clicked on tile $mapX, $mapY
}

ViewTournament

ActivateGuide

Inventory & Skill Events

UseItem

Triggered by An item being used by the player
Event Parameter Item Name
CancelTransaction Cancels the normal 'Use' behaviour (the normal behaviour usually involves removing the item from the inventory). e.g. If a food item, the world server would normally remove the item from the player's inventory and update their hunger.
Notes Not all items will always have a 'Use' option. You can control which ones do or don't by changing their behaviour using *setitemuse or by setting the *settings → World Rules → Inventory Mode. (Inventory Mode 2 makes all items usable irrespective of their behaviour type)

Example

Event( "UseItem", "Axe" )
{
    *msg %PLAYER% You used the axe to chop down the nearest tree
    *grantitem %PLAYER% 1 Wood
    CancelTransaction()    // Calling this means the player keeps the Axe
}

ItemAdded

Triggered by A new item being added to the player's inventory
Event Parameter Item Name
CancelTransaction N/A
Notes

Example

Event( "ItemAdded", "Bronze Sword" )
{
    // Level up when the player first gets a bronze sword
    if ( $gPlayerLevel < 1 )
    {
        *setlevel %PLAYER% 1
        *notifylarge %PLAYER% Level up!
    }
}

ItemRemoved

UseSkill

SkillAdded

SkillRemoved

BarterRequest

Weapon Events

FireWeapon

WeaponHitGround

WeaponHitPlayer

Task System Events

BuildingTaskStart

Triggered by A player building task starting (See *dobuildingtask)
Event Parameter Building Type
CancelTransaction N/A
Notes $gTaskItem1 = 2. $gTaskItem2 = Building record num.

Example

Event( "BuildingTaskStart", "10" )
{
    *msg %PLAYER% You triggered a building task from a building of type 10
}

CustomTaskStart

CombiTaskStart

BuildingTaskComplete

CustomTaskComplete

CombiTaskComplete

TaskComplete

Triggered by A player task completing
Event Parameter Task Type
0 = Combination task (Triggered through the 'Combination Item' interface or via *docombitask command)
1 = Custom task (Triggered through the *dotask command)
2 = Building task (Triggered through the *dobuildingtask command)
CancelTransaction N/A
Notes TBD - $gTaskItem1 etc

Example

Event( "TaskComplete", "1" )
{
    if ( $gTaskItem1 == 100 )
    {
        *msg %PLAYER% You completed task 100 
    }
}

TaskStart

Building Events

NewBuilding

PreAccessBuilding

AccessBuilding

AccessConstruction

BuildingPurchase

BuildingDestroyed

BuildingTriggered

BuildingTriggerSequenceComplete

BuildingProductionRun

BuildingDemolished

BuildingOwnerDied

PlaceBuilding

PlaceAnyBuilding

BuildingCapture

BuildingIDProxEnter

BuildingIDProxLeave

BuildingProxEnter

BuildingProxLeave

PickupBuilding

BuildingDamaged

Minigame Events

ActivateRC

CrowFlagTouch

CrowFlagTouchAny

CrowExit

Subgame

SubgameDuelStart

SubgameDuelCountdownStart

RaceStart

RaceEnd

RaceWinner

FlagPickup

FlagCapture

HornballGoal

EnterGameZone

ExitGameZone

Timed Events

DayOfYear

OnTheHour

Triggered by Realtime clock reaching the hour
Event Parameter None
CancelTransaction N/A

Example

Event( "OnTheHour", "" )
{
    $numBongs = sysRealTime("Hour")
    if ( $numBongs > 12 )
    {
        $numBongs -= 12
    }
    $loop = 0
    while ( $loop < $numBongs )
    {
       	*customsoundall 1
       Sleep(10)
       $loop += 1
    }
}

TenToTheHour

FiveToTheHour

WorldUpdate

Triggered by Regular time interval specified in seconds in *settingsWorldScript Empty WorldUpdate Timer or Script WorldUpdate Timer ; The 'Empty' value is used when there are no players on the world. If the settings value is 0 the timer is not called.
Event Parameter None
CancelTransaction N/A

Special Server Events

Custom

ProductionRunStart

ProductionRunEnd

EndSequence

&command

Timer

ScriptReload

RangeLeave

SeaDepth

KillWildlife

Triggered by A player killing wildlife
Event Parameter The type of the wildlife (Defaults to 0)
CancelTransaction N/A

Example

Event( "KillWildlife", "0" )
{
    *say %PLAYER% called a sheep
    *grantitem %PLAYER% 1 Wool
}

BongoChant

Entity Events

EntityDestroyed

EntityDamaged

EntityUpdate

EntityPickup

Town Events

TownButton

TownDeclareWar

TownEndWar

Battle Events

InitChallenge

AcceptChallenge

BattleStart

BattleUpdate

BattleEnd

BattleSurrender

BattleLeave

BattleJoin

BattleAcceptSurrender

BattleComplete