Vulcli

vulcli is the official command-line tool for Vulpis. It wraps CMake and vcpkg to handle building, running, and cleaning your project with single commands.

Installation

The CLI tool is written in Python and can be installed globally so you can run vulcli from any directory.

Automatic Installation

The repository includes an installer script that detects your OS and sets up the necessary paths.

Linux / macOS

# Navigate to the tool directory
cd vulcli

# Run with sudo to create a symlink in /usr/local/bin
sudo python3 install.py

Windows

# Navigate to the tool directory
cd vulcli

# Run the installer (Administrator recommended)
python install.py

Windows Users

If the command isn't recognized after installation, try restarting your device. The installer updates your user Registry PATH, which may require a fresh session to take effect.

Manual Installation

If the installer fails, you can set up the tool manually.

Linux / macOS (Symlink)

Create a symbolic link from the script to your binary folder:

ln -s "path to vulcli.py" /usr/local/bin/vulcli
chmod +x "path to vulcli.py"

Windows (PATH)

1. Copy the full path to the vulcli folder.
2. Search Windows for "Edit the system environment variables".
3. Click Environment Variables -> Select Path -> Edit.
4. Click New and paste the path.
5. Click OK and restart your terminal.

Usage

Once installed, you can run vulcli commands from your project root.

Command	Description
vulcli init	Creates a .vulpis marker file to initialize a project.
vulcli build	Automates CMake configuration and compilation. Detects OS presets automatically.
vulcli run	Builds the project (if needed) and launches the executable.
vulcli clean	Deletes the build/ directory to force a fresh compilation.

First-Time Build Duration

When you run vulcli build or vulcli run for the very first time, the process may take several minutes to complete. This is because vcpkg needs to download and compile all the core C++ dependencies (such as SDL2, Yoga, and network libraries) from source. this will only happen for the very first build and it may also happen when some modules are needs to be updated, you don't have to rebuild the app after this to see your lua side changes it will update automatically

The Asset Baking Pipeline

When you run vulcli build or vulcli run, you might notice a baked/ directory appear in your project root containing .vtex files. This is the Vulpis Asset Baker in action.

Why do we bake assets?

Standard image formats like .png and .jpg are heavily compressed for disk storage, but GPUs cannot read them directly. Normally, a game engine has to decompress a PNG into raw pixel data on the CPU, and then send that massive, uncompressed chunk of memory to the GPU. This is slow and uses a lot of RAM.

How it works

1. When you trigger a build, vulcli runs a background executable called asset_baker.
2. It scans your assets/ folder for images.
3. It converts them into DXT5 Compressed Textures and saves them as .vtex (Vulpis Texture) files in the baked/ directory.

Because DXT5 is a format the GPU natively understands, Vulpis can stream these .vtex files straight from your hard drive to the graphics card, bypassing CPU decompression entirely. This results in near-instant image loading and massively reduced RAM usage.

Version Control

The baked/ directory is essentially a cache. It will automatically regenerate if deleted. You should add baked/ to your project's .gitignore file so you don't commit duplicate image data to your repository.