Valence CLI

The ultimate scaffolding tool for hybrid 3D applications.

Valence CLI automates the creation and management of high-performance desktop applications using Angular, Electron, and Babylon.js. It provides a robust, pre-configured environment with TypeScript support, build orchestration, and "production-ready" defaults.

🚀 Installation

npm install -g valence-cli

✨ Quick Start

Create a new project with the Valence Identity template (includes 3D scene, SVG logo, and debug HUD):

valence new my-game
cd my-game
valence start

🛠 Commands

valence new <name>

Scaffolds a new high-performance project. You will be prompted to select your engine:

• 3D (Babylon.js): Full 3D capabilities with Havok Physics, XR, and Inspector support.
• 2D (Phaser): Fast 2D game engine with configured scenes and arcade physics.

Both environments include:

• Angular: Latest CLI, SCSS, Routing.
• Electron: TypeScript Main/Preload processes, securely configured.
• Forge: Configured for building .exe / .zip / installers.
• Valence UI: Premium glassmorphic HUD with FPS and status tracking.

valence start

Runs the application in Development Mode:

• Cleans previous builds.
• Builds Angular (Dev config).
• Compiles Electron (TypeScript).
• Launches Electron window with live reload enabled.

valence build

Compiles the application for Production:

• Outputs to dist/browser (Angular) and dist/electron (Main Process).
• Optimizes assets.
• Enforces relative paths (baseHref="./") for Electron compatibility.

valence package

Packages the application for distribution:

• Runs valence build.
• Executes Electron Forge to generate installers (e.g., Windows Squirrel.exe, Zip).
• Artifacts saved to out/.

valence publish

Automates the release pipeline:

• Bumps project version (patch).
• Updates README.md version badges.
• Builds & Packages.
• Generates RELEASES_README.md entry.
• Publishes via Electron Forge.

🎮 Gameplay Services

Valence can automatically inject core game systems into your project.

valence add <feature>

Core Systems

• input: Unified Action Mapping (Keyboard/Gamepad) via Angular Signals.
• audio: Channel-based audio manager (Master/Music/SFX) using Howler.js.
• storage: Secure, atomic file I/O for save games (Write-Temp-Rename pattern) via Electron IPC.
• settings: Centralized configuration manager (Audio/Graphics) persisted to storage.
• state: Strict Game State Machine (Boot, Menu, Gameplay, Paused) via Signals.
• intro: Cinematic splash screen displaying technology stack (Valence, Angular, Electron, Babylon.js).

3D Features (Babylon.js)

• physics: Installs Havok engine (WASM) & initializes physics.
• inspector: Installs & binds Babylon Inspector to Ctrl+I.
• gui: Installs lil-gui debug panel.
• materials: Installs @babylonjs/materials.
• skybox: Creates environmental skybox.
• xr: Initializes WebXR (VR/AR) experience.

Universal Features

• tailwind: Configures TailwindCSS with Angular.
• multiplayer: Scaffolds Colyseus server & client.
• pipeline: Enables Asset Optimization Pipeline (sharp).
• native: Scaffolds Rust (Neon) native module.

🎨 Templates

valence template <name>

Instantly hot-swaps the 3D scene in valence-engine.service.ts with a pre-built archetype:

• orbit: Standard OrbitCamera setup with a sphere (Default).
• fps: First-Person Shooter setup with WASD movement, gravity, and collisions.
• platformer: Third-Person setup with a capsule player and follow camera.
• iso: Isometric (Cavalier) Orthographic projection with tile grid.
• gallery: Slow-walking "Museum" setup with raycast interaction.

🎲 Generators

valence generate scene <name>

Alias: valence g scene <name>

Scaffolds a new Scene component:

• 3D: Pre-wired Babylon.js Scene with Camera/Light/Resize handling.
• 2D: Pre-wired Phaser Scene class with lifecycle methods.

valence generate bridge <name>

Alias: valence g bridge <name>

Generates a type-safe IPC communication channel:

• Main Process: Registers ipcMain.handle.
• Preload: Exposes contextBridge API.
• Service: Creates Angular service wrapper.

valence codegen assets

Scans src/assets and generates typed constants in core/asset-keys.ts for IntelliSense.

🩺 Diagnostics

valence doctor

Diagnoses your development environment (Node, NPM, Git).

valence verify

Performs deep health check of project structure and configuration.