Please read this post entirely. We know it is a lot, but there’s a lot going on! Most basic questions are answered in this post.
If you’re reading this, welcome to VRChat Udon! We’ve been working on this for quite a while, and are super excited about getting you in to create, share, remix, and play with Udon. There’s a few things that we’ll address in this thread, and we’ll keep it up to date with Udon.
This post will include: introductions, links, a super basic guide, and a basic video introducing how to get started with Udon.
I know there’s a lot in this post, but please read this entirely! There’s a lot of information here, and we don’t want you to miss any of it.
Current Udon Status
Udon is currently in LIVE ALPHA. What does that mean?
Live: Udon is usable in the current Live version of VRChat! You can build creations with Udon, upload to VRChat, and share it with thousands upon thousands of people across the world. We’ve got a few requests, though:
- When applicable to the platform you’re on, use the #MadeWithUdon hashtag to share your work!
- When sharing VRChat Udon creations, ensure that you inform your viewers/readers that Udon is still in alpha and some things may not be working completely just yet. This isn’t the final state of Udon.
- When someone wants to try Udon, don’t send them files, send them to this thread! This is the best place to get started with Udon, which is why I named the thread this way.
Alpha: Udon is not feature-complete, it has bugs, and therefore is considered in an Alpha state. We’ve still got a lot to do! Read the Known Issues section below for more info.
What’s this Udon thing anyways?
VRChat Udon is a programming language built completely in-house by the VRChat Development Team. It is designed to be secure, performant, and easy to use via the VRChat Udon Node Graph, a built-in visual programming interface that uses nodes and wires (we call them “noodles”) to connect flow, inputs, and outputs. You can build complex behaviors with Udon-- far more complex and easier to understand than unwieldy chains of Triggers and Actions.
Not only can you replicate the full behavior of Triggers and Actions with VRChat Udon, but you can create your own behaviors, sync variables with others, interact with scenes, interact with players, and more.
In addition, Udon runs in both the VRChat client and the Unity Editor, allowing you to test and debug your creations with ease.
For the more technically inclined: VRChat Udon is a VM running bytecode compiled from Udon Assembly. You can generate Udon Assembly using the built-in VRChat Udon Node Graph UI, writing your own Udon Assembly, or even by writing your own compiler to generate Udon Assembly or bytecode programs directly.
Where do I download Udon?
Current Editor Version
Please check our documentation on the Current Unity Version for the most up to date links and instructions on how to install the current version of Unity we’re using.
Current SDK Version
You can grab the VRCSDK3 + Udon package on the VRChat Home website! Just login and click the “Download” button on the left, then click “VRCSDK3 + Udon”.
Current Client Build
Udon is currently available on the “Live” branch of VRChat-- in other words, no beta build required.
How do I import Udon?
Just like any other Unity package, like the VRCSDK!
Assets > Import Package... > Custom Package. Just import the VRCSDK3+Udon package, and you’re good to go.
Make sure your Client Path setting in the SDK is correct, and is pointing to the VRChat EXE for local testing.
Can I use Udon in my old project?
No. You need to create a new project to use VRCSDK3 and Udon. We do not support “migrating” or “upgrading” VRCSDK2 projects to VRCSDK3 and Udon.
Can I use SDK3 to make avatars?
How do I use Udon?
First, make a new project, then import the SDK3+Udon package.
Seriously, make a new project first. This is in alpha. Things will break, so protect your other projects!
After importing VRCSDK3, check out the VRChat Examples folder in your project. Open the readme and follow the instructions to take your first steps into Udon.
What are all these Udon things called?
Good question, there’s a lot of things going on! Here’s a short glossary:
- Udon Behavior : The Udon Component itself.
- Udon Program : Udon code, which could be created in a few ways-- primarily via the Udon Graph UI.
- Udon Graph : The built-in method to create Udon Programs.
- Udon Assembly : Also called UAssembly. This is what is created when you create a program in the Udon Graph UI. Unless you’re getting into complex stuff, you mostly don’t need to worry about this directly.
Generally, anything that returns a program for Udon to use is called a Program Source Asset. Graphs can be called Graph Assets. You might also have Assembly Assets or Program Assets, depending on how you build your Udon Program.
With the built-in tools in the Udon SDK, you’ll be building Udon Programs out of Udon Graphs, to slot into Udon Behaviors in VRChat scenes.
How do I use Udon in VRChat?
You can run VRChat Udon in your editor entirely, and the same code that you run in Editor will run in the Client once you upload it!
Once you’re happy with your setup in the editor, you probably want to get it uploaded to VRChat! Simply upload your SDK3 Udon-powered world to VRChat like any other world, and join it.
What’s working? What isn’t working?
Easier to tell you what isn’t working, and you can find that in the “Known Issues / Features Still Under Work / Caveats / etc” section below.
Where do I post bugs or feedback?
You can also click the categories for bug report or feedback, and you’ll be redirected.
What about questions?
You can ask questions in our Questions category! If someone posts a solution to your question, make sure you click the solved button below their post, like this:
How should bug posts be formatted?
Please include the following information:
- Name of the VRCSDK package you have imported.
- Name of the Udon SDK package you have imported.
- Version/build of VRChat you’re using to test, if necessary.
- A general description of the bug you’re encountering.
- Step by step guide how to replicate the bug.
- Screenshot of the Node Graph.
- If required, a link to the UnityPackage for the scene, ideally uploaded to Google Drive.
- For the below items, use PasteBin, 0bin, or a similar service. Make sure you set the paste expiry to “Never”!!!
- If required, the Udon paste string (just copy the nodes)
- If required, the compiled assembly. Get this by expanding the “Compiled Graph Assembly” dropdown in the Udon Behavior component and click “Copy Assembly to Clipboard” button.
- If needed, a link to the world.
- If you’re feeling extra helpful, a video! Record with OBS or similar software, and upload unlisted to YouTube.
Can I make Udon Programs in Assembly, or write my own compiler?
Yes! We’re still working on documentation and a guide for this, but the short answer is yes. Take a look at the preliminary and very early documentation in our Releases category.
That being said, we’re focusing on the Node Graph method of creating Udon Programs. We’d appreciate you creating, testing, and reporting bugs for the Node Graph primarily. If you’d like to get your hands dirty in Udon assembly or try your hand at writing a compiler, go for it! Just keep in mind we’ll be focusing on bugs and feedback for the main VRChat Udon creation loop involving the VRChat Udon Node Graph.
I already know how to program. Are there any compilers already out there?
Yes! There are two major projects with posts on this forum, and likely more to come in the future.
- UdonSharp by Merlin - One of the more fully-featured Udon compilers out there, UdonSharp (or U#) uses C#-like syntax.
- UdonPie by zz_roba - UdonPie is a Python-like way to write logic for your VRChat worlds that compiles down to Udon assembly. There’s a good guide provided by Orels if you want to get started.
Udon is releasing with SDK3, which is a complete refactor of our current live SDK, SDK2. It is best to think of VRChat worlds as either being “SDK2” or “SDK3” worlds.
There’s some differences you should know about!
SDK3 comes bundled with Udon. Udon cannot be used with VRCSDK2.
SDK3 does not include Triggers or Actions. This is intended! Udon is meant to replace everything that Triggers and Actions perform right now. You can think of worlds being “SDK2” or “SDK3”, where SDK2 worlds are powered by Triggers and Actions, and SDK3 worlds are powered by Udon.
Udon easily replicates all of the behavior that triggers and actions have.
You cannot mix SDK2 and SDK3. They are completely separate. Attempting to import and use SDK2 components in a SDK3 world (or vice versa) will not work and will result in undocumented or completely non-functional behavior.
You cannot “port” SDK2 worlds to SDK3. For one, the components for various things won’t get replaced in-place. You should be starting new projects for SDK3/Udon worlds. You can, of course, use the same assets and etc, but you shouldn’t be chopping out SDK2, shoving in SDK3, and expecting it to work.
There’s other incompatibilities, but generally you should be starting a fresh and clean project to get started with SDK3+Udon.
Some components and scripts available in SDK2 may not be available in SDK3. In particular, we have removed the Unity Standard Assets from the list of usable scripts. The behavior in Standard Assets is fairly easily replicated with Udon.
If you run into issues, its best to try a few basic debugging steps. During testing, it is generally a good idea during debugging to try making a new project. If you find a consistent issue that is solved by restarting Unity or something similar, that’s probably a reportable bug.
SDK2 is not going away, but in the future, we’re going to be favoring SDK3 worlds in many ways. We’ll still support SDK2 and provide a download for it, but SDK3 is the “way of the future” for VRChat. New SDK features are likely to live specifically in SDK3. We will continue to support SDK2 for as long as people are still making content for it, and as long as people are still visiting/using content powered by SDK2-- in short, quite a long time. SDK2 isn’t going anywhere.
Known Issues / Features Still Under Work / Caveats / etc
Syncing Udon variables is being worked on. Check out this thread to learn more about how Sync works in Udon.
Currently, Array Sync and Animator Sync are not functional.
Instantiation (as in, creation of objects from prefabs) should be working. However, network instantiation is not functional at this time. For the most part, local instantiation should work fine. We’re working on it currently.
We’re working on making it possible to make powerful video players with all kinds of features — and let users add new functionality, like custom offsets (for karaoke), syncing different videos (“I like subs!” “Well I like dubs!”), and other features. In progress!
Midi and OSC
Midi and OpenSoundControl (OSC) are amazingly expressive protocols used widely in the Music and Theatre industries. (There’s a lot of Synth and VJ Nerds on our team who have been asking for this!) We’re looking forward to getting these supported ASAP, so you could wire up any Midi Keyboard or OSC controller to affect things in your worlds. You’re not limited to using these for just music performances, you can control anything in your world with a Midi or OSC action.
Very few creators use VRC_Panorama in VRCSDK2 for… well, panoramas. Instead, most people use it to get a remote image from the internet. We’re formalizing this by creating a “dynamic image” component that lets you grab images from the web. This is on the way.
Sometimes your graph won’t compile when you expect it to, resulting in out-of-date graphs running. Compilation occurs when:
- You save the scene
- You press “Manual Compile” on the Node Graph UI
- You’ve touched the Node Graph UI and 5 seconds has passed
Just in case, save your file before entering Play mode. Sometimes issues occur on first run. We’re working on this as well.
Components that used to depend on Triggers/Actions
VRC_Components that depend on Triggers and Actions will not work in SDK3 worlds until they’ve been updated. This means that some built-in VRChat components may not work properly. Most of these have been handled. We’re actively working on this right now.
Using PlayerAPI functions to interact and get information about and act on players in the world is in, however we’re not done implementing all the parts just yet. A good bit of it is working, but some of it will be missing. Consider it “under construction”.
For the most part, performance should be pretty good-- but there’s a bug currently affecting iteration across large arrays when running in the VRChat client. Try not to do that for now!
There’s also an intermittent issue in the Editor when entering Play mode where it takes quite a while to launch. This gets worse over time. Restart your Editor if you encounter this.
If you encounter any other performance issues, please feel free to report it as a bug. We’re looking at these as high-priority items.
The UI is not finalized. There’s a lot of weird UI bits that are confusing or hard to work with. Report those, make suggestions or feedback-- but just realize that we’re focusing on adding features and making core functionality work correctly, first.
Subgraphs were in for a bit, but we’re rolling them back for now. They’re “Coming Soon”. We’ve got a different design on the way.
Graph zooming isn’t in yet, but we plan on adding it.
Please stop this is so much text
It’s fine. We’re done! Go forth with Udon! Report bugs, provide feedback, and build some cool stuff. Post about it. Show it off. Strut a little.
Udon is just half the equation-- without talented creators like you, this doesn’t work. We’re extremely excited to see what you can do with it as you create graphs, share nodes, and play in new VRChat Udon-powered worlds. Have fun!
and never forget THE CUBE