From 76512daba29d46909a9ba7c6bdb88c00e2f0eeca Mon Sep 17 00:00:00 2001
From: scawful <justin.scofield@outlook.com>
Date: Mon, 22 Dec 2025 14:51:38 -0500
Subject: [PATCH] chore: add usdasm fetch helper

---
 .gitignore                          |  1 +
 docs/internal/debug/ai_asm_guide.md |  7 +++++++
 scripts/README.md                   |  9 +++++++++
 scripts/fetch_usdasm.sh             | 20 ++++++++++++++++++++
 4 files changed, 37 insertions(+)
 create mode 100755 scripts/fetch_usdasm.sh

diff --git a/.gitignore b/.gitignore
index 3bac54dc..c2a51f45 100644
--- a/.gitignore
+++ b/.gitignore
@@ -75,6 +75,7 @@ src/lib/cmake/
 src/lib/GL/
 src/lib/libpng/
 src/lib/zlib/
+assets/asm/usdasm/
 src/app/gui/modules/component.h
 src/ios/macOS/Info-macOS.plist
 src/ios/macOS/MainMenu.storyboard
diff --git a/docs/internal/debug/ai_asm_guide.md b/docs/internal/debug/ai_asm_guide.md
index b44abcc2..604d9033 100644
--- a/docs/internal/debug/ai_asm_guide.md
+++ b/docs/internal/debug/ai_asm_guide.md
@@ -24,6 +24,13 @@ z3ed emu start --rom oracle_of_secrets.sfc --grpc-port 50051
 
 Load symbols from your ASM source directory for meaningful labels:
 
+If you need the vanilla usdasm disassembly, fetch it on demand:
+
+```bash
+scripts/fetch_usdasm.sh
+# or: USDASM_DIR=/path/to/usdasm scripts/fetch_usdasm.sh
+```
+
 ```protobuf
 rpc LoadSymbols(SymbolFileRequest) returns (CommandResponse)
 
diff --git a/scripts/README.md b/scripts/README.md
index 37a3a865..f6772a7b 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -2,6 +2,15 @@
 
 This directory contains build automation and maintenance scripts for the YAZE project.
 
+## fetch_usdasm.sh
+
+Fetch the usdasm disassembly on demand (not vendored in the repo).
+
+```bash
+scripts/fetch_usdasm.sh
+# or: USDASM_DIR=/path/to/usdasm scripts/fetch_usdasm.sh
+```
+
 ## build_cleaner.py
 
 Automates CMake source list maintenance and header include management with IWYU-style analysis.
diff --git a/scripts/fetch_usdasm.sh b/scripts/fetch_usdasm.sh
new file mode 100755
index 00000000..440ac930
--- /dev/null
+++ b/scripts/fetch_usdasm.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_URL="${USDASM_REPO_URL:-https://github.com/spannerisms/usdasm.git}"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TARGET_DIR="${USDASM_DIR:-$ROOT_DIR/assets/asm/usdasm}"
+
+if [ -d "$TARGET_DIR/.git" ]; then
+  echo "usdasm already present at $TARGET_DIR"
+  exit 0
+fi
+
+if [ -e "$TARGET_DIR" ]; then
+  echo "Removing existing path at $TARGET_DIR"
+  rm -rf "$TARGET_DIR"
+fi
+
+mkdir -p "$(dirname "$TARGET_DIR")"
+git clone --depth 1 "$REPO_URL" "$TARGET_DIR"
+echo "usdasm fetched to $TARGET_DIR"