/unity-vrc-udon-sharp

name: unity-vrc-udon-sharp
description: >-
    UdonSharp scripting skill for SDK 3.7.1-3.10.4. Use when writing,
    reviewing, debugging, or migrating UdonSharp C# and UdonBehaviour code.
    Positive triggers include UdonSharp, NetworkCallable, NetworkCalling,
    CallingPlayer, Udon network authorization, synced runtime state, a local public helper,
    public-method audit, and C# to Udon conversion. VRCTween calls,
    PhysBone/Contact callbacks, world VRCPhysBoneCollider runtime access,
    persistence, collection, web, and other component APIs trigger this skill
    when the request is about Udon, C#, or runtime API access. Excludes
    scene setup, component setup, Build Panel work, layers, optimization, and
    upload; route those requests to unity-vrc-world-sdk-3.
license: MIT
metadata:
    author: niaka3dayo
    version: "3.0.1"
    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](references/patterns-performance.md#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.

| # | NEVER do this | Why it fails silently | Use instead | |---|---------------|----------------------|-------------| | 1 | Use `List<T>`, `Dictionary<T,K>`, or any generic collection | Compile error — blocked by Udon compiler | `T[]` arrays, `DataList`, `DataDictionary` (`DataDictionary.EnsureCapacity` / custom capacities require SDK 3.10.4+) | | 2 | Use `async`/`await`, `System.Threading`, or coroutines | Udon is single-threaded; these features do not exist | `SendCustomEventDelayedSeconds()` | | 3 | Modify `[UdonSynced]` fields without owning the object | Change appears local but is **silently reverted** on next deserialization | `Networking.SetOwner()` before modify, then `RequestSerialization()` | | 4 | Forget `RequestSerialization()` after modifying synced fiel