Use the Unity Plugin¶

The FlexVault Unity plugin integrates FlexVault directly into the Unity Editor. It takes automatic draft snapshots in the background and after high-entropy edits so your assets stay protected, tracks asset changes alongside companion .meta files, and lets you publish and sync updates without leaving Unity.

Compatibility¶

The plugin enforces semantic version checks against the fxv binary and blocks incompatible CLI versions to prevent wire format issues. If your installed fxv is out of range, the plugin's error message states the exact range it requires.

Before you begin¶

Ask your team lead or technical team to confirm:

• You have Unity 2021.3 LTS, 2022.3 LTS, or Unity 6+ installed.
• The FlexVault CLI tool is installed on your computer (see Install FlexVault). If it's incompatible with this plugin version, the plugin reports the required range when you try to use it.
• Your project is placed inside a FlexVault workspace.

Enable the plugin in your project¶

Choose whichever method fits your setup:

Method 1: Automatic team setup¶

If your team already added FlexVault to your project configuration, you do not need to install anything manually.

When you open the project in Unity, the editor downloads and enables the plugin automatically. You can go straight to Connect and sign in below.

Method 2: Add package from Git URL¶

If you are adding the plugin to a project yourself, using the repository URL is the simplest method:

1. Open your project in the Unity Editor.
2. In the top menu, click Window > Package Management > Package Manager.
3. Click the + button in the top-left corner of the window and select Install package from git URL.
4. Paste the repository URL:

   https://github.com/FlexVaultSCM/fxv-unity-plugin.git
   

   To pin your project to a specific release version, add the version tag at the end (for example, https://github.com/FlexVaultSCM/fxv-unity-plugin.git#v0.3.0).
5. Click Install.

Unity downloads the plugin, adds required dependencies, and displays FlexVault in your menus. When you share your workspace changes, other team members receive this package setup automatically.

Method 3: Add package from a release file¶

This method does not require Git. Unity's Package Manager can install a release .tgz file either by URL or from a local copy you download first.

Unity installs the plugin into your project right away.

Unity's generated folders are excluded automatically¶

The first time the plugin starts in a project, it adds Unity's generated folders, such as Library/, Temp/, Logs/, and obj/, to .fxvignore so FlexVault never tracks them. This happens silently; check the Console for a [FlexVault] Added default ignore(s) to .fxvignore message if you want to confirm it ran.

Connect and sign in¶

After installing the plugin, confirm that Unity is connected to FlexVault:

1. In the top menu, go to Edit > Project Settings.
2. In the list on the left, click Version Control.
3. In the Mode dropdown at the top, select FlexVault.
4. Click Test CLI Connection. A message confirms that Unity can talk to FlexVault. If the CLI executable is not found, verify that FlexVault is installed on your machine.
5. Under User Identity & Authentication, confirm your username is shown. If not, enter your username and click Log In.

Open the FlexVault window¶

Go to Window > Version Control > FlexVault.

Dock this tab next to your Project or Inspector tab so it stays handy while you work.

The window gives you two views:

• Changes: Shows assets you have modified, added, or deleted. This is where you save progress, sync your workspace, and share work with your team.
• History: Shows recent updates published by you and your teammates.

The toolbar at the top of the window shows your current branch, the revision your workspace is synced to, and whether you are behind the remote. From there you can also sync or jump to a specific revision at any time.

How to work with your assets¶

Spotting changes in the Project window¶

As you edit scenes, tweak materials, or import textures, small color badges appear on asset icons in your Project window:

• [+] Green: A new asset you added to the project.
• [~] Blue: An existing asset you modified.
• [-] Red: An asset you deleted.
• [!] Orange: A conflict where both you and a teammate edited the same asset.

You do not need to manage Unity's companion .meta files yourself. The plugin automatically pairs every asset with its .meta file whenever you save, revert, or share changes.

Saving your local work (Snapshots)¶

A snapshot is like a personal save point or checkpoint. It saves your current progress locally on your computer. Nobody else on your team sees your snapshots until you choose to publish them.

You do not need to trigger snapshots yourself. The plugin takes them automatically after high-entropy edits (bulk reimports, large scene edits, and asset deletions), and periodically in the background while you have pending changes.

Sharing work with your team (Publish)¶

When your work is ready for the team to use:

1. Open the Changes tab in the FlexVault window.
2. Type a clear description of what you changed (for example, Added hero character idle animations). A description is required before the publish button becomes active.
3. Click Publish to Remote.

The plugin takes a final snapshot and publishes your updates to the team repository in one step.

Getting updates from teammates (Sync)¶

To download new work published by your team, click Sync Latest in the toolbar at the top of the FlexVault window. The button shows how many revisions you are behind when your workspace is out of date.

If you are behind the remote and try to publish, the plugin detects this automatically. The publish button changes to Sync & Publish and prompts you to confirm before it syncs your workspace and then publishes your changes in one step.

Unity reloads the project assets automatically after a sync completes.

Undoing changes (Revert)¶

If you made changes you do not want to keep and want to reset an asset back to the team version:

• In the Changes tab, click Revert next to the asset you want to discard.
• Or right-click the asset in the Project window and choose Assets > FlexVault > Revert Selected.

Confirm the prompt.

The asset and its companion .meta file immediately return to their last published state.

Handling conflicts¶

If you and a teammate edited the same asset at the same time:

1. A conflict banner appears in the Changes tab, and the asset displays an orange [!] badge. Hover over the asset name to see why it conflicts: both sides changed its content, one side deleted it while the other changed it, or one side replaced it with a folder that the other kept as a file (or vice versa).
2. Next to the file, choose:
   • Mine: Keeps your local version and discards the incoming team version.
   • Theirs: Discards your local edits and takes the teammate's published version.

Updating the plugin¶

When a new version of the plugin is released:

• If installed via Git URL: Open Window > Package Management > Package Manager, change the filter dropdown in the top-left to In Project, select FlexVault VCS, and click Update in the bottom-right corner.
• If installed via a release file: Repeat Method 3 with the latest release file, by URL or downloaded file.
• If your team manages the project repository: Simply sync your workspace. Unity automatically loads whatever plugin version is pinned in the project.

Watch the announcements channel on the FlexVault Discord for new plugin and CLI release notices.