UnityTrafficSimulation/BUILDING.md

# Linux build and launch

The simulation builds and runs on Debian 13 x86_64 with its original
**Unity 2018.1.6f1** editor. UNet, the legacy .NET runtime, the scene, and the
traffic algorithms are retained. The source recovery is described in
[Recovery/README.md](Recovery/README.md).

## Run over SSH

On the server:

```sh
./run-linux.sh --vnc
```

On your local computer, open a second SSH connection with a tunnel:

```sh
ssh -L 5901:127.0.0.1:5901 your-server
```

Connect a VNC viewer to `127.0.0.1:5901`. The VNC service listens only on
localhost; access it through the SSH tunnel. The launcher starts a virtual
1280×800 display, both Python services, the simulation server, and its graphical
client. It requires `xvfb`, `xauth`, and `x11vnc`. Close the client or press
Ctrl-C in the launcher terminal to stop all its processes.

Other modes:

```sh
./run-linux.sh --server  # Python services and headless simulation server
./run-linux.sh --demo    # Server plus graphical client on the current desktop
```

Python 3 and Bash are required. The launcher uses local HTTP ports 8080/8081 and
UNet port 7777; it refuses to start if an existing service occupies those ports.
Traffic lights start in the original `off` state (uncontrolled intersections).
The simulation does not automatically cycle them; the original HTTP API can
control them. Logs are written under `Builds/linux/`.

A separate graphical Linux client can connect to an already running server:

```sh
Builds/linux/Simulation.x86_64 --connect SERVER_ADDRESS \
  -screen-width 1280 -screen-height 800 -screen-fullscreen 0 -force-glcore
```

Without `--connect`, the player opens the original connection menu. `--server`
starts the server automatically; `--traffic-url` and `--event-url` can select
other HTTP services. Keep server and client in separate processes, as the
original simulation uses delayed client interpolation.

## Build

```sh
./build-linux.sh
```

Output: `Builds/linux/Simulation.x86_64` and `Builds/linux/Simulation_Data/`.
Distribute both together. The build log is `Builds/linux/build.log`.
The script uses Xvfb when no display is available and places temporary import
files in `Builds/linux/tmp` by default to avoid filling a small `/tmp` tmpfs.
Override the editor or temporary directory when needed:

```sh
UNITY_EDITOR=/path/to/2018.1.6f1/Editor/Unity TMPDIR=/large/tmp ./build-linux.sh
```

The build includes `Assets/Scenes/Main.unity`. The original build settings
incorrectly named the nonexistent `SampleScene.unity`.

## Installed toolchain

- `/opt/unity/2018.1.6f1/Editor/Unity`, including Linux player support.
- Blender 2.79b at `/opt/blender-2.79b-linux-glibc219-x86_64/blender`, also
  available as `blender` on PATH for importing the original `.blend` models.
- GTK 2, libsoup 2.4, GLU, and GConf 2 compatibility libraries. GConf came from
  Debian's `libgconf-2-4_3.2.6-8_amd64.deb` and
  `gconf2-common_3.2.6-8_all.deb`, as Debian 13 no longer includes it.
- Xvfb, xauth, and x11vnc for SSH access. Mesa llvmpipe successfully rendered the
  client without a physical GPU. This software rendering can be slower than a
  desktop GPU. The machine has no audio device, so Unity reports audio fallback
  messages and runs without sound.

Downloads: [Unity 2018.1.6f1](https://unity.com/releases/editor/whats-new/2018.1.6f1),
[Blender 2.79b](https://download.blender.org/release/Blender2.79/),
[Debian GConf packages](https://deb.debian.org/debian/pool/main/g/gconf/).
Recovery-only tools (ILSpy, UnityPy, OpenEXR, and .NET SDK) are not needed to build
or run the restored source.

## Activation on this machine

Unity Personal was activated using the signed-in account. The modern
entitlement alone was insufficient for this editor; Unity's official Licensing
Client successfully issued the compatible legacy license with `--activate-ulf`.
The editor now reads `~/.local/share/unity3d/Unity/Unity_lic.ulf`.
No additional sign-in is needed for builds on this machine while that license
remains valid. Licenses and credentials are outside the repository and build.

`./unity-ssh.sh` opens a private D-Bus session with a dedicated keyring in
`~/.local/share/unity-ssh/keyrings`. It preserves the desktop keyring. Use the
same local keyring password when reopening it; this is separate from your Unity
account password. The helper checks that credentials can be stored before
opening its shell. Run `./unity-ssh.sh --check` to check the keyring alone.

For an account sign-in or modern Personal activation, run inside that shell:

```sh
unity auth login
unity license activate --personal --accept-eula
unity license status
```

The login command prints a browser URL usable on another computer. The activation
command accepts the Personal terms. Those commands alone may still require the
legacy ULF compatibility step for Unity 2018. See the official
[Unity CLI documentation](https://docs.unity.com/en-us/unity-cli/use-unity-cli).

## Verification

Verified on this host:

- Linux player and editor C# compilation using the genuine Unity 2018 libraries.
- A complete Linux standalone build, followed by server and graphical client
  startup through `run-linux.sh --vnc`.
- Client connection, car spawning, completed trips, and traffic counts sent to
  the original Python backend.
- HTTP traffic-light changes, queuing at red lights, and resumed traffic.
- A local event displayed by the client's notification UI.
- Rendered town, pedestrians, cars, post-processing, and recovered lighting.
- No missing-script warnings or managed runtime exceptions during the successful
  server/client test. Old vendor API deprecation and model import warnings remain.
- Launcher shutdown cleans up the services, players, VNC server, and virtual
  display it started.

Local screenshots and test captures are under `Builds/linux/`; generated output
and the preserved old Library cache are ignored by Git.