/unity-vrc-udon-sharp

name: unity-vrc-udon-sharp
description: >-
    UdonSharp scripting skill for VRChat SDK 3.10.5 (active and verified target). 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, C# to Udon conversion, and UdonSharp Assembly Version Defines.
    VRCQualitySettings and 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: "4.1.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 code that runs in the Udon runtime. Editor-evaluated field initializers are a separate context: they can use some ordinary C# features to generate a final value that Udon can hold. 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** — For Udon runtime code, assume standard C# features are blocked until verified. Treat Editor-evaluated field initializers separately and require a final Udon-supported value. 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)**.

**Synced arrays: always apply them from `OnDeserialization()`**. Array element changes do not provide a reliable `FieldChangeCallback` signal, and the same guidance applies to same-length changes, array reassignments, and length changes. Have the owner call the same idempotent apply method immediately after mutation, then request Manual serialization once. If a revision guard protects a historical one-shot side effect, a late joiner's first `OnDeserialization()` receives the current revision and may otherwise replay that effect. Baseline the first received rev