AI trainer support: refactor, infrastructure, and one desync fix

.gitignore

@@ -3,6 +3,10 @@ options_cache.py
 libgag.a
 libusl.a
 src/glob2
+test/TestsRunner
+test/WinningConditionsHarness
+test/CampaignLoadHarness
+testResults.xml
 .sconf_temp
 .sconsign.dblite
 *.o
@@ -12,3 +16,10 @@ src/glob2
 __pycache__/
 build/
 vcpkg_installed/
+.DS_Store
+compile_commands.json
+.cache/
+Glob2.app/
+Glob2-*.dmg
+test/CampaignSelectionHarness
+test/NetSendOrderDecodeTest

AUTHORS

@@ -0,0 +1,16 @@
+Globulation 2 -- Authors
+
+Original authors of Globulation 2. Their contact information was previously
+included in per-file source headers; sources now carry SPDX short-form
+license identifiers (see COPYING for the full GPL v3 text).
+
+Stephane Magnenat <stephane@magnenat.net>          (2001-2008)
+Luc-Olivier de Charrière <NuageBleu@gmail.com>     (2001-2008)
+Martin S. Nyffenegger <barock@ysagoon.com>         (SGSL scripting language)
+Bradley Arsenault                                  (2006-2008)
+Eli Dupree                                         (2005, AIWarrush)
+Leo Wandersleb <Leo.Wandersleb@gmx.de>             (2006-2007, terrain generation)
+Michiel De Muynck                                  (2010)
+Kyle Lutze                                         (2006-2009)
+
+For ongoing contributors, see the project's git history.

CLAUDE.md

@@ -0,0 +1,152 @@
+# glob2 (Legacy C++ Codebase)
+
+This is the original Globulation 2 C++ codebase. It is legacy code and is not under active development.
+
+## Build Commands
+
+```bash
+cd glob2
+
+# Build (requires SCons, Python 3)
+scons -j16
+
+# Install (may need root)
+scons install
+
+# Clean
+scons -c
+
+# Build options
+scons release=1          # Optimized release build
+scons server=1           # Build YOG server only (no GUI/sound)
+scons --build=/tmp/out   # Out-of-source build
+scons mingw=true         # Windows cross-compile
+
+# Custom paths
+scons BINDIR=/path/bin INSTALLDIR=/path/share
+```
+
+**Dependencies:** SDL2, SDL2_net, SDL2_ttf, SDL2_image, libvorbis, libogg, speex, OpenGL, GLU, libepoxy, Boost (thread, date_time, system), zlib, fribidi, pcre. Optional: portaudio (voice chat). See `vcpkg.json` for the full list.
+
+**Server build gotcha:** Always build the YOG server with `scons server=1` — never with a bare `scons build/src/glob2-server`. The `server=1` flag both selects the server target and defines `YOG_SERVER_ONLY` (which strips out GUI/audio code via `#ifndef` guards) and switches `libgag` to its stripped `libgag_server.a` variant. Without the flag, the .o files are compiled with the full GUI code path but link against the stripped libgag, producing dozens of misleading "undefined symbol" errors that look like fundamental rot. SCons also caches the option in `options_cache.py`, so once you've run `server=1`, subsequent `scons` invocations stay in server mode — pass `server=0` explicitly to switch back.
+
+**Use `release=1` for headless runs.** The default `scons` build is `-g` with no `-O` flag, so `--nox` / `-test-games-nox` runs a debug binary that's roughly 10× slower than necessary. Always build with `scons release=1 -j16` for replay generation, benchmarking, or any throughput-sensitive headless work. Drop back to the default build only when you need a debugger, sanitizers, or fast incremental rebuilds. The flag is sticky via `options_cache.py`, so once set it persists until you pass `release=0`.
+
+## Running Tests
+
+Tests live in `glob2/test/` and are built as part of the SCons build. After `scons -j16`, run the resulting binaries (`TestsRunner`, `WinningConditionsHarness`).
+
+See [`test/README.md`](test/README.md) for the **Map subclass test pattern** — the trick used in `MapQueryTest.cpp` to unit-test Map predicates without pulling in `globalContainer`, `Bullet`, `Team`, or the full simulation surface.
+
+## Build System Internals
+
+SCons-based. `SConstruct` is the main build script with platform detection (Linux, Darwin, Windows/MinGW). Library checks are done via custom configure functions in `scons/`. Build options are cached in `options_cache.py`.
+
+## CI
+
+Travis CI runs Docker-based builds on Ubuntu 18.04–21.04. See `.travis.yml` in the repo root.
+
+## Architecture
+
+### Engine Loop (40ms tick)
+
+The engine is **synchronous** — no multithreading in the core. Every 40ms, `Engine::run()` calls `.step()` on the class hierarchy. See `doc/sourceCodeUnderstanding.txt` for the full explanation.
+
+```
+Engine::run() loop:
+  gui.step()                    → handle input
+  net.pushOrder(gui.getOrder()) → send local player order to network
+  net.pushOrder(ai.getOrder())  → send AI orders
+  net.step()                    → exchange orders over network
+  gui.executeOrder(...)         → execute all received orders
+  gui.drawAll()                 → render
+  sleep()                       → maintain 40ms frame
+```
+
+### Class Hierarchy
+
+```
+Engine
+├─ NetGame          (network abstraction, order transmission via UDP)
+└─ GameGUI          (rendering, input)
+   └─ Game          (game state)
+      ├─ Map        (terrain, resources)
+      ├─ Team[32]   (a "colony" — has color, units, buildings)
+      │  ├─ Unit[1024]
+      │  └─ Building[1024]
+      ├─ Player[32] (human interface — keyboard+mouse or AI)
+      └─ Session    (serializable state: BasePlayer[32], BaseTeam[32])
+```
+
+**Team vs Player:** A Team is a logical colony (color, units, buildings). A Player is a controller (human or AI). Multiple players can control one team. Only teams can be allied.
+
+### Deterministic Networking
+
+All clients compute identical game state. Only Orders (player actions) are transmitted. This requires:
+- **Use `Utilities::syncRand()`** instead of `rand()` — all machines must get the same random numbers
+- **Avoid `std::set`** — it is non-deterministic across platforms
+- Orders are buffered in per-player FIFO queues (256 slots) to handle latency
+
+### Key Source Directories
+
+- **`src/`** — Main game (382 files): engine, game logic, AI, networking, GUI screens, YOG online system
+- **`libgag/`** — Graphics/GUI toolkit library (widget system, sprites, file I/O, rendering)
+- **`libusl/`** — USL scripting language for maps/campaigns
+- **`data/`** — Runtime assets (graphics, fonts, music, GUI resources)
+- **`maps/`** — Game maps
+- **`campaigns/`** — Campaign definitions
+- **`doc/`** — Architecture documentation
+
+### Headless Mode & Replay Generation
+
+See [docs/headless-replays.md](docs/headless-replays.md) for full details on running headless AI games and generating `.replay` files for cross-codebase testing.
+
+Quick reference:
+```bash
+# Random AI-vs-AI game, headless, runs until game over or 90k ticks (loops forever — kill after first game)
+./glob2 -test-games-nox
+
+# Single game from a .game file, headless
+./glob2 --nox <game-file> <steps> <runs>
+# Example: ./glob2 --nox games/my_ai_game.game 5000 1
+```
+
+Replays are always written to `replays/last_game.replay` (overwritten each game).
+
+### AI System
+
+Multiple AI implementations in `src/`: AICastor, AIEcho, AINicowar, AINumbi, AIToubib, AIWarrush — all inherit from `AI` base class.
+
+### Orders System
+
+All player actions are serialized as `Order` objects (see `src/Order.h`). `NullOrder` means "player did nothing this tick" — distinct from "we haven't heard from this player yet." Orders carry complete action data (team, position, type, unit counts).
+
+### YOG (Online Gaming)
+
+Server/client architecture for online play. `YOGServer` handles matchmaking, chat channels, ratings, map database. LAN play is peer-to-peer. Build server-only binary with `scons server=1`.
+
+## Conventions
+
+**Filenames:** PascalCase (`Game.cpp`, `GameRenderUnits.cpp`). Do NOT introduce snake_case C++ filenames in `glob2/`. When splitting an existing PascalCase file, the new pieces stay PascalCase too.
+
+**Header guards:** `#pragma once`. We are moving away from legacy `#ifndef` guards.
+
+**macOS rename caveat:** Case-only filename renames need `git mv -f Foo.cpp foo_tmp.cpp && git mv -f foo_tmp.cpp Foo.cpp` — plain `git mv foo.cpp Foo.cpp` may silently no-op on a case-insensitive filesystem.
+
+## Logging is dead — do not restore
+
+`glob2/src/LogFileManager.h` defines `#define fprintf if(false)fprintf`. Every translation unit that includes that header gets all `fprintf` calls rewritten to a runtime `if(false)` branch the compiler dead-code-eliminates. ~60 files include `LogFileManager.h`. Original devs disabled logging "for bugs" (per the deprecation comment) and never came back; the infrastructure has been load-bearing in constructors but doing nothing for 15+ years.
+
+**Cleanup pattern when refactoring a class with a `FILE* logFile` member and a `globalContainer->logFileManager->getFile(...)` call in its constructor:** drop the field, drop the `getFile()` call, drop every `fprintf(logFile, …)` site (already no-ops), drop the include of `LogFileManager.h`. No replacement needed — there's no live consumer.
+
+`LogFileManager.h` itself stays — it carries the silencing macro.
+
+**Don't propose adding `spdlog` or another logging library to "preserve diagnostic intent."** There's no consumer asking for the data and 15 years of silence means there's no demand. Re-introduce only when something concrete needs it.
+
+## Pathfinding gotcha — chamfer pass cap
+
+For the chamfer distance transform in `glob2/src/map/gradient/MapGradientGlobal.cpp`, the convergence-pass cap is bounded by the Uint8 value range (256), **not** by the Borgefors 1986 1-pass result.
+
+Borgefors 1-pass holds only on an obstacle-free grid. With obstacles forcing the propagation path to bend (mountains, water channels, building footprints), each direction change costs ~K/2 passes. Real glob2 maps (128×128, e.g. `G2.game`) need significantly more than 4 passes — empirically 32 was sufficient and 8 was not.
+
+Use the value-range bound (256). The cap is a tripwire for monotonicity violations, not a real-workload throttle. Do not try to derive a tighter bound from grid geometry — obstacle topology dominates.

SConstruct

@@ -1,4 +1,4 @@
-EnsureSConsVersion(0, 96, 92)
+EnsureSConsVersion(3, 0, 0)
 import sys
 import os
 import glob
@@ -8,7 +8,7 @@ import dmg
 import nsis
 
 isWindowsPlatform = sys.platform=='win32'
-isLinuxPlatform = sys.platform=='linux2'
+isLinuxPlatform = sys.platform.startswith('linux')
 isDarwinPlatform = sys.platform=='darwin'
 
 
@@ -17,7 +17,7 @@ def establish_options(env):
     opts.Add("CXXFLAGS", "Manually add to the CXXFLAGS", "-g")
     opts.Add("LINKFLAGS", "Manually add to the LINKFLAGS", "-g")
     if isDarwinPlatform:
-        opts.Add(PathOption("INSTALLDIR", "Installation Directory", "./"))
+        opts.Add(PathVariable("INSTALLDIR", "Installation Directory", "./"))
     else:
 	    opts.Add("INSTALLDIR", "Installation Directory", "/usr/local/share")
     opts.Add("BINDIR", "Binary Installation Directory", "/usr/local/bin")
@@ -110,9 +110,9 @@ def configure(env, server_only):
         missing.append("zlib")
     else:
         if conf.CheckLib("z"):
-            env.Append(LIBS="z")
+            env.Append(LIBS=["z"])
         elif conf.CheckLib("zlib1"):
-            env.Append(LIBS="zlib1")
+            env.Append(LIBS=["zlib1"])
         else:
             print("Could not find libz or zlib1.dll")
             missing.append("zlib")
@@ -121,51 +121,31 @@ def configure(env, server_only):
         print("Could not find regex.h")
         missing.append("regex")
 
-    boost_thread = ''
-    if conf.CheckLib("boost_thread") and conf.CheckCXXHeader("boost/thread/thread.hpp"):
-        boost_thread="boost_thread"
-    elif conf.CheckLib("boost_thread-mt") and conf.CheckCXXHeader("boost/thread/thread.hpp"):
-        boost_thread="boost_thread-mt"
-    else:
-        print("Could not find libboost_thread or libboost_thread-mt or boost/thread/thread.hpp")
-        missing.append("libboost_thread")
-    env.Append(LIBS=[boost_thread])
-
     boost_date_time = ''
     if conf.CheckLib("boost_date_time") and conf.CheckCXXHeader("boost/date_time/posix_time/posix_time.hpp"):
-        boost_thread="boost_thread"
+        boost_date_time="boost_date_time"
     elif conf.CheckLib("boost_date_time-mt") and conf.CheckCXXHeader("boost/date_time/posix_time/posix_time.hpp"):
-        boost_thread="boost_thread-mt"
+        boost_date_time="boost_date_time-mt"
     else:
-        print("Could not find libboost_date_time or libboost_date_time-mt or boost/thread/thread.hpp")
+        print("Could not find libboost_date_time or libboost_date_time-mt or boost/date_time/posix_time/posix_time.hpp")
         missing.append("libboost_date_time")
     env.Append(LIBS=[boost_date_time])
-    env.Append(LIBS=["boost_system", "pthread"])
+    if conf.CheckLib("boost_system"):
+        env.Append(LIBS=["boost_system"])
+    env.Append(LIBS=["pthread"])
 
 
-    if not conf.CheckCXXHeader("boost/shared_ptr.hpp"):
-        print("Could not find boost/shared_ptr.hpp")
-        missing.append("boost/shared_ptr.hpp")
-    if not conf.CheckCXXHeader("boost/tuple/tuple.hpp"):
-        print("Could not find boost/tuple/tuple.hpp")
-        missing.append("boost/tuple/tuple.hpp")
-    if not conf.CheckCXXHeader("boost/tuple/tuple_comparison.hpp"):
-        print("Could not find boost/tuple/tuple_comparison.hpp")
-        missing.append("boost/tuple/tuple_comparison.hpp")
     if not conf.CheckCXXHeader("boost/logic/tribool.hpp"):
         print("Could not find boost/logic/tribool.hpp")
         missing.append("boost/logic/tribool.hpp")
-    if not conf.CheckCXXHeader("boost/lexical_cast.hpp"):
-        print("Could not find boost/lexical_cast.hpp")
-        missing.append("boost/lexical_cast.hpp")
 
     #Do checks for OpenGL, which is different on every system
     gl_libraries = []
     if not server_only:
         has_gl = True
         if isDarwinPlatform:
             print("Using Apple's OpenGL framework")
-            env.Append(FRAMEWORKS="OpenGL")
+            env.Append(FRAMEWORKS=["OpenGL", "CoreFoundation"])
         elif conf.CheckLib("GL") and conf.CheckCXXHeader("GL/gl.h"):
             gl_libraries.append("GL")
         elif conf.CheckLib("GL") and conf.CheckCXXHeader("OpenGL/gl.h"):
@@ -255,6 +235,10 @@ def main():
     env = Environment()
     env["VERSION"] = "0.9.5.0"
     establish_options(env)
+
+    # Emit compile_commands.json for clangd / IDE LSPs.
+    env.Tool('compilation_db')
+    env.CompilationDatabase()
 
     if env['mingwcross']:
             env.Platform('cygwin')
@@ -263,10 +247,6 @@ def main():
             env['AR']  = 'i586-mingw32msvc-ar'
             env['RANLIB'] = 'i586-mingw32msvc-ranlib'
 
-    try:
-        env.Clone()
-    except AttributeError:
-        env.Clone = env.Copy
 
 
     # Add specific paths.
@@ -276,8 +256,18 @@ def main():
         env.Append(CPPPATH=["C:/msys/1.0/local/include/SDL", "C:/msys/1.0/local/include", "C:/msys/1.0/include/SDL", "C:/msys/1.0/include"])
         env.Append(CPPPATH=['/usr/local/include/SDL'])
     if isDarwinPlatform:
-        env.Append(LIBPATH=["/opt/local/lib"])
-        env.Append(CPPPATH=["/opt/local/include"])
+        import subprocess
+        try:
+            brew_prefix = subprocess.check_output(["brew", "--prefix"], text=True).strip()
+        except (FileNotFoundError, subprocess.CalledProcessError):
+            brew_prefix = None
+        if brew_prefix:
+            env.Append(LIBPATH=[brew_prefix + "/lib"])
+            env.Append(CPPPATH=[brew_prefix + "/include"])
+            env['ENV']['PATH'] = brew_prefix + "/bin:" + env['ENV'].get('PATH', '')
+        else:
+            env.Append(LIBPATH=["/opt/local/lib"])
+            env.Append(CPPPATH=["/opt/local/include"])
     if env['mingwcross']:
         if os.path.isabs(env['crossroot']):
             crossroot_abs = env['crossroot']
@@ -295,15 +285,23 @@ def main():
 
     env.Append(CPPPATH=['#libgag/include', '#'])
     env.Append(CPPPATH=['#libusl/src', '#'])
-    env.Append(CXXFLAGS=' -Wall -fPIC')
+    env.Append(CPPPATH=['#src', '#src/yog', '#src/ai', '#src/building',
+                        '#src/game/entities',
+                        '#src/gui',
+                        '#src/map', '#src/map/edit', '#src/map/generator',
+                        '#src/map/gradient', '#src/map/io', '#src/map/pathfind',
+                        '#src/net', '#src/net/irc', '#src/net/message',
+                        '#src/team',
+                        '#src/unit'])
+    env.Append(CXXFLAGS=' -std=c++20 -Wall -fPIC')
     env.Append(LINKFLAGS=' -Wall')
     env.Append(LIBS=['SDL2_net'])
     if not server_only:
         env.Append(LIBS=['vorbisfile', 'SDL2_ttf', 'SDL2_image', 'speex'])
 
     if env['release']:
         env.Append(CXXFLAGS=' -O3 -s')
-        env.Append(LINKFLAGS=' -O3 -s --fwhole-program')
+        env.Append(LINKFLAGS=' -O3 -s -fwhole-program')
     if env['profile']:
         env.Append(CXXFLAGS=' -pg')
         env.Append(LINKFLAGS='-pg')
@@ -315,11 +313,9 @@ def main():
         env.Append(LINKFLAGS=['-mwindows'])
         env.Append(CPPDEFINES=['-D_GNU_SOURCE=1', '-Dmain=SDL_main'])
     elif isDarwinPlatform:
-        env.ParseConfig("/opt/local/bin/sdl-config --cflags")
-        env.ParseConfig("/opt/local/bin/sdl-config --libs")
+        env.ParseConfig("pkg-config sdl2 --cflags --libs")
     else:
-        env.ParseConfig("sdl2-config --cflags")
-        env.ParseConfig("sdl2-config --libs")
+        env.ParseConfig("pkg-config sdl2 --cflags --libs")
 
 
     env["TARFILE"] = env.Dir("#").abspath + "/glob2-" + env["VERSION"] + ".tar.gz"
@@ -356,7 +352,8 @@ def main():
         dmg.create_dmg("Glob2-%s"%env["VERSION"],"%s.app"%env["BUNDLE_NAME"],env)
 
         #TODO mac_bundle should be dependency of Dmg:    
-        arch = os.popen("uname -p").read().strip()
+        import subprocess
+        arch = subprocess.check_output(["uname", "-p"], text=True).strip()
 #        mac_packages = env.Dmg('Glob2-%s-%s.dmg'% (fullVersion, arch),  env.Dir('Glob2.app/') )
 #        env.Alias("package", mac_packages)
 

campaigns/SConscript

@@ -4,7 +4,7 @@ Import("env")
 Import("PackTar")
 
 
-if 'dist' or 'install' in COMMAND_LINE_TARGETS:
+if 'dist' in COMMAND_LINE_TARGETS or 'install' in COMMAND_LINE_TARGETS:
     any=False
     for file in os.listdir("."):
         if file.find(".txt") != -1 or file.find(".map") != -1: