unity-vrc-udon-sharp

name: unity-vrc-udon-sharp description: > UdonSharp (C# to Udon Assembly) scripting skill for VRChat world development. Use this skill when writing, reviewing, or debugging UdonSharp C# code. Covers compile constraints (List/async/await/try/catch/LINQ blocked), network sync (UdonSynced, RequestSerialization, FieldChangeCallback, NetworkCallable), persistence (PlayerData/PlayerObject), Dynamics (PhysBones, Contacts, VRCTween, VRCPhysBoneCollider Udon access), Web Loading, DataList/DataDictionary capacity APIs, VRAM management (texture lifecycle, Dispose vs Destroy), asmdef / Assembly Definition / U# Assembly Definition guidance, VPM package workflow boundaries, Auto Referenced tradeoffs, and event handling. SDK 3.7.1 - 3.10.4 coverage. Triggers on: UdonSharp, Udon, VRC SDK, UdonBehaviour, UdonSynced, NetworkCallable, VRCPlayerApi, SendCustomEvent, PlayerData, PhysBones, VRCTween, Box Contacts, Global Avatar PhysBone Colliders, VRCPhysBoneCollider, DataList capacity, DataDictionary EnsureCapacity, synced variables, asmdef, Assembly Definition, U# Assembly Definition, VPM package, Auto Referenced, VRChat world scripting, C# to Udon. license: MIT metadata: author: niaka3dayo version: "2.5.2" tags: vrchat, udonsharp, udon, networking, sync, persistence, dynamics, asmdef, vpm, assembly-definition

UdonSharp Skill

Why This Skill Matters

UdonSharp looks like regular Unity C# scripting — until you hit its hidden walls. Many standard C# features (List<T>, async/await, try/catch, 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 RequestSerialization 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.

Every rule in this skill exists because UdonSharp's default behavior is to fail silently. Read the Rules before generating any code.

Before Writing Network Code

Four architectural decisions that must be made before choosing sync modes or writing any synced variable. Changing them mid-implementation typically requires a full rewrite:

• Who owns this state? One owner writes; all others read. If two players can both write (e.g., a shared toggle), you need an ownership transfer protocol — writes without ownership are silently discarded.
• When does ownership transfer? On grab? Interact? Game event? OnPlayerLeft? Networking.SetOwner is locally immediate on the calling client — Networking.IsOwner(gameObject) is true synchronously after the call, and writing [UdonSynced] fields plus RequestSerialization() immediately afterwards is safe under an IsOwner guard. Concurrent SetOwner calls from multiple clients are resolved by network arrival order — there is no client-side arbitration, so accept that the loser's write is overwritten.
• What do late joiners see? State set only by one-time events (SendCustomNetworkEvent) is invisible to late joiners. Late-joiner-visible state must live in [UdonSynced] variables, which are delivered automatically via OnDeserialization; no manual RequestSerialization() on join is needed.
• What if the owner leaves mid-session? VRChat automatically transfers ownership to a remaining player (selection rule is not publicly documented), and OnOwnershipTransferred fires on all clients. Synced variables are preserved, so state is not frozen; decide upfront whether to keep the current value, reset to a known default, or re-apply/re-broadcast derived state in OnOwnershipTransferred.

Context Preservation

For complex synced systems, ownership-sensitive refactors, or work resumed after compaction/handoff, consider loading references/context-preservation.md. It provides a lightweight task-context note for source of truth, transport, sync mode, storage, ownership, late-joiner behavior, and validation rationale. This is optional guidance for complex work, not a step for small mechanical edits. Keep private data and raw transcripts out of any note.

For VRChat SDK Build Panel validation alerts, red/yellow/white warnings, or Auto Fix side effects that involve world scene setup rather than UdonSharp compiler constraints, use unity-vrc-world-sdk-3 and read references/build-validation.md.

Core Principles

1. Constraints First — Assume standard C# features are blocked until verified. Check udonsharp-constraints.md before using any API.
2. Ownership Before Mutation — Only the owner of an object can modify its synced variables. Always SetOwner → modify → RequestSerialization.
3. Late Joiner Correctness — State must be correct for players who join after events have occurred. Design for re-serialization, not just live updates.
4. Sync Minimization — Every synced variable costs bandwidth (see data budget in udonsharp-sync-selection.md). Derive what you can locally; sync only the source of truth.
5. Event-Driven, Not Polling — Use OnDeserialization, [FieldChangeCallback], and SendCustomEvent instead of checking state in Update() for state-change reactions; for hot-path or periodic work, see Event Dispatch & Cross-Behaviour Call Cost Tiers.

Common Mistakes (NEVER List)

These constraints cause either compile-time failures or silent runtime failures. Check this list before writing any UdonSharp code.

Sync Mode Quick Decision

Changing every frame (position, rotation)?    -> Continuous sync
Changing on user action (toggle, score)?      -> Manual sync + RequestSerialization()
No sync needed (local UI, effects)?           -> NoVariableSync
Need reliable one-shot calls with params?     -> [NetworkCallable] (SDK 3.8.1+)
Temporary effect for all players, no state?   -> SendCustomNetworkEvent (no synced vars)

For detailed decision trees, data budget, and minimization principles, see rules/udonsharp-sync-selection.md.

Sync Debugging Quick Decision

When sync "looks correct locally but doesn't work for others":

Remote players don't see my state change?
  ├── Did I call RequestSerialization() after writing? (Manual sync) → Add it
  ├── Does the local player own the object?                          → Networking.SetOwner() first
  └── Using Continuous sync for button/toggle state?                → Switch to Manual + RequestSerialization()

RequestSerialization() called but still not syncing?
  ├── Is Networking.IsClogged == true?           → Throttle; retry after delay
  └── Non-owner writing the field?               → Acquire ownership first — a non-owner RequestSerialization() is a silent no-op (see NEVER #12)

Late joiners don't see current state?
  ├── State set only on event (e.g., player trigger)?  → Verify the state lives in a [UdonSynced] field — synced values are delivered to late joiners automatically; SendCustomNetworkEvent calls before join are never replayed
  └── Using SendCustomNetworkEvent for persistent state? → Use [UdonSynced] variables instead

OnOwnershipTransferred not firing on a remote client?
  └── On the caller, the callback fires synchronously inside SetOwner — confirm the calling client called Networking.SetOwner(LocalPlayer, gameObject), and that remote clients resolve the same gameObject reference (scene path or prefab GUID)

Reference Loading Guide

Load only what you need. Over-loading wastes tokens; under-loading causes critical mistakes.

Pattern Selection Guide

Six pattern files cover different domains. Use this quick routing to pick the right one:

Building a UI, menu, or HUD?           -> patterns-ui.md
VR finger/touch interaction on Canvas? -> patterns-ui.md
Modular app with multiple screens?     -> patterns-ui.md
Syncing state across players?           -> patterns-networking.md
Multiple identical rooms from one model? -> patterns-networking.md (distant-room)
Optimizing Update() or heavy loops?     -> patterns-performance.md
Heavy rebuild, replay, or reset/cancel?  -> patterns-performance.md
Playing or streaming video?             -> patterns-video.md
Need array helpers, event bus, or       -> patterns-utilities.md
  pseudo-delegates?
Basic interactions, timers, audio,      -> patterns-core.md
  pickups, or teleportation?
Station + trigger zone detection?       -> troubleshooting.md

Multiple concerns? Load the primary pattern file plus its dependencies. For example, a synced video player needs both patterns-video.md and patterns-networking.md.

Template Selection Guide

17 templates cover common starting points. Pick the closest match and adapt:

Multiple needs? Start with the template closest to your primary concern, then pull patterns from others. For example, a synced game with undo needs UndoableGameManager.cs as the base plus patterns from RateLimitedSync.cs for throttling.

Rules (Constraints & Networking)

Compile constraints and networking rules are defined in always-loaded Rules:

After installation, place these in the agent's rules directory for automatic loading.

SDK Versions

Note: SDK versions below 3.9.0 are deprecated as of December 2, 2025. New world uploads are no longer possible.

Official Resources

References

Templates (assets/templates/)

Hooks

Quick Reference

• CHEATSHEET.md - One-page quick reference