Vulpis

Appearance

Getting Started ​

This guide will help you set up your environment, understand the project structure, and create your first "Hello Vulpis" window.

1. Project Structure ​

Vulpis uses a strict directory structure to keep your logic and resources organized.

text
.
├── src/                 #  WRITE YOUR CODE HERE (Lua scripts)
├── assets/              #  PUT RESOURCES HERE (Images, Fonts, Audio)
├── utils/               #  Core framework utilities
├── vulcli/              #  Build tools
└── build/               #  Compiled binaries (Generated)

Rule of Thumb

  • Logic goes in src/.
  • Resources go in assets/.
  • Never modify build/ manually.

2. Initialize Dependencies ​

Before writing code, ensure the C++ package manager is ready, check out the Vulcli Reference. Vulpis uses vcpkg to handle external libraries.

Run the initialization command to bootstrap vcpkg:

bash
vulcli vcpkg

This downloads and configures the package manager locally. You only need to run this once.

3. Scripting & Imports ​

The Vulpis engine automatically configures Lua's package.path on startup to include the following directories:

  • src/
  • utils/
  • lua/

This means you can require files directly from these folders without typing the full path.

Example: If you have a file at utils/core/elements.lua:

lua
-- You can require it like this:
local el = require("core.elements") 

-- Or explicitly:
local el = require("utils.core.elements")

4. Creating Your First Window ​

Create a new file at src/app.lua. This will be the entry point for your application.

Copy the following code to create a simple "Hello Vulpis" window:

lua
function Window()
	return { title = "Vulpis Typography One-Screen", w = 800, h = 600, resizable = true }
end

function App()
	return {
		type = "vbox",
		style = {
			BGColor = "#000000",
			alignItems = "center",
			justifyContent = "center",
		},
		children = {
			{
				type = "text",
				text = "Hello Vulpis",
				style = {
					color = "#ff7b00",
					fontSize = 60,
				},
			},
		},
	}
end

5. Build and Run ​

Now that your code is ready, use the Vulcli tool to compile and launch the application.

Step A: Build the Engine ​

This compiles the C++ core and links your Lua scripts.

bash
vulcli build

(The first build may take a few minutes as it compiles dependencies like SDL2 and Yoga).

Step B: Run the Application ​

This launches the engine and loads your src/app.lua.

bash
vulcli run

Congratulations! You should now see the Vulpis window on your screen.