unity-vrc-udon-sharp
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUdonSharp Skill
UdonSharp技能
Why This Skill Matters
本技能的重要性
UdonSharp looks like regular Unity C# scripting — until you hit its hidden walls. Many standard C# features (, , , LINQ, generics) silently fail or refuse to compile in Udon. Networking is even more treacherous: modifying a synced variable without ownership produces no error — it just does nothing. Forgetting means your state changes never leave your machine. Standard single-player local testing gives zero signal about these networking bugs because there is only one player.
List<T>async/awaittry/catchRequestSerializationEvery rule in this skill exists because UdonSharp's default behavior is to fail silently. Read the Rules before generating any code.
UdonSharp看起来和常规Unity C#脚本完全一样——直到你撞上它的隐藏限制。许多标准C#特性（、、、LINQ、泛型）在Udon中会静默失败或拒绝编译。网络部分则更加棘手：在没有所有权的情况下修改同步变量不会产生任何错误——只是完全不起作用。忘记调用意味着你的状态变更永远不会同步到其他玩家的设备。标准的单人本地测试无法发现这些网络bug，因为测试环境中只有一个玩家。
List<T>async/awaittry/catchRequestSerialization本技能中的每一条规则都源于UdonSharp的默认行为是静默失败。在生成任何代码之前，请先阅读这些规则。
Core Principles
核心原则
- Constraints First — Assume standard C# features are blocked until verified. Check before using any API.
udonsharp-constraints.md - Ownership Before Mutation — Only the owner of an object can modify its synced variables. Always → modify →
SetOwner.RequestSerialization - Late Joiner Correctness — State must be correct for players who join after events have occurred. Design for re-serialization, not just live updates.
- Sync Minimization — Every synced variable costs bandwidth (see data budget in ). Derive what you can locally; sync only the source of truth.
udonsharp-sync-selection.md - Event-Driven, Not Polling — Use ,
OnDeserialization, and[FieldChangeCallback]instead of checking state inSendCustomEvent.Update()
- 优先考虑限制——默认假设标准C#特性被禁用，直到验证可用。使用任何API前请查看。
udonsharp-constraints.md - 先获取所有权再修改——只有对象的所有者才能修改其同步变量。请遵循→ 修改 →
SetOwner的流程。RequestSerialization - 迟加入玩家兼容性——对于在事件发生后加入的玩家，状态必须保持正确。设计时要考虑重新序列化，而不仅仅是实时更新。
- 最小化同步——每个同步变量都会消耗带宽（详见中的数据预算）。尽可能在本地推导数据；仅同步真相源。
udonsharp-sync-selection.md - 事件驱动而非轮询——使用、
OnDeserialization和[FieldChangeCallback]，而非在SendCustomEvent中检查状态。Update()
Overview
概述
SDK Coverage: 3.7.1 - 3.10.2 (as of March 2026)
SDK支持范围：3.7.1 - 3.10.2（截至2026年3月）
Rules (Constraints & Networking)
规则（限制与网络）
Compile constraints and networking rules are defined in always-loaded Rules:
| Rule File | Contents |
|---|---|
| Blocked features, code generation rules, attributes, syncable types |
| Ownership, sync modes, RequestSerialization, NetworkCallable |
| Sync pattern selection, data budget, minimization principles |
After installation, place these in the agent's rules directory for automatic loading.
编译限制和网络规则定义在始终加载的规则中：
| 规则文件 | 内容 |
|---|---|
| 禁用特性、代码生成规则、属性、可同步类型 |
| 所有权、同步模式、RequestSerialization、NetworkCallable |
| 同步模式选择、数据预算、最小化原则 |
安装完成后，请将这些文件放置在Agent的规则目录中以实现自动加载。
SDK Versions
SDK版本
| SDK Version | Key Features |
|---|---|
| 3.7.1 | Added |
| 3.7.4 | Added Persistence API (PlayerData/PlayerObject) |
| 3.7.6 | Multi-platform Build & Publish (PC + Android simultaneously) |
| 3.8.0 | PhysBone dependency sorting, Drone API (VRCDroneInteractable) |
| 3.8.1 | |
| 3.9.0 | Camera Dolly API, Auto Hold pickup simplification |
| 3.10.0 | VRChat Dynamics for Worlds (PhysBones, Contacts, VRC Constraints) |
| 3.10.1 | Bug fixes and stability improvements |
| 3.10.2 | EventTiming extensions, PhysBones fixes, shader time globals |
Note: SDK versions below 3.9.0 are deprecated as of December 2, 2025. New world uploads are no longer possible.
| SDK版本 | 关键特性 |
|---|---|
| 3.7.1 | 新增 |
| 3.7.4 | 新增持久化API（PlayerData/PlayerObject） |
| 3.7.6 | 多平台构建与发布（同时支持PC和Android） |
| 3.8.0 | PhysBone依赖排序、Drone API（VRCDroneInteractable） |
| 3.8.1 | 新增** |
| 3.9.0 | 相机轨道API、自动拾取简化 |
| 3.10.0 | 面向VRChat世界的动力学系统（PhysBones、Contacts、VRC Constraints） |
| 3.10.1 | Bug修复与稳定性提升 |
| 3.10.2 | EventTiming扩展、PhysBones修复、着色器时间全局变量 |
注意：截至2025年12月2日，3.9.0以下的SDK版本已被弃用。不再支持上传新的世界。
Web Search
网页搜索
When to Search
何时搜索
| Scenario | Action |
|---|---|
| New SDK version support | Check official docs for latest API |
| "Is this possible?" questions | Verify feasibility in official docs |
| Unknown errors | Refer to official troubleshooting |
| New feature usage | Retrieve latest code examples |
| 场景 | 操作 |
|---|---|
| 新SDK版本支持 | 查看官方文档获取最新API |
| “这是否可行？”类问题 | 在官方文档中验证可行性 |
| 未知错误 | 参考官方故障排除指南 |
| 新特性使用 | 获取最新代码示例 |
Search Strategy
搜索策略
undefinedundefinedOfficial documentation search
官方文档搜索
WebSearch: "feature or API name site:creators.vrchat.com"
WebSearch: "feature or API name site:creators.vrchat.com"
UdonSharp API reference
UdonSharp API参考
WebSearch: "API name site:udonsharp.docs.vrchat.com"
WebSearch: "API name site:udonsharp.docs.vrchat.com"
Error investigation: VRChat official forums
错误排查：VRChat官方论坛
WebSearch: "error message site:ask.vrchat.com"
WebSearch: "error message site:ask.vrchat.com"
Error investigation: Canny (bug reports / known issues)
错误排查：Canny（bug报告/已知问题）
WebSearch: "error message site:feedback.vrchat.com"
WebSearch: "error message site:feedback.vrchat.com"
Error investigation: GitHub Issues
错误排查：GitHub Issues
WebSearch: "error message UdonSharp site:github.com"
undefinedWebSearch: "error message UdonSharp site:github.com"
undefinedOfficial Resources
官方资源
| Resource | URL | Contents |
|---|---|---|
| VRChat Creators | creators.vrchat.com/worlds/udon/ | Official Udon / SDK documentation |
| UdonSharp Docs | udonsharp.docs.vrchat.com | UdonSharp API reference |
| VRChat Forums | ask.vrchat.com | Q&A, solutions |
| VRChat Canny | feedback.vrchat.com | Bug reports, known issues |
| GitHub | github.com/vrchat-community | Samples and libraries |
| 资源 | URL | 内容 |
|---|---|---|
| VRChat创作者平台 | creators.vrchat.com/worlds/udon/ | 官方Udon/SDK文档 |
| UdonSharp文档 | udonsharp.docs.vrchat.com | UdonSharp API参考 |
| VRChat论坛 | ask.vrchat.com | 问答、解决方案 |
| VRChat Canny | feedback.vrchat.com | Bug报告、已知问题 |
| GitHub | github.com/vrchat-community | 示例与库 |
References
参考资料
| File | Contents | Search Hints |
|---|---|---|
| C# feature availability in UdonSharp; blocked features; syncable types; attributes | List, async, try/catch, LINQ, generics, DataList, DataDictionary |
| Ownership model, sync modes, RequestSerialization, NetworkCallable, network events, data limits | UdonSynced, SetOwner, BehaviourSyncMode, FieldChangeCallback, OnDeserialization, master leave, ownership cascade |
| Bandwidth throttling, bit packing, synced data size examples, debugging, owner-centric architecture | IsClogged, bandwidth, throttle, bit packing, data budget, IsMaster |
| 6 anti-patterns to avoid; 5 advanced sync patterns with template links | anti-pattern, race condition, ownership fight, late-joiner, PackedStateSync, BatchedSync |
| PlayerData/PlayerObject API (SDK 3.7.4+); per-player save data | PlayerData, PlayerObject, OnPlayerRestored, SetInt, TryGetInt |
| PhysBones, Contacts, VRC Constraints (SDK 3.10.0+) | PhysBone, ContactReceiver, ContactSender, VRCConstraint, OnContactEnter |
| Initialization, interaction, player detection, timer, audio, pickup, animation, UI, teleportation, lazy init guard | Interact, OnEnable, Initialize, AudioSource, VRCPickup, Animator, UI, TeleportTo |
| Object pooling, NetworkCallable patterns, persistence integration, dynamics integration, synced game state, delayed event debounce | pool, MasterManagedPlayerPool, NetworkCallable, DamageReceiver, game state, debounce, state machine |
| Partial class pattern, update handler, PostLateUpdate, spatial query, platform optimization | Update, PostLateUpdate, Bounds, AnimatorHash, performance, mobile, PC |
| Array helpers (List alternatives), event bus, GameObject relay communication | ArrayUtils, EventBus, relay, subscriber, FindIndex, ShuffleArray |
| String/Image downloading, VRCJson, Trusted URLs | VRCStringDownloader, VRCImageDownloader, VRCJson, DataDictionary, VRCUrl |
| VRCPlayerApi, Networking, enums reference | GetPlayers, playerId, isMaster, isLocal, GetPosition, SetVelocity, Drone, VRCDroneApi |
| All Udon events (including OnPlayerRestored, OnContactEnter) | OnPlayerJoined, OnPlayerLeft, OnPlayerTriggerEnter, OnOwnershipTransferred |
| Editor scripting and proxy system | UdonSharpEditor, UdonSharpBehaviourProxy, SerializedObject |
| Sync pattern examples (Local/Events/SyncedVars) | Continuous, Manual, NoVariableSync, sync example |
| Common errors and solutions | NullReference, compile error, sync not working, FieldChangeCallback |
| SDK migration guide (3.7 to 3.10), version-by-version changes and checklists | migration, deprecated, upgrade, 3.7, 3.8, 3.9, 3.10 |
| 文件 | 内容 | 搜索提示 |
|---|---|---|
| UdonSharp中C#特性的可用性；禁用特性；可同步类型；属性 | List, async, try/catch, LINQ, 泛型, DataList, DataDictionary |
| 所有权模型、同步模式、RequestSerialization、NetworkCallable、网络事件、数据限制 | UdonSynced, SetOwner, BehaviourSyncMode, FieldChangeCallback, OnDeserialization, 主机离开, 所有权传递 |
| 带宽限制、位打包、同步数据大小示例、调试、以所有者为中心的架构 | IsClogged, bandwidth, throttle, bit packing, data budget, IsMaster |
| 需避免的6种反模式；5种高级同步模式及模板链接 | anti-pattern, 竞态条件, 所有权争夺, 迟加入玩家, PackedStateSync, BatchedSync |
| PlayerData/PlayerObject API（SDK 3.7.4+）；每个玩家的保存数据 | PlayerData, PlayerObject, OnPlayerRestored, SetInt, TryGetInt |
| PhysBones、Contacts、VRC Constraints（SDK 3.10.0+） | PhysBone, ContactReceiver, ContactSender, VRCConstraint, OnContactEnter |
| 初始化、交互、玩家检测、计时器、音频、拾取、动画、UI、传送、延迟初始化守卫 | Interact, OnEnable, Initialize, AudioSource, VRCPickup, Animator, UI, TeleportTo |
| 对象池、NetworkCallable模式、持久化集成、动力学集成、同步游戏状态、延迟事件防抖 | pool, MasterManagedPlayerPool, NetworkCallable, DamageReceiver, game state, debounce, state machine |
| 分部类模式、更新处理器、PostLateUpdate、空间查询、平台优化 | Update, PostLateUpdate, Bounds, AnimatorHash, performance, mobile, PC |
| 数组助手（List<T>替代方案）、事件总线、GameObject中继通信 | ArrayUtils, EventBus, relay, subscriber, FindIndex, ShuffleArray |
| 字符串/图片下载、VRCJson、可信URL | VRCStringDownloader, VRCImageDownloader, VRCJson, DataDictionary, VRCUrl |
| VRCPlayerApi、Networking、枚举参考 | GetPlayers, playerId, isMaster, isLocal, GetPosition, SetVelocity, Drone, VRCDroneApi |
| 所有Udon事件（包括OnPlayerRestored、OnContactEnter） | OnPlayerJoined, OnPlayerLeft, OnPlayerTriggerEnter, OnOwnershipTransferred |
| 编辑器脚本与代理系统 | UdonSharpEditor, UdonSharpBehaviourProxy, SerializedObject |
| 同步模式示例（本地/事件/同步变量） | Continuous, Manual, NoVariableSync, sync example |
| 常见错误与解决方案 | NullReference, compile error, sync not working, FieldChangeCallback |
| SDK迁移指南（3.7至3.10）；版本间变更与检查清单 | migration, deprecated, upgrade, 3.7, 3.8, 3.9, 3.10 |
Templates (assets/templates/
)
assets/templates/模板（assets/templates/
）
assets/templates/| Template | Purpose |
|---|---|
| Interactive object with |
| Network-synced object (Manual sync, ownership guard, late-joiner init flag) |
| Per-player movement settings (walk/run/jump speed) |
| State machine with synced state and transitions |
| PlayerData save/load with OnPlayerRestored (SDK 3.7.4+) |
| Contact receiver for world-side collision detection (SDK 3.10.0+) |
| Custom editor inspector with UdonSharpEditor |
| Master-managed player object pool; FIFO ring buffer; OnPlayerJoined/Left; VerifyAssignments after master handoff |
| Subscriber list event bus (max 32 listeners); RegisterListener/UnregisterListener/RaiseEvent; in-place compaction |
| List<T> alternatives: Add, Contains, AddUnique, Remove, RemoveAt, Insert for GameObject[]; FindIndex/ShuffleArray for int[] |
| History/undo sync with byte[] state history; NetworkCallable OwnerProcessMove/OwnerUndo/OwnerReset |
| Pack 3 ints into one Vector3 UdonSynced field; OnPreSerialization/OnDeserialization |
| 0.15s sync cooldown with _syncLocked/_changeCounter; _OnSyncUnlock callback |
| Local + synced copy with _dirty flag; strict OnPreSerialization/OnDeserialization separation |
| Idempotent ScheduleBatchedSync with 0.2s BatchDelay; _FlushBatch delayed callback |
| Networking.IsClogged check; linear back-off (RetryDelay * retryCount); MaxRetries=5 |
| 模板 | 用途 |
|---|---|
| 带有 |
| 网络同步对象（手动同步、所有权守卫、迟加入玩家初始化标记） |
| 每个玩家的移动设置（行走/奔跑/跳跃速度） |
| 带有同步状态与转换的状态机 |
| 基于OnPlayerRestored的PlayerData保存/加载（SDK 3.7.4+） |
| 用于世界端碰撞检测的Contact接收器（SDK 3.10.0+） |
| 带有UdonSharpEditor的自定义编辑器检视面板 |
| 主机管理的玩家对象池；FIFO环形缓冲区；OnPlayerJoined/Left；主机切换后验证分配 |
| 订阅者列表事件总线（最多32个监听器）；RegisterListener/UnregisterListener/RaiseEvent；原地压缩 |
| List<T>替代方案：GameObject[]的Add、Contains、AddUnique、Remove、RemoveAt、Insert；int[]的FindIndex/ShuffleArray |
| 基于byte[]状态历史的历史记录/撤销同步；NetworkCallable的OwnerProcessMove/OwnerUndo/OwnerReset |
| 将3个整数打包到一个Vector3类型的UdonSynced字段中；OnPreSerialization/OnDeserialization |
| 0.15秒同步冷却，带有_syncLocked/_changeCounter；_OnSyncUnlock回调 |
| 本地+同步副本，带有_dirty标记；严格分离OnPreSerialization/OnDeserialization |
| 幂等的ScheduleBatchedSync，带有0.2秒BatchDelay；_FlushBatch延迟回调 |
| Networking.IsClogged检查；线性退避（RetryDelay * retryCount）；MaxRetries=5 |
Hooks
钩子
| Hook | Platform | Purpose |
|---|---|---|
| Windows (PowerShell) | PostToolUse constraint validation |
| Linux/macOS (Bash) | PostToolUse constraint validation |
| 钩子 | 平台 | 用途 |
|---|---|---|
| Windows（PowerShell） | 工具使用后的约束验证 |
| Linux/macOS（Bash） | 工具使用后的约束验证 |
Quick Reference
快速参考
- - One-page quick reference
CHEATSHEET.md
- - 单页快速参考手册
CHEATSHEET.md