#@djodjonx/gwen-cli

GWEN CLI — Command-line interface for game development

Build, develop, and scaffold GWEN game projects from the command line.

Installation

npm install -D@djodjonx/gwen-cli
# or globally
npm install -g@djodjonx/gwen-cli

Quick Start

Create a New Project

npm create gwen-app@latest my-game
cd my-game
npm install
npm run dev

Commands

gwen dev

Start the development server with WASM hot-reload.

gwen dev

Options:

• --port 3000 — Custom port (default: 5173)
• --open — Auto-open in browser

gwen build

Build for production.

gwen build

Outputs optimized WASM and JavaScript to dist/.

gwen prepare

Prepare the project (one-time setup).

gwen prepare

gwen lint

Lint your code with oxlint.

gwen lint
# Fix issues
gwen lint --fix

gwen format

Format code with oxfmt.

gwen format --check  # Check only
gwen format          # Fix

Configuration

gwen.config.ts

Configure your game engine:

// gwen.config.ts
import { defineConfig } from '@djodjonx/gwen-kit';
import { InputPlugin } from '@djodjonx/gwen-plugin-input';
import { AudioPlugin } from '@djodjonx/gwen-plugin-audio';

export default defineConfig({
  // Canvas element ID
  canvas: 'game-canvas',

  // Engine configuration
  fps: 60,

  // Plugins
  plugins: [new InputPlugin(), new AudioPlugin()],
});

vite.config.ts

import { defineConfig } from 'vite';
import { gwen } from '@djodjonx/gwen-vite-plugin';

export default defineConfig({
  plugins: [
    gwen({
      cratePath: './crates/gwen-core',
      watch: true,
    }),
  ],
});

Project Structure

my-game/
├── src/
│   ├── main.ts              # Entry point
│   ├── scenes/              # Game scenes
│   │   └── GameScene.ts
│   ├── components/          # Component definitions
│   ├── systems/             # Game systems
│   └── prefabs/             # Entity prefabs
├── crates/
│   └── gwen-core/           # Rust WASM core
├── gwen.config.ts           # Engine config
├── vite.config.ts           # Build config
├── index.html               # HTML entry
└── package.json

Examples

Development Workflow

# Install dependencies
npm install

# Start dev server
npm run dev
# → http://localhost:5173
# → WASM auto-reloads on .rs changes

# Build for production
npm run build

# Preview production build
npm run preview

Create a Scene

// src/scenes/GameScene.ts
import { defineScene, defineComponent, Types } from '@djodjonx/gwen-engine-core';

const Position = defineComponent('Position', {
  x: Types.f32,
  y: Types.f32,
});

export const GameScene = defineScene({
  name: 'game',
  async onInit(api) {
    const engine = api.engine;

    // Create player entity
    const player = engine.createEntity();
    engine.addComponent(player, Position, { x: 100, y: 100 });
  },
  onUpdate(delta) {
    // Game logic
  },
});

Using Plugins

// gwen.config.ts
import { InputPlugin } from '@djodjonx/gwen-plugin-input';
import { AudioPlugin } from '@djodjonx/gwen-plugin-audio';

export default defineConfig({
  plugins: [new InputPlugin(), new AudioPlugin()],
});

// In your scene:
const input = api.services.get('input');
const audio = api.services.get('audio');

if (input.isJustPressed('Space')) {
  audio.play('jump');
}

Troubleshooting

Port Already in Use

gwen dev --port 3001

WASM Build Fails

• Ensure Rust toolchain is installed: rustup target add wasm32-unknown-unknown
• Check Cargo.toml in crates/gwen-core/
• Try cargo build --target wasm32-unknown-unknown manually

Hot-Reload Not Working

• Verify vite.config.ts has gwen() plugin registered
• Check that .rs files are in the crate directory
• Enable verbose logging: gwen({ verbose: true })

See Also

• @djodjonx/gwen-engine-core — Core engine API
• @djodjonx/gwen-vite-plugin — Vite integration
• GWEN Documentation