ubuild

Unreal Engine project management CLI tool for Agent integration.

Features

• Project Detection (ubuild list): Detect and analyze Unreal Engine projects
• Engine Information (ubuild engine): Resolve engine associations and versions
• Build Execution (ubuild build): Build projects with various configurations
• Project Generation (ubuild generate): Generate IDE project files (Visual Studio, VSCode, etc.)
• Project Initialization (ubuild init): Create new Unreal Engine projects (C++ or Blueprint)
• Run Project (ubuild run): Run Unreal Engine Editor or Game executable
• Update Tool (ubuild update): Update ubuild to the latest version
• Generate Compile Commands (ubuild gencodebase): Generate compile_commands.json for IDE code completion

Installation

# Global installation
npm install -g @zitool/ubuild

# Or as project dependency
npm install @zitool/ubuild --save-dev

Usage

CLI Commands

# Detect project in current directory
ubuild list
ubuild ls

# Show engine information
ubuild engine

# Build project (default: Editor, Development, Win64)
ubuild build
ubuild build --target Game --config Shipping
ubuild build --platform Linux --verbose

# Generate IDE project files
ubuild generate
ubuild generate --ide vscode

# Initialize new project
ubuild init --name MyProject --type cpp
ubuild init --name MyBlueprintProject --type blueprint

# Run project (Editor or Game)
ubuild run
ubuild run --target Game --config Development
ubuild run --build-first

# Generate compile commands for IDE
ubuild gencodebase
ubuild gencodebase --target Editor --config Development

# Update ubuild to latest version
ubuild update

Programmatic API

import UEBuildAPI from '@zitool/ubuild';

// Detect project
const project = await UEBuildAPI.project.detect();

// Resolve engine
const engine = await UEBuildAPI.engine.resolve();

// Build project
const buildResult = await UEBuildAPI.build.execute({
  target: 'Editor',
  config: 'Development',
  platform: 'Win64'
});

// Generate project files
const genResult = await UEBuildAPI.generate.generate({
  ide: 'vscode'
});

// Initialize new project
const initResult = await UEBuildAPI.init.initialize({
  name: 'MyProject',
  type: 'cpp'
});

// Create concurrent builder/runner
const builder = UEBuildAPI.concurrent.createBuilder();
const runner = UEBuildAPI.concurrent.createRunner();

Command Reference

ubuild list / ubuild ls

Detect Unreal Engine project in current directory.

Options:

• -r, --recursive: Search recursively for .uproject files
• -j, --json: Output result as JSON

ubuild engine

Display engine information for the current project.

Options:

• -p, --project <path>: Path to project directory or .uproject file
• -j, --json: Output result as JSON
• -v, --verbose: Show verbose engine detection details

ubuild build

Build Unreal Engine project.

Options:

• -t, --target <target>: Build target (Editor, Game, Client, Server) - default: Editor
• -c, --config <config>: Build configuration (Debug, DebugGame, Development, Shipping, Test) - default: Development
• -p, --platform <platform>: Build platform (Win64, Win32, Linux, Mac, Android, IOS) - default: Win64
• --project <path>: Path to project directory or .uproject file
• --engine-path <path>: Path to Unreal Engine installation
• --clean: Clean build (rebuild everything)
• --verbose: Verbose output
• --dry-run: Show what would be built without actually building
• --list-targets: List available build targets for project

ubuild generate / ubuild gen

Generate IDE project files.

Options:

• -i, --ide <ide>: IDE type (sln, vscode, clion, xcode, vs2022) - default: sln
• --project <path>: Path to project directory or .uproject file
• --engine-path <path>: Path to Unreal Engine installation
• --force: Force regeneration of project files
• --list-ides: List available IDE types

ubuild init

Initialize a new Unreal Engine project.

Options:

• -n, --name <name>: Project name (alphanumeric, underscores, hyphens) - required
• -t, --type <type>: Project type (cpp, blueprint, blank) - default: cpp
• --template <template>: Project template (Basic, FirstPerson, ThirdPerson, etc.) - default: Basic
• -d, --directory <path>: Directory to create project in (default: ./)
• --engine-path <path>: Path to Unreal Engine installation
• --force: Force initialization even if directory is not empty
• --dry-run: Show what would be created without actually creating

ubuild run

Run Unreal Engine project (Editor or Game executable).

Options:

• -t, --target <target>: Run target (Editor, Game, Client, Server) - default: Editor
• -c, --config <config>: Build configuration (Debug, DebugGame, Development, Shipping, Test) - default: Development
• -p, --platform <platform>: Platform (Win64, Win32, Linux, Mac, Android, IOS) - default: Win64
• --project <path>: Path to project directory or .uproject file
• --engine-path <path>: Path to Unreal Engine installation
• --dry-run: Show what would be run without actually running
• --build-first: Build the project before running
• --no-build: Do not build, just run existing executable
• --detached: Run the process in detached mode (non-blocking)
• --args <args...>: Additional arguments to pass to the executable

ubuild gencodebase

Generate compile_commands.json for IDE (VSCode clangd, CLion, etc.).

Options:

• -t, --target <target>: Build targets (Editor is recommended for IDE code completion) - default: Editor
• -c, --config <config>: Build configuration (Debug, DebugGame, Development, Shipping, Test) - default: Development
• -p, --platform <platform>: Platform (Win64, Win32, Linux, Mac) - default: Win64
• --project <path>: Path to project directory or .uproject file
• --engine-path <path>: Path to Unreal Engine installation
• --include-plugin-sources: Include plugin sources in compile commands (default: true)
• --no-include-plugin-sources: Exclude plugin sources
• --include-engine-sources: Include engine sources in compile commands (default: true)
• --no-include-engine-sources: Exclude engine sources
• --use-engine-includes: Use engine includes in compile commands (default: true)
• --no-use-engine-includes: Do not use engine includes
• --json: Output result as JSON

ubuild update

Update ubuild to the latest version.

Automatically detects whether ubuild is installed globally or locally and updates accordingly.

Engine Detection

The tool automatically detects Unreal Engine installations using:

1. Windows Registry: HKEY_CURRENT_USER\SOFTWARE\Epic Games\Unreal Engine\Builds
2. Launcher Installation: %LOCALAPPDATA%\UnrealEngine\Common\LauncherInstalled.dat
3. Environment Variables: UE_ENGINE_PATH, UE_ROOT, UNREAL_ENGINE_PATH
4. Manual Specification: --engine-path option

When multiple engines are found, the tool will prompt for selection during initialization.

Development

# Clone repository
git clone <repository-url>
cd ubuild

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

License

MIT