LUA scripts

OpenNox implements an experimental LUA map script runtime.


LUA scripts are deprecated. Consider using new NoxScript runtime.


To create a LUA map script, put <mapname>.lua file in the map’s directory.

For example:


You also need to request a specific version of the scripting API that you want to use:

Nox = require("Nox.Map.Script.v0")

Now you are ready to write some magic Nox scripts!

It is also possible to add more LUA files, for example:


And use require to load it:

other_file = require("other_file")

Debugging with the in-game console

You can access script variables for debugging using Nox console.

First, you should enable cheats (racoiaws), and the prefix all you commands with lua .

For example:

lua p =
lua print(p)


Timers allow to trigger some LUA function at a later time.

Frame timer

This timer will call a given function after N game frames (server ticks).

function MyFunc()
Nox.FrameTimer(60, MyFunc)

Seconds timer

This timer will call a given function after N in-game seconds pass.

function MyFunc()
Nox.SecondTimer(10, MyFunc)


Walls in Nox are positioned on a regular grid. Thus, walls can be addressed by those grid positions. If walls are marked as scriptable in the editor, it will be possible to enable (close) and disable (open) them.

  • Wall(xi,yi) - get a wall by its grid coordinates.
  • WallAt(x,y) - get a wall at exact real coordinates (not grid ones).
  • WallNear(x,y) - get a wall near specific real coordinates (not grid ones).
  • WallNear(obj) - get a wall near a specific object or waypoint.
  • WallGroup(id) - finds a wall group by the ID.

Wall object

This object represents a single wall on the map.

  • w.xi - returns X grid coordinate of the wall.
  • w.yi - returns Y grid coordinate of the wall.
  • w.x - returns real X coordinate of the wall.
  • w.y - returns real Y coordinate of the wall.
  • w.enabled - checks if the wall is enabled (closed) or sets the enabled state.
  • w:Pos() - returns wall’s real position as a pair of X,Y coordinates.
  • w:Toggle() - toggles the wall’s state (opened/closed).
  • w:Break() - break this wall (must be set as breakable).


This object represents a group of one or more walls on the map.

  • - returns ID of this wall group.
  • w:Toggle() - toggles walls state (opened/closed).
  • w:Break() - break these walls (must be set as breakable).


Open secret wall near the player (must be really close):

local p =
Nox.WallNear(p).enabled = false

Break a wall group with ID MyGroup on the map:

local g = Nox.WallGroup("MyGroup")


This section describes player-related objects and functions.

Players meta-class

Players list can be accessed via Nox.Players meta-class.

  • Players() - returns current list of players as LUA array.
  • Players[i] - returns a player by index i.
  • Players:Print(text) - prints a text message to all players.
  • Players:Blind() - blinds all players (fades the screen to black).
  • Players:Blind(false) - unblinds all players (fade back to normal).

Player object

Player object includes information about human-controlled player, as well as a unit he controls.

  • - returns player’s name.
  • - checks if player is a host.
  • p.unit - returns player’s unit, if any.
  • p.x - gets or sets player’s unit X coordinate.
  • p.y - gets or sets player’s unit Y coordinate.
  • p:Pos() - returns player’s unit position as a pair of X,Y coordinates.
  • p:SetPos(x,y) - instantly moves player’s unit to given coordinates.
  • p:SetPos(obj) - instantly moves player’s unit to a given object or waypoint.
  • p:Print(text) - prints a text message to the player.
  • p:Blind() - blinds player (fades the screen to black).
  • p:Blind(false) - unblinds player (fade back to normal).


Iterating over all players:

local players = Nox.Players()
for i,p in ipairs(players) do

Getting the first player:

local p = Nox.Players[1]

Getting the host player:

local p =

Getting player’s name:

local p =

Checking if player is a host:

local p = Nox.Players[1]
if then
    print("it's the host!")

Blind everyone:


Blind everyone except the host:

local players = Nox.Players()
for i,p in ipairs(players) do
    if not then


This section describes different object present in game.


Object type describes a “prototype” of an object that can be spawned in-game.

  • Nox.ObjectType(id) - find an object type by ID.
  • - returns object type ID.
  • t:Create(x,y) - creates a new object instance at given coordinates.
  • t:Create(obj) - creates a new object instance at the position of another object or waypoint.

Object instance

  • Nox.Object(id) - find an object by ID.
  • - returns object’s ID, if any.
  • v.owner - returns or sets object’s owner.
  • v.x - gets or sets object’s X coordinate.
  • v.y - gets or sets object’s Y coordinate.
  • v.z - gets or sets object’s Z coordinate.
  • v.enabled - checks if object is enabled or sets the enabled state.
  • v:Pos() - returns object’s position as a pair of X,Y coordinates.
  • v:SetPos(x,y) - instantly moves object to given coordinates.
  • v:SetPos(obj) - instantly moves object to another object or waypoint.
  • v:SetOwner(obj) - sets object owner; same as v.owner, but allow chaining.
  • v:Delete() - permanently delete object from the map.
  • v:Toggle() - toggles object’s enabled state.

Unit object

Unit extends the generic object, so everything that can be done with object can be done with a unit.

  • - current health of the unit.
  • v.max_health - max health of the unit.
  • v.mana - current mana of the unit.
  • v.max_mana - max mana of the unit.
  • v:Freeze() - freezes the unit in place.
  • v:Wander() - make the unit wander around.
  • v:Return() - make the unit return to its starting position.
  • v:Idle() - make the unit idle.
  • v:Guard() - make the unit guard position.
  • v:Hunt() - make the unit hunt for enemies.
  • v:LookAt(x,y) - make the unit look at certain position.
  • v:LookAt(obj) - make the unit look at another object or waypoint.
  • v:LookAtDir(dir) - make the unit look in a given direction.
  • v:LookAngle(dir) - make the unit look at a given angle.
  • v:MoveTo(x,y) - make the unit move to certain position.
  • v:MoveTo(obj) - make the unit move to another object or waypoint.
  • v:WalkTo(x,y) - make the unit walk to certain position.
  • v:WalkTo(obj) - make the unit walk to another object or waypoint.
  • v:Follow(obj) - make the unit follow another object.
  • v:Attack(obj) - make the unit attack another object.
  • v:HitMelee(x,y) - make the unit hit melee a certain position.
  • v:HitMelee(obj) - make the unit hit melee another object or waypoint.
  • v:HitRanged(x,y) - make the unit hit ranged a certain position.
  • v:HitRanged(obj) - make the unit hit ranged another object or waypoint.


Teleport player 10 pixels right:

p =
x, y = p:Pos()
x = x + 10

Teleport player 1 to player 2:

p1 = Nox.Players[1]
p2 = Nox.Players[2]

Spawn 10 apples near the player:

apple = Nox.ObjectType("RedApple")
p =
for i = 1,10 do

Spawn Mimic near the player and make him friendly:

mimic = Nox.ObjectType("Mimic")
p =

Spawn 2 Beholders and make them follow the player:

beholder = Nox.ObjectType("Beholder")
p =
arr = {}
for i = 1,2 do
    arr[i] = beholder:Create(p)
squad = Nox.ObjectGroup(unpack(arr))

Make a train of 5 Bombers that follow each other and the player:

function trainFollow()
    p:Print("Bomber train!")
    prev = p
    for i, b in ipairs(bombers) do
        prev = b

function makeTrain()
    bomber = Nox.ObjectType("Bomber")
    p =
    bombers = {}
    for i = 1,5 do
        bombers[i] = bomber:Create(p)
    train = Nox.ObjectGroup(unpack(bombers))
    -- give them a frame or two to appear
    Nox.FrameTimer(2, trainFollow)