Migrating from v1
Why v2 changed, and how to move a v1 project to it
Updated
v2 reads configs and file names differently, so a v1 project needs a new config and some renamed files.
Why v2 Changed
v1 had many small rules that could disagree, and each problem got its own switch or marker file. v2 has three rules that hold everywhere:
- The outermost route governs. In v1 the deepest rule won, so
ReplicatedFirst/main.client.luauwent toStarterPlayerScripts, and holding a folder still took.structureor.sync. In v2 a folder's route covers everything inside it. - Only
@routes a name. v1 read routes from prefixes and suffixes, soHttpClient.luauwent to the client asHttp. In v2 only a name likeSave@server.luauroutes, and Rojo's.serverand.clientkeep their meaning. - You write every route. v1's keywords and wrapper folders were built in, and unmatched files went to
ReplicatedStorage. In v2 only the routes you declare exist.rogen initdeclares a*route for the files that match none, and without it such a file is left out with a warning.
Move a Project to v2
Set the v1 Config Aside
Every command stops with legacy.config while a v1 config is in the folder. Rename it, and any other *.rogen.json v1 read:
mv .rogen.json .rogen.json.v1Run rogen init
Install v2 and run rogen init. It writes default.rogen.json, taking in an existing default.project.json. Run the git rm --cached command it prints.
Match Your Old Paths
To keep your v1 require paths, write v1's wrapper folders into the targets:
{
"routes": {
"server": "ServerScriptService/server",
"client": "StarterPlayer/StarterPlayerScripts/client",
"shared": "ReplicatedStorage/shared",
"*": "ReplicatedStorage/shared"
}
}Leave the wrappers out if you used unwrap, and capitalise them if you used casing: "PascalCase". Add each of your aliases as a route.
Rename Files Until rogen check Is Clean
rogen checkEach v1 name that no longer routes gets a warning that names the fix. The step is done when rogen check prints nothing. Files that v1 built only under a tag get no warning, so move them as Tags describes.
Compare With Your v1 Build
Run rogen serve and compare Studio's Explorer with your v1 build. When every script sits where it did, delete .rogen.json.v1.
What Replaces Each v1 Feature
| v1 | v2 |
|---|---|
source, -s | sourcePaths |
aliases, built-in keywords | routes |
casing, unwrap, .unwrap | the route's target path |
verbatim, .verbatim | not needed |
| keywords in names | @key or a routing folder. See Names |
tags, -t | an overlay source path. See Tags |
modes, -m | a second config, such as dist.rogen.json |
a mode's build, -b | compiledPath |
a mode's output, -o | none. rogen build -o now builds a place |
project, template, -p | tree in the config |
.structure | a marker file such as @shared |
.sync | a $path node in the tree |
^ at the service's root | ^ at the route's target |
| several places from one config | a config per place |
Names
v1: src/Combat/server_Combat.luau v2: src/Combat/Server/Combat.luau
v1: src/Combat/Combat_Server.luau v2: src/Combat/Combat@server.luau
v1: src/Combat/Types.shared.luau v2: src/Combat/Types@shared.luau
v1: src/Combat/Hud.client.luau v2: unchanged
v1: src/Combat/.server v2: src/Combat/@serverTags
Few projects used tags. Move a file that v1 built only under a tag into a folder of its own, and list that folder as a later source path, where its file replaces the one at the same path:
v1: src/Teleport/TeleportDev.luau (tag dev)
v2: dev/Teleport/Teleport.luau (the dev source path)Write a second config without it, such as release.rogen.json with "sourcePaths": ["src"] and its own name.