Skip to content

Use the Godot Plugin

The FlexVault Godot plugin integrates FlexVault directly into the Godot Editor. It takes automatic draft snapshots in the background and after high-entropy edits so your project files stay protected, displays modified files, and lets you publish, sync, and resolve conflicts without leaving Godot.

The Godot plugin is in beta

If you run into issues, have questions, or want to share feedback, join the FlexVault Discord.

Compatibility

Supported Godot Engine
Godot 4.0 – 4.3+

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

Confirm the following prerequisites before setting up the plugin:

  • You have Godot 4.0, 4.1, 4.2, 4.3, or later 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 Godot project folder is placed inside an initialized FlexVault workspace.

Install the plugin in your project

  1. Download the latest release archive fxv-godot-plugin.zip from GitHub Releases (or download a versioned archive fxv-godot-plugin-<version>.zip).
  2. Extract the archive into your Godot project root. The archive itself contains the addons/flexvault/ folder, so extracting it adds that folder to your project; it does not need to exist beforehand. If your project already has an addons/ folder from other plugins, extracting merges flexvault/ into it alongside them. Either way, you should end up with: 
    res://
└── addons/
    └── flexvault/
        ├── plugin.cfg
        ├── flexvault_plugin.gd
        ├── core/
        └── ui/
  3. Open your project in the Godot Editor.
  4. In the top menu, go to Project > Project Settings > Plugins.
  5. Locate FlexVault in the list and check Enable.

Configure plugin settings

The plugin auto-detects your fxv binary from standard system install locations and your system PATH. If you need to specify a custom binary path or visual diff tool:

  1. In the top menu, go to Editor > Editor Settings.
  2. In the top-right corner of the Editor Settings window, enable Advanced Settings. The Version Control category, and the FlexVault settings under it, are hidden until you turn this on.
  3. In the categories list on the left, navigate to Version Control > FlexVault.
  4. Adjust your settings:
  5. Binary Path: Enter an explicit path to fxv.exe (Windows) or fxv (macOS/Linux). Leave blank to use auto-discovery. On Windows, the file picker filters for executable files (*.exe).
  6. Diff Tool: Enter the path to your preferred external diff application (such as VS Code, Beyond Compare, WinMerge, or KDiff3). Leave blank to use system defaults or environment variables (FXV_DIFF_TOOL or DIFF).
  7. Auto Refresh: Controls whether the plugin automatically refreshes repository status every 10 seconds while the editor is active.

Access the plugin interface

Once enabled, the plugin provides access through a bottom dock panel:

Bottom dock panel

Click FlexVault in the bottom dock of the Godot Editor to expand the main panel.

The toolbar at the top displays:

  • The Sync Workspace button to sync with the remote repository.
  • Your active branch, current revision, and how many revisions your workspace is behind the remote.

The panel contains two main tabs:

  • Changes: Displays modified, added, deleted, and conflicted files alongside snapshot and publish controls.
  • History: Displays commit history and allows switching revisions.

How to work with your project files

Viewing changed files

The Changes tab lists all files in your workspace that differ from the current revision, along with their size and color-coded status:

  • Added (Green): A new file added to the project.
  • Modified (Blue): An existing file with local edits.
  • Deleted (Red): A tracked file removed from the workspace.
  • Conflicted (Orange): A file where both you and a teammate made overlapping changes.

Automatic companion file handling

Godot creates companion .import metadata files and .uid files for resources. The FlexVault plugin automatically coordinates these companion files:

  • Reverting or resolving an asset (such as icon.svg) automatically includes its companion files (icon.svg.import and icon.svg.uid).
  • Selecting a companion metadata file automatically includes its corresponding asset file.
  • Selecting a folder automatically recurses and bundles all child files and their companions while safely excluding internal directories (.godot/ and .fxv_workspace/).
  • Companion files for deleted assets are detected and handled even if they have already been removed from disk.

Saving your local work (Snapshots)

A snapshot saves your current work locally as a checkpoint on your computer. Your teammates will not see these 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 file or folder deletions), and periodically in the background while you have pending changes.

Sharing work with your team (Publish)

When your work is ready to share with the rest of the team:

  1. Open the Changes tab in the FlexVault dock.
  2. Enter a description in the Description box summarizing your changes. A description is required before publishing.
  3. Click Publish.

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

Getting updates from teammates (Sync)

To bring down new revisions published by your team:

  1. Click Sync Workspace in the top toolbar of the FlexVault panel (or select Project > Tools > FlexVault: Sync Workspace from the main menu).
  2. The plugin pulls remote revisions and updates your workspace.
  3. Godot automatically rescans the resource filesystem once the sync completes.

Undoing changes (Revert)

To discard uncommitted changes and return files to their base state:

  1. In the Changes tab, select one or more files (multi-selection is supported).
  2. Click Revert Selected.
  3. A confirmation dialog appears showing the number of selected files and warning that uncommitted changes will be lost. Click OK to confirm.

The plugin reverts the selected files along with any companion .import and .uid files, then triggers a filesystem rescan in Godot.

Comparing changes with Diff Base

To review your edits against the base version before saving or publishing:

  1. Select a file in the Changes tab list. If multiple files are selected, the diff viewer opens for the first selected file.
  2. Click Diff Base.

The plugin extracts the base version into a temporary folder and launches your configured external visual diff tool (such as VS Code, Beyond Compare, WinMerge, or KDiff3).

Resolving conflicts

When a sync results in conflicting changes:

  1. Conflicted files appear with orange status badges in the Changes list, and resolution buttons become visible in the toolbar. Hover over a conflicted file 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 directory that the other kept as a file (or vice versa).
  2. Choose your resolution scope:
  3. Resolve selected files: Select one or more conflicted files in the list.
  4. Resolve all files: Deselect all files in the list to apply the resolution to all conflicts in the workspace.
  5. Click either:
  6. Resolve (Mine): Keeps your local version and marks the files resolved.
  7. Resolve (Theirs): Discards your local version and adopts the incoming remote version.
  8. The plugin applies the resolution to the files and their companion metadata files, then rescans the filesystem.

Browsing history and jumping to revisions

To inspect past changes or switch your workspace to an earlier checkpoint:

  1. Open the History tab in the FlexVault dock.
  2. Click Refresh History to load recent revisions (the view fetches the last 50 commits).
  3. The list shows the revision identifier, author, timestamp, and description. The active revision is highlighted in cyan with a dot indicator (●).
  4. To switch your workspace to a specific revision, select that row and click Switch to Revision (Goto).
  5. The plugin runs safety checks, switches the workspace to the target revision, and rescans the project assets.

Updating the plugin

When a new version of the plugin is released:

  • If installed from a release archive: Download the latest fxv-godot-plugin.zip from GitHub Releases and replace the existing addons/flexvault/ folder in your project.
  • If your team manages the project repository: Simply sync your workspace. Godot reloads the updated plugin scripts automatically.

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