unity-vrc-udon-sharp

name	unity-vrc-udon-sharp
description	UdonSharp scripting skill for VRChat SDK 3.10.4 (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, 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":"4.0.0","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.

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.

SDK 3.10.4 event receiver arguments

SDK 3.10.4 is the active and verified target for this Skill. SDK 3.10.4: UdonSharpBehaviour implements IUdonEventReceiver directly. An API that requires a receiver can therefore receive this directly:

VRCStringDownloader.LoadUrl(dataUrl, this);

The receiver argument is still required; only the explicit (IUdonEventReceiver) cast is unnecessary on the active SDK. Keep any pre-3.10.4 cast in the historical migration reference only. This follows the official SDK 3.10.4 release notes and the SDK source declaration.

Public fields: Inspector visibility is not persistence policy

[HideInInspector] only hides a public field from the Inspector; Unity still serializes it. Use [HideInInspector] public when Editor-time DI, baking, or autowiring must persist the value into a Scene/Prefab. Use [System.NonSerialized] public for a runtime-only value that another UdonBehaviour must access through direct access or SetProgramVariable. When [HideInInspector] is intentional, leave a comment explaining why the value must be persisted.

Editor-evaluated field initializers

Field initializers are evaluated as ordinary C# on the Unity/Editor side to produce initial data for the compiled Udon program; their expressions do not run in the Udon runtime. A Random.Range call in an initializer is evaluated in the Editor and stored as a baked default, not runtime randomness. LINQ, lambdas, or a same-behaviour static helper that uses List<T> can therefore generate an array initializer even though the same code is unavailable from Start(), Interact(), or another Udon runtime method. The final field type and value must be supported by Udon. Keep generation independent of scene, player, and runtime state, and do not call main-thread-only Unity APIs because field initializers and constructors can run on a loading thread. See references/constraints.md for both supported forms and their boundaries.

Use Start() or a lazy-init guard only for local or per-client randomness. For shared per-object or per-session seed/state, the owner generates it and stores it in a [UdonSynced] field; with Manual sync, establish ownership before writing and then call RequestSerialization(). Receivers may apply derived state in OnDeserialization() when needed, but that callback is not required for the field synchronization itself, and late joiners receive the current synced state.

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 instead
1	Use List<T>, Dictionary<T,K>, or any generic collection in Udon runtime code	Compile error — blocked by Udon compiler	T[] arrays, DataList, DataDictionary (DataDictionary.EnsureCapacity / custom capacities require SDK 3.10.4+); Editor-evaluated field generation is the limited exception above
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 fields (Manual sync)	State changes never leave the local client — no error, no warning	Always call RequestSerialization() after modifying [UdonSynced] fields
5	Use try/catch/finally/throw	Compile error — exception handling is blocked	Defensive null checks + early return
6	Access Networking.LocalPlayer in field initializers	Editor-side initial value generation has no player or Udon runtime state	Initialize in Start() or use lazy-init guard
7	Use static fields for per-instance state	Static fields are shared across all instances on the same client and are not synced	Instance fields with [UdonSynced] if sync is needed
8	Call RequestSerialization() every frame in Manual sync	Floods the ~11 KB/s network budget, causing congestion for the entire world

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] (introduced in SDK 3.8.1; active target 3.10.4)
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.

SDKs before 3.8.1 do not define the NetworkCallable attribute or parameterized network-event API, so code that uses them normally fails to compile.

A [NetworkCallable] method must return void.

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.

Task	MANDATORY READ	Optional	Do NOT Load
Writing networking/sync code	networking.md, networking-antipatterns.md	networking-bandwidth.md, sync-examples.md	dynamics.md, web-loading.md, image-loading-vram.md
Building UI/menus	patterns-ui.md, events.md	patterns-core.md, api.md	networking-bandwidth.md, dynamics.md, web-loading.md
Implementing persistence (save/load)	persistence.md	patterns-networking.md, events.md	dynamics.md, web-loading.md, image-loading-vram.md
Downloading strings/images from web	web-loading.md	web-loading-advanced.md, image-loading-vram.md	dynamics.md, persistence.md, networking-bandwidth.md
Using VRCTween, cancelable delayed calls, or tween cleanup	vrctween.md	patterns-utilities.md, api.md	dynamics.md, web-loading.md, persistence.md
Using PhysBones/Contacts/Constraints, Box Contacts, Global Avatar PhysBone Colliders, or world VRCPhysBoneCollider Udon access	dynamics.md, events.md	patterns-networking.md, api.md	web-loading.md, image-loading-vram.md, persistence.md
Tuning DataList/DataDictionary capacity or using DataDictionary.EnsureCapacity	api.md

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:

Starting Point	Template	Key Feature
Interaction & Objects
Interactive object (click/use)	BasicInteraction.cs	Cooldown, toggle, audio feedback
Synced toggle / shared object	SyncedObject.cs	Ownership guard, FieldChangeCallback, late-joiner init
Per-player movement settings	PlayerSettings.cs	Walk/run/jump speed via trigger zone
Contact-based collision detection	ContactReceiver.cs	OnContactEnter/Exit, avatar vs world, debounce (introduced in SDK 3.10.0; active target 3.10.4)
State & Game Logic
State machine / game flow	StateMachine.cs	Timed transitions, synced state, late-joiner safety
Game with undo/history	UndoableGameManager.cs	byte[] history, NetworkCallable _OwnerProcessMove/_OwnerUndo/_OwnerReset
Object pool (player slots)	MasterManagedPlayerPool.cs	FIFO ring buffer, master-managed, OnPlayerJoined/Left
Persistence & Data
Save/load player data	DataPersistence.cs	PlayerData API, OnPlayerRestored, auto-save (introduced in SDK 3.7.4; active target 3.10.4)
Networking Patterns
Rate-limited sync (slider drag)	RateLimitedSync.cs	0.15s cooldown, last-write-wins
Batched sync (rapid events)	BatchedSync.cs	Idempotent schedule, 0.2s delay, single packet
Congestion-aware retry	CloggedRetrySync.cs	IsClogged check, linear back-off, MaxRetries
Dual local+synced copy	DualCopySync.cs	Local working copy + synced transport, dirty flag

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:

Rule File	Contents
rules/udonsharp-constraints.md	Blocked features, code generation rules, attributes, syncable types
rules/udonsharp-networking.md	Ownership, sync modes, RequestSerialization, NetworkCallable, network-event sender authorization
rules/udonsharp-sync-selection.md	Sync pattern selection, data budget, minimization principles

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

SDK Versions

Active support / last verified: SDK 3.10.4

From v4.0.0 onward, the policy is latest stable SDK only; support moves to a new stable release only after this repository verifies it. A new stable release is not supported automatically. Current last verified target: 3.10.4.

The table below keeps feature-introduction history for migration reference. SDK 3.7.1-3.10.3 entries are historical information only; they are not active support or validation targets for this Skill. This is the Skill's support boundary, not a statement about VRChat's own SDK policy. Primary generated examples target SDK 3.10.4 unless a reference explicitly marks a historical migration case.

SDK Version	Key Features	Status
3.7.1	Added StringBuilder, RegularExpressions, System.Random	Historical
3.7.4	Added Persistence API (PlayerData/PlayerObject)	Historical
3.7.6	Multi-platform Build & Publish (PC + Android simultaneously)	Historical
3.8.0	PhysBone dependency sorting, Drone API (VRCDroneInteractable)	Historical
3.8.1	[NetworkCallable] attribute, parameterized network events, NetworkCalling.CallingPlayer/.InNetworkCall, NetworkEventTarget.Others/.Self	Historical
3.9.0	Camera Dolly API, Auto Hold pickup simplification	Historical
3.10.0	VRChat Dynamics for Worlds (PhysBones, Contacts, VRC Constraints)	Historical
3.10.1	Bug fixes and stability improvements	Historical
3.10.2	EventTiming extensions, PhysBones fixes, shader time globals	Historical
3.10.3	VRCPlayerApi.isVRCPlus, VRCRaycast (avatar), Mirror render-order fix	Historical
3.10.4	VRCTween, Box-shaped Contacts, Global Avatar PhysBone Colliders, world VRCPhysBoneCollider Udon access, DataList/DataDictionary custom capacity, DataDictionary.EnsureCapacity, UdonSharpBehaviour implements IUdonEventReceiver and accepts direct receiver this	Active / Last verified

Use SDK 3.10.4 for publishing. Check the matching release notes before relying on a version-specific API or migration step.

Official 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

References

File	Contents	Search Hints
constraints.md	C# feature availability in UdonSharp; blocked features; syncable types; attributes; DataList vs array decision guidance; DataList/DataDictionary capacity APIs; advanced workarounds (object array pseudo-struct); synced VRCUrl lists	List, async, try/catch, LINQ, generics, DataList, DataDictionary, DataList capacity, DataDictionary capacity, EnsureCapacity, DataList vs array, when to use DataList, VRCUrl array, VRCUrl sync, pseudo-struct, object array cast, multi-field state container
networking.md	Ownership model, sync modes, RequestSerialization, NetworkCallable, network-event sender authorization, data limits	UdonSynced, SetOwner, BehaviourSyncMode, FieldChangeCallback, OnDeserialization, NetworkCalling, CallingPlayer, InNetworkCall, legacy event, underscore, authorization, master leave, ownership cascade
networking-bandwidth.md	Bandwidth throttling, bit packing, synced data size examples, debugging, owner-centric architecture	IsClogged, bandwidth, throttle, bit packing, data budget, IsMaster
networking-antipatterns.md	6 anti-patterns to avoid; 5 advanced sync patterns with template links	anti-pattern, race condition, ownership fight, late-joiner, PackedStateSync, BatchedSync
persistence.md	Storage layer decision tree (local/synced/PlayerData/PlayerObject); PlayerData/PlayerObject API (introduced in SDK 3.7.4; active target 3.10.4); per-player save data; storage usage query API (introduced in SDK 3.10.0; active target 3.10.4)	storage layer, decision tree, local variable, PlayerData, PlayerObject, OnPlayerRestored, SetInt, TryGetInt, GetPlayerDataStorageUsage, GetPlayerDataStorageLimit, GetPlayerObjectStorageUsage, GetPlayerObjectStorageLimit, RequestStorageUsageUpdate, OnPersistenceUsageUpdated, storage quota, storage usage, which storage, when to use PlayerData
dynamics.md	PhysBones, Contacts, VRC Constraints (introduced in SDK 3.10.0; active target 3.10.4); VRCTween, Box-shaped Contacts, Global Avatar PhysBone Colliders, world VRCPhysBoneCollider Udon access (SDK 3.10.4+)	PhysBone, ContactReceiver, ContactSender, Box Contact, Global Avatar PhysBone Collider, VRCPhysBoneCollider, VRCTween, VRCConstraint, OnContactEnter
patterns-core.md	Initialization, interaction, player detection, timer, audio, pickup, animation, UI, teleportation, lazy init guard, remote players

Templates (assets/templates/)

Template	Purpose
BasicInteraction.cs	Interactive object with Interact() handler
SyncedObject.cs	Network-synced object (Manual sync, ownership guard, late-joiner init flag)
PlayerSettings.cs	Per-player movement settings (walk/run/jump speed)
StateMachine.cs	State machine with synced state and transitions
DataPersistence.cs	PlayerData save/load with OnPlayerRestored (introduced in SDK 3.7.4; active target 3.10.4)
ContactReceiver.cs	Contact receiver for world-side collision detection (introduced in SDK 3.10.0; active target 3.10.4)
CustomInspector.cs	Custom editor inspector with UdonSharpEditor
MasterManagedPlayerPool.cs	Master-managed player object pool for non-security session arbitration; FIFO ring buffer; OnPlayerJoined/Left; _VerifyAssignments after master handoff
EventBus.cs	Subscriber list event bus (max 32 listeners); RegisterListener/UnregisterListener/RaiseEvent; in-place compaction
ArrayUtils.cs	List<T> alternatives: Add, Contains, AddUnique, Remove, RemoveAt, Insert for GameObject[]; FindIndex/ShuffleArray for int[]
UndoableGameManager.cs	History/undo sync with byte[] state history; NetworkCallable _OwnerProcessMove/_OwnerUndo/_OwnerReset
PackedStateSync.cs	Pack 3 ints into one Vector3 UdonSynced field; OnPreSerialization/OnDeserialization
RateLimitedSync.cs	0.15s sync cooldown with _syncLocked/_changeCounter; _OnSyncUnlock callback
DualCopySync.cs	Local + synced copy with _dirty flag; strict OnPreSerialization/OnDeserialization separation
BatchedSync.cs	Idempotent ScheduleBatchedSync with 0.2s BatchDelay; _FlushBatch delayed callback

Hooks

Hook	Platform	Purpose
validate-udonsharp.ps1	Windows (PowerShell)	PostToolUse constraint validation
validate-udonsharp.sh	Linux/macOS (Bash)	PostToolUse constraint validation

The Bash validator requires jq. If it is unavailable, the hook passes its input through unchanged and emits VALIDATOR-WARNING: validation skipped (JQ_UNAVAILABLE) instead of silently reporting successful validation.

Quick Reference

• CHEATSHEET.md - One-page quick reference