lua

Lua

Every map can contain a Lua script which can interact with the game via the ZED Online API.
To edit a Lua script open a map with the map editor. Under view switch to Lua to switch from the map screen to the Lua editor.

Hello World

function onGameStart()
    sendNews("Hello World!")
end

This code prints the message "Hello World!" in chat on game start. onGameStart() is a function that will be called by the game when the game is about to start.

Hooks

Hooks are special functions that get called by the game. The name and parameters of these functions are fixed and can now be changed.

onMapLoaded() This function will be called when the map is loaded and before any objects contained in the .zmap file are created
onGameStart() This functions will be called when the game starts. This function will never be called again.
everySecond() This function will be called once per second.
onFrame() This functions will be called once every server tick. About 25 times per second. Code for this function should be as short as possible since it is called so often. Note that while the Lua script is running the server's execution is paused.
onObjectDeath(obj) This function will be called when an object is destroyed. The parameter is a reference to the onject that got destroyed. Note that an objects can be almost everything. A robot, vehicle, cannon, building, rock, tree, grenade box etc.
onChat(message) This function is called when the server receives a chat message. The parameter is a string containing the chat message that was received.

Examples

To create a new object you can use the following code

x = math.random(50*16, 100*16)
y = math.random(50*16, 100*16)
obj = createObject(ROBOT, GRUNT, x, y, RED)
sendNews("Grunt created", 255, 0, 0)

This code generates two random numbers x, y between tile 50 and 100 (note that tiles are 16 pixel wide). createObject() creates a grunt robot for team red at position (x, y). sendNews() then writes a message to chat. Note that 255, 0, 0 is the color red, so the chat message will be shown in red.
Also observe that createObject() returns a reference to the object that was created. You could for example use this reference to kill the object like this:

killObject(obj)

or move the object to the right by 50 pixels by either changing the position directly

x, y = getPosition(obj)
setPosition(obj, x+50, y)

or by issuing a move command

x, y = getPosition(obj)
setWaypoint(obj, MOVE, x+50, y)

Note that getPosition() returns the center position of an object. setPosition() expects the object's center as a command.
setWaypoint() adds a waypoint to the object's list of wayoints. You can delete an object's list of waypoints by calling clearWaypoints().
MOVE is a constant and ensures that an object will do a normal move command. This is the default behavior in the game. Other options are ATTACK, FORCE_MOVE, AGRO, DODGE, ENTER_FORT, etc.

Iterate over all objects

getObjectCount() returns the total number of all objects, getObject() takes one parameter as an index and returns an handle to the corresponding object. You can iterate over all objects like this:

max = getObjectCount()  
for i=0, max-1 do
        obj = getObject(i)
 end

Example: Kill all objects of a player on command

Here, we will use the hook onChat(). If a player write the message "kill" in chat, we will destroy all objects that belong to the blue player.
We will iterate over all objects, check which belong to the blue player and kill it if it does belong to blue.

function onChat(message)
   if (message == "kill") then  --Check if we received the correct command
        max = getObjectCount()     --Get total number of object
        for i=0, max-1 do          --Loop through all objects
           obj = getObject(i)        --Get the handle to the i-th object
          owner =  getOwner(obj)    --Get the owner of the i-th object via the handle
          if (owner == BLUE) then   --If the object belong to the blue player
                  killObject(obj)        --Kill the object. Here we again use the object's handle
          end
     end
 end

Example: Make all light tanks invisible

We will use the handle everySecond() to iterate over all objects. Check every object if it a light tank and if is is make it invisible.

function everySecond()
    max = getObjectCount()                   --Get total number of object
     for i=0, max-1 do                       --Loop through all objects
              obj = getObject(i)                   --Get the handle to the i-th object
             if getType(obj) == VEHICLE then       --If the object is a vehicle
                    if getSubtype(obj) == LIGHT then   --If the vehicle turns out to be a light tank
                         setVisible(obj, false)           --Set visibility to false. This will make the object invisible
                    end
             end
end

Reference of all API functions

addToBuildList(BuildingType, Level, Type, SubType)

Adds a unit to the building list of a production factory. For example after calling addToBuildList(FORT, 1, VEHICLE, HEAVY) level 1 forts (forts with 1 star) should be able to produce heavy tanks.

allowSurrender(Enable)

Enables or Disables the ability for players to surrender.
Call allowSurrender(true) to allow surrendering and allowSurrender(false) to disable it.

createObject(Type, SubType, X, Y, Owner, [palette])

Creates a new objects of a given type and subtype at position X and Y. X and Y are the uper-left corner of the object and must be given in pixels.
Type must be one of the following values:

Value	Description
CANNON	One of the four cannon objects
VEHICLE	Tanks, cranes, APC
ROBOT	One of the six robor types
MAP_ITEM	Objects on the map like rocks, grenade boxes, etc.

Subtype depends on Type. For type CANNON there are the following subtypes

Value	Description
GATLING	t.b.a.
GUN	t.b.a.
HOWITZER	t.b.a.
MISSILE_CANNON	t.b.a.

Subtypes for type VEHICLE:

Value	Description
JEEP	t.b.a.
LIGHT	t.b.a.
MEDIUM	t.b.a.
HEAVY	t.b.a.
APC	t.b.a.
MO_MISSILE	t.b.a.
CRANE	t.b.a.

Subtypes for type ROBOT:

Value	Description
GRUNT	t.b.a.
PSYCHO	t.b.a.
TOUGH	t.b.a.
SNIPER	t.b.a.
PYRO	t.b.a.
LASER	t.b.a.

Subtypes for type MAP_ITEM:

Value	Description
GRENADES	t.b.a.

Owner can be one of the following values:

Value	Description
NEUTRAL	t.b.a.
RED	t.b.a.
BLUE	t.b.a.
GREEN	t.b.a.
YELLOW	t.b.a.
PURPLE	t.b.a.
TEAL	t.b.a.
PINK	t.b.a.
BROWN	t.b.a.

Palette is an optional parameter. If Palette is not specified the objects will use the palette of the map. The specifiy a palette use on of the following values:

Value	Description
DESERT	t.b.a.
VOLCANIC	t.b.a.
ARCTIC	t.b.a.
JUNGLE	t.b.a.
CITY	t.b.a.

Return value:

A reference to the create object will be returned.

createRobotGroup(SubType, X, Y, Owner)

Creates an entire robot group. See createObject() for an explanation of the parameters. This function will for example create 3 Grunt objects a choose on of them to be the leader.

Return value:

The leader object of the group will be returned.

createCannon()

createMissile()

clearWaypoints()

execute()

enableProduction()

getFort()

getHealth(obj)

Returns the number of hitpoints of object obj. For example 50 is returned if the object has 50% of its health.

getOwner()

getType()

getSubtype()

getObjectCount()

getObject()

getPosition()

getPlanet()

Returns the planet type of the loaded map. The return value is either DESERT, VOLCANIC, ARCTIC, JUNGLE or CITY.

getTime()

Returns the number of seconds elapsed after the match started.

getUnitStat_GroupAmount(Type, SubType)

Returns the number of units in a group for a specific type. For example getUnitStat_GroupAmount(ROBOT, GRUNT) should return 3 since there are 3 robots in a group of grunt robots.

getUnitStat_MoveSpeed(Type, SubType)

getUnitStat_AttackDamage(Type, SubType)

getUnitStat_AttackDamageRadius(Type, SubType)

getUnitStat_AttackRange(Type, SubType)

getUnitStat_AttackCooldown(Type, SubType)

getUnitStat_AttackDamageChance(Type, SubType)

getUnitStat_AttackSnipeChance(Type, SubType)

getUnitStat_MissileSpeed(Type, SubType)

getUnitStat_MaxHealth(Type, SubType)

getUnitStat_MaxStamina(Type, SubType)

getUnitStat_BuildTime(Type, SubType)

getUnitStat_VisionDiameter(Type, SubType)

getVisionDiameter(obj)

isInBuildList(BuildingType, Level, Type, SubType)

Returns true if and only if a specific unit can be build by a factory. For example isInBuildList(FORT, 1, ROBOT, GRUNT) should return true since grunts can be build by a level 1 fort (a fort with 1 star).

killObject()

removeFromBuildList(BuildingType, Level, Type, SubType)

Removes a unit from the building list of a production factory. For example after calling removeFromBuildList(FORT, 1, ROBOT, GRUNT) level 1 forts (forts with 1 star) should no longer be able to produce grunts.

sendNews()

setHealth(obj, healthPercent)

Sets the number of hitpoint of obj. For example setHealth(obj, 50) sets the number of hitpoints of object obj to 50% of the maximum hitpoints.

setPosition()

setWaypoint()

setAttackDamage()

setVisionDiameter(obj, newVisionDiameter)

setPalette()

setUnitStat_GroupAmount(Type, SubType, NewGroupAmount)

Sets the number of units in a group for a specific type. For example setUnitStat_GroupAmount(ROBOT, GRUNT, 4) sets the group amount for grunts to 4.
After this change when grunts are produced they should spawn in a group of 4 robots.

setUnitStat_MoveSpeed(Type, SubType, NewMoveSpeed)

setUnitStat_AttackDamage(Type, SubType, NewAttackDamage)

setUnitStat_AttackDamageRadius(Type, SubType, NewDamageRadius)

setUnitStat_AttackRange(Type, SubType, NewAttackRange)

setUnitStat_AttackCooldown(Type, SubType, NewAttackCooldown)

setUnitStat_AttackDamageChance(Type, SubType, NewDamageChance)

setUnitStat_AttackSnipeChance(Type, SubType, NewSnipeChance)

setUnitStat_MissileSpeed(Type, SubType, NewMissileSpeed)

setUnitStat_MaxHealth(Type, SubType, NewMaxHealth)

setUnitStat_MaxStamina(Type, SubType, NewMaxStamina)

setUnitStat_BuildTime(Type, SubType, NewBuildTime)

setUnitStat_VisionDiameter(Type, SubType, NewVisionDiameter)

setVisible()