Init Repo

2026-06-03 09:00:11 +08:00
commit 9be48d8b9e
155 changed files with 14827 additions and 0 deletions
@@ -0,0 +1,81 @@
+# AGENTS.md
+
+## Project
+
+C++17 / Windows desktop app using **OpenUSD + ImGui + OpenGL**. USD scene editor with layer-based overrides for lights, geometry, and materials — similar to Maya Render Layers.
+
+---
+
+## Build Commands
+
+```powershell
+# Configure (Visual Studio 17 2022, outputs to ./build, installs to ./install)
+cmake --preset default
+
+# Build Release
+cmake --build build --config Release
+
+# Install
+cmake --install build --config Release
+
+# Build & run tests
+cmake --build build --config Release
+ctest --test-dir build -C Release
+```
+
+- **Always** use `cmake --preset default` — do not invoke CMake manually with ad-hoc `-G` flags.
+- Build output: `./build/` | Install prefix: `./install/`
+- The installed `App.exe` lives in `install/bin/`.
+
+---
+
+## Key Paths
+
+| What | Where |
+|---|---|
+| OpenUSD SDK | `third_party/OpenUSD_v25.05/` |
+| ImGui source | `third_party/imgui-1.92.7/` |
+| GLAD loader | `third_party/glad/` |
+| Inter font | `third_party/Inter/Inter.ttc` |
+| CMake Find modules | `cmake/modules/` (`FindOpenUSD.cmake`, `FindImgui.cmake`, `FindGlad.cmake`) |
+| USD business logic | `src/core/` |
+| ImGui panels | `src/ui/` |
+| Utilities | `src/utils/` |
+| Tests | `tests/` |
+| OpenSpec specs/changes | `openspec/changes/` |
+
+> Note: AGENTS.md previously listed `OpenUSD_v25.08` — the actual SDK on disk is `OpenUSD_v25.05`. Trust `CMakePresets.json` / `third_party/` over prose.
+
+---
+
+## Architecture Notes
+
+- **Namespace**: all project code uses `namespace UsdLayerManager`.
+- USD plugin registry: at runtime the app scans `<exe_dir>/usd/` for `plugInfo.json` and registers plugins via `pxr::PlugRegistry`.
+- Renderer uses `UsdImagingGLEngine` into a `GlfDrawTarget` FBO; viewport picking done via engine ray-cast.
+- `ViewportCamera` mirrors `usdview`'s `FreeCamera.py` (Tumble/Truck/AdjustDistance/FrameSelection); supports both Free and USD camera-prim modes.
+- ImGui docking branch is used; docking enabled via `IMGUI_HAS_DOCK`.
+- Python 3.12 (`python312.dll`) must be present — OpenUSD runtime requires it. CMake copies it to output via `POST_BUILD`.
+- Windows-only: uses `imgui_impl_win32` + `imgui_impl_opengl3`.
+
+---
+
+## Critical Rules
+
+1. **API Pre-check**: Before writing any OpenUSD API call, scan headers first:
+   ```powershell
+   findstr /r /s "FunctionName" third_party\OpenUSD_v25.05\include\
+   ```
+   Never assume an API exists — the actual SDK version may differ from docs.
+
+2. **Build before test**: Complete `cmake --build` + `cmake --install` before running `App.exe` or CTest. Tests copy USD/Python DLLs via `POST_BUILD`; skipping the build step breaks DLL resolution.
+
+3. **Self-healing**: If compilation fails, extract the MSBuild error log and fix the root cause. Do not retry the same approach more than once.
+
+4. **No CI**: There are no GitHub Actions workflows. Validation is manual via CTest and running `App.exe`.
+
+---
+
+## Feature Workflow (OpenSpec)
+
+Feature proposals live under `openspec/changes/<name>/` with `proposal.md`, `design.md`, `specs/`, and `tasks.md` (checkbox-tracked). Use the `openspec-*` skills (via Kilo) to propose, implement, and archive changes.