Aqua IV 0.11
Documentation Editor Engine API
Documentation /API / Scripting in Go

Why Go

In Warcraft III you made a map's rules with JASS or with the trigger tree. W4 uses Go instead of a new language of its own.

Go is small. It has twenty-five keywords and usually one obvious way to do a thing. The compiler tells you what is wrong and on which line. It is widely used, so there are editors, lessons and people to ask. If you have written TypeScript, Lua or Python, you can read a W4 script on the first day.

You do not need to know Go, programming or git to start. The first script is a few lines you can copy, and each one is explained.

What it means for you

  • Help while you type. Open the map's scripts folder in an editor like VS Code or Zed. It suggests W4's functions, shows what each one takes, and underlines a mistake before you start the game.
  • Mistakes show up early. A misspelled name or a wrong number of arguments is marked on the line. You do not find it ten minutes into a game.
  • A script is a text file. You can read it, copy it, send it to a friend or paste it into a chat to ask for help.
  • Trying a change is quick. The editor builds the script in a moment.
  • A map cannot harm your computer. The game runs the script in a closed box. It cannot read your files or reach the internet. See Multiplayer rules.
  • No manual memory management. Go cleans up after you. In JASS you had to remember RemoveLocation, DestroyGroup and DestroyEffect or the game slowly leaked. In Go there is nothing to remember: you make a value, use it, and drop it.
  • Functions can remember things. A function you hand to a timer can use the variables around it. In the example on the home page a wave counter lives in main, and the timer function counts it up every twenty seconds. Go calls this a closure. JASS has no closures, so the same thing there needs a global variable and a separate named function.

How it runs: standard Go, in a sandbox

There is no W4 dialect. The editor builds your files with the ordinary Go toolchain to WebAssembly (GOOS=wasip1), and the engine runs the result in wasmtime, beside the simulation. The w4 packages (events, game, players, UI) are a normal Go module that ships with the editor, so completion and error checks work in any Go-aware editor. The API reference is generated from that module's doc comments, so it cannot drift from the code.

The game's simulation is deterministic, so a script has to be too. Go's own sources of difference are closed off: the clock a script sees is game time, math/rand and game.Random draw from the game's seed, and map iteration order comes from that seed. Every computer in a match, and every replay, then gets the same answers. The rules are on Multiplayer rules.

What a script can and cannot do

  • It can react to events and timers, spawn and order units, read and change what the API exposes, and show each player their own interface text, buttons and panels.
  • It cannot read your disk, use the network or look at the real clock. A handler that runs too long, about 200 million instructions in one call, is stopped for the rest of the game and the reason goes to the message log; the game keeps running. Memory is capped at 256 MB.
  • It cannot yet do everything Warcraft III's triggers could: there is no hot reload into a running game, and sound and camera control from scripts are planned. What is next keeps the honest list.

The cost

Go is code. If you have never written any, the trigger tree with Events, Conditions and Actions is gentler than a text file, and W4 does not have one yet. GUI triggers are planned for later, as an optional layer that writes ordinary Go for you. It will not be a second language. Until then the tutorials start small and the API reference lists every function.

Why not JASS or Lua

JASS is used only by Warcraft III, so its tools are few and old. Lua is a fine language, but it tells you about a typo only when the game reaches that line. Go checks everything before the game starts.