Create Your First Snowpulse Game

This guide is for game developers using a packaged Snowpulse SDK. You will generate a standalone project, build its desktop target, run the starter scene, and make a small gameplay-code change.

The generated game owns its source and assets and consumes Snowpulse as a dependency. It does not need to live inside the Snowpulse engine repository.

Before You Begin

For the shortest first run, use a Windows or macOS development machine with:

• CMake 3.21 or newer, which supports the generated CMake presets
• A C++17 compiler: Visual Studio 2022 on Windows or Xcode command-line tools on macOS
• A POSIX-style shell for the Snowpulse CLI, such as Git Bash or WSL on Windows, or Terminal on macOS
• An extracted Snowpulse SDK package supplied by Snowblink Studios

Web, iOS, and Android require additional platform toolchains. Get the desktop starter running first, then continue with the platform links near the end of this guide.

1. Open the Packaged SDK

After extracting the SDK archive, its root looks like this:

snowpulse-sdk-<version>-build<build>-<timestamp>/
  snowpulse          # project CLI
  README.md
  engine/
  sdk/

Open a shell in that directory. The ./snowpulse command below is the launcher at the root of the extracted SDK; it is not snowpulse-engine, the tool used by Snowpulse engine maintainers.

2. Create a Standalone Game

From the extracted SDK root, generate a minimal game project:

./snowpulse new \
  --name MyGame \
  --id com.example.mygame \
  --dir /path/to/projects

Replace /path/to/projects with the directory where you keep game projects. The bundle ID should be a stable identifier that you control; Snowpulse uses it for application metadata and persistent storage.

The default minimal-game template creates /path/to/projects/MyGame and vendors the SDK source under third_party/snowpulse. The resulting game can be moved, archived, or opened on another machine without depending on the SDK directory that generated it.

To start with the first-party top-down gameplay template instead, add:

--template topdown-with-character

3. Configure and Build the Game

Enter the generated project, then use its desktop debug presets:

cd /path/to/projects/MyGame
cmake --preset desktop-debug
cmake --build --preset desktop-debug

The first configuration builds Snowpulse and its vendored native dependencies, so it takes longer than later incremental builds. The generated CMake target is mygame, derived from the project name.

If you have CMake 3.16–3.20, use the equivalent manual commands instead:

cmake -S . -B cmake-build-debug -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake-build-debug --target mygame

4. Run the Starter Scene

Run the mygame target from CLion, Visual Studio, or VSCode with the CMake Tools extension. From a shell, the exact artifact path depends on the operating system and CMake generator:

• macOS commonly produces cmake-build-debug/MyGame.app; launch it with open cmake-build-debug/MyGame.app.
• A single-configuration Windows generator commonly produces cmake-build-debug/MyGame.exe.
• Visual Studio and other multi-configuration generators normally place it under cmake-build-debug/Debug/MyGame.exe. If needed, build explicitly with cmake --build --preset desktop-debug --config Debug.

The minimal starter opens a dark scene with a cyan square rotating at its center. Seeing that animation confirms that the game target, application lifecycle, scene graph, renderer, and desktop host are working together.

5. Make Your First Change

Open src/scene.cc. In Scene::init(), change the marker color:

markerQuad->color = { 0.96f, 0.35f, 0.64f, 1.0f };

In Scene::update(), make it rotate faster:

_marker->transform().rotation.z += 120.0f * dt;

Build and run the game again:

cmake --build --preset desktop-debug

The square should now be pink and rotate more quickly. This is the normal Snowpulse iteration loop: edit game-owned source or assets, rebuild the game target, and run it again.

6. Know the Project Layout

The generated project separates game-owned files from generated infrastructure and the vendored engine:

MyGame/
  CMakeLists.txt          # game features, identity, and platform settings
  CMakePresets.json       # local and production build presets
  android/                # this game's Gradle project
  assets/                 # textures, audio, fonts, maps, and other content
  src/
    main.cc               # creates the App and exports the platform entry point
    app.h
    app.cc                # application initialization and active Scene
    scene.h
    scene.cc              # starter scene, nodes, components, and game updates
  third_party/snowpulse/  # vendored Snowpulse and Snowgears SDK source
  .snowpulse/             # generated-file versions and update state

The important runtime relationship is:

1. main.cc creates your App and passes its factory to SNOWPULSE_DEFINE_APP.
2. App::init() installs the first Scene.
3. The scene creates nodes and attaches components such as QuadRenderer.
4. Scene::update(dt) and updatable components advance gameplay each frame.

Most early game work happens in src/scene.* and assets/. As the project grows, add more scenes and components under src/ rather than modifying the vendored engine.

7. Keep Generated Infrastructure Current

Use the launcher from a newer extracted SDK to preview and apply safe project updates. Run these commands from the generated game directory:

/path/to/current-snowpulse-sdk/snowpulse update --dir . --dry-run
/path/to/current-snowpulse-sdk/snowpulse update --dir .

Updates refresh the vendored SDK and unchanged generated infrastructure. They do not replace gameplay source or existing assets. If a managed file was customized, the proposed replacement is written under .snowpulse/pending/ for review.

Build for Another Platform

Once the desktop starter works, continue with the guide for the target you need:

• Web builds, portals, and playable ads
• iOS simulator and device builds
• Android installation, builds, and deployment
• Windows and macOS production packages

Learn the Engine

• Core explains App, AppContext, and the frame lifecycle.
• Runtime covers scenes, nodes, transforms, and traversal.
• Components lists the behavior and rendering building blocks.
• Assets shows how content under assets/ is loaded and packaged.
• Input and UI cover interaction and screen-space layouts.

Working on Snowpulse itself?

Games under the engine repository's examples/ directory use the maintainer-only ./snowpulse-engine workflow. It changes the engine checkout and its root CMake registration, so it is not the normal path for a standalone game. See Engine-Tree Example Projects.