Introduction

Scene Fusion is a tool that allows level designers to work together in real-time. It synchronizes changes as they are made to facilitate instant feedback. It is focused on sychronizing in-scene changes, and operates under the assumption that a revision control system is used to synchronize project files. Source control is still strongly recommended to track changes project-wide.

Workflow Considerations (Unity Engine)

Getting Set Up

Prior to starting the collaboration session, each team member must sychronize their project copies with each other. If source control is used, each team member can check out the same branch, or create their own branches from a common branch.

The recommended workflow to start collaborating is to designate one person as the 'host'. This person starts the session, is the last to leave the session, and will be responsible for saving the scene file(s) and committing them to revision control.

To start, the host should open the desired scene file and start the session. It will take a little bit of time for Scene Fusion to sychronize the scene data with the session. Once the data is synchoronized, the other users can join the session.

Using Scene Fusion with Source Control

Scene Fusion can synchronize some asset files, such as terrain or prefabs. This requires some care when using source control as it can generate merge conflicts.

Your team will experience merge conflicts in scene files and possibly in synced assets (terrain/terrain layers/lighting settings) or metafiles that were created or modified during the session. This is because the local file ids and guids will be different.

There are two possible solutions: The first is to choose a single person as the 'host' whose responsible for checking in all new files generated or modified during the Scene Fusion session, while all other participants simply discard their local changes. The second is to have each participant create a branch from the master branch, and any or all of them may check in the changes. This allows the 'host' to be chosen after the fact, and only one branch will be merged back into the master branch.

Folders to Ignore

You do not need to commit the KinematicSoup folder in the root of your project to source control. It contains logs and server config files. It is recommended you add a rule in your source control to ignore this folder.

During The Session

Scene Fusion will attempt to locate the copy of the scene file used in the session for each new person joining. If it cannot locate the scene file it will create it using the same filename and path as the file opened by the host. If it does find the scene file, it will open it. If any differences are detected, they are discarded so that the scene file matches the scene used to create the session.

Gameobjects in the scene are locked when selected by a user, and unlocked when unselected or when the user disconnects. When an object is locked, it can only be changed by the user who owns the lock.

What is Synchonrized

Scene Fusion will not sync game objects that have any of the following HideFlags: HideInHierarchy, DontSaveInEditor. It will also not sync game objects with an sfIgnore or sfGuidList component. Children of unsynced game objects will also not sync.

Terrain editing is an exception to the lock rule. Multiple users may edit a terrain simultaneously. Be aware that it can take some time for changes to synchronize, and the changes from one user can replace the changes from another if they are editing the same location.

Assets and Prefabs

Scene Fusion will sync scene changes, changes to terrain and terrain layer assets, lighting settings, and materials. It will not sync other asset types, assets that are not referenced in the scene, asset deletions or renames, or changes to code or existing prefabs. Scene Fusion attempts to block prefab modifications by other plugins or code, though this may prevent the proper operation of those plugins or code. Modification of an existing prefab can happen if it's changed on disk, such as being updated from revision control. If that happens, the behavior of Scene Fusion is undefined.

Adding new prefabs during a session is possible, however once the prefab is created it cannot be edited during the session. Scene Fusion will automatically sync prefabs created during a session with other users. Deleting and renaming prefab assets during a session is not recommended. Deleting a prefab asset will not delete the prefab for other users and will not unlink the prefab instances from the prefab for other users. Renaming a prefab will cause a duplicate prefab to be created for other users at the new path. Instances of a missing prefab are represented at '?' icons in the scene, which are replaced automatically once the prefab is available.

Special Considerations

Play Mode

Scene Fusion allows users to enter and leave play mode. Entering play mode will disconnect you from the session temporarily. Scene Fusion will reconnect once you enter play mode. Changes made by others are not applied until play mode is exited.

Recompiles

In the event a recompile is triggered, the user will be disconnected from the session. When the recompile is completed, Scene Fusion will establish a fresh connection to the session.