Kimura SCM

Appearance

Native Unreal Project Setup ​

Overview ​

This guide shows one practical way to set up a native Unreal Engine project with Kimura SCM. The goal is to keep the Unreal Engine source, the game project, and reusable plugins in separate repositories, then bring them together in one workspace through repository links (repository map).

This layout is useful when teams build Unreal Engine from source, maintain project-specific plugins, or need to version engine, game, and plugin changes independently.

Use separate repositories for the major ownership boundaries:

  • Engine: the Unreal Engine source used by the team. This repository typically sits at the root of the workspace.
  • Game: the game project files.
  • PluginName: each shared plugin that should have its own history and release cadence.

A combined workspace can then map those repositories into one local tree, for example:

text
UnrealWorkspace/
  Engine/
  Templates/
  GenerateProjectFiles.bat
  Game/
    Game.uproject
    Plugins/
      PluginName/

In that example, the repository map would link / to the engine repository, /Game to the game repository, and /Game/Plugins/PluginName to the plugin repository.

Prerequisites ​

Before starting, make sure you have:

  • Kimura SCM installed.
  • A running Kimura server.
  • A user account with permission to create repositories, repository maps, and workspaces.
  • Access to Epic's Unreal Engine source repository if you plan to build the engine from source.
  • Visual Studio or another supported Unreal Engine build environment.

Use the Visual Server to start the Kimura server if this is a first-time setup. Use the Visual Client for the workspace, repository-link, ignore-rule, and submit steps in this guide.

Create the Repositories ​

Create separate Kimura repositories for each major component.

For a typical source-built Unreal project, create:

  • an engine repository,
  • a game project repository,
  • one repository for each reusable plugin.

For the engine repository, use a version-based name so it is obvious which Unreal source baseline it contains, for example ue-5.8.0.

You can create these from the Visual Client administration tools if your account has permission. You can also use the KSCM CLI when scripting setup, but the rest of this guide assumes the Visual Client workflow.

Import Unreal Engine Source ​

Start by putting the Unreal Engine source into its own workspace and repository.

  1. Sync or clone Unreal Engine source from Epic's GitHub repository into a local Unreal root folder (the folder that contains Engine, Templates, and root files such as Setup.bat).
  2. If you cloned from GitHub, run Setup.bat from the Unreal root to download required dependencies.
  3. Do not generate project files or a project solution yet, and do not add any generated build outputs to Kimura. Keep this initial import source-only.
  4. In the Visual Client, create a workspace using the local Unreal root path: the folder that contains Engine, Templates, and root batch files such as Setup.bat.
  5. Mark everything for add, then prune out Setup.bat if you do not want to version it.
  6. Submit the initial engine source change list.

This first submit can be large. Let it complete before adding ignore rules, generating project files, or building the engine in that folder.

Add Engine Ignore Rules ​

After the initial engine source is submitted, add ignore rules for Unreal-generated files.

  1. Select the engine repository root in the Visual Client workspace tree.
  2. Open the Ignore rules tab.
  3. Apply an Unreal Engine ignore preset first.
  4. Add manual rules only if needed for branch- or team-specific generated folders (for example build outputs, intermediate files, saved data, and derived data caches).
  5. Applying a preset, adding or modifying rules automatically marks .kscmignore for add or edit and places it in a change list.
  6. Submit the .kscmignore change list.

The .kscmignore file is stored in and bound to the engine repository. The game project and each plugin repository use their own .kscmignore files.

Build the Engine ​

Build the engine after source and ignore rules are in place.

  1. Generate project files.
  2. Build the editor with your chosen supported build tool.
  3. Leave generated files untracked unless your team has a specific reason to version them.

If the build creates extra files that appear in reconcile views, update the engine .kscmignore rules and submit that change.

Create the Game Project Repository ​

Create the game project after the engine is available locally.

  1. Launch the built editor.
  2. Create a new C++ project in a folder outside the engine source folder.
  3. Close the editor after the project opens successfully.
  4. In the Visual Client, create or open a workspace that maps the game repository to the project folder.
  5. Mark the project files for add and submit the initial project change list.

Keep the project repository focused on project-owned files. Shared plugins that need their own lifecycle should be mapped separately under Game/Plugins/PluginName.

Add Project Ignore Rules ​

Add ignore rules for the game project repository before regular work starts.

  1. Select the game project root in the Visual Client workspace tree.
  2. Open Ignore rules.
  3. Add an Unreal project ignore preset or manually exclude generated folders such as Binaries, Intermediate, Saved, and DerivedDataCache.
  4. Confirm the .kscmignore file is under the game project repository link, not the engine repository link.
  5. Submit the .kscmignore change list.

This keeps the project change lists focused on source, content, configuration, and other files the team intentionally versions.

Add Plugin Repositories ​

Use separate plugin repositories when a plugin should be shared between projects, reviewed independently, or released on its own schedule.

For each plugin:

  1. Create a Kimura repository for the plugin.
  2. Place the plugin under the project, usually at Game/Plugins/PluginName.
  3. Map that folder to the plugin repository with a repository link.
  4. Add and submit the plugin source files.
  5. Add plugin-specific ignore rules if the plugin creates generated files.

For the Kimura Unreal plugin itself, see Plugin Setup. That guide documents the project-plugin installation path and connection requirements.

Create the Repository Map ​

After the individual repositories are ready, create a repository map that links them into one Unreal layout.

Note: Repository-map editing is planned to be revamped in a future version. In the current version, it can be unclear which map you are editing versus which map is currently used by the selected workspace.

Use the Visual Client Repository Links tab for this. You can edit the current map, but for this guide create and save a new named map so the setup is explicit and easy to review.

  1. Open Repository Links in the Visual Client.
  2. Start from the current workspace mappings, or click Select repository map from server if you want to use an existing map as a base. If the engine workspace created earlier in this guide is still available, it is a good base because its root mapping already points to the engine repository.
  3. In the mapping list, add or edit links so the layout includes engine at /, game at /Game, and plugins under /Game/Plugins/<PluginName>. You can right-click items in the list to add, edit, or remove links directly.
  4. Verify there are no overlapping paths and that each link points to the intended repository and branch.
  5. Click Save repository map to server, enter a new map name, and keep overwrite disabled.
  6. Click Apply to apply the selected mappings to the current workspace.

A typical repository map looks like this:

text
/                          -> ue-5.8.0/main
/Game                      -> Game/main
/Game/Plugins/PluginName   -> PluginName/main

Share the Repository Map for User Workspaces ​

Use this repository map as the shared source of truth for developer workspaces.

  1. Give the map a clear project/version name so users can identify it quickly (for example {ProjectName}-native-ue5.8.0-main).
  2. Confirm the active links still match the intended layout before sharing (/, /Game, and plugin paths under /Game/Plugins/...).
  3. Have each developer create their own workspace from this repository map.
  4. Recommend a local workspace root such as C:/Workspaces/{NativeProjectName}, then sync.

If you later change repository links, click Apply and have users sync their workspaces again.

Open the Project in Unreal ​

Open the project from a workspace created from the shared repository map once sync is complete.

  1. Launch the editor built from the workspace engine, or open the .uproject with the matching source-built engine.
  2. Let Unreal finish any project file or module checks.
  3. Enable and connect the Kimura Unreal plugin if the project uses editor-integrated source control.
  4. Confirm the plugin connects to the workspace that contains the project path.

The Unreal plugin expects the workspace and repository links to already be correct. Use the Visual Client to fix workspace mapping issues before troubleshooting the plugin.

Verify the Setup ​

Before handing the workspace to the team, verify the basic workflow.

  1. Create a new clean workspace from the same repository map and sync it fully.
  2. Generate project files so the generated solution includes both engine and game.
  3. Build the editor and run the project once.
  4. In the Visual Client, reconcile and confirm build artifacts are ignored and do not appear for add.
  5. If generated files appear, update the relevant repository .kscmignore file, then submit that ignore-rule change.

Common Issues ​

Files Appear Under the Wrong Repository ​

Check the repository links for the workspace. The path for each link must start with / and is relative to the workspace root. Nested plugin links should point exactly at the plugin folder, such as /Game/Plugins/PluginName.

Ignore Rules Apply to One Repository but Not Another ​

Ignore rules are stored in .kscmignore per repository. Add rules separately for the engine, game, and plugin repositories.

Unreal Generates Many Extra Files ​

Build outputs and caches should usually be ignored. Add ignore rules for generated folders, then reconcile again to confirm the workspace is clean.

The Unreal Plugin Cannot Find the Workspace ​

The plugin filters available workspaces by the current project path. Confirm the project is inside the selected workspace and that the repository map includes the project repository link.