SDK2 to Udon Migration - CyanLaser/CyanTrigger GitHub Wiki

SDK2 to SDK3 (Udon) project Migration

Since CyanTrigger is similar to SDK2's VRC_Trigger, it is possible to convert SDK2 projects into SDK3. Not everything will migrate cleanly. Please consider the risks before trying to migrate a project.

Read through everything on this page to know what will and will not migrate. A step by step guide for migrating a project is written below after the migration info.

The Migration can be added to your project through the VCC using the CyanTrigger VCC listing.

All information below is based on Version 2.1 of the SDK2 Migrator

SDK2 Items That Will Be Migrated

VRC_Trigger

All Trigger Event types.
- Some events may be split into multiple events to ensure everything works the same as SDK2. Check the comments on the event to understand what it was migrated from.
Most Trigger Actions
- SendRPC - Depending on the target action, some SendRPC types are not supported
- PlayAnimation - Legacy Animations are not supported in SDK3.
- SpawnObject - Spawned objects in Udon cannot be synced. All broadcasts not set to local will be ignored in VRChat. If sync is needed, this will need to be manually converted to using an ObjectPool.
Randomized Actions
Broadcast gating
- Anyone, Owner, Master
- Owner is determined by the CyanTrigger's owner instead of the receivers with VRC_Trigger.
Broadcast Type
- Local and Everyone is supported
- Buffering is not supported

VRC Components

Audio Bank
Avatar Pedestal
Combat System
Custom Renderer Behaviour
Object Sync
- Position Sync only. Animation sync is not supported.
Pickup
Pipeline manager
Player Audio Override
Player Mods
- Speed and Jump mods only
Portal Maker
Scene Descriptor
Scene Reset Position
Scene Smooth Shift
Spatial Audio Source
Station (Chair)
UI Shape

Non VRC Items

Animation Events

ExecuteCustomTrigger animation events will automatically be converted to SendCustomEvent
All MonoBehaviour or StandardAsset events will be migrated if possible
- Methods with parameters will ignore the parameter due to Udon limitations
Unsupported events will be converted to SendCustomEvent to prevent VRChat from removing ALL Animation Events on the clip.

Legacy Animations (Experimental)

Legacy Animations will take the main clip and convert it to an Animator Controller, if the GameObject does not already have an Animator
This is does not work in every case. Animation and Animator components will act different in certain situations. Legacy Animation Clip features are not supported in Animator Controllers.

UnityEvents

SDK3 introduces a UI Event whitelist, removing all not on the list

All UIBehaviours with UnityEvents will be migrated to CyanTrigger. Only Actions supported in Udon will be migrated.
Events handled specially:
- StandardAsset Methods
- Button.Press
- SendMessage, SendMessageUpwards, and BroadcastMessage will only send the event to UdonBehaviours
- Animation.Sample will be converted to AnimationClip.SampleAnimation and will ignore the Animator or Animation component during runtime.

Standard Assets

Some scripts may not work exactly the same as in SDK2. See notes for specific known differences.

Cameras
- AutoCam (Auto Target Player is ignored)
- FreeLookCam (Auto Target Player is ignored)
- HandHeldCam (Auto Target Player is ignored)
- LookatTarget (Auto Target Player is ignored)
- ProtectCameraFromWallClip
- TargetFieldOfView (Auto Target Player is ignored)
Characters
- RollerBall
  - Ball
  - BallUserControl
- ThirdPersonCharacter
  - AICharacterControl
  - ThirdPersonCharacter
  - ThirdPersonUserControl
ParticleSystems
- AfterburnerPhysicsForce
- ExplosionFireAndDebris
- ExplosionPhysicsForce
- Explosive
- ExtinguishableParticleSystem
- FireLight
- Hose
- ParticleSystemMultiplier
- SmokeParticles
- WaterHoseParticles (Only one particle checked per frame due to missing event not exposed in Udon)
Utility
- ActivateTrigger
- AutoMoveAndRotate
- FollowTarget
- FPSCounter
- ObjectResetter
- ParticleSystemDestroyer
- SmoothFollow
- TimedObjectActivator
- TimedObjectDestructor
- WaypointCircuit
- WaypointProgressTracker
Vehicles
- Aircraft
  - AeroplaneAiControl
  - AeroplaneAudio
  - AeroplaneController
  - AeroplaneControlSurfaceAnimator
  - AeroplanePropellerAnimator
  - AeroplaneUserControl2dAxis
  - AeroplaneUserControl4dAxis
  - JetParticleEffect
  - LandingGear
- Car
  - BrakeLight
  - CarAiControl
  - CarAudio
  - CarController
  - CarSelfRighting
  - CarUserControl
  - Mudguard
  - SkidTrail
  - Suspension
  - WheelEffects

SDK2 Items That Cannot Be Migrated

Note that CyanTrigger and SDK3 does not support everything that was allowed in SDK2. See the following list of items that CANNOT be migrated cleanly:

VRC_Trigger

VRC_Trigger Buffered Actions
- CyanTrigger does not support SDK2's VRC_Trigger buffered actions. This means that converted worlds will not have any late joiner support.
Owner is determined by the CyanTrigger's owner instead of the receivers with VRC_Trigger.
SpawnObject Action - Spawned objects in Udon cannot be synced. All broadcasts not set to local will be ignored in VRChat. If sync is needed, this will need to be manually converted to using an ObjectPool.
SendRPC gating
- SendRPC has its own gate separate from VRC_Trigger. These are not properly supported as Udon does not provide instigator information when using network events.

VRC Components

These components will not be convert to CyanTrigger. This may change in the future.

Animation Sync
Avatar Components
Data Storage
Destructible Standard
Juke Box
Midi
OSC
Panorama
Slide Show
Video Players
Legacy Components

Non VRC Items

Standard Assets
- 2D
  - Camera2DFollow
  - CameraFollow
  - Platformer2DUserControl
  - PlatformerCharacter2D
- FirstPersonCharacter
  - FirstPersonController
  - HeadBob
  - RigidbodyFirstPersonController
- Utility
  - AlphaButtonClickMask
  - AutoMobileShaderSwitch
  - DragRigidbody
  - DynamicShadowSettings
  - EventSystemChecker
  - PlatformSpecificContent
  - SimpleMouseRotator
Legacy Animation
- VRChat removed the legacy "Animation" component from the SDK3 whitelist. The migrator will take the base clip on the Animation component and add a non legacy Animator component with just this clip. This does not work in all situations and may need to be manually updated.
Animation Events
- SDK3 introduces a Animation Event whitelist. Animation events that do not target UdonBehaviour.SendCustomEvent will most likely be stripped out.
UnityEvents - SDK3 introduces a UI Event whitelist.
- Most UnityEvents on UIBehaviours will be converted, but not everything is exposed in Udon

Migration steps

Video Guide (v0.1)

Migrate your projects at your own risk! This system will permanently change your project that you cannot reverse!
Please Follow Every Step In Order!

This guide is for version 2.1 of the migrator.

Update the project to Unity 2019 and verify In VRChat that everything works properly.
- The latest SDK2 package will have errors that may prevent opening the build control panel. To resolve this, open the Unity Package Manager and import the Mathematics and Burst packages.
- When making a build of your world in SDK2, a popup will appear asking if you would like to Reload the scene or Ignore changes. Press Ignore
Open an empty scene by clicking File/New Scene or by pressing Control + N.
Open the Project Settings window.
- Go to the "Editor" tab, find "Asset Serialization" and ensure "Mode" is set to "Force Text". Changing this setting will take some time to reserialize your project.
- Keep the Project Settings window open.
Close Unity.
Backup Your Project! This is the last time it is known to work in SDK2.
Delete the "Assets/VRCSDK" folder.
- Keep the "Assets/VRChat Examples" folder, as the prefabs included here are necessary.
Delete all other scripts that use VRChat components.
- This is intended for those who imported or wrote editor scripts. Step 11 will make it obvious what should be removed.
- Some known assets that will cause compile errors:
  - CyanEmu
  - CyanClimbing setup script
  - Iwsd-SubInspector
Delete Post Processing if it was manually imported and not through the package manager.
- VRCSDK3 will automatically download this when importing SDK3.
Open Unity.
In Project Settings, go to the "Player" tab, remove all "Script Define Symbols" and press enter, allowing Unity to recompile.
Resolve all compile errors shown in the console.
- Remove or fix all scripts looking for SDK2 components.
Add your project to the VRChat Creator Companion (VCC) and add the "VRChat Package Resolver Tool" and "VRChat SDK - Worlds" packages
- If you see errors relating to Infinite Import Loops, find and delete UdonImportPostProcessor.cs from your project.
Close and Restart Unity.
Resolve any remaining compile errors.
In VCC add the "CyanTrigger" and the "CyanTrigger SDK2 Migrator" packages.
Backup Your Project! If an error occurs, you will need to start over from this point before migrating again.
Find the menu item at "Window/CyanTrigger/Migrate SDK2 Project". This will open the SDK2 Migrator Window
In the SDK2 Migrator Window, check or uncheck the settings to use during migration.
- In the "Directories to Migrate" section, select the folders that the migrator is allowed to search and modify assets.
  - Only Prefabs, Scenes, and Animations will be modified. All other assets, such as Materials or textures, will be ignored.
  - Make sure to include the VRChat Examples folder!
When ready, and you have accepted the risks, click the "Migrate Project" button and in the popup that appears, click "Yes, Migrate Project".
Check the Unity Console window for migration information. There will be warnings and errors!
- Some errors are for information only, such as mentioning an action can't be converted.
- If you get an exception that breaks the migration, copy the error and send it in CyanLaser's discord to help debug the process.
If no major errors, open your world scene and verify in VRChat that everything works.