Install on Linux

• Appimage release
• Binary archive release
• Flatpak release
• Snap release

Install on Windows

Installation process

1. Install original Nox. Prefer locations outside of “Program Files”.
2. Download latest OpenNox installer. Use .exe file for Windows.
3. Install it to any directory (shouldn’t be the same as Nox itself).

Playing

HD version

1. Go to OpenNox installation directory.
2. Make a shortcut for opennox-hd.exe.
3. Run it!

Legacy version

1. Go to OpenNox installation directory.
2. Make a shortcut for opennox.exe.
3. Run it!

Troubleshooting

OpenNox doesn’t start

First, try running OpenNox with Administrator permissions. If it works, then your Nox copy is likely installed in the protected folder like “Program Files” which causes issues. Delete OpenNox folder, reinstall Nox to some other folder and install OpenNox again.

If it doesn’t help, open opennox.yml in OpenNox installation directory in a text editor (Notepad++ is a good option). Find section similar to this:

game:
  data: C:\Games\Nox

Change the path manually to a folder where your copy of Nox is installed. Restart OpenNox.

If it still doesn’t work, please contact us on OpenNox Discord in #feedback channel. It will help if you share opennox.log located in log folder in OpenNox install directory.

Can’t connect to a server: Version mismatch

As was explained in the installation section, HD and legacy versions won’t join servers of the opposite version.

Most online servers still run legacy version, so if you want to join them, you must run legacy version of OpenNox as well. Make sure to try a correct version when joining a server.

Install on Steam Deck

Installing

1. Install original Nox from GoG (via Lutris or Heroic).
2. Install OpenNox via Flatpak.

Playing

HD version

Installation should create a “OpenNox HD” shortcut in the start menu. Alternatively: run opennox-hd binary from terminal.

Legacy version

Installation should create a “OpenNox” shortcut in the start menu. Alternatively: run opennox binary from terminal.

Troubleshooting

OpenNox doesn’t start

Try starting opennox from the terminal. Check if there are any error messages there.

If it doesn’t help, open opennox.yml in OpenNox installation directory in a text editor. Find section similar to this:

game:
  data: /home/user/some/path/to/Nox

Change the path manually to a folder where your copy of Nox is installed. Restart OpenNox.

If it still doesn’t work, please ping us on OpenNox Discord in #feedback channel. It will help if you share opennox.log located in log folder in OpenNox install directory.

Can’t connect to a server: Version mismatch

As was explained in the installation section, HD and legacy versions won’t join servers of the opposite version.

Most online servers still run legacy version, so if you want to join them, you must run legacy version of OpenNox as well. Make sure to try a correct version when joining a server.

Nox Quest

OpenNox provides more commands for Nox Quest game mode.

Originally, Nox Quest:

• Prevents players to skip levels if they haven’t completed them already
• Skips only 5 levels at a time.
• Disables the portal after level 20.
• Even if portal cutoff is increased to more than 20, it won’t teleport to next levels.

To solve all of this, you can run (in the game console; F1):

racoiaws
set quest warp.allow
set quest warp.inc 10
set quest warp.inf

For more detailed description of commands, read on.

warp.allow

This option disables the requirement to complete a certain Quest level before accessing the portal.

Example:

# always allow to pass through the portal
set quest warp.allow
set quest warp.allow 1

# original Nox behavior
set quest warp.allow 0

warp.inc

Changes the number of levels that the portal skips at a time.

Example:

# portal will only skip one level instead of 5
set quest warp.inc 1
# skip 20 levels
set quest warp.inc 20

# original Nox behavior
set quest warp.allow 5

warp.inf

Allows the portal to work indefinitely instead of shutting down at level 20.

Example:

# portal will always be enabled
set quest warp.inf
set quest warp.inf 1

# original Nox behavior
set quest warp.inf 0

level.inc

Changes the number of levels that will be skipped on the stage completion. In other words, how quickly the levels will increase when you complete a Quest level.

This allows to ramp up difficulty much faster without affecting other Quest rules.

Example:

# completing level 5 will lead to level 7 (+2) instead of 6 (+1)
set quest level.inc 2

# original Nox behavior
set quest level.inc 1

Multiplayer campaign

Starting campaign in multiplayer

1. Host regular Quest game.
2. Wait for all players to join.
3. Open game console with F1 and type racoiaws (enables console commands).
4. Disable map restrictions: set maps allow.all.
5. Load desired campaign: load wiz01a (for Wizard), load con01a (for Conjurer), load war01a (for Warrior).
6. Enjoy!

Known issues

• Game saves won’t work. All your progress for this session will be lost. Use load to jump to other chapters.
• Players likely won’t be able to reconnect. Full game restart is required (for both client and server!).
• Other players can run around during cutscenes. If you break them - you’ll have to restart the map.
• Death of any player will trigger the death screen and stop the campaign.

Useful commands

• Teleport P2 to P1: tp (or tp 0).
• Teleport P1 to P2: tpto (or tpto 0).
• Unfreeze P1 after broken cutscene: unstuck.

Use SSH remote console to copy-paste commands.

Manual spell casting

Surprisingly, vanilla Nox has a hidden feature that allows casting spells manually by pressing one of 9 phoneme/gesture keys in the right order to cast specific spells. It is similar to the way spell casting works in Magicka.

OpenNox restores this feature by default. Manually casting each spell is challenging, thus we think that it doesn’t give any advantage in multiplayer (actually the opposite), so can be enabled safely.

All that needs to be done to use it to set hotkeys in OpenNox input options. There are 8 main phonemes, plus a special “end” phoneme to finish and cast the spell.

It’s typical to use numpad keys for phonemes where 5 or Enter is an “end” phoneme, and actual phonemes occupy other number keys:

Another typical layout is to use QWER-ASDF block for 8 phonemes and set “end” to any key that is close enough.

For more details, see this post.

Hosting using a client

The simplest way to host a game is by using OpenNox game client.

Run OpenNox or OpenNox HD, go to the “Network” page, and host the game. Simple as that!

OpenNox will automatically register the game online (for both OpenNox and Nox Reloaded).

It will also attempt to automatically forward ports for the server (using UPnP on your router).

Hosting a dedicated server

OpenNox also ships with the opennox-server binary, which can be used to run a dedicated server.

Also, Docker images are available for the server.

When hosting a dedicated server, it is important to setup access by remote console and/or HTTP API to control the server remotely.

Remote SSH console

Vanilla Nox supported a telnet-based remote console (RCON) which allowed controlling Nox server remotely.

OpenNox has dropped telnet support in favor of SSH-based remote console.

To enable RCON, OpenNox must be started with an additional argument:

opennox --rcon=:18522 --rcon-pass=my-secret-password

This will allow SSH connections on port 18522 with a password my-secret-password:

ssh -p 18522 127.0.0.1

ssh -p 18522 127.0.0.1

  /888888                                /88   /88           /88   /88
 /88__  88                              | 888 | 88          | 88  / 88
| 88  \ 88  /888888   /888888  /8888888 | 8888| 88  /888888 |  88/ 88/
| 88  | 88 /88__  88 /88__  88| 88__  88| 88 88 88 /88__  88 \  8888/
| 88  | 88| 88  \ 88| 88888888| 88  \ 88| 88  8888| 88  \ 88  >88  88
| 88  | 88| 88  | 88| 88_____/| 88  | 88| 88\  888| 88  | 88 /88/\  88
|  888888/| 8888888/|  8888888| 88  | 88| 88 \  88|  888888/| 88  \ 88
 \______/ | 88____/  \_______/|__/  |__/|__/  \__/ \______/ |__/  |__/
          | 88
          | 88        Version: v1.9.x (xxxxxxxxx)
          |__/

user@opennox:~$

From here, all console commands will work the same way as via in-game console. A good starting point is a help command.

Server HTTP API

Server info

GET /api/v0/game/info

Example request using curl:

curl 'http://127.0.0.1:18580/api/v0/game/info'

Example response:

{
  "name":"OpenNox",
  "map":"estate",
  "mode":"arena",
  "vers":"v1.8.0",
  "players":{
    "cur":1,
    "max":32,
    "list":[
      {
        "name":"Jack",
        "class":"wizard"
      }
    ]
  }
}

Setting the token

You need to run the server with NOX_API_TOKEN=<some-random-string> to allow using control APIs.

All examples below assume NOX_API_TOKEN=xyz.

Change map

POST /api/v0/game/map
X-Token: xyz

estate

Example request using curl:

curl -X POST -H 'X-Token: xyz' -d 'estate' 'http://127.0.0.1:18580/api/v0/game/map'

Run console command

POST /api/v0/game/cmd
X-Token: xyz

load estate

Example request using curl:

curl -X POST -H 'X-Token: xyz' -d 'load estate' 'http://127.0.0.1:18580/api/v0/game/cmd'

Run NS script

POST /api/v0/game/eval
X-Token: xyz

ns4.CreateObject("RedApple", ns4.GetHost().Unit().Pos())

Example request using curl:

curl -X POST -H 'X-Token: xyz' -d 'ns4.CreateObject("RedApple", ns4.GetHost().Unit().Pos())' 'http://127.0.0.1:18580/api/v0/game/eval'

Run Lua script

POST /api/v0/game/lua
X-Token: xyz

p = Nox.Players[1];
apple = Nox.ObjectType("RedApple");
apple:Create(p);

Example request using curl:

curl -X POST -H 'X-Token: xyz' -d 'p = Nox.Players[1]; apple = Nox.ObjectType("RedApple"); apple:Create(p)' 'http://127.0.0.1:18580/api/v0/game/lua'

Tweaking the game balance

Vanilla Nox stores game balance values in an encoded gamedata.bin file.

OpenNox allows overriding values specified in that file with the ones written in a text-based gamedata.yml file.

To try it out, copy gamedata.yml to the Nox game directory (not OpenNox directory!). After this, you can edit it using any text editor (Notepad++ is recommended for Windows users).

Changing spells

Vanilla Nox stores spell configs in three different places:

• As a section in thing.bin file
• Balance file
• Built into the engine

The engine defines a list of all supported spell IDs (e.g. SPELL_BLINK) and the effect associated with it.

The thing.bin then lists spells that should be enabled in the game (by ID) and additionally configures them. Unfortunately, this configuration is quite limited.

The balance file may additionally tune per-level spell parameters, or special parameters that are unique to certain spells.

OpenNox extends this system and allows using spells.yml file to configure new spell parameters, as well as old ones in one place.

Note: this modding feature is still in development. Not all the config options for spells are available in spells.yml. We will keep adding new ones in each version of OpenNox.

Generating base spells.yml file

Since this feature is in the development, it is strongly advised to generate a fresh spells.yml based on the latest OpenNox version and your Nox game data.

This can be done by running OpenNox with NOX_DUMP_SPELLS=true environment variable.

On Linux:

NOX_DUMP_SPELLS=true opennox

On Windows (via cmd.exe):

set NOX_DUMP_SPELLS="true"
opennox.exe

This should create a spells.yml in Nox game data directory (not OpenNox directory!).

Alternatively, you could copy the spells.yml file to your Nox game directory. Be aware that the sample file might be old and won’t list all options available in the engine.

Modifying spells.yml

Note that modifying spells.yml currently requires OpenNox restart.

Usually, the spell section will look like this:

name: SPELL_BLINK
icon:
  ind: 131860
icon_enabled:
  ind: 131938
mana_cost: 10
price: 3000
flags:
- 1
- MOBS_CAN_CAST
- 128
- 1024
- CAN_COUNTER
- CANT_HOLD_CROWN
- 1048576
- CLASS_ANY
- 2147483648
phonemes: [cha, et, un]
title: thing.db:Blink
desc: thing.db:SPELL_BLINK_DESC
cast_sound: BlinkCast
---

Where:

• name - specifies spell ID to use; if effect is not set, this also determines the spell effect
• effect - specifies spell ID which will control the actual effect of the spell; see adding spells
• icon.ind - the sprite index from video.bag that is used as a spell icon
• icon_enabled.ind - same as icon.ind, but for enabled spell icon
• mana_cost - mana cost of the spell
• price - base spell book price; Quest uses an additional multiplier for this price
• flags - different flags that controls which category spell belongs to, what it can target, etc
• phonemes - a unique list of spell phonemes/gestures that invoke this spell; see spell casting
• title - a string ID for the spell title
• desc - a string ID for the spell description
• cast_sound - a sound for casing a spell
• on_sound - a sound for enabling a spell
• off_sound - a sound for disabling a spell

These are the only parameters that can be originally controlled via thing.bin, and was ported to spells.yml.

Apart from these, OpenNox provides more options for certain spells. For example, SPELL_MAGIC_MISSILE has a new section:

missiles:
  spread: 16
  projectile: MagicMissile
  vel_mult: 0.1
  offset: 4
  speed_rnd_min: 0.80000001
  speed_rnd_max: 1.2
  search_dist: 600

Here, a count parameter is omitted, because it is usually controlled via balance file (see MagicMissileCount). Specifying it here will override balance data.

When a special section like missiles this is present, all parameters in there can be controlled individually for each spell level:

missiles:
  # default parameters for all levels
  spread: 16
  projectile: MagicMissile
  vel_mult: 0.1
  offset: 4
  speed_rnd_min: 0.80000001
  speed_rnd_max: 1.2
  search_dist: 600
  # per-level configs
  levels:
    # levels 1-3: copied from balance file
    - count: 1
    - count: 2
    - count: 3
    # level 4: same number of missiles as lvl3, but longer homing distance
    - count: 3
      search_dist: 800
    # level 5: make it ultimate: more missiles, longer distance, faster missiles
    - count: 10
      speed_rnd_min: 1.0
      speed_rnd_max: 2.0
      search_dist: 800

Spell flags

Not all flags are completely understood at this point. So we recommend to see what flags are set for existing spells and experiment by setting/unsetting them in your mod.

Names of the spell flags provided below may change in a freshly-generated spells.yml, but OpenNox will still support old names as well.

Player class flags:

• CLASS_ANY - spell can be used by any magic class (Conjurer and Wizard)
• CLASS_WIZARD - spell can only be used by Wizard
• CLASS_CONJURER - spell can only be used by Conjurer
• Setting none of these flags will effectively hide the spell.

Targeting flags

• TARGETED - spell is homing
• AT_LOCATION - spell can be cast at a point
• CANT_TARGET_SELF - spell cannot be targeted at the character

Cast flags:

• NO_MANA - spell doesn’t require mana
• NO_TRAP - spell can’t be used in traps
• INSTANT - spell is instant
• DURATION - spell is duration-based
• OFFENSIVE - spell is offensive
• DEFENSIVE - spell is defensive
• CAN_COUNTER - spell can be countered
• MOBS_CAN_CAST - mobs are allowed to use this spell
• CANT_HOLD_CROWN - spell can’t be cast when holding a flag/crown/ball

Special flags

• SUMMON_SPELL - this is the base Summon Creature spell
• SUMMON_CREATURE - this is Summon for a specific creature
• MARK_SPELL - this is the base Mark Location spell
• MARK_NUMBER - this is Mark Location with a specific number
• GOTO_MARK_SPELL - this is the base Go To Mark spell
• GOTO_MARK_NUMBER - this is Go To Mark with a specific number

There are some flags that don’t have names, which means we are not sure of its effect.

Adding new spells

Currently, adding new spells in OpenNox is not supported.

Having said that it is possible to replace unused spell slots that already exist in the game.

In spell section there’s a name parameter that defines the slot that the spell uses and effect for the engine to know which effect to run.

Usually these two IDs are the same (or effect is empty and derived from name), but these fields can be used to replace unused spell IDs with custom ones.

For example, there’s SPELL_PHANTOM which doesn’t appear in the game and has no effect in the engine. This gives us a free spell slot to use. Let’s replace it with a custom magic missiles (SPELL_MAGIC_MISSILE) variant. For this we need to set name: SPELL_PHANTOM (or find existing section with it) to specify which slot we are using, and set effect: SPELL_MAGIC_MISSILE for the engine to know which logic to use for it. The result should look like this:

name: SPELL_PHANTOM # replacing Phantom spell slot
effect: SPELL_MAGIC_MISSILE # but effect is based on Magic Missiles
phonemes: [un, ro, do] # phonemes must be unique, so we keep ones from Phantom
# the rest is copied from Missiles and modified
icon:
  ind: 18248
icon_enabled:
  ind: 131967
mana_cost: 50
price: 5000
flags:
  - AT_LOCATION
  - MOBS_CAN_CAST
  - OFFENSIVE
  - CAN_COUNTER
  - CANT_TARGET_SELF
  - CLASS_WIZARD
  - 536870912
  - 1073741824
title: thing.db:MissilesOfMagic
desc: thing.db:SPELL_MAGIC_MISSILE_DESC
cast_sound: MagicMissileCast
missiles:
  count: 5
  spread: 30
  projectile: MagicMissile
  vel_mult: 0.1
  offset: 4
  speed_rnd_min: 0.1
  speed_rnd_max: 0.3
  search_dist: 800
---

Replacing sprites

The main build supports a way to replace sprites used by the game.

For it to work, you may first need to get original sprites:

cd Nox
noxtools videobag extract -z --out ./video.bag.zip

Find sprites that you want to replace and put them into Nox/images (create if not exists). Make the changes to the sprite in this directory and run the game to test it.

Note that it will ONLY work with this Nox version. Original Nox, GoG version or Nox Reloaded doesn’t support this.

Adjusting sprite offsets

If you decide to change the sprite significantly, e.g. changing its size or completely redrawing the image, you may need to change the sprite offset used by the engine.

First, get the original sprite metadata:

cd Nox
noxtools videobag extract -z --out ./video.bag.zip --json

Now this archive will contain .json files that correspond to each sprite. Copy selected ones to Nox/images, adjust the offsets using the text editor and check them in game.

Customizing translation

Most of the text used in Nox is stored in the CSF files which are encoded and are hard to modify.

This build provides an easier way to customize those texts.

First, decode the original file:

noxtools strings csf2json nox.csf

This will produce nox.csf.json file that you can modify with a regular text editor. The build will automatically use this file instead of the original nox.csf.

The nox.csf.json file will consist of sections similar to this:

    {
      "id": "ParseCmd.c:exithelp",
      "vals": [
        {
          "str": "Exit the game to Main Menu."
        }
      ]
    }

For translation Nox texts to a different language (or changing existing texts), you need to keep the id field, but translate all str fields.

For adding custom strings, you need to add a new section with a unique id add at least one str. Then you should be able to use this new id in your map or mod.

Scripts

OpenNox provides multiple scripting runtimes. Some of them are experimental or in development.

• NoxScript
• LUA scripts

OpenNox console

Enabling all commands

Just like in vanilla Nox, OpenNox starts with most console commands disabled. This is done to prevent cheating in the solo campaign. Most commands will not work in multiplayer, unless you are a server admin/host.

To enable all commands, open the console (F1 by default) and type:

racoiaws

Remote server administration

OpenNox does not support original RCON protocol based on telnet.

Instead, it implements remote console via built-in SSH server.

List commands

To get a list of all available commands, use help.

Here’s the list of the most interesting ones.

image

Take a screenshot and save it as a PNG image.

image

show

This command displays various information, including debug information.

Available sub-commands:

• show bindings - lists all console bindings (macros).
• show extents - toggle displaying of names and sizes for all objects on the screen.
• show ai - toggle displaying of AI paths and prints all AI decisions to console.
• show gui - toggle graphical user interface.

list

This command lists various in-game spells, items, monsters, maps and players.

These commands prints item IDs that can be the used with spawn command.

Available sub-commands:

• list staffs - lists all staves and wands.
• list armor - lists all armor.
• list weapons - lists all weapons.
• list food - lists all consumables.
• list monsters - lists all monsters and NPCs.
• list spells - lists all spells.
• list maps - lists all maps.
• list users - lists all players.

load

This command switches current game map to the one specified:

load wiz01a

In vanilla Nox, not every map can be loaded like that. For example, it’s impossible to load campaign maps in multiplayer. OpenNox allows bypassing those restrictions by using set maps allow.all command.

set god

A vanilla cheat for invulnerability, all spells and infinite mana.

set god

To disable:

unset god

Note that using this cheat will cause the character to learn all spells up to the maximal level. This cannot be reversed, even if the cheat is disabled. See cheat god if you only need invulnerability and infinite mana.

set quest

These command allow more controls for Nox Quest game mode. See this page for details.

set maps

These commands allow more control for game map loading.

• set maps allow.all - disable game mode checks when loading the map; allows loading campaign in multiplayer, etc

cheat god

A cheat for invulnerability and infinite mana.

cheat god

To disable:

cheat god 0

For additionally getting all spells see cheat sage, or set god.

cheat sage

A cheat for getting all class spells, scrolls and/or abilities.

cheat sage

To disable:

cheat sage 0

cheat spells

A cheat for getting all spells.

For getting class spells:

cheat spells

For getting class spells with a specific spell level:

cheat spells 3

To get all spells, even hidden ones:

cheat spells all

cheat scrolls

A cheat for getting all beast scrolls.

cheat scrolls

To disable:

cheat scrolls 0

cheat goto

Teleport to given coordinates or a waypoint.

For teleporting to coordinates (X, Y):

cheat goto 1000 2000

For teleporting to a waypoint:

cheat goto MyWaypoint

cheat spawn

Spawn a given item or monster at the player’s position.

Command accepts IDs returned by the list command.

cheat spawn OblivionOrb
cheat spawn Mimic

It is also possible to specify a number of items to spawn:

cheat spawn RedApple 5

cheat gold

Adds specified amount of gold to all players.

cheat gold 10000

cheat health

Sets or restores health for the character.

Without arguments, command will restore health to maximum:

cheat health

You can also specify the desired health value:

cheat health 999

cheat mana

Sets or restores mana for the character.

Without arguments, command will restore mana to maximum:

cheat mana

You can also specify desired mana value:

cheat mana 999

cheat equip.all

Removes equipment requirements from all items. In other words, any class can equip and use any armor/weapons.

cheat equip.all

To disable it:

cheat equip.all 0

cheat charm.all

Allows charming any hostile creatures and NPCs (including scripted ones, humanoids, etc).

cheat charm.all

To disable it:

cheat charm.all 0

cheat summon.nolimit

Remove the limit for the number of summoned creatures.

cheat summon.nolimit

To disable it:

cheat summon.nolimit 0

lua

This commands executes given Lua code.

For example, to replicate cheat spawn RedApple with Lua:

apple = Nox.ObjectType("RedApple")
p = Nox.Players.host
apple:Create(p)

In the console, each line must start with lua command:

lua apple = Nox.ObjectType("RedApple")
lua p = Nox.Players.host
lua apple:Create(p)

Notice that variables defined in one lua commands can be used in other ones.

It’s also possible to write a multi-line command in a single line:

apple = Nox.ObjectType("RedApple"); p = Nox.Players.host; apple:Create(p)

or

Nox.ObjectType("RedApple"):Create(Nox.Players.host)

For more information about Lua scripting, see this page.

Migrate from NS3

NS4 provides the same functionality as NS3, but uses object-oriented approach. It also supports a few unique features which are not available in NS3.

Changes

Objects

The ns3.ObjectID is replaced with ns4.Obj type. The main difference is that ns4.Obj is opaque and can no longer be used or stored as an integer.

It is possible to convert ns4.Obj to/from ns3.ObjectID using the following code:

ns4.AsObj(obj)

ns3.ObjectID(obj.ObjScriptID())

Similar functions are available for ns4.ObjGroup and ns3.ObjectGroupID:

ns4.AsObjGroup(group)

ns3.ObjectGroupID(group.ObjGroupScriptID())

Most object-specific functions are now available on the object itself, instead of a top-level library function:

obj.Enable(false)
obj.Delete()

ns3.ObjectOff(obj)
ns3.Delete(obj)

Object position is now available as a point type, instead of separate X and Y coordinates:

pos := obj.Pos()
x, y := pos.X, pos.Y

x, y := ns3.GetObjectX(obj), ns3.GetObjectY(obj)

Most functions can now accept this new position type instead of a coordinate pair:

pos := obj.Pos()
obj2.HitMelee(pos)

x, y := ns3.GetObjectX(obj), ns3.GetObjectY(obj)
ns3.HitLocation(obj2, x, y)

Position can also be constructed from X and Y values:

obj.HitMelee(ns4.Ptf(10, 20))

ns3.HitLocation(obj, 10, 20)

Waypoints

Similar to objects, waypoints are also represented with opaque ns4.WaypointObj type.

Conversion to/from ns3.WaypointID is still available:

ns4.AsWaypoint(wp)

ns3.WaypointID(wp.WaypointScriptID())

Waypoints now also have methods instead of top-level library functions:

wp.Enable(false)

ns3.WaypointOff(wp)

Position is also returned as a point data type:

pos := wp.Pos()
x, y := pos.X, pos.Y

x, y := ns3.GetWaypointX(obj), ns3.GetWaypointY(obj)

This, in turn, allows using any type that has Pos() method (also known as ns4.Positioner) in places where position is expected:

ns4.CreateObject("Beholder", ns4.Ptf(10, 20))
ns4.CreateObject("Beholder", ns4.GetHost())
ns4.CreateObject("Beholder", ns4.Waypoint("Spot"))

ns3.CreateObject("Beholder", ns3.Waypoint("Spot"))

Migrate from original

This guide will help migrate existing NoxScript 3 maps to NS3 in OpenNox.

In this guide we will refer to “NoxScript 3” as the original Nox script, while “NS3” as the new Go-based scripts for OpenNox.

Why?

First logical question: why bother? OpenNox runs original NoxScript 3 just fine.

A few reasons to migrate to OpenNox scripts:

• NoxScript 3 is limited to what original Nox engine exposes. Which isn’t a lot. There won’t be any updates.
• NS3 in OpenNox is a drop-in replacement. Same functions are supported.
• We provide tooling to migrate 90% of your code automatically. Only minor tweaks are needed.
• NS4 (and beyond) will have more and more features going forward, including modding support.
• You won’t need a separate script compiler. Scripts are run directly from source.
• More comprehensive type system: proper arrays, dictionaries (map), structures, classes.
• Libraries included: string manipulation, full UTF8 support, math, sorting, etc.
• Better performance: all libraries are compiled into OpenNox and run natively.
• Better debugging: if script crashes, there’s a stack trace. Scripts can recover from it as well!
• Go language used in scripts is used in OpenNox itself. Maybe one day you’ll decide to contribute?

It wouldn’t be fair to not list downsides:

• It only works with OpenNox.
• You’ll need to learn a new scripting language.
• Script may need to do more work when saving/loading.

If you heard about EUD script compiler by Panic and maybe considered it, see this guide.

In general, we believe that OpenNox is the future of Nox modding, thus porting your map may give it an entirely new life!

How?

There are two path currently: converting the compiled script from the map or converting the source.

Converting the map script

You’ll need a recent noxtools installed (assuming you have Go 1.20+ installed):

go install github.com/opennox/libs/cmd/noxtools@latest

From the map directory:

noxscript ns decomp <mapname>.map

It will print a decompiled source code converted to Go and NS3 runtime.

Because of the limitation of Nox script assembly:

• All variable names will be lost.
• Some control flow may be replaced with goto.

But after fixing these issues, you should be ready to go!

Converting the source

TODO: Add a guide for using cxgo to automate it.

Currently, you’ll have to manually convert the source. Until we automate it as well, please consider converting the extracted map script, as shown above.

NoxScript 3 is similar to C, which has a lot in common with Go. However, Go syntax is slightly different in regard to types.

Conversion steps will include:

• Swapping argument and variable names with types: int a -> a int.
• Adding either var or const to variable definitions: int a -> var a int.
• Moving function return type to the end: int foo() -> func foo() int.
• Moving { to the previous line. E.g. func foo()\n{ -> func foo() {. Same for if, else, for.
• Adding { ... } to if and else which do not have them: if (1) foo() -> if (1) { foo() }.
• Removing void from returns.
• Fixing variable types (Go doesn’t allow implicit type conversion).

After this, add the following header to your file:

package example

import (    
    . "github.com/opennox/noxscript/ns/v3"
)

Dot import should automatically resolve all references to NS3 functions.

After conversion

Limitations

There are some temporary limitations you should be aware of:

• Timers will stop each time the map is reloaded. You’ll need to restart them from the script.
• All callbacks will reset when map is reloaded. You’ll need to set them again from the script.

These issues will be resolved eventually.

New: Syntax

We highly recommend checking our Go tour to get familiar with the syntax, but we’ll give a short recap here.

File structure

All files must start with package <mapname>:

package example

It can be followed by one or more package imports:

import "fmt"
import "strconv"
// it is typical to group them:
import (
	"fmt"
	"strconv"
)

Then global variables and/or functions follow. Order of declarations doesn’t matter.

Variables and types

Most notable syntax distinction: in Go, the type name is on the right side, instead of on the left as in NoxScript 3:

var x int

int x;

Note that ; is no longer needed, and variable declaration must start with var (or const).

There’s a very good reason why types are on the right: it makes reading complex types more natural. Just read them left to right!

For example, array: var x [3][2]int simply reads left to right as “array of 3 elements, each containing 2 int values”. Much better than a random order of int x[2][3];.

Same for pointers: *[2]int reads “pointer to an array of 2 ints”. Compare it to int* x[2];.

Functions

Function declarations are also different:

• They must start with func.
• Types for arguments are on the right.
• Return type is after the arguments.
• Void return type must be omitted.
• The opening { must be on the same line as the function header.
• Arguments with the same types can be grouped.
• Multiple returns are supported.

func foo(a int) {
}

func bar(x, y int, s string) int {
}

void foo(int a)
{
}

int bar(int x, int y, string s)
{
}

Control flow

All control flow structures require the opening { to be on the same line, for example:

if (x) { foo() }

if (y) {
    bar()
}

if (x) foo();

if (y)
{
    bar();
}

The () in the condition is also optional:

if x { foo() }

if y {
    bar()
}

if (x) foo();

if (y)
{
    bar();
}

Same rules for { apply for else:

if x {
    foo()
} else {
    bar()
}

if (x) foo()
else bar()

Loops

Loops must not include ( and have same rules in regard to {:

var i int
for i = 0; i < 10; i++ {
}

int i;
for (i = 0; i < 10; i++)
{
}

Loop that use while must use for keyword:

for x {
}

while (x)
{
}

New: Core types

In original NoxScript 3, there were only a few types available: int, float, string, object.

In NS3 the list is much longer: bool, int, uint, float32 (analog of float), string, any, etc. The object type is replaced with more specific types from NS3 package: ObjectID, ObjectGroupID, WaypointID, etc.

An important distinction is that Go doesn’t allow implicit type conversion. For example, in NoxScript it was okay to have an int variable and put an object there. In NS3, this is requires an explicit type conversion: int(x). But, of course, it’s better to have correct types for your variables.

Another distinction of NS3 is the support of direct conversions between int and float. It is done the same way: int(x) or float32(x).

Converting between int and string is supported via IntToString, but it’s better to use Go’s standard library instead: strconv.Itoa.

It also supports conversion from string to int via Go’s standard library: strconv.Atoi. Note, that this function may return an error, which you are free to ignore (with _):

x, _ := strconv.Atoi("1")

New: Strings

NoxScript 3 had a limitation that a frequent + operation on strings overflows a string table.

There’s no such limitation in NS3: any number of strings can be created.

Printing to strings is also supported with Go’s fmt.Sprintf:

s := fmt.Sprintf("Hello player %d!", n)

There are quite a few more string functions available in strings, https://pkg.go.dev/strconv and unicode packages.

Even though strings can be created with + and individual bytes can be accessed with s[i], strings are immutable in Go! This means, once created, they cannot be edited, only new ones can be created. If you need to change a few characters, consider converting to byte array, making changes, and converting back:

s := "Gello"
b := []byte(s) // type: []byte
b[0] = 'H'
s = string(b) // "Hello"

New: Variable type inference

NoxScript 3 requires a type for new variables to be set explicitly. NS3 allows automatic inference of variable type:

a := 10 // int
b := false // bool
x := ns.Object("Bob") // ObjectID

int a = 10; // int
int b = 0; // bool 
int x = Object("Bob"); // object

The := operator does two things: defines a new variable (similar to var) and infers a type for it.

But note that using float values produces a float64 type, not float32:

x := 0.0 // float64!
y := float32(0.0) // float32
x = y // error!

However:

const x = 0.0 // untyped float
var y float32 = x // no error

Constants are “untyped” and infer the type automatically from a variable they assigned to.

New: Range loop

In NS3 a new type of loop is available: for range, which allows to loop over all values in an array.

var arr [3]int
// writing: loop over indexes only
for i := range arr {
    arr[i] = i+1;
}
cnt := 0
// reading: loop over values
for _, v := range arr {
    cnt += v
}

int i;
int arr[3];
int cnt = 0;
for (i = 0; i < 3; i++) // writing
{
    arr[i] = i+1;
}
for (i = 0; i < 3; i++) // reading
{
    cnt += arr[i];
}

New: Dynamic arrays (slices)

In NoxScript 3, only fixed arrays are supported. NS3 has support for Go slices, which are arrays with dynamic length:

var arr []int
for i := 0; i < 3; i++ {
    arr = append(arr, i+1) // adds elements to the end
}
// len(arr) == 3

int i;
int arr[3];
for (i = 0; i < 3; i++)
{
    arr[i] = i+1;
}

New: Structures

NS3 completely supports custom struct types. They are very similar to classes in other programming languages.

Let’s say we want to build an RPG map, and we want to record a new character class for all player units:

type MyUnit struct {
	ID ns.ObjectID // types on the right: field "ID" with type "ns.ObjectID"
	Class string
}

func init() {
    unit := ns.Object("Bob")
    // creates a new struct instance, takes pointer to it
    myUnit := &MyUnit{ID: unit, Class:"archer"}
    changeClass(myUnit, "shaman")
}

// changeClass accepts a pointer to struct be able to change fields.
// Removing the pointer will make a copy of the struct for this function!
func changeClass(unit *MyUnit, cl string) {
    unit.Class = cl
}

The changeClass function can also be rewritten as a method on MyUnit struct:

type MyUnit struct {
	ID ns.ObjectID // types on the right: field "ID" with type "ns.ObjectID"
	Class string
}

// changeClass is a method on MyUnit struct pointer.
// Removing the pointer will make a copy of the struct for this function!
func (u *MyUnit) changeClass(cl string) {
    u.Class = cl
}

func init() {
    unit := ns.Object("Bob")
    myUnit := &MyUnit{ID: unit, Class:"archer"}
	// now changeClass is available as a method on the struct instance
    myUnit.changeClass("shaman")
}

For developer coming from C, new structs always have their fields initialized to zero vales.

New: Dictionaries (maps)

NS3 support dictionaries/sets, which are unordered collections of values indexed by a key of any type.

For example, we made a MyUnit struct in the previous example. But how to quickly find MyUnit for ns.ObjectID?

type MyUnit struct {
	ID ns.ObjectID // types on the right: field "ID" with type "ns.ObjectID"
	Class string
}

// mapUnits maps ns.ObjectID to *MyUnit.
// All maps must be created with make before use!
var mapUnits = make(map[ns.ObjectID]*MyUnit)

func init() {
	createMyUnits()
	findAndChangeClass()
}

func createMyUnits() {
    unit := ns.Object("Bob")
    myUnit := &MyUnit{ID: unit, Class:"archer"}
    // add new record to the map, index by ID
    mapUnits[unit] = myUnit
}

func findAndChangeClass() {
    unit := ns.Object("Bob")
	// find by ID
	myUnit := mapUnits[unit]
	if unit == nil {
	    return // not found	
    }
	myUnit.Class = "shaman"
}

Keys can also be deleted from the map:

delete(mapUnits, unit) // delete by unit ID

Migrate from EUD

This guide will help migrate existing Panic’s EUD maps to NS3 and EUD layer in OpenNox.

First, it’s important to understand that “memhacks” and direct memory access is technically not possible in OpenNox.

Here are a few reasons why:

• Memhacks target a specific binary. This means it only works on one Nox version. OpenNox constantly evolves, thus we cannot guarantee any specific memory layout.
• Memhacks usually inject assembly code that targets a specific CPU architecture (Intel/AMD x86). OpenNox can be potentially compiled for ARM (e.g. MacBooks, Android, RPi), thus script will stop working there.

We attempted to resolve these issues with EUD developer Panic, but we don’t see any willingness for collaboration from his side. If you really want EUD to be supported directly in OpenNox, please reach out to Panic. Resolving these technical challenges is possible, but requires tight collaboration, and will to do so from him, first and foremost.

Why?

First logical question: why bother with converting to OpenNox? EUD works great in original Nox.

A few reasons to migrate to OpenNox scripts:

• OpenNox is evolving and supports new features that are impossible in vanilla (e.g. HD, better multiplayer, modding, etc).
• EUD library in OpenNox is a drop-in replacement. Same functions will be supported.
• NS4 (and beyond) will have even more features going forward.
• You won’t need a separate script compiler. Scripts are run directly from source.
• More comprehensive type system: proper arrays, dictionaries (map), structures, classes.
• A lot more libraries included: string manipulation, full UTF8 support, math, sorting, etc.
• Better performance: all libraries are compiled into OpenNox and run natively.
• Better debugging: if script crashes, there’s a stack trace. Scripts can recover from it as well!
• Go language used in scripts is used in OpenNox itself. Maybe one day you’ll decide to contribute?

In general, we believe that OpenNox is the future of Nox modding, thus porting your map may give it an entirely new life!

How?

At this point, we are still working on improving the EUD compatibility layer, so quite a few functions might still be unavailable. Please talk to us for more details.

In general the conversion process is very similar to the one for converting NS3 source manually. Same changes must be done to the source to align the syntax. We are working on a more automated process.

You need to be aware that all functions using GetMemory and SetMemory must be rewritten in any case. The first thing to do is to check if functions you are using are already available in Panic’s EUD library. If so, updating your EUD script to using these function will help you convert to our EUD library later as well.

We aim to provide a good migration path for well-known EUD libraries, so if you copied code from another EUD project, there’s a high chance we support it in one of the libraries.

Still, if you cannot find anything similar, talk to us. We will help convert your code and include necessary functionality into next OpenNox release.

After conversion

The NS3 guide applies here as well, so make sure to check it out!