Skip to content

Migration checklist

This is the order that causes the fewest surprises. Skip ahead only when you already know the area is unaffected.

0. Before you touch the place

  • Save the original .rbxl somewhere outside the project.
  • Note the Roblox version/era the place was built for.
  • List the game's hard dependencies: services, data stores, marketplace products, teleports, HTTP endpoints, plugins.
  • Decide whether you are targeting the 2022 API (Nova's backport target) or a newer surface. Newer APIs are often present, but the compatibility pages are the source of truth.

1. Load the place

  • Open the place in NovaStudio.
  • Read the Output window for skipping unknown class lines. Each one is a class to check in the API reference.
  • Open the Explorer and confirm the service tree exists (Workspace, Lighting, ReplicatedStorage, ServerScriptService, StarterGui, StarterPlayer, Players, SoundService, ...).
  • Save a copy immediately. Round-tripping through Nova is the first test of the serializer.

2. Scripts and language

  • Search for type annotations, continue, compound assignment, and string interpolation. They are accepted by the Luau VM; see Scripting and Luau.
  • Search for require paths and confirm every module exists.
  • Search for modern globals that Nova does not register: buffer, vector.
  • Search for deprecated APIs (wait, spawn, delay, lowercase findFirstChild, IsPlaying, Pitch, MinDistance, MaxDistance). They usually still work, but prefer the modern spelling.
  • Replace typeof checks only if something behaves unexpectedly; typeof is supported.

3. Services

  • Replace TextChatService usage with the legacy chat or a custom UI.
  • Replace LocalizationService/LocalizationTable with a string module or per-locale places.
  • Check MarketplaceService product and game-pass flows against the class page.
  • Check DataStoreService against Data stores; remove DataStoreOptions, request-budget, and newer option usage.
  • Check TeleportService flows against the place launcher and reserved server support.
  • Remove VRService, VideoFrame, VoiceChatService, and Open Cloud usage.

4. Data and networking

  • Confirm the server owns all gameplay state.
  • Replace UnreliableRemoteEvent with RemoteEvent.
  • Make RemoteEvent handlers tolerant of objects that have not replicated yet (WaitForChild).
  • Rate-limit and validate every remote that a client can call.
  • Test with two clients, not just Play Solo.

5. Physics and spatial queries

  • Replace Workspace:Raycast with Workspace:FindPartOnRayWithIgnoreList (see Physics).
  • Replace RaycastParams with an explicit ignore list.
  • Replace GetPartBoundsInBox / GetPartsInPart with FindPartsInRegion3WithIgnoreList.
  • Check constraints: Hinge, BallSocket, Spring, Rope, AlignPosition, AlignOrientation, LinearVelocity, AngularVelocity, VectorForce, WeldConstraint, Weld, and Motor6D are present; Prismatic, Cylindrical, Universal, and Plane are not.
  • Re-tune anything that depended on modern solver behavior; Nova uses the PGS solver with modern selection rules.

6. UI

  • List every UIListLayout, UIGridLayout, UITableLayout, UIPadding, UIScale, UICorner, UIGradient, UIStroke, CanvasGroup, and constraint instance.
  • Replace automatic layout with a manual layout pass (Build a UI without UIListLayout).
  • Replace rounded corners, gradients, and strokes with 9-slice images or baked assets.
  • Replace UIAspectRatioConstraint with a size-recalculation function.
  • Check ViewportFrame usage; it is not implemented yet.

7. Audio, animation, avatar

  • Sound playback, groups, rolloff, and effects usually work unchanged.
  • Replace Pitch/MinDistance/MaxDistance aliases with PlaybackSpeed/RollOffMinDistance/RollOffMaxDistance where practical.
  • Confirm animation assets load; Animator:LoadAnimation works, but skeletal skinning and Bone do not.
  • Replace HumanoidDescription customization with legacy body parts and clothing.
  • Remove SurfaceAppearance, WrapLayer, and WrapTarget dependence.

8. Assets and content

  • Confirm every rbxassetid:// asset resolves through the deployment's asset proxy.
  • Re-upload or re-map assets that only exist on Roblox's marketplace and are not available to the Nova deployment.
  • Check MeshPart/SpecialMesh and CSG unions in the world.
  • Replace SurfaceAppearance with baked textures.

9. Test and publish

  • Play Solo.
  • Local server with one client.
  • Local server with two clients.
  • Join from the web client if you support it.
  • Check the Output window for permission errors, failed asset loads, and missing members.
  • Publish and rejoin from a fresh client.

Known-good escape hatches

When a modern API is missing, the legacy equivalent is usually still present:

Modern API Nova alternative
WorldRoot:Raycast / RaycastParams Workspace:FindPartOnRayWithIgnoreList
GetPartBoundsInBox / GetPartsInPart FindPartsInRegion3WithIgnoreList
UIListLayout / UIGridLayout Manual Position/Size pass
UICorner / UIStroke / UIGradient 9-slice images or baked textures
UIAspectRatioConstraint Recompute Size from AbsoluteSize
ProximityPrompt ClickDetector + BillboardGui
TextChatService Legacy chat / bubble chat
HumanoidDescription Legacy body parts and clothing
UnreliableRemoteEvent RemoteEvent

If a missing API is a hard blocker, document it in the issue tracker with the class/member name from the reference page. The compatibility page shows which gaps affect the most classes.