Skip to content

Engine-Tree Example Projects

Use snowpulse-engine for games that live under this repository's examples/ directory and intentionally evolve alongside the engine. Use the standalone snowpulse new workflow for games that should vendor or reference a packaged SDK without modifying the engine checkout.

Engine source checkout only

This is a contributor and maintainer workflow for a full Snowpulse engine source checkout. These commands create or modify examples/ projects and their registration in the repository's root CMakeLists.txt; they do not manage standalone client-game projects. To create a normal game from the Snowpulse SDK, follow Getting Started instead.

Create and Inspect Examples

Run the tool from the engine repository root:

./snowpulse-engine new \
  --name "Sample App" \
  --id com.example.sampleapp \
  --template minimal-game \
  --web-mode game

./snowpulse-engine list

new derives the directory and CMake target from the display name, creates the source/assets skeleton, assets/asset-packs.json, and a complete Android Gradle project, then adds one unconditional add_subdirectory(examples/<project>) line to the tool-managed root CMake block. Use --disabled to create the files without registering the project.

When a required --name or --id is omitted in an interactive terminal, the tool prompts for it. Automation must provide required values explicitly.

Adopt or Update an Existing Example

./snowpulse-engine update sampleapp \
  --id com.example.sampleapp \
  --display-name "Sample App"

With no scope selector, update is equivalent to --all: it refreshes the managed project CMakeLists.txt and Android scaffold and creates assets/asset-packs.json when it is missing. Use an explicit scope selector when only part of that work is wanted:

./snowpulse-engine update sampleapp --android
./snowpulse-engine update sampleapp --asset-packs
./snowpulse-engine update sampleapp --all --dry-run

The --id and --display-name options refresh both the managed project files and Android metadata. --template and --web-mode refresh the managed project files even when combined with a narrow capability selector, preventing project metadata and CMake from diverging. Configuration options are not themselves scope selectors, so --web-mode playable alone performs the default full update; combine it with --android or --asset-packs to limit the remaining work. Managed-file conflict rules still apply to every destination separately.

The Android scaffold points to the repository root CMake project, the example's own assets/, and snowpulse/android/runtime. The asset-pack manifest is created only when absent and is never overwritten.

Android-ready game code must use a complete declarative game target and an app factory. The same CMake declaration also owns desktop, web, and iOS setup:

snowpulse_add_game(mygame
    SOURCES ${MYGAME_SOURCES}
    DISPLAY_NAME "My Game"
    BUNDLE_ID "com.example.mygame"
    ASSETS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/assets"
    ASSIMP OFF
    SPINE_VERSION "4.2"
    WEB_MODE GAME
    WEB_PLATFORM POKI
)

SNOWPULSE_DEFINE_APP(createApplication)

The settings block at the top of generated CMakeLists.txt is the easy place to change Assimp, Spine, web mode, and web platform. --web-mode game selects GAME plus POKI; --web-mode playable selects PLAYABLE_AD plus GOOGLE_ADS. The CLI intentionally has no separate web-platform flag.

Generated-File Conflicts

Project state is committed under:

examples/<project>/.snowpulse-engine/
  project.conf
  managed-files.tsv
  pending/                 # present only when an update conflicts

Unchanged generated infrastructure can be refreshed automatically. The generated CMakeLists.txt and Android files are hash-managed. If one was customized, update preserves it and writes the proposed version under .snowpulse-engine/pending/ for review. Use --force-managed only when deliberately replacing customized generated files. Gameplay source, assets, and the project README remain developer-owned. Metadata is parsed as data and is never executed as shell code.

Enable, Disable, and Remove

./snowpulse-engine enable sampleapp
./snowpulse-engine disable sampleapp
./snowpulse-engine remove sampleapp

enable normalizes the project to one unconditional root CMake registration. The project's CMake is therefore responsible for guarding platform-specific packaging. disable removes active registrations but leaves every project file untouched.

remove is permanent. It displays the exact directory and Git changes, then requires the project name as confirmation. Non-interactive automation must pass --yes. The command rejects nested paths, traversal, symlinks, and any target outside a direct examples/<project> child.

Android Build

./snowpulse-engine doctor android
cd examples/sampleapp/android
./gradlew :app:assembleDebug
./gradlew :app:installDebug

Release signing, APK/AAB commands, and verification are identical to standalone generated projects; see Android.