/unity-vrc-udon-sharp

name: unity-vrc-udon-sharp
description: >-
    Rules and references for VRChat UdonSharp on SDK 3.10.6, the active and verified target.
    UdonSharp compiles only a subset of C#, and its networking fails without an error, so load
    this skill before writing, reviewing, debugging, or migrating any UdonSharp or UdonBehaviour
    code, even a short script. Covers synced runtime state and ownership, NetworkCallable events,
    NetworkCalling.CallingPlayer and Udon network authorization, a local public helper or
    public-method audit, C# to Udon conversion, persistence, data containers, web loading,
    UdonSharp Assembly Version Defines, and runtime API access from Udon such as VRCTween calls,
    VRCQualitySettings, VRCBillboard, constraint source methods, PhysBone/Contact callbacks, and
    world VRCPhysBoneCollider runtime access. Not for scene setup, component setup, Build Panel
    work, layers, scene and rendering optimization, or upload; use unity-vrc-world-sdk-3 for those.
license: MIT
metadata:
    author: niaka3dayo
    version: "4.3.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 rule sheets in `rules/` before generating any code (see [Rules](#rules-read-before-generating-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`.

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. If the local player is not the owner, `SetOwner` first; then modify → `RequestSerialization` (Manual sync). 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 revision without the side effect, but run durable `ApplyValues()` before the baseline check; only later revisions should trigger the one-shot. Revision is not ordering or stale-packet protection.

Common Mistakes (NEVER List)

These Udon runtime and Unity serialization constraints cause either **compile-time failures** or **silent data errors**. Check this list before writing UdonSharp code or serialized initial values.

| # | NEVER do this | Why it fails silently | Use in