Recent changes to lua

lua modified by DaMarkov

DaMarkov — Wed, 16 Dec 2020 21:56:02 -0000

--- v9
+++ v10
@@ -18,6 +18,7 @@

 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.
@@ -109,6 +110,14 @@
 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.
@@ -199,19 +208,76 @@
 #####execute()#####
 #####enableProduction()#####
 #####getFort()#####
-#####getTime()#####
-#####setPosition()#####
+
+#####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()#####
-#####getObjectCount()#####
-#####getObject()#####
+
+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()#####

lua modified by DaMarkov

DaMarkov — Thu, 02 May 2019 13:03:14 -0000

--- v8
+++ v9
@@ -183,15 +183,16 @@
 JUNGLE |  t.b.a.
 CITY |  t.b.a.

-Return value:
+######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:
+######Return value:######
 The leader object of the group will be returned.
+
 #####createCannon()#####
 #####createMissile()#####
 #####clearWaypoints()#####

lua modified by DaMarkov

DaMarkov — Thu, 02 May 2019 13:01:33 -0000

--- v7
+++ v8
@@ -109,9 +109,10 @@
 Reference of all API functions
 --

-    #####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:
+#####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
 ---------- | ----------
@@ -186,6 +187,7 @@
 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:

lua modified by DaMarkov

DaMarkov — Thu, 02 May 2019 13:00:24 -0000

--- v6
+++ v7
@@ -112,6 +112,7 @@
     #####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      
@@ -119,10 +120,8 @@
 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.
@@ -131,52 +130,57 @@
 MISSILE_CANNON | t.b.a.

 Subtypes for type VEHICLE:
-Value | Description
----------- | ----------
-JEEP     | 
-LIGHT      | 
-MEDIUM        | 
-HEAVY | 
-APC | 
-MO_MISSILE | 
-CRANE | 
+
+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     | 
-PSYCHO      | 
-TOUGH        | 
-SNIPER | 
-PYRO | 
-LASER | 
+
+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     | 
+
+Value | Description
+---------- | ----------
+GRENADES     |  t.b.a.

 Owner can be one of the following values:
-Value | Description
----------- | ----------
-NEUTRAL     | 
-RED      | 
-BLUE        | 
-GREEN | 
-YELLOW | 
-PURPLE | 
-TEAL | 
-PINK | 
-BROWN | 
+
+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     | 
-VOLCANIC      | 
-ARCTIC        | 
-JUNGLE | 
-CITY | 
+
+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.

lua modified by DaMarkov

DaMarkov — Thu, 02 May 2019 12:57:24 -0000

--- v5
+++ v6
@@ -109,8 +109,83 @@
 Reference of all API functions
 --

-#####createObject#####
-#####createRobotGroup()#####
+    #####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     | 
+LIGHT      | 
+MEDIUM        | 
+HEAVY | 
+APC | 
+MO_MISSILE | 
+CRANE | 
+
+Subtypes for type ROBOT:
+Value | Description
+---------- | ----------
+GRUNT     | 
+PSYCHO      | 
+TOUGH        | 
+SNIPER | 
+PYRO | 
+LASER | 
+
+Subtypes for type MAP_ITEM:
+Value | Description
+---------- | ----------
+GRENADES     | 
+
+Owner can be one of the following values:
+Value | Description
+---------- | ----------
+NEUTRAL     | 
+RED      | 
+BLUE        | 
+GREEN | 
+YELLOW | 
+PURPLE | 
+TEAL | 
+PINK | 
+BROWN | 
+
+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     | 
+VOLCANIC      | 
+ARCTIC        | 
+JUNGLE | 
+CITY | 
+
+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()#####

lua modified by DaMarkov

DaMarkov — Sat, 20 Apr 2019 16:11:09 -0000

--- v4
+++ v5
@@ -70,7 +70,7 @@
  end
 ~~~

-####Example: Kill all objects of an player on command####
+####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.

lua modified by DaMarkov

DaMarkov — Sat, 20 Apr 2019 16:10:33 -0000

--- v3
+++ v4
@@ -59,6 +59,53 @@
 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 an 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
 --

lua modified by DaMarkov

DaMarkov — Sat, 20 Apr 2019 15:56:34 -0000

--- v2
+++ v3
@@ -58,3 +58,31 @@
 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.
+
+Reference of all API functions
+--
+
+#####createObject#####
+#####createRobotGroup()#####
+#####createCannon()#####
+#####createMissile()#####
+#####clearWaypoints()#####
+#####execute()#####
+#####enableProduction()#####
+#####getFort()#####
+#####getTime()#####
+#####setPosition()#####
+#####getOwner()#####
+#####getType()#####
+#####getSubtype()#####
+#####getPosition()#####
+#####getPlanet()#####
+#####getObjectCount()#####
+#####getObject()#####
+#####killObject()#####
+#####sendNews()#####
+#####setWaypoint()#####
+#####setAttackDamage()#####
+#####setPalette()#####
+#####setVisible()#####
+

lua modified by DaMarkov

DaMarkov — Sat, 20 Apr 2019 15:53:04 -0000

--- v1
+++ v2
@@ -41,6 +41,20 @@
 killObject(obj)
 ~~~

-or move the object to the right by 50 pixels
+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.

lua modified by DaMarkov

DaMarkov — Fri, 19 Apr 2019 19:56:20 -0000

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.

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

[...]