Installation
- Download the VersionCTRL script
- Unzip the downloaded zip file
- In Cavalry navigate to
Scripts > Show Scripts Folder - Drag the contents of the zip into the Scripts folder
- In Cavalry navigate to
Scripts > VersionCTRL
Getting started
Open any saved .cv scene and the panel will detect it automatically. If the scene has no version history yet, the main button reads Initialize Version Control — click it to create the first log entry and rename the file to YourScene_v1.0.0.cv. From that point on, the Patch / Minor / Major buttons are live.
The script requires that your scene has been saved to disk at least once before version control can be initialized. Unsaved scenes show a prompt to save first.
Workflow tips
Day-to-day iteration: Use Patch for small changes and work-in-progress saves. Use Minor when you reach a stable checkpoint (client delivery, review point). Use Major for significant redesigns or direction changes.
Before a big change: Save a Patch with a clear commit message so you have a named rollback point.
Cleaning up after a project: Run Clean Up Patches to delete intermediate files. The milestone versions (highest patch per minor, latest overall) are automatically kept.
Nested scenes: Enable Referenced File on any scene that another project links to. The referencing project will always see the latest version without you needing to update its asset path.
Main Panel
The compact docked panel is your day-to-day interface.
Status indicator
The bold label at the top shows the current state of the open scene. Colors encode meaning at a glance:
| Color | Meaning |
|---|---|
| Green | Current version — you're on the latest |
| Amber | Warning — older version open, reference outdated, or scene renamed |
| Red | Error — no scene open, log corrupted, or save failed |
When an older version is open, the status reads "v1.2.0 is not the latest — v1.3.0 available" and the version buttons are disabled until you act.
Reference File badge
A small green Reference File label appears below the status when Referenced File mode is active (see below). It is hidden otherwise.
Commit message field
Type an optional note describing what changed before clicking a version button. If left empty, the log entry records "No commit message". The field clears automatically after each save.
Version buttons
| Button | What it does |
|---|---|
| Patch | Saves a new patch version — e.g. v1.2.3 → v1.2.4 |
| Minor | Saves a new minor version, resets patch — e.g. v1.2.4 → v1.3.0 |
| Major | Saves a new major version, resets minor and patch — e.g. v1.3.0 → v2.0.0 |
All three are disabled while an older version is open (to prevent accidental forks).
History and Settings buttons
The two icon buttons to the right of the version buttons open their respective floating panels. Hover over either button for a tooltip.
Contextual action button
The wide button below the version row changes its label and behaviour depending on the current scene state:
| State | Button label | Action |
|---|---|---|
| Up to date | Save | Saves the scene without bumping the version |
| Older version open | Open Newest Version | Opens the latest version from history |
| Referenced File mode | Update Reference Copy | Writes the versionless stable copy without a new version entry |
| Scene renamed | Open Renamed Version | Opens the newest file under the new project name |
| No scene open | Refresh | Re-checks the current scene state |
History Panel
Open with the history icon button (clock icon). A floating panel showing the complete version list for the current scene.
History cards
Each saved version is displayed as a dark card with:
- Version number — e.g.
v1.3.0 - Commit message — what you wrote before saving, or "No commit message"
- Date and time — localized to your system locale
- Open / Active / Deleted button
The Open button opens that version of the scene in Cavalry. The button is labelled Active (and disabled) for the currently open version, and Deleted (and disabled) for entries whose files no longer exist on disk.
Cards are shown newest-first.
Promote to New Version
The Promote to New Version button at the bottom of the history panel is enabled when you have an older version open. It opens a small dialog where you choose to promote the current file to either the next Minor or Major release relative to the newest log entry. The original files stay on disk — promotion creates a new copy at the chosen version number, logs a commit entry, and makes that the new current version.
Use this when you want to roll back to a previous state and continue from there.
Settings Panel
Open with the settings icon button (gear icon). A scrollable floating panel with four sections.
Rename Scene
Renames the scene file and its version log to a new base name. The current version number is preserved — only the project name changes.
- Type the new name in the field (pre-filled with the current base name).
- Click Rename.
- A redirect stub is written to the old log file so that opening an older copy of the scene can still guide you to the new name.
Clean Up Patches
Removes intermediate patch files, keeping only the highest patch per minor version group — plus the overall latest version and the currently open file. Useful after a lot of iterative patching.
- Click Clean Up Patches to see a preview of what would be deleted.
- Confirm to permanently remove the listed files.
- This operation cannot be undone; the log entries for deleted files remain visible in history (shown as Deleted).
Referenced File
Toggle this on when your scene is used as a nested asset in other Cavalry projects.
While enabled, every versioned save also writes a versionless copy of the scene — e.g. MyScene.cv alongside MyScene_v2.1.0.cv. Other scenes that link to the fixed name (MyScene.cv) always receive your latest version automatically, without needing to update their asset path.
Use the Update Reference Copy button in the main panel to push an in-progress save to the stable copy without creating a new version entry.
Debug Logging
Toggle this on before reproducing a crash or unexpected behaviour. A timestamped _debug.log file is written next to your scene, recording every save, UI refresh, and error that passes through the script. Share this file with support when reporting an issue.
The log is off by default and only active for the current session after you enable it.
Version history and log file
VersionCTRL stores its data in a _versioning.json file placed next to your scene, named {SceneName}_versioning.json. This file contains:
- All log entries (version, date, commit message, filename)
- References snapshot per entry — which asset versions were in use at save time
- Referenced File mode flag
- Schema version for forward-compatibility
Do not rename or delete this file manually. If you rename a project outside of VersionCTRL, opening an old file will show an amber warning with an Open Renamed Version button pointing you to the right place.
Notes
- VersionCTRL does not replace Cavalry's native save (
Cmd/Ctrl+S). Both can be used side by side. - Undo is not available at the script level. Use Promote to recover a previous state.