From 2be040216d68f8f60ade8c60673dc30af39bd215 Mon Sep 17 00:00:00 2001
From: Paul Huliganga <paje0101@gmail.com>
Date: Fri, 15 May 2026 10:44:04 -0400
Subject: [PATCH] =?UTF-8?q?docs(readme):=20add=20full=20setup=20guide=20?=
 =?UTF-8?q?=E2=80=94=20SSH=20access,=20clone,=20overlay,=20build=20steps?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds SSH key setup instructions for paje.ca, correct Gitea hostname
(git.paje.ca), step-by-step clone+overlay workflow, Unity batch build
command, DLL rsync note (Builds/ not Library/), and an update workflow
for pulling future script changes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 102 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 79 insertions(+), 23 deletions(-)

diff --git a/README.md b/README.md
index 46b5a76..b500ece 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 # sdsandbox-rl-scripts
 
 Modified C# scripts for the sdsandbox Unity simulator, used with the
-[donkeycar-rl-autoresearch](https://paje.ca/git/paulh/donkeycar-rl-autoresearch) project.
+[donkeycar-rl-autoresearch](https://git.paje.ca/paulh/donkeycar-rl-autoresearch) RL training project.
 
 ## What's here
 
@@ -9,37 +9,93 @@ Modified C# scripts for the sdsandbox Unity simulator, used with the
 - `ProjectSettings/` — Unity project settings
 - `Packages/` — Unity package manifest
 
+Binary assets (textures, models, scenes) are **not** included here — they come from the
+upstream sdsandbox repo. See **Setup** below.
+
 ## Key modifications (vs upstream tawnkramer/sdsandbox)
 
-- **`Car.cs`** — per-wheel OverlapSphere barrier collision detection; CCD mode
-- **`TcpCarHandler.cs`** — `regen_road` message support with direct RoadBuilder+PathManager fallback when no TrainingManager present; `set_ai_text` overlay message
+- **`Car.cs`** — per-wheel OverlapSphere barrier collision detection; CCD tunneling prevention
+- **`TcpCarHandler.cs`** — `regen_road` TCP message with direct RoadBuilder+PathManager fallback
+  when no TrainingManager is present; `set_ai_text` overlay message; BrakeOnUpdate support
 - **`PathManager.cs`** — self-intersection fix: retry loop with XZ segment-segment math (up to 20 retries)
-- **`RoadBuilder.cs`** — BoxCollider per segment with overlap; `showBarrierMeshes` flag
-- **`MapOverlay.cs`** — minimap refresh on road node position change (not just count)
+- **`RoadBuilder.cs`** — BoxCollider per segment with overlap to close corner gaps; `showBarrierMeshes` flag
+- **`MapOverlay.cs`** — minimap refreshes on road node position change (not just node count)
 
 ## Setup on a new machine
 
-1. Clone the upstream sdsandbox (provides all binary assets Unity needs):
-   ```bash
-   git clone https://github.com/tawnkramer/sdsandbox
-   ```
+### Step 1 — SSH access to paje.ca (one-time)
 
-2. Clone this repo:
-   ```bash
-   git clone git@paje.ca:paulh/sdsandbox-rl-scripts.git
-   ```
+Generate an SSH key if you don't have one:
+```bash
+ssh-keygen -t ed25519 -C "your-name@your-machine"
+```
 
-3. Overlay our scripts into the sdsandbox project:
-   ```bash
-   cp -r sdsandbox-rl-scripts/Scripts/*        sdsandbox/sdsim/Assets/Scripts/
-   cp -r sdsandbox-rl-scripts/ProjectSettings/* sdsandbox/sdsim/ProjectSettings/
-   cp -r sdsandbox-rl-scripts/Packages/*        sdsandbox/sdsim/Packages/
-   ```
+Copy the public key:
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
 
-4. Open `sdsandbox/sdsim` in Unity 6000.4.4f1. Unity will reimport assets on first open.
+Add it to Gitea: log in at **https://git.paje.ca** → Settings → SSH / GPG Keys → Add Key.
 
-5. Build: **Edit → Project Settings → Player Builder → WinBuild** (or use the batch build command from the donkeycar-rl-autoresearch SESSION_HANDOFF.md).
+Test it:
+```bash
+ssh -T git@paje.ca
+# Expected: Hi there, paulh! You've successfully authenticated...
+```
 
-## Unity version
+### Step 2 — Clone both repos
 
-**Unity 6000.4.4f1** — other versions are not tested and may have incompatible APIs.
+Clone the upstream sdsandbox (provides all binary assets Unity needs):
+```bash
+git clone https://github.com/tawnkramer/sdsandbox
+```
+
+Clone this repo:
+```bash
+git clone git@paje.ca:paulh/sdsandbox-rl-scripts.git
+```
+
+### Step 3 — Overlay our scripts
+
+```bash
+cp -r sdsandbox-rl-scripts/Scripts/*         sdsandbox/sdsim/Assets/Scripts/
+cp -r sdsandbox-rl-scripts/ProjectSettings/* sdsandbox/sdsim/ProjectSettings/
+cp -r sdsandbox-rl-scripts/Packages/*        sdsandbox/sdsim/Packages/
+```
+
+### Step 4 — Open in Unity
+
+Open `sdsandbox/sdsim` in **Unity 6000.4.4f1**. Unity will reimport assets on first open
+(takes a few minutes).
+
+Other Unity versions are not tested and may have incompatible APIs.
+
+### Step 5 — Build the simulator
+
+Run the batch build from WSL:
+```bash
+"/mnt/c/Program Files/Unity/Hub/Editor/6000.4.4f1/Editor/Unity.exe" \
+  -quit -batchmode \
+  -projectPath "C:/path/to/sdsandbox/sdsim" \
+  -executeMethod PlayerBuilder.WinBuild \
+  -logFile "C:/Users/YourName/AppData/Local/Temp/unity_rebuild.log"
+```
+
+Build output lands in `sdsim/Builds/DonkeySimWin/`. Copy the `Assembly-CSharp.dll`
+from **that folder** (not `Library/ScriptAssemblies/`) to the runtime sim folder:
+```bash
+rsync -av "sdsim/Builds/DonkeySimWin/donkey_sim_Data/Managed/Assembly-CSharp.dll" \
+  "/path/to/DonkeySimWin/donkey_sim_Data/Managed/Assembly-CSharp.dll"
+```
+
+## Keeping scripts up to date
+
+To pull the latest script changes onto an existing sdsandbox clone:
+```bash
+cd sdsandbox-rl-scripts && git pull
+cp -r Scripts/*         ../sdsandbox/sdsim/Assets/Scripts/
+cp -r ProjectSettings/* ../sdsandbox/sdsim/ProjectSettings/
+cp -r Packages/*        ../sdsandbox/sdsim/Packages/
+```
+
+Then rebuild in Unity (Step 5 above).