@gamedevland/vite 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0 — 2026-11-07
+
+- Add `gamedevland create <directory>` to generate a blank SDK consumer project and install
+  its dependencies, with `--no-install` for offline/custom installation and `--name` for
+  an explicit npm package name.
+- Ship the template inside the npm package: strict TypeScript, Vite, ESLint, an empty
+  FSM scene with DI/layout registration, manifest-based JSON assets, and audio volume config.
+- Include web and CrazyGames development/build scripts with relative asset paths.
+- Reject nonempty destinations, symlink destinations and invalid names; never overwrite
+  existing project files. Invoke dependency installation without interpolating user paths.
+- Update the engine dependency to 0.0.11 and test generated project structure and CLI behavior.
+
 ## 0.1.2 — 2026-11-04
 
 - Release the package and its source under MIT.
@@ -19,3 +31,19 @@
 - Use the official pinned Poki CLI, per-game private credentials or `POKI_UPLOAD_TOKEN`, and verified upload receipts.
 - Keep authentication out of check/build subprocesses and reject source maps, private files, symlinks and leaked upload tokens in build output.
 - Preserve existing Vite configuration exports and browser SDK injection.
+
+## 0.0.4
+
+- Update the engine dependency to 0.0.5.
+
+## 0.0.3
+
+- Update package links and the engine dependency to 0.0.4.
+
+## 0.0.2
+
+- Update repository metadata and the engine dependency to 0.0.3.
+
+## 0.0.1
+
+- First npm release of the Vite tooling.

package/README.md

@@ -1,5 +1,20 @@
 # @gamedevland/vite
 
+## Create a blank game
+
+```sh
+npx --yes --package @gamedevland/vite@0.2.0 gamedevland create my-game
+cd my-game
+npm run dev
+```
+
+When installed locally, run `npx gamedevland create my-game`. The CLI generates a
+strict TypeScript/PixiJS project with an empty FSM scene, scene/global DI, JSON
+layout and audio config, and web/CrazyGames build scripts. Dependencies are installed
+by default. `--no-install` skips installation; `--name my-game` sets the npm name
+when the destination directory has a different name. New or empty directories only;
+nonempty directories and symlink destinations are rejected without overwriting files.
+
 Vite build tooling for HTML5 games built with `@gamedevland/engine`.
 
 ## Install

package/dist/cli/GamedevlandCli.js

@@ -2,19 +2,26 @@ import { parseArgs } from 'node:util';
 import { PokiArchive } from '../poki/PokiArchive.js';
 import { PokiProject } from '../poki/PokiProject.js';
 import { PokiUpload } from '../poki/PokiUpload.js';
+import { ProjectCreator } from '../project/ProjectCreator.js';
 /** Public command-line interface; no dependency on a particular game layout. */
 export class GamedevlandCli {
     static async run(argv, cwd) {
         const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
                 help: { type: 'boolean', short: 'h' }, root: { type: 'string' },
                 name: { type: 'string' }, notes: { type: 'string' },
+                'no-install': { type: 'boolean', default: false },
             } });
         if (values.help || positionals.length === 0) {
-            process.stdout.write('Usage: gamedevland poki <pack|upload> [--root <project>] [--name <version>] [--notes <text>]\npack validates/packages an existing build; upload runs configured checks and a fresh build before uploading.\n');
+            process.stdout.write('Usage: gamedevland create <directory> [--name <name>] [--no-install]\n       gamedevland poki <pack|upload> [--root <project>] [--name <version>] [--notes <text>]\ncreate generates a blank project and installs dependencies.\npack validates/packages an existing build; upload runs configured checks and a fresh build before uploading.\n');
+            return;
+        }
+        if (positionals[0] === 'create' && positionals.length === 2 && positionals[1]) {
+            await ProjectCreator.create({ cwd, directory: positionals[1], install: !values['no-install'],
+                ...(values.name === undefined ? {} : { name: values.name }) });
             return;
         }
         if (positionals.length !== 2 || positionals[0] !== 'poki' || !['pack', 'upload'].includes(positionals[1] ?? '')) {
-            throw new Error('[gamedevland] Expected poki pack or poki upload; use --help');
+            throw new Error('[gamedevland] Expected create <directory>, poki pack or poki upload; use --help');
         }
         const project = PokiProject.load(values.root ?? cwd);
         if (positionals[1] === 'pack') {

package/dist/project/ProjectCreator.d.ts

@@ -0,0 +1,13 @@
+interface CreateProjectOptions {
+    readonly cwd: string;
+    readonly directory: string;
+    readonly name?: string;
+    readonly install: boolean;
+}
+/** Creates a blank consumer project without overwriting existing files. */
+export declare class ProjectCreator {
+    static create(options: CreateProjectOptions): Promise<string>;
+    private static copy;
+    private static install;
+}
+export {};

package/dist/project/ProjectCreator.js

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+import { lstat, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SchemaDecoder as S } from '@gamedevland/engine/validation';
+/** Creates a blank consumer project without overwriting existing files. */
+export class ProjectCreator {
+    static async create(options) {
+        const root = path.resolve(options.cwd, options.directory);
+        const name = options.name ?? path.basename(root);
+        if (!/^[a-z0-9][a-z0-9._-]*$/.test(name) || name.length > 214) {
+            throw new Error('[create] Use a lowercase npm project name (letters, digits, dots, hyphens).');
+        }
+        const info = await lstat(root).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return undefined;
+        });
+        if (info && (!info.isDirectory() || info.isSymbolicLink() || (await readdir(root)).length > 0)) {
+            throw new Error('[create] Destination must be a new or empty directory. Existing files are never overwritten.');
+        }
+        const pkg = S.decode(JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8')), S.object({ version: S.string({ nonEmpty: true }), dependencies: S.object({
+                '@gamedevland/engine': S.string({ nonEmpty: true }),
+            }) }), 'tooling/package.json');
+        const replacements = new Map([
+            ['__PROJECT_NAME__', name], ['__ENGINE_VERSION__', pkg.dependencies['@gamedevland/engine']],
+            ['__TOOLING_VERSION__', pkg.version],
+        ]);
+        await mkdir(root, { recursive: true });
+        await this.copy(fileURLToPath(new URL('../../templates/empty/', import.meta.url)), root, replacements);
+        if (options.install)
+            await this.install(root);
+        process.stdout.write(`[create] Created ${root}\nNext: cd ${JSON.stringify(options.directory)}${options.install ? '' : ' && npm install'} && npm run dev\n`);
+        return root;
+    }
+    static async copy(source, target, replacements) {
+        for (const entry of await readdir(source, { withFileTypes: true })) {
+            const destination = path.join(target, entry.name === 'gitignore' ? '.gitignore' : entry.name);
+            if (entry.isDirectory()) {
+                await mkdir(destination);
+                await this.copy(path.join(source, entry.name), destination, replacements);
+            }
+            else if (entry.isFile()) {
+                let content = await readFile(path.join(source, entry.name), 'utf8');
+                for (const [token, value] of replacements)
+                    content = content.replaceAll(token, value);
+                await writeFile(destination, content, { flag: 'wx' });
+            }
+            else
+                throw new Error('[create] Invalid template entry');
+        }
+    }
+    static async install(root) {
+        const npmEntry = process.env.npm_execpath;
+        const command = npmEntry ? process.execPath : 'npm';
+        const args = npmEntry ? [npmEntry, 'install'] : ['install'];
+        await new Promise((resolve, reject) => {
+            const child = spawn(command, args, { cwd: root, stdio: 'inherit',
+                shell: process.platform === 'win32' && !npmEntry });
+            child.once('error', reject);
+            child.once('close', (code) => code === 0 ? resolve()
+                : reject(new Error('[create] Dependency installation failed; retry npm install in the generated directory.')));
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamedevland/vite",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Vite build tooling for Gamedev Land HTML5 games.",
   "license": "MIT",
@@ -25,7 +25,8 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"
@@ -44,7 +45,7 @@
     "build": "npm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths"
   },
   "dependencies": {
-    "@gamedevland/engine": "0.0.8",
+    "@gamedevland/engine": "0.0.11",
     "@poki/cli": "0.1.19",
     "fflate": "0.8.3"
   },

package/templates/empty/.env.crazygames

@@ -0,0 +1 @@
+VITE_PLATFORM=crazygames

package/templates/empty/AGENTS.md

@@ -0,0 +1,10 @@
+# Project instructions
+
+- Use public `@gamedevland/engine` subsystem exports; do not deep-import internals.
+- Keep flow in FSM → Command → Service. Components/actions own node visuals and input.
+- Keep static hierarchies and authored visual values in JSON layouts/prefabs/configs.
+- Keep every music/SFX channel and per-asset volume in the audio JSON config.
+- Use SDK autoplay recovery and platform-owned data where available.
+- Use strict TypeScript; avoid unsafe casts and non-null assertions.
+- Run `npm run typecheck`, `npm run lint`, and `npm run build` after changes.
+- Do not claim real-browser/device verification from simulated tests.

package/templates/empty/README.md

@@ -0,0 +1,24 @@
+# __PROJECT_NAME__
+
+A blank TypeScript/PixiJS game using the Gamedev Land SDK. No demo gameplay or media assets.
+
+```sh
+npm run dev
+npm run typecheck
+npm run lint
+npm run build
+```
+
+The CLI installs dependencies by default. If created with `--no-install`, run `npm install` first.
+Node.js 22.12+ is required.
+
+Entry: `game/src/main.ts`. Configuration: `game/src/config/GameConfiguration.ts`.
+The empty scene uses the SDK's FSM, scene DI, asset manifest and JSON layout.
+Add gameplay through FSM → Command → Service; put visuals in components/actions.
+
+All music/SFX channel and per-file levels belong in
+`game/assets/json/configs/audio/sounds-volumes.json`.
+
+`npm run dev:crazygames` enables the official CrazyGames v3 SDK on localhost.
+`npm run build:crazygames` produces `dist/crazygames/` with relative asset paths.
+Report gameplay start/stop when actual gameplay is added; a blank scene is not gameplay.

package/templates/empty/eslint.config.js

@@ -0,0 +1,8 @@
+import js from '@eslint/js';
+import ts from 'typescript-eslint';
+
+export default [
+  { ignores: ['dist/**', 'node_modules/**'] },
+  js.configs.recommended,
+  ...ts.configs.recommended,
+];

package/templates/empty/game/assets/json/configs/audio/sounds-volumes.json

@@ -0,0 +1 @@
+{ "channel.music": 1, "channel.sfx": 1 }

package/templates/empty/game/assets/json/layouts/scenes/main/layout.json

@@ -0,0 +1 @@
+{ "root": { "type": "Container", "children": {} } }

package/templates/empty/game/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <link rel="icon" href="data:," />
+    <title>__PROJECT_NAME__</title>
+    <style>
+      html, body, #app { margin: 0; width: 100%; height: 100%; overflow: hidden; background: #07111f; }
+      body { overscroll-behavior: none; user-select: none; -webkit-user-select: none; }
+      canvas { display: block; }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/main.ts"></script>
+  </body>
+</html>

package/templates/empty/game/src/config/GameConfiguration.ts

@@ -0,0 +1,29 @@
+import { AssetManifestBuilder } from '@gamedevland/engine/assets';
+import type { GameConfig } from '@gamedevland/engine/core';
+import { MainSceneDefinition } from '../scenes/main/MainSceneDefinition';
+import { ProjectDi } from './ProjectDi';
+
+export class GameConfiguration {
+  static readonly config: GameConfig = {
+    system: {
+      canvasBackground: '#07111f',
+      screen: {
+        land: { width: 960, height: 540, fit: 'height' },
+        port: { width: 540, height: 960, fit: 'height' },
+        dpr: 'native', maxDpr: 2, render: { maxCanvasPixels: 1500000 },
+      },
+      boot: { configs: { engineStartBundles: ['configs'] } },
+      audio: { volumeConfigId: 'json/configs/audio/sounds-volumes.json' },
+    },
+    assets: {
+      bundles: new AssetManifestBuilder({
+        configsJson: import.meta.glob<string>('../../assets/json/configs/**/*.json', { eager: true, query: '?url', import: 'default' }),
+        layoutsJson: import.meta.glob<string>('../../assets/json/layouts/**/*.json', { eager: true, query: '?url', import: 'default' }),
+        audio: {}, fonts: {}, images: {}, localesJson: {}, prefabsJson: {},
+      }).build(),
+      preload: ['layouts'],
+    },
+    scenes: { initial: 'main', map: { main: MainSceneDefinition.config } },
+    di: new ProjectDi(),
+  };
+}

package/templates/empty/game/src/config/ProjectDi.ts

@@ -0,0 +1,8 @@
+import { GameDiDefinition } from '@gamedevland/engine/di';
+import { MainSceneDi } from '../scenes/main/MainSceneDi';
+import { ProjectGlobalDi } from './ProjectGlobalDi';
+
+export class ProjectDi extends GameDiDefinition {
+  protected override createGlobalDefinition() { return new ProjectGlobalDi(); }
+  protected override createSceneDefinitions() { return [new MainSceneDi()]; }
+}

package/templates/empty/game/src/config/ProjectGlobalDi.ts

@@ -0,0 +1,12 @@
+import { GlobalDiDefinition } from '@gamedevland/engine/di';
+import type { ElementFactoriesGroup } from '@gamedevland/engine/di';
+import { Container, Graphics, Text } from '@gamedevland/engine/layouts';
+
+export class ProjectGlobalDi extends GlobalDiDefinition {
+  protected override registerElements(group: ElementFactoriesGroup): void {
+    group.add('Container', Container).add('Graphics', Graphics).add('Text', Text);
+  }
+  protected override registerComponents(): void {}
+  protected override registerCommands(): void {}
+  protected override registerServices(): void {}
+}

package/templates/empty/game/src/main.ts

@@ -0,0 +1,4 @@
+import { Engine } from '@gamedevland/engine';
+import { GameConfiguration } from './config/GameConfiguration';
+
+await Engine.run('#app', GameConfiguration.config);

package/templates/empty/game/src/scenes/main/MainScene.ts

@@ -0,0 +1,3 @@
+import { FsmDrivenScene } from '@gamedevland/engine/scenes';
+
+export class MainScene extends FsmDrivenScene {}

package/templates/empty/game/src/scenes/main/MainSceneDefinition.ts

@@ -0,0 +1,10 @@
+import type { SceneConfig } from '@gamedevland/engine/core';
+import { MainScene } from './MainScene';
+
+export class MainSceneDefinition {
+  static readonly config: SceneConfig = {
+    key: 'main', useClass: MainScene,
+    layout: 'json/layouts/scenes/main/layout.json',
+    fsm: { initial: 'ready', states: { ready: {} } },
+  };
+}

package/templates/empty/game/src/scenes/main/MainSceneDi.ts

@@ -0,0 +1,7 @@
+import { SceneDiDefinition } from '@gamedevland/engine/di';
+
+export class MainSceneDi extends SceneDiDefinition {
+  override getSceneKey(): string { return 'main'; }
+  protected override registerProviders(): void {}
+  protected override registerServices(): void {}
+}

package/templates/empty/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.log
+.DS_Store

package/templates/empty/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "engines": { "node": ">=22.12.0" },
+  "scripts": {
+    "dev": "vite",
+    "dev:crazygames": "vite --mode crazygames",
+    "build": "vite build",
+    "build:crazygames": "vite build --mode crazygames --outDir ../dist/crazygames",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings=0",
+    "preview": "vite preview"
+  },
+  "dependencies": { "@gamedevland/engine": "__ENGINE_VERSION__", "pixi.js": "^8.16.0" },
+  "devDependencies": {
+    "@gamedevland/vite": "__TOOLING_VERSION__", "@types/node": "^24.7.0",
+    "typescript": "^5.9.3", "vite": "^8.0.16", "eslint": "^9.37.0",
+    "@eslint/js": "^9.37.0", "typescript-eslint": "^8.46.0"
+  }
+}

package/templates/empty/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext", "moduleResolution": "Bundler", "strict": true,
+    "noUncheckedIndexedAccess": true, "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true, "resolveJsonModule": true, "isolatedModules": true,
+    "skipLibCheck": true, "noEmit": true, "types": ["node", "vite/client"]
+  },
+  "include": ["game", "vite.config.ts"], "exclude": ["dist", "node_modules"]
+}

package/templates/empty/vite.config.ts

@@ -0,0 +1,7 @@
+import { fileURLToPath } from 'node:url';
+import { GameViteConfig } from '@gamedevland/vite';
+
+export default ({ mode }: { mode: string }) => ({
+  ...GameViteConfig.create({ mode, repoRoot: fileURLToPath(new URL('.', import.meta.url)) }),
+  server: { open: false },
+});