VRChat UdonSharp skills, rules, and validation hooks for correct code generation

GitHub stars
368

Install

/plugin install vrc-udon-skills@agent-skills-vrc-udon

Run it inside Claude Code after adding the marketplace with /plugin marketplace add niaka3dayo/agent-skills-vrc-udon.

Contents

Discovered from source

Skills 2

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).

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.

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 thisWhy it fails silentlyUse instead
1Use List<T>, Dictionary<T,K>, or any generic collection in Udon runtime codeCompile error — blocked by Udon compilerT[] arrays, DataList, DataDictionary (DataDictionary.EnsureCapacity / custom capacities require SDK 3.10.4+); Editor-evaluated field generation is the limited exception above
2Use async/await, System.Threading, or coroutinesUdon is single-threaded; these features do not existSendCustomEventDelayedSeconds()
3Modify [UdonSynced] fields without owning the objectChange appears local but is silently reverted on next deserializationNetworking.SetOwner() before modify, then RequestSerialization()
4Forget RequestSerialization() after modifying synced fields (Manual sync)State changes never leave the local client — no error, no warningAlways call RequestSerialization() after modifying [UdonSynced] fields
5Use try/catch/finally/throwCompile error — exception handling is blockedDefensive null checks + early return
6Access Networking.LocalPlayer in field initializersEditor-side initial value generation has no player or Udon runtime stateInitialize in Start() or use lazy-init guard
7Declare a non-const static field (static readonly included)UdonSharp compile error (Static fields are not yet supported on user defined types); Unity's own C# compilation passes, so only the UdonSharp compiler reports itInstance fields ([UdonSynced] if sync is needed), a parameter, or const; static methods are supported
8Call RequestSerialization() every frame in Manual syncFloods the ~11 KB/s network budget, causing congestion for the entire worldThrottle to 1-10 Hz with change detection; check Networking.IsClogged
9Use LINQ (.Where, .Select, etc.) or lambda expressions in Udon runtime codeCompile error — not supported by Udon compilerManual for loops with named methods; Editor-evaluated field generation is the limited exception above
10Use Button.onClick.AddListener()Not available in Udon — no runtime delegate supportConfigure SendCustomEvent via Inspector OnClick
11Mix Continuous and Manual sync concerns on one behaviourWastes bandwidth (discrete values in Continuous) or loses control (redundant RequestSerialization in Continuous)Separate behaviours: Continuous for position/rotation, Manual for discrete state
12Write to [UdonSynced] fields without an IsOwner guardNon-owner writes are purely local and silently reverted on the next deserialization from the actual ownerNetworking.SetOwner first if needed (locally immediate), then write under IsOwner and call RequestSerialization()
13Use [NetworkCallable] on an unsupported SDK below 3.8.1 (historical migration only)Compile error — the attribute and parameterized network-event API are unavailableUse the active SDK target; for historical migration notes, use synced variables and react in OnDeserialization/FieldChangeCallback instead of pairing them with a network event
14Use PhysBones/Contacts API (OnPhysBoneGrabbed, OnContactEnter, etc.) on an unsupported SDK below 3.10.0 (historical migration only)Compiles but silently ignored at runtime — world-side Dynamics did not exist pre-3.10.0, so callbacks never fireUse the active SDK target; for historical migration, verify the project is at least SDK 3.10.0
15Use PlayerData persistence API on an unsupported SDK below 3.7.4 (historical migration only)Compile error — missing symbol; PlayerData, PlayerObject, and OnPlayerRestored were added in 3.7.4 and are not in the Udon whitelist before thenUse the active SDK target; for historical migration, verify the project is at least SDK 3.7.4
16Put a Unity .asmdef around UdonSharpBehaviour without matching U# Assembly DefinitionUnity compiles the C# assembly, but UdonSharp reports the script does not belong to a U# assemblyFor simple world scripts, avoid asmdef; for package/asmdef workflows, create the corresponding U# Assembly Definition and set Source Assembly to the Unity .asmdef (see references/assembly-definitions.md)
17Create a .cs script without a corresponding .asset fileScript is not recognized as UdonBehaviour — "The associated script cannot be loaded", no Udon compilationEvery time a .cs is created: verify Assets/Editor/UdonSharpProgramAssetAutoGenerator.cs exists, install from references/editor-scripting.md if missing, notify the user (see Rule 8 in rules/udonsharp-constraints.md)
18Call Debug.Log() inside Update(), PostLateUpdate(), or any per-frame eventVRChat's client-side log rate limiter silently drops excess entries; the implicit string allocation every frame causes sustained GC pressure that tanks framerate. ClientSim and Unity Editor hide both symptomsGuard with if (debugMode && Time.frameCount % 60 == 0), or move all logging to event-driven callbacks
19Use [UdonSynced] on a GameObject, Transform, UdonBehaviour, or any component referenceOnly primitives, value types (Vector3, Quaternion, Color, etc.), string, VRCUrl, and simple arrays of these are syncable. Component references either fail at compile time or are silently never serialized depending on SDK versionSync a player ID (int) or scene object index (int) and resolve the actual reference locally on each client
20Initialize any UdonSharp VRCUrl field that needs an independent initial value with VRCUrl.EmptyVRCUrl.Empty is a shared instance, so Inspector data can leak between fields, array elements, or GameObjects that use the same UdonSharp programGive [SerializeField], [UdonSynced], and ordinary private fields—and each array element—their own new VRCUrl(""); reserve VRCUrl.Empty for runtime sentinel use
21Call GetSourceCount() / SetSourceWeight(), or edit a VRC constraint's Sources list directly from UdonThe two methods do not exist (compile error); VRChat reports reliability issues with direct Sources edits from UdonSourceCount and a GetSource() / SetSource() round trip, then ApplyConfigurationChanges() once (SDK 3.10.6+); see dynamics.md
22Leave a parameterless public method without a leading _ when only local code or an Inspector event calls itIt is a legacy network entry: any player can run it on other clients with SendCustomNetworkEvent, and nothing reports itPrefix local-only public methods with _; UI SendCustomEvent, delayed events, and cross-behaviour calls still reach them. Expose an intentional network entry with [NetworkCallable]; inside it, return unless NetworkCalling.InNetworkCall is true, then compare NetworkCalling.CallingPlayer with the player who is allowed to send it (see rules/udonsharp-networking.md)
23Look up a user layer (22-31) by the name set in Unity, as in LayerMask.NameToLayer("Projectiles") or LayerMask.GetMask(...)The VRChat client renames layers 22-31 to user0-user9, so in the client NameToLayer returns -1 and GetMask returns an empty mask (0), although both work in the editor and ClientSim; 1 << -1 then silently targets layer 31Use the layer number or a mask built from it; see references/layers.md in the unity-vrc-world-sdk-3 skill

Sync Mode Quick Decision

Changing every frame (position, rotation)?    -> Continuous sync
Changing on user action (toggle, score)?      -> Manual sync + RequestSerialization()
No sync, no network events (local UI, FX)?    -> None
Network events only, no synced variables?     -> Manual (Continuous if VRCObjectSync is on it)
Avoid NoVariableSync in new code               -> see references/networking.md
Need reliable one-shot calls with params?     -> [NetworkCallable] (introduced in 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.

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)

Field and Receiver Boundaries

Three places where UdonSharp differs from what the C# on the page suggests.

SDK 3.10.4 event receiver arguments

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.

Rules (Read Before Generating Code)

Three rule sheets hold the compact, checkable form of the constraints. They are not loaded automatically, so read the ones that apply:

Rule FileRead itContents
rules/udonsharp-constraints.mdBefore writing or reviewing any UdonSharp scriptBlocked features, code generation rules, attributes, syncable types
rules/udonsharp-networking.mdBefore code that syncs state or sends network eventsOwnership, sync modes, RequestSerialization, NetworkCallable, network-event sender authorization
rules/udonsharp-sync-selection.mdBefore choosing what to syncSync pattern selection, data budget, minimization principles

Reference Loading Guide

Load only what you need. Over-loading wastes tokens; under-loading causes critical mistakes. When a request spans several rows, load every MANDATORY READ those rows list; a Do NOT Load entry never overrides another matching row's MANDATORY READ.

Every reference starts with a table of contents. For an Optional reference, read the sections the task needs.

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.

TaskMANDATORY READOptionalDo NOT Load
Writing networking/sync codenetworking.md, networking-antipatterns.mdnetworking-bandwidth.md, sync-examples.mddynamics.md, web-loading.md, image-loading-vram.md
Building UI/menuspatterns-ui.md, events.mdpatterns-core.md, api.mdnetworking-bandwidth.md, dynamics.md, web-loading.md
Implementing persistence (save/load)persistence.mdpatterns-networking.md, events.mddynamics.md, web-loading.md, image-loading-vram.md
Downloading strings/images from webweb-loading.mdweb-loading-advanced.md, image-loading-vram.mddynamics.md, persistence.md, networking-bandwidth.md
Using VRCTween, cancelable delayed calls, or tween cleanupvrctween.mdpatterns-utilities.md, api.mddynamics.md, web-loading.md, persistence.md
Using PhysBones/Contacts/Constraints, Box Contacts, Global Avatar PhysBone Colliders, or world VRCPhysBoneCollider Udon accessdynamics.md, events.mdpatterns-networking.md, api.mdweb-loading.md, image-loading-vram.md, persistence.md
Reading/writing VRCQualitySettings at runtimeapi.mdevents.md; scene defaults: unity-vrc-world-sdk-3networking.md, dynamics.md, web-loading.md
Tuning DataList/DataDictionary capacity or using DataDictionary.EnsureCapacityapi.mdconstraints.md, patterns-utilities.md, web-loading.mddynamics.md, persistence.md, networking-bandwidth.md
Optimizing performance (Update loops, VRCBillboard)patterns-performance.mdpatterns-utilities.md, api.mddynamics.md, web-loading.md, persistence.md
Building a video playerpatterns-video.mdevents.md, web-loading.mddynamics.md, persistence.md, image-loading-vram.md
Debugging/troubleshootingtroubleshooting.mdconstraints.md, networking.md, testing.mdpatterns-*.md, dynamics.md, web-loading.md
Debugging ownership / sync conflictsnetworking.md, troubleshooting.mdnetworking-antipatterns.mddynamics.md, web-loading.md
Migrating between SDK versions / fixing post-upgrade breakagesdk-migration.mdtroubleshooting.md, networking.md, dynamics.mdweb-loading.md, image-loading-vram.md
Resuming complex work after compaction / handoff / ownership-sensitive multi-file refactorCurrent task's primary referencescontext-preservation.mdUnrelated domain references
Writing new UdonSharp scripts (not sure if sync needed)constraints.mdnetworking.mddynamics.md, web-loading.md, image-loading-vram.md
Setting up new script files (.cs/.asset wiring, program asset generation)editor-scripting.mdtroubleshooting.mdnetworking.md, dynamics.md
VPM/package/asmdef workflows, Assembly Version Defines, U# Assembly Definition wiring, Auto Referenced decisionsassembly-definitions.mdeditor-scripting.md, troubleshooting.mdnetworking.md, dynamics.md, web-loading.md
Building editor setup tools / placement UX (custom inspectors, scene wiring helpers, IEditorOnly)editor-scripting.mdconstraints.md, assembly-definitions.mdnetworking.md, dynamics.md, web-loading.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 in assets/templates/ cover common starting points. Pick the closest match and adapt:

Starting PointTemplateKey Feature
Interaction & Objects
Interactive object (click/use)BasicInteraction.csCooldown, toggle, audio feedback
Synced toggle / shared objectSyncedObject.csManual sync, ownership guard, FieldChangeCallback, late-joiner init flag
Per-player movement settingsPlayerSettings.csWalk/run/jump speed via trigger zone
Contact-based collision detectionContactReceiver.csOnContactEnter/Exit, avatar vs world, debounce (introduced in SDK 3.10.0)
State & Game Logic
State machine / game flowStateMachine.csTimed transitions, synced state, late-joiner safety
Game with undo/historyUndoableGameManager.csbyte[] history, NetworkCallable _OwnerProcessMove/_OwnerUndo/_OwnerReset
Object pool (player slots)MasterManagedPlayerPool.csMaster-managed player object pool for non-security session arbitration; FIFO ring buffer; OnPlayerJoined/Left; _VerifyAssignments after master handoff
Persistence & Data
Save/load player dataDataPersistence.csPlayerData API, OnPlayerRestored, auto-save (introduced in SDK 3.7.4)
Networking Patterns
Rate-limited sync (slider drag)RateLimitedSync.cs0.15s sync cooldown with _syncLocked/_changeCounter; _OnSyncUnlock callback; last-write-wins
Batched sync (rapid events)BatchedSync.csIdempotent ScheduleBatchedSync with 0.2s BatchDelay; _FlushBatch delayed callback; single packet
Congestion-aware retryCloggedRetrySync.csNetworking.IsClogged check; linear back-off (RetryDelay * retryCount); MaxRetries=5
Dual local+synced copyDualCopySync.csLocal + synced copy with _dirty flag; strict OnPreSerialization/OnDeserialization separation
Pack multiple values into one fieldPackedStateSync.csPack 3 ints into one Vector3 UdonSynced field; OnPreSerialization/OnDeserialization
Utilities
Array helpers (List<T> alternative)ArrayUtils.csAdd, Contains, AddUnique, Remove, RemoveAt, Insert for GameObject[]; FindIndex/ShuffleArray for int[]
Event bus (pub/sub)EventBus.csSubscriber list event bus (max 32 listeners); RegisterListener/UnregisterListener/RaiseEvent; in-place compaction
Custom editor inspectorCustomInspector.csCustom editor inspector with UdonSharpEditor: UdonSharpGUI, SerializedProperty, Undo
Auto-generate .asset for new scriptsUdonSharpProgramAssetAutoGenerator.csAssetPostprocessor that auto-creates UdonSharpProgramAsset for new scripts; domain-reload-only, auto-compile

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.

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.

SDK Versions

Active support / last verified: SDK 3.10.6

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.

Generated examples target the active SDK unless a reference marks a historical migration case. Other SDK versions named in this Skill record when a feature was introduced; they are not active support or validation targets. This is the Skill's support boundary, not a statement about VRChat's own SDK policy.

Feature introductions by SDK version and upgrade steps are in references/sdk-migration.md. Check the matching release notes before relying on a version-specific API or migration step.

Official Resources

ResourceURLContents
VRChat Creatorscreators.vrchat.com/worlds/udon/Official Udon / SDK documentation
UdonSharp Docsudonsharp.docs.vrchat.comUdonSharp API reference
VRChat Forumsask.vrchat.comQ&A, solutions
VRChat Cannyfeedback.vrchat.comBug reports, known issues
GitHubgithub.com/vrchat-communitySamples and libraries

References

FileContentsSearch Hints
constraints.mdC# 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 listsList, 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.mdOwnership model, sync modes, RequestSerialization, NetworkCallable, network-event sender authorization, data limitsUdonSynced, SetOwner, BehaviourSyncMode, FieldChangeCallback, OnDeserialization, NetworkCalling, CallingPlayer, InNetworkCall, legacy event, underscore, authorization, master leave, ownership cascade, None, NoVariableSync
networking-bandwidth.mdBandwidth throttling, bit packing, synced data size examples, debugging, owner-centric architectureIsClogged, bandwidth, throttle, bit packing, data budget, IsMaster
networking-antipatterns.md6 anti-patterns to avoid; 5 advanced sync patterns with template linksanti-pattern, race condition, ownership fight, late-joiner, PackedStateSync, BatchedSync
persistence.mdStorage layer decision tree (local/synced/PlayerData/PlayerObject); PlayerData/PlayerObject API (introduced in SDK 3.7.4); per-player save data; storage usage query API (introduced in SDK 3.10.0)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.mdPhysBones, Contacts, VRC Constraints (introduced in SDK 3.10.0); VRCTween, Box-shaped Contacts, Global Avatar PhysBone Colliders, world VRCPhysBoneCollider Udon access (SDK 3.10.4+); constraint source methods and SmoothingFactor (SDK 3.10.6+)PhysBone, ContactReceiver, ContactSender, Box Contact, Global Avatar PhysBone Collider, VRCPhysBoneCollider, VRCTween, VRCConstraint, SourceCount, GetSource, SetSource, SmoothingFactor, OnContactEnter
patterns-core.mdInitialization, interaction, player detection, timer, audio, pickup, animation, UI, teleportation, lazy init guard, remote playersInteract, OnEnable, Initialize, AudioSource, VRCPickup, Animator, UI, TeleportTo, remote players, _GetRemotePlayers, exclude local player, FindAll alternative
patterns-networking.mdObject pooling, NetworkCallable sender-validation patterns, persistence integration, dynamics interactions, synced game state, distant-room pseudo-multi-room (state/presentation split, self-owned or master-coordinated session arbitration), delayed event debounce, string join for array syncpool, MasterManagedPlayerPool, NetworkCallable, CallingPlayer, InNetworkCall, sender authorization, DamageReceiver, game state, distant room, pseudo multi-room, room assignment, roomIndex, LocalRoomPresenter, RoomAssignment, TeleportTo per-client, debounce, state machine, string join, array sync, paragraph separator, U+2029
patterns-performance.mdPartial class pattern, update handler, PostLateUpdate, VRCBillboard (SDK 3.10.6+), spatial query, platform optimization, frame budget Stopwatch, heavy processing architecture (rebuild, replay, reset/cancel), rate limit resolver, GameObject lookup cost tiersUpdate, PostLateUpdate, VRCBillboard, Bounds, AnimatorHash, performance, mobile, PC, Stopwatch, frame budget, SendCustomEventDelayedFrames, heavy processing, rebuild, replay, reset, cancel, operation log, authoritative data, derived state, cursor rebuild, rate limit, URL scheduler, video load queue, GameObject.Find, Find cost, lookup cost tier, SerializeField vs Find, silent failure on rename, SendCustomEvent cost, cross-behaviour call, EventBus hot path, delayed loop spike, public method lookup, event dispatch tier
patterns-utilities.mdArray helpers (List alternatives), event bus, GameObject relay communication, pseudo-struct double-cast, abstract class callback, cancellable delayed event, re-entrance guard, UdonEvent pseudo-delegateArrayUtils, EventBus, relay, subscriber, FindIndex, ShuffleArray, object array, pseudo struct, double cast, abstract class, callback, interface alternative, cancellable timer, re-entrance, emitting guard, UdonEvent, pseudo delegate
patterns-ui.mdUI/Canvas patterns: immobilize guard, avatar-scale-aware UI, FOV-responsive positioning, platform-adaptive layout, dynamic player list, scroll input abstraction, lookup-table localization, toggle-animator bridge, settings persistence via PlayerObject, listener-based menu events, finger touch interaction, modular app architectureCanvas, UI, menu, Immobilize, avatar scale, FOV, platform, Quest, VR, desktop, player list, scroll, localization, language, Toggle, Animator, PlayerObject, settings, persistence, listener, broadcast, finger touch, fingertip, haptic, FingerPointer, FingerTouchCanvas, touch canvas, app architecture, AppModule, AppManager, plugin lifecycle, CanvasGroup transition
patterns-video.mdVideo player state machine, server-time playback sync, late joiner sync, AVPro Blit buffering, error retry with fallback, synced playlist/queue, platform URL selectionvideo player, AVPro, VRCUnityVideoPlayer, BaseVRCVideoPlayer, playback sync, server time, GetServerTimeInMilliseconds, late joiner, VRCGraphics.Blit, OnVideoReady, OnVideoError, retry, fallback, playlist, queue, shuffle, repeat, Quest URL
web-loading.mdString/Image downloading, VRCJson, Trusted URLsVRCStringDownloader, VRCImageDownloader, VRCJson, DataDictionary, VRCUrl
image-loading-vram.mdAdvanced VRAM management for image loading: Destroy vs Dispose, double-buffer fade, stock mode, mipmap biasVRAM, texture memory, memory leak, Destroy, Dispose, double buffer, fade, mipmap, TextureInfo
web-loading-advanced.mdAdvanced data loading: Base64 texture embedding via StringDownloader, cross-platform compression, URL double-key indexing, LRU decode cacheBase64, LoadRawTextureData, StringDownloader texture, DXT1, ETC_RGB4, UNITY_ANDROID, LRU cache, packed resources, binary format
api.mdVRCPlayerApi, Networking, NetworkCalling sender context, enums reference, VRCObjectPool methods + Interact-driven ownership patternsGetPlayers, playerId, isMaster, isLocal, GetPosition, SetVelocity, NetworkCalling, CallingPlayer, InNetworkCall, Drone, VRCDroneApi, VRCObjectPool, TryToSpawn, Return, Shuffle, pool owner, Interact pool, pool forwarded spawn, pool ownership transfer
events.mdAll Udon events (including OnPlayerRestored, OnContactEnter)OnPlayerJoined, OnPlayerLeft, OnPlayerTriggerEnter, OnOwnershipTransferred, OnControllerColliderHitPlayer, CharacterController, OnMasterTransferred, OnAvatarChanged, OnSpawn, VRC Economy, OnPurchaseConfirmed, OnAsyncGpuReadbackComplete
editor-scripting.mdEditor scripting, proxy system, custom inspectors, editor-only setup components (IEditorOnly), build pipeline callbacks, and UdonSharpProgramAsset auto-generationUdonSharpEditor, UdonSharpBehaviourProxy, SerializedObject, CopyProxyToUdon, ApplyProxyModifications, UpdateProxy, GetUdonSharpComponent, RecordPrefabInstancePropertyModifications, serializedPublicVariablesBytesString, scene diff, UdonSharpProgramAsset, auto-generate, AssetPostprocessor, .asset missing, IEditorOnly, EditorOnly tag, setup helper, setup component, build exclusion, custom inspector, ContextMenu, IVRCSDKBuildRequestedCallback, OnBuildRequested, build callback, IPreprocessCallbackBehaviour, OnPreprocess
assembly-definitions.mdUdonSharp assembly definitions, Unity .asmdef vs U# Assembly Definition, VPM package workflows, Runtime/Editor separation, and Auto Referenced tradeoffsVersion Defines, VRC_ENABLE_, asmdef, Assembly Definition, U# Assembly Definition, Source Assembly, VPM package, Auto Referenced, Runtime, Editor, package layout, prefab-first, code-integration API
sync-examples.mdSync pattern examples (Local/Events/SyncedVars)Continuous, Manual, None, sync example
troubleshooting.mdCommon errors and solutionsNullReference, compile error, sync not working, FieldChangeCallback, VRCStation, seated player, trigger zone, OnPlayerTriggerEnter not firing, station collider, position polling, OnStationEntered
sdk-migration.mdSDK migration guide (3.7 to 3.10), version-by-version changes and checklistsmigration, deprecated, upgrade, 3.7, 3.8, 3.9, 3.10
testing.mdTesting and debugging guide: ClientSim editor testing, Build and Test (single and multi-client), Debug.Log patterns, pre-release cleanup, testing checklistClientSim, Build and Test, multi-client, late joiner test, debug, Debug.Log, ownership test, sync test, testing checklist
context-preservation.mdContext-preservation guide: recording task-specific design intent (source of truth, sync strategy, ownership, late-joiner behavior, validation) across context compaction/handoff; minimal task-context note; privacy guidance; resume checklistcontext preservation, design intent, compaction, handoff, resume, task context note, why this design, ownership rationale, design-context loss

Hooks

HookPlatformPurpose
validate-udonsharp.ps1Windows (PowerShell)PostToolUse constraint validation
validate-udonsharp.shLinux/macOS (Bash)PostToolUse constraint validation

When a validator is registered, its findings arrive as additional context after a .cs edit, one line each, prefixed [UdonSharp]. Treat them as review input for the code just written; the edit is never blocked. A clean edit produces no output, so silence does not prove that a validator ran: check generated code against the Rules either way. The Claude Code plugin registers the Bash validator automatically; other installs must register one in the agent's hook settings (see the repository README).

A validator that cannot run reports VALIDATOR-WARNING: validation skipped (<reason>) on the edit instead of silently reporting successful validation.

Quick Reference

  • CHEATSHEET.md - One-page quick reference

VRChat World SDK 3 Guide

Table of Contents

SectionContentReference
Scene SetupVRC_SceneDescriptor, SpawnThis file
ComponentsPickup, Station, Mirrorreferences/components.md
Layers & CollisionLayers, Collision Matrixreferences/layers.md
PerformanceOptimization guidereferences/performance.md
LightingLighting settingsreferences/lighting.md
Audio & VideoAudio, Video playersreferences/audio-video.md
Build ValidationRed/yellow/white SDK alertsreferences/build-validation.md
World UploadUpload workflowreferences/upload.md
TroubleshootingProblem solvingreferences/troubleshooting.md
CheatsheetQuick referenceCHEATSHEET.md

Common Mistakes (NEVER List)

These cause silent world failures, performance disasters, or Quest incompatibility:

#NEVER do thisWhy it hurtsUse instead
1Enable Mirror by default (active on world join)A mirror adds another costly scene render; the impact depends on view, scene, resolution, and deviceDefault Mirror OFF; add a player-controlled toggle and profile each target device
2Use realtime directional lights with real-time shadows without profilingRealtime shadow cost varies with scene geometry, view, and target device and can dominate frame time on AndroidPrefer baked lightmaps + light probes; profile the target device before keeping any realtime shadows
3Set Respawn Height at or above the world floorPlayer respawns → falls → respawns again → infinite loop; players cannot recoverSet to an unreachable depth (e.g., floor at Y=0 → Respawn at Y=-100)
4Skip "Setup Layers for VRChat" on a new projectLayer collision matrix is wrong by default — players walk through walls, Pickups clip floorsRun VRChat SDK > Builder > "Setup Layers for VRChat" before placing any colliders
5Enable Post-Processing without an Android build profilePost-processing is disabled at runtime on Android, so the authored effect will not appear and unnecessary resources can still enlarge the buildUse a separate Android build profile with post-processing removed
6Leave several video players decoding at once without profiling the target devicesEach active player adds decoding overhead, which can cause frame drops and audio issuesDisable players that are not playing; profile concurrent playback on each target
7Use Cloth on Android, or add many Unity Constraints without profilingCloth is disabled on Android. Unity Constraints are permitted in worlds, but overuse can significantly affect performanceRemove Cloth from the Android build; prefer VRC Constraints for new work and profile any constraint-heavy setup
8Upload without completing a lightmap bakeRealtime GI adds substantial scene-dependent render cost and is unsuitable as an unmeasured fallback on AndroidBake lights before upload, then verify the result on the target device
9Place player walkable surfaces on Default layer (0)Collision matrix is wrong by default — avatar physics collision is unreliable; players may clip through geometryUse Environment (layer 11) for all walkable geometry, walls, and floors
10Use very high lightmap resolution for large areas without profilingTexture memory can spike significantly at high resolutions; a common cause of OOM crashes on mobile headsetsStart at 10-20 texels/unit (PC) / 5-10 (Quest) as a practical guideline; profile VRAM and adjust — official guidance says "keep lightmap resolution low" for Quest
11Add VRC_UIShape to a Screen Space or Overlay CanvasVRC_UIShape requires World Space Canvas; other modes throw a runtime Unity error in VRChat — the UI renders visually but is not interactive, with no visible error to the world builderSet Canvas > Render Mode to World Space before adding VRC_UIShape

Reference Loading Guide

Load only what the task requires. When a request spans several rows, load every MANDATORY READ those rows list; a Do NOT Load entry never overrides another matching row's MANDATORY READ.

TaskMANDATORY READOptionalDo NOT LoadLoad Rationale
Setting up a new scene from scratchcomponents.md, layers.mdupload.mdaudio-video.md, troubleshooting.mdCollision matrix non-obvious; component deps needed upfront
Making objects grabbable (VRC_Pickup)components.mdlayers.mdaudio-video.md, lighting.mdPickup/Rigidbody requirements not in standard Unity docs
Configuring Dynamics for Worlds (PhysBones, Contacts, Box Contacts, Global Avatar PhysBone Colliders, world VRCPhysBoneCollider access)components.mdlayers.md, troubleshooting.md; use unity-vrc-udon-sharp for Udon codeaudio-video.md, lighting.mdDynamics component availability and Udon access are SDK-version sensitive
Setting up seating (VRC_Station)components.mdlayers.mdaudio-video.md, performance.mdStation collider + exit requirements are VRChat-specific
Optimizing FPS for Questperformance.md, lighting.mdtroubleshooting.mdaudio-video.md, upload.mdQuest limits differ from PC; bake requirements non-obvious
Adding audio or video player / voice zones (SetVoiceGain, Steam Audio)audio-video.md, components.mdtroubleshooting.mdlighting.md, performance.mdAVPro vs Unity Video selection is VRChat-specific
Configuring WorldQualitySettings, realtime probes, or Shadowmask Modecomponents.mdlighting.md; Udon API: unity-vrc-udon-sharpaudio-video.md, layers.mdExisting startup setters and override flags can overwrite authored quality choices
Baking lights / lightmap setuplighting.md, performance.md—audio-video.md, layers.mdLightmap resolution and probe placement affect Quest VRAM
SDK Build Panel validation alerts, red/yellow/white warnings, or Auto Fix questionsbuild-validation.mdupload.md, troubleshooting.mdaudio-video.md, lighting.mdAlert severity, build consequence, and Auto Fix side effects must come from SDK-backed catalog
World upload and publishupload.mdbuild-validation.md, troubleshooting.mdaudio-video.md, lighting.mdUpload steps and validation order are fragile; easy to miss
Debugging collision or layer issueslayers.md, troubleshooting.mdcomponents.mdaudio-video.md, lighting.mdVRChat collision matrix differs from Unity default
Mirror setup and configurationcomponents.mdperformance.mdaudio-video.md, upload.mdMirror layer mask requirements are VRChat-specific

Before Starting a New World — Design Decisions

These decisions shape every downstream choice. Make them first, before placing any component.

DecisionOptionsImplication
Quest required?Yes / NoYes → Quest First philosophy applies from day 0, not as a retrofit
Expected player count?1–8 / 9–40 / 40+Affects spawn count, mirror policy, max video players
Primary interaction?Grab (Pickup) / Sit (Station) / Watch (Video) / ExploreDetermines which SDK components are mandatory
Lighting approach?Baked / Mixed / RealtimePrefer baked lighting on Android; profile each target device before keeping realtime lighting or shadows
Networked objects?None / Physics (Pickup+ObjectSync) / State (UdonSynced)Determines sync architecture before Udon scripting begins

Design Philosophy: Quest First

If the world must run on Android, decide those constraints before tuning the PC build. Test each target separately.

Android headsets have mobile CPU, GPU, memory, and thermal budgets that differ from PC and vary by device:

  • GPU: Realtime lights, shadows, overdraw, and complex shaders can dominate frame time
  • Memory: Textures and lightmaps share limited system memory with the client
  • Thermals: Sustained load can reduce available performance during a session

Measure each target device independently; PC results do not establish Android performance, and a single-client Quest result does not predict a particular PC frame rate. Use the Unity Profiler and the official Android content optimization guide before publishing.

NEVER optimize exclusively for PC with "Quest support added later" — by that point, lighting, materials, and mesh density are all locked to PC quality, and the Quest port requires rebuilding everything.

Quest First Cascade — when Quest is required, every downstream decision inherits constraints:

Quest required? → Yes
  ├── Shaders: World shaders are unrestricted; prefer mobile-compatible shaders and profile custom ones
  ├── Lighting: Baked by default; retain realtime effects only after target-device profiling
  ├── Geometry: Budget approximately 250,000 triangles for the whole world; reduce further when profiling calls for it
  ├── Materials: Minimize unique materials and draw calls; no fixed world upload limit is documented
  ├── Audio: Mono, compressed, limited concurrent sources
  └── Physics: Simplified colliders, minimal Rigidbodies

SDK Versions

Active support / last verified: SDK 3.10.6

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.

Guidance targets the active SDK unless a reference marks a historical migration case. Other SDK versions named in this Skill record when a feature was introduced; they are not active support or validation targets. This is the Skill's support boundary, not a statement about VRChat's own SDK policy.

Feature introductions by SDK version are in CHEATSHEET.md, and the Components table below lists the SDK that introduced each component. Verify version-sensitive APIs against the matching release notes before migrating a project.


Scene Setup

VRC_SceneDescriptor (Required)

Exactly one is required in every VRChat world.

[VRCWorld Prefab]
├── VRC_SceneDescriptor (Required)
├── VRC_PipelineManager (Auto-added)
├── VRCWorldSettings (Optional - movement speed settings)
└── AvatarScalingSettings (Optional - avatar scale limits)
Key Properties
PropertyTypeDescriptionDefault
SpawnsTransform[]Array of spawn pointsDescriptor position
Spawn OrderenumFirst/Sequential/Random/Demo (First: always the first spawn; Demo: spawn point is the center of room scale)Sequential
Spawn OrientationenumDefault/Align Player With Spawn Point/Align Room With Spawn PointDefault
Respawn HeightfloatRespawn height (Y axis)-100
Object Behaviour At RespawnenumRespawn/DestroyRespawn
Reference CameraCameraPlayer camera settings referenceNone
Forbid User PortalsboolDisable user portalsfalse
Voice Falloff RangefloatVoice attenuation range-
Interact PassthroughLayerMaskInteract passthrough layersNothing
Maximum CapacityintMax player count (hard limit)-
Recommended CapacityintRecommended player count (UI)-
Reference Camera Usage
// Usage:
// 1. Adjust Near/Far clipping (recommended for VR: 0.01 ~ 1000)
// 2. Apply Post Processing effects
// 3. Set background color

// ⚠️ MUST disable the Camera component after configuring — an active Reference Camera
//    renders a second viewport. VRChat reads only the camera settings, not its output.
// Assign the configured (disabled) Camera to VRC_SceneDescriptor > Reference Camera.

Spawn Points Setup

// Spawn points are empty GameObjects assigned to VRC_SceneDescriptor > Spawns array.
// Players enter facing the Z+ direction of the spawn Transform.

// VRChat-specific requirements:
// - One spawn point is supported; add more if simultaneous joins should not stack on one spot
// - Place slightly above the floor (~0.1m) to avoid floor collision on spawn
// - Keep clear of obstacles (VR player guardian area is larger than their avatar)
// - Account for VR guardian boundaries — desktop player sizes differ from VR

Required Setup Checklist

□ Exactly one VRCWorld Prefab exists in the scene
□ At least one Transform set in Spawns
□ Respawn Height set to an appropriate value (well below the floor)
□ Reference Camera configured for clipping distances (for VR)
□ Layer/Collision Matrix correctly configured
□ "Setup Layers for VRChat" has been executed

Components

MANDATORY READ references/components.md (~970 lines) before configuring any VRC component below. Load in full — dependency requirements and Udon event hooks are distributed throughout. Do NOT Load: references/audio-video.md (unless the task involves audio/video components), references/lighting.md (unless the task configures WorldQualitySettings, realtime reflection probes, or Shadowmask Mode).

ComponentRequired ElementsPurposeSDK
VRC_SceneDescriptor-World settings (required)-
VRC_PickupCollider + RigidbodyGrabbable objects-
VRC_StationColliderSittable locations-
VRC_ObjectSyncRigidbodyAuto-sync Transform/physics-
VRC_MirrorReflection-Mirror (⚠️ high cost)-
VRC_PortalMarker-Portal to other worlds-
VRC_SpatialAudioSourceAudioSource3D audio-
VRC_UIShapeCanvas (World Space)Unity UI interaction-
VRC_AvatarPedestal-Avatar display/switch-
VRC_CameraDolly-Camera dolly3.9+
VRCCameraSettingsNone (static API)Read camera info from Udon3.8.1+
VRCBillboard-Face the local viewpoint3.10.6+
VRCVelocityTracker-Read velocity without a loop3.10.6+
VRCPlacementZone-Control user portal/sticker placement3.10.6+

VRC_ObjectSync vs UdonSynced

ScenarioVRC_ObjectSyncUdonSynced variables
Throwable objects / physics✅ Recommended❌
State only / complex logic❌✅ Recommended

SDK 3.8.0+: Force Kinematic On Remote — Makes Rigidbody kinematic on non-owner clients, preventing unexpected physics behavior.


Layers & Collision

VRChat Reserved Layers

Layer #NamePurpose
0DefaultGeneral objects
9PlayerRemote players
10PlayerLocalLocal player
11EnvironmentEnvironment (walls, floors)
13PickupGrabbable objects
14PickupNoEnvironmentPickups that don't collide with environment
17WalkthroughWalk-through objects
18MirrorReflectionMirror reflection only
22-31User LayersAvailable for custom use

Layer Setup Steps

1. VRChat SDK > Show Control Panel
2. Builder tab
3. Click "Setup Layers for VRChat"
4. Collision Matrix is automatically configured

MANDATORY READ references/layers.md when setting up collision or debugging physics. The default Unity collision matrix differs from the VRChat-correct one — always verify. Do NOT Load: references/audio-video.md, references/upload.md.


Performance

Performance Criteria

Define the performance target from the supported devices, representative scenes, and expected player count. Record a frame-time or frame-rate target for each build target before profiling. VRChat does not provide one fixed FPS upload threshold for worlds.

Starting Budgets

ItemRecommendedReason
Mirrors1, default OFFRenders the entire scene 2x
Video players1-2 recommendedDecoding overhead; no documented hard limit
Realtime lightingBaked by defaultKeep realtime lights or shadows only after target-device profiling
LightmapsBake and verifyPrimary Android lighting path

Quest/Android Restrictions

ComponentPCQuest
Dynamic Bones✅❌ Disabled
Cloth✅❌ Disabled
Post-Processing✅❌ Disabled
Unity Constraints✅✅ Permitted in worlds; profile cost
Realtime lights✅⚠️ Expensive; keep only with device evidence

Performance Optimization Workflow

Bottleneck TypeKey IndicatorsReference
CPU-boundHigh script time, physics overheadperformance.md §Optimization-Workflow
GPU-boundDraw calls, overdraw, shader complexityperformance.md §Optimization-Workflow
MemoryVRAM usage, texture size, mesh countperformance.md §Optimization-Workflow

MANDATORY READ: Load performance.md before optimizing — measure first, then target the largest bottleneck — and references/lighting.md for Quest optimization. Do NOT Load: references/audio-video.md, references/upload.md.


Lighting

Baked Lighting (Default)

✅ Recommended settings:
├── Lightmapper: Progressive GPU
├── Lightmap Resolution: 10-20 texels/unit (PC) / 5-10 (Quest)
├── Light Mode: Baked by default; use Mixed/Realtime only when the effect is necessary and measured
└── Light Probes: Place along player paths

❌ Avoid:
├── Realtime lights (dynamic shadows)
├── High-resolution lightmaps (memory consumption)
└── Excessive Reflection Probes

MANDATORY READ references/lighting.md when configuring lightmaps or light probe placement. Do NOT Load: references/audio-video.md, references/upload.md, references/layers.md.


Audio & Video

VRC_SpatialAudioSource

Plan each world AudioSource with a VRC_SpatialAudioSource: a bare AudioSource triggers a VRChat SDK Build Panel warning. Add the companion deliberately, avoid Auto Fix as a blind default, and do not overwrite existing VRC_SpatialAudioSource values or tuned AudioSource curves unless requested.

PropertyDescriptionBaseline / safe-preserve note
GainVolume boost (0-24 dB)10 dB is common/default; use 0 dB for warning-only additions to preserve loudness
NearAttenuation start0m unless the sound needs an intentional near field
FarAttenuation endMatch existing maxDistance or the intended audible range; avoid blind default/Auto Fix ranges
Volumetric RadiusSource spread0m for point sources; set intentionally for wide sources
Enable Spatialization3D positioningfalse for intentional 2D/global audio; true for authored 3D audio

When preserving an existing AudioSource, keep volume, spatialBlend, rolloffMode, maxDistance, and custom curves; use Gain 0 dB; enable Use AudioSource Volume Curve for tuned 3D rolloff; match Far to the existing maxDistance or intended audible range; and keep Near at 0m unless an existing minDistance/Near value was intentionally authored.

Video Player Selection

FeatureAVProUnity Video
Live streaming✅❌
Editor preview❌✅
YouTube/Twitch✅❌
Quest support✅✅

MANDATORY READ references/audio-video.md for VRC_SpatialAudioSource or video player configuration. Optional: references/components.md when wiring audio/video components. Do NOT Load: references/lighting.md, references/performance.md.


World Upload

Upload Steps

1. Check Validation
   └── VRChat SDK > Build Panel > Validations

2. Build & Test (local testing)
   └── "Build & Test New Build"
   └── Supports multi-client testing

3. Upload
   └── "Build and Upload"
   └── Set Content Warnings
   └── Set Capacity

4. Publish settings
   └── Configure public/private on the VRChat website

Pre-Upload Checklist

□ VRC_SceneDescriptor × 1
□ Spawns configured
□ Respawn Height appropriate
□ Layer/Collision Matrix verified
□ Lighting approach finalized (bake complete, or realtime cost measured)
□ Mirrors default OFF unless the world's purpose needs them on (cost measured)
□ Project-defined frame-time or frame-rate target met in representative scenes and player counts
□ No Validation errors
□ Content Warnings set
□ Capacity set

MANDATORY READ references/upload.md before running Build & Upload. Verify all pre-upload checklist items first. MANDATORY READ references/build-validation.md when the user asks about SDK Build Panel validation, red/yellow/white warnings, Auto Fix, or a copied validation message. Do NOT Load: references/audio-video.md, references/lighting.md.


Troubleshooting

Quick Router

Identify the symptom category and jump to the reference section:

Symptom CategoryCommon CauseReference
Player walks through walls / floorLayer setup not run; geometry not on Environment (11)troubleshooting.md §Layer & Collision
Can't grab / Pickup not workingMissing Collider, Rigidbody, or VRC_Pickup componenttroubleshooting.md §Component
Object not syncing / snaps backMissing VRC_ObjectSync or ownership not transferredtroubleshooting.md §Networking
Can't sit / clips through StationMissing Collider; Station Enter Player Location needs adjustmenttroubleshooting.md §Component
Mirror not reflectingLayers mask missing Player/PlayerLocal/MirrorReflectiontroubleshooting.md §Component
Build / Upload failsMissing SceneDescriptor, script errors, layer warningstroubleshooting.md §Build
Performance issuesMirror ON, realtime lights, uncooked lightmapsperformance.md
Works in Editor but fails in VRChatEditor Play ≠ SDK runtime; use Build & Testtroubleshooting.md §Editor
UI visible but not clickableVRC_UIShape on Screen Space / Overlay Canvas (see NEVER #11)troubleshooting.md §Editor

MANDATORY READ references/troubleshooting.md when diagnosing any issue. Do NOT Load for non-troubleshooting tasks.


Related Skills

For C# scripting, network sync, and UdonSharp event implementation, use the unity-vrc-udon-sharp skill.


Method Migration

The following public methods were renamed because an unprefixed, parameterless public UdonSharp method remains callable through legacy network dispatch:

BeforeAfter
ForceDropPickup_ForceDropPickup
IsHeld_IsHeld
IsOccupied_IsOccupied
StopSound_StopSound
SlowUpdate_SlowUpdate

Update Inspector event strings, SendCustomEvent* calls, delayed events and nameof(...) expressions, and cross-behaviour calls. Compatibility aliases are not provided because an old unprefixed alias would restore the same legacy network exposure.

Templates (assets/templates/)

Starter templates for common SDK component patterns. Repository checks cover static checks; import them into the target SDK project, compile, and run Build & Test before use. Adjust Inspector fields and extend the event stubs for your world.

TemplatePurpose
VRC_Pickup_Rigidbody.csVRC_Pickup with Rigidbody — OnPickup/OnDrop/OnPickupUseDown/OnPickupUseUp events, ownership transfer, audio feedback
VRC_Station_Basic.csVRC_Station controller — OnStationEntered/OnStationExited events, PlayerMobility, force-eject API

References

FileContent
references/components.mdAll component details, component whitelist, Dynamics for Worlds, editor-only exclusion (EditorOnly tag / IEditorOnly)
references/layers.mdLayers & collision
references/performance.mdPerformance optimization
references/lighting.mdLighting settings
references/audio-video.mdAudio & video
references/build-validation.mdSDK 3.10.6 Build Panel red/yellow/white validation alert catalog, safe fixes, Auto Fix side effects
references/upload.mdUpload procedure
references/troubleshooting.mdTroubleshooting guide
CHEATSHEET.mdQuick reference

Sponsors

Details

Marketplace
niaka3dayo/agent-skills-vrc-udon
Category
Community