agent-skills-vrc-udon

v1.4.0

Published

6 days ago

AI Agent Skills for VRChat UdonSharp - Rules, validation hooks, and knowledge base for correct UdonSharp code generation

0High
0Medium
0Low

niaka3dayo

vrchat udonsharp udon ai-agent ai-skills claude-code codex-cli gemini-cli agent-skills vrc-sdk

English | 日本語 | 简体中文 | 繁體中文 | 한국어

使用 UdonSharp（C# → Udon Assembly）進行 VRChat 世界開發時，存在嚴格的編譯限制，與標準 C# 有顯著差異。List<T>、async/await、try/catch、LINQ、lambda 等功能會導致編譯錯誤。

本專案為 AI 程式碼代理提供必要知識，使其從一開始就能生成正確的 UdonSharp 程式碼。

| 問題 | 解決方案 | |------|----------| | AI 生成 List<T>、async/await 等不支援的語法 | 規則 + 掛鉤自動偵測並發出警告 | | 同步變數過度膨脹 | 決策樹 + 資料量預算 | | 不正確的網路模式 | 模式庫 + 反模式集 | | SDK 版本間功能差異 | 版本對照表與功能對應 | | Late Joiner 狀態不一致 | 同步模式選擇框架 |

本專案並非：

VRChat SDK 或 UdonSharp 的發布版本
Unity 專案（不包含可執行程式碼）
VRChat 官方文件的替代品
AI 行為的完整保證

Issues：歡迎透過 GitHub Issues 提交錯誤回報與知識請求。 PRs：不接受 Pull Request。詳情請參閱 CONTRIBUTING.md。

從 fork/clone 遷移？ — 自 v1.0.0 起，本專案以 npm 套件 形式發布。您不再需要 fork 或 clone 此儲存庫。只需在您的 VRChat Unity 專案中執行以下任一安裝指令即可。如果您先前曾 clone 此儲存庫，可以安全地刪除該目錄並改用 npm 安裝方式。

方法 1：skills CLI（推薦）

npx skills add niaka3dayo/agent-skills-vrc-udon

此方法使用 skills.sh 生態系統將技能安裝至您的專案。

方法 2：Claude Code 外掛

claude plugin add niaka3dayo/agent-skills-vrc-udon

方法 3：npx 直接安裝

npx agent-skills-vrc-udon

選項：

npx agent-skills-vrc-udon --force    # 覆寫現有檔案
npx agent-skills-vrc-udon --list     # 預覽待安裝檔案（模擬執行）

方法 4：git clone

git clone https://github.com/niaka3dayo/agent-skills-vrc-udon.git

skills/                                  # 所有技能
  unity-vrc-udon-sharp/                 # UdonSharp 核心技能
    SKILL.md                              # 技能定義 + frontmatter
    LICENSE.txt                           # MIT 授權條款
    CHEATSHEET.md                         # 快速參考（1 頁）
    rules/                               # 限制規則
      udonsharp-constraints.md
      udonsharp-networking.md
      udonsharp-sync-selection.md
    hooks/                               # PostToolUse 驗證
      validate-udonsharp.sh
      validate-udonsharp.ps1
    assets/templates/                    # 程式碼範本（4 個檔案）
    references/                          # 詳細文件（20 個檔案）
  unity-vrc-world-sdk-3/                # VRC World SDK 技能
    SKILL.md, LICENSE.txt, CHEATSHEET.md, references/（7 個檔案）
templates/                               # AI 工具設定範本
  CLAUDE.md  AGENTS.md  GEMINI.md        # 透過安裝程式分發給使用者
.claude-plugin/marketplace.json         # Claude Code 外掛註冊
CLAUDE.md                               # 開發指南（僅限本儲存庫）

unity-vrc-udon-sharp

UdonSharp 腳本核心技能。涵蓋編譯限制、網路、事件與範本。

| 領域 | 內容 | |------|------| | 限制 | 被禁止的 C# 功能與替代方案（List<T> → DataList、async → SendCustomEventDelayedSeconds） | | 網路 | 所有權模型、Manual/Continuous 同步、FieldChangeCallback、反模式 | | NetworkCallable | SDK 3.8.1+ 參數化網路事件（最多 8 個參數） | | 持久化 | SDK 3.7.4+ PlayerData/PlayerObject API | | 動態元件 | SDK 3.10.0+ PhysBones、Contacts、VRC Constraints for Worlds | | 網頁載入 | String/Image 下載、VRCJson、VRCUrl 限制 | | 範本 | 4 個入門範本（BasicInteraction、SyncedObject、PlayerSettings、CustomInspector） |

unity-vrc-world-sdk-3

世界級場景設定、元件配置與效能最佳化。

| 領域 | 內容 | |------|------| | 場景設定 | VRC_SceneDescriptor、出生點、Reference Camera | | 元件 | VRC_Pickup、Station、ObjectSync、Mirror、Portal、CameraDolly | | 圖層 | VRChat 保留圖層與碰撞矩陣 | | 效能 | FPS 目標、Quest/Android 限制、最佳化檢查清單 | | 光照 | 烘焙光照最佳實踐 | | 音訊/視訊 | 空間音訊、影片播放器選擇（AVPro vs Unity） | | 上傳 | 建置與上傳流程、上傳前檢查清單 |

規則是在 AI 代理生成程式碼之前提供指引的限制檔案。

| 規則檔案 | 內容 | |----------|------| | udonsharp-constraints | 被禁止的 C# 功能、程式碼生成規則、屬性、可同步型別 | | udonsharp-networking | 所有權模型、同步模式、反模式、NetworkCallable 限制 | | udonsharp-sync-selection | 同步決策樹、資料量預算目標、6 項最小化原則 |

同步決策樹

Q1: 其他玩家是否需要看到？
    否  --> 不需同步（0 位元組）
    是  --> Q2

Q2: Late Joiner 是否需要取得當前狀態？
    否  --> 僅使用事件（0 位元組）
    是  --> Q3

Q3: 是否持續變化？（位置/旋轉）
    是  --> Continuous 同步
    否  --> Manual 同步（最少量的 [UdonSynced]）

目標：每個 behaviour 低於 50 位元組。中小型世界：合計低於 100 位元組。

PostToolUse 掛鉤會在 .cs 檔案被編輯時自動執行。

| 類別 | 檢查項目 | 嚴重程度 | |------|----------|----------| | 禁止功能 | List<T>、async/await、try/catch、LINQ、Coroutine、lambda | ERROR | | 禁止模式 | AddListener()、StartCoroutine() | ERROR | | 網路 | [UdonSynced] 缺少 RequestSerialization() | WARNING | | 網路 | [UdonSynced] 缺少 Networking.SetOwner() | WARNING | | 同步膨脹 | 每個 behaviour 超過 6 個同步變數 | WARNING | | 同步膨脹 | int[]/float[] 同步（建議使用更小的型別） | WARNING | | 設定不符 | NoVariableSync 模式下使用 [UdonSynced] 欄位 | ERROR |

同時支援 Bash（validate-udonsharp.sh）與 PowerShell（validate-udonsharp.ps1）。

SDK 版本

| SDK 版本 | 主要功能 | 狀態 | |:--------:|:---------|:----:| | 3.7.1 | StringBuilder、Regex、System.Random | 已支援 | | 3.7.4 | Persistence API（PlayerData / PlayerObject） | 已支援 | | 3.7.6 | 多平台建置與發布（PC + Android） | 已支援 | | 3.8.0 | PhysBone 依賴排序、Force Kinematic On Remote | 已支援 | | 3.8.1 | [NetworkCallable] 參數化事件、Others/Self 目標 | 已支援 | | 3.9.0 | Camera Dolly API、Auto Hold pickup | 已支援 | | 3.10.0 | VRChat Dynamics for Worlds（PhysBones、Contacts、VRC Constraints） | 已支援 | | 3.10.1 | 錯誤修正、穩定性改善 | 已支援 | | 3.10.2 | EventTiming.PostLateUpdate/FixedUpdate、PhysBones 修正、shader 時間全域變數 | 最新穩定版 |

注意：SDK 3.9.0 以下版本已於 2025 年 12 月 2 日棄用。新的世界上傳需使用 3.9.0 以上版本。

官方資源

| 資源 | 網址 | |------|------| | VRChat Creators 文件 | https://creators.vrchat.com/ | | UdonSharp API 參考 | https://udonsharp.docs.vrchat.com/ | | VRChat 論壇（問答） | https://ask.vrchat.com/ | | VRChat Canny（錯誤/功能建議） | https://feedback.vrchat.com/ | | VRChat 社群 GitHub | https://github.com/vrchat-community |

歡迎提交 Issues -- 錯誤回報和知識請求有助於改善本專案。

不接受 Pull Request -- 所有修正與更新由維護者進行。

詳情請參閱 CONTRIBUTING.md。

本專案與 VRChat Inc. 無任何關聯。不暗示任何官方背書、合作關係或從屬關係。
「VRChat」、「UdonSharp」、「Udon」及相關名稱/標誌為 VRChat Inc. 的商標。所有商標均歸其各自所有者所有。
本儲存庫是一個個人知識庫，旨在協助 AI 程式碼代理生成正確的 UdonSharp 程式碼。本專案不分發 VRChat SDK 或 UdonSharp 編譯器的任何部分。

準確性

內容以**「現狀」**提供，不附帶任何保證。請參閱 LICENSE。
這是一個個人專案。可能存在錯誤、過時資訊或不完整的內容。 請務必與 VRChat 官方文件進行核對。
作者不對本儲存庫造成的問題承擔任何責任（建置錯誤、上傳被拒絕、非預期的世界行為等）。
SDK 涵蓋範圍（3.7.1 - 3.10.2）反映的是最後更新時的狀態。VRChat 發布新版本時，行為可能會有所變更。

AI 輔助建立

本知識庫在 AI 工具（Claude、Gemini、Codex）的輔助下建立與維護。所有內容均經過審閱，但 AI 生成的部分可能包含細微錯誤。使用時請自行承擔風險。

授權條款

本專案採用 MIT 授權條款。詳情請參閱 LICENSE。

您可以在 MIT 授權條款下自由 fork、修改與再發布。本授權條款適用於本儲存庫中的文件、規則、範本與掛鉤。本授權不授予 VRChat SDK、UdonSharp 編譯器或其他 VRChat 智慧財產權的任何權利。