Command-line tool for creating UntoldEngine game projects.

The untoldengine CLI tool allows you to scaffold new game projects using UntoldEngine from the terminal. This is an optional tool - you can also create projects using the Untold Editor GUI.

• macOS 14.0 or later
• Swift 6.0 or later
• Xcode 15.0 or later (for building)

From the repository root:

# Clone the repository (if you haven't already)
git clone https://github.com/untoldengine/UntoldEngine.git
cd UntoldEngine

# Run the install script
./scripts/install-untoldengine-create.sh

This will build the CLI in release mode and install it to /usr/local/bin, making it available globally.

If you prefer to build manually from this directory (Tools/UntoldEngineCLI):

# Debug build
swift build

# Release build
swift build -c release

Once installed using the script, you can use untoldengine from anywhere:

# Show help
untoldengine --help

# Create a macOS project
cd ~/anywhere
mkdir MyGame && cd MyGame
untoldengine create MyGame

# Create an iOS project
mkdir MobileGame && cd MobileGame
untoldengine create MobileGame --platform ios --bundle-id com.company.game

# Create a visionOS project
untoldengine create VRGame --platform visionos

# Create a multi-platform project (macOS, iOS, visionOS)
mkdir CrossPlatformGame && cd CrossPlatformGame
untoldengine create CrossPlatformGame --platform multi --team-id YOUR_TEAM_ID

Runs Blender in background mode to convert a USD/USDZ asset into the engine's .untold runtime format. The command can be run from any directory.

untoldengine export \
  --input /path/to/model.usdz \
  --output /path/to/model.untold \
  --convert-orientation \
  --compress-geometry

Writes, removes or lists the gaussianAsset records of a .untold asset so an entity's mesh gets a cooked .untoldgs twin. Every other chunk of the file is copied unchanged. The payload path is stored relative to the directory of the file that is written (the input with --in-place, the --output file otherwise), which is where the runtime resolves it; keep the payload inside or beside that file. A meshTwin link on an entity without a mesh (the root of a multi-node asset) is written with a warning that lists the mesh-bearing entities.

untoldengine gaussian-link --untold Chair/chair.untold --entity 0 \
  --payload Chair/chair.untoldgs --swap-distance 8 --occluder-shrink 0.02 --in-place
untoldengine gaussian-link --untold Chair/chair.untold --entity 0 \
  --remove --output Chair/chair_plain.untold
untoldengine gaussian-link --untold Chair/chair.untold --list

Creates a new UntoldEngine game project.

Arguments:

• projectName - Name of the project to create

Options:

• --platform <platform> - Target platform: macos, ios, ios-ar, visionos, multi (default: macos)
• --bundle-id <id> - Bundle identifier (e.g., com.company.game)
• --output <path> - Output directory (default: current directory)
• --macos-version <version> - macOS deployment version: 13, 14, 15 (default: 15)
• --ios-version <version> - iOS deployment version: 16, 17, 18 (default: 17)
• --visionos-version <version> - visionOS deployment version: 1, 2 (default: 2)
• --team-id <id> - Apple Developer Team ID for code signing
• --optimization <level> - Optimization level: none, speed, size (default: none)
• --debug / --no-debug - Include debug information (default: yes)

Examples:

# Create macOS project in current directory
mkdir MyGame && cd MyGame
untoldengine create MyGame

# Create iOS AR project
mkdir ARGame && cd ARGame
untoldengine create ARGame --platform ios-ar --bundle-id com.company.argame

# Create visionOS project with custom output
untoldengine create VRGame --platform visionos --output ~/Projects

# Create multi-platform project
mkdir MultiGame && cd MultiGame
untoldengine create MultiGame --platform multi --team-id ABCD1234EF

Updates only the GameData folder in an existing project, preserving custom code changes.

Arguments:

• project - Project name or path to the project directory

Options:

• --asset-path <path> - Path to game assets directory

Examples:

# Update project in default location
untoldengine update MyGame --asset-path ~/GameAssets

# Update project at specific path
untoldengine update ~/Projects/MyGame --asset-path ~/GameAssets

Manages the visual editor. Running untoldengine studio with no subcommand launches the editor, offering to install it first if it isn't present. Releases are downloaded from the official UntoldEditor releases.

Subcommands:

• launch - Launch the editor, installing it first if missing (default)
• install - Download and install the editor into /Applications (or ~/Applications if not writable)
• update - Update an existing install to the latest release

Install options:

• --version <version> - Version to install, e.g. 0.13.0 (default: latest release)
• --destination <path> - Directory to install into (default: /Applications)
• --force - Replace an existing install without prompting

Examples:

# Launch the editor (installs it first if missing)
untoldengine studio

# Install the latest release
untoldengine studio install

# Install a specific version
untoldengine studio install --version 0.13.0

# Update to the latest release
untoldengine studio update

Generated projects have the following structure:

MyGame/
├── Package.swift              # Swift Package configuration
├── README.md
└── Sources/
    └── MyGame/
        ├── AppDelegate.swift      # macOS: App lifecycle
        ├── GameScene.swift        # Game initialization and loop
        ├── GameViewController.swift # View controller
        ├── Base.lproj/
        │   └── Main.storyboard
        ├── Info.plist
        └── GameData/              # Bundled game content
            ├── Scenes/            # Scene files (.json)
            ├── Scripts/           # USC scripts (.uscript)
            ├── Models/            # 3D models
            ├── Textures/          # Texture files
            └── Shaders/           # Compiled Metal shaders

This CLI tool is part of the UntoldEngine repository but is packaged separately to avoid adding unnecessary dependencies to projects that use UntoldEngine.

• Standalone Package: The CLI is its own Swift Package under Tools/UntoldEngineCLI
• Local Dependency: It depends on the main UntoldEngine package via a local path reference
• No Impact: When users add UntoldEngine to their projects, they don't get the CLI or its dependencies (like swift-argument-parser)

When making changes to the CLI:

1. Make your changes in Tools/UntoldEngineCLI/Sources/UntoldEngineCLI/
2. Test by running swift build from this directory
3. Verify the CLI works: swift run untoldengine --help
4. Ensure the main engine package still builds without the CLI

Copyright (C) Untold Engine Studios
Licensed under the Mozilla Public License 2.0 (MPL-2.0).