@kurot/cli 1.1.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kelvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,22 +1,22 @@
 {
 	"name": "@kurot/cli",
-	"version": "1.1.0",
+	"version": "1.1.1",
 	"description": "Kurot CLI - build tool for the Kurot game engine",
+	"author": "Kelvin <kyia.x52@gmail.com>",
+	"license": "MIT",
 	"type": "module",
+	"main": "./dist/define.js",
+	"types": "./dist/define.d.ts",
 	"bin": {
 		"kurot": "./dist/index.js"
 	},
-	"main": "./dist/define.js",
-	"types": "./dist/define.d.ts",
 	"files": [
 		"dist",
 		"templates",
 		"README.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"LICENSE"
 	],
-	"publishConfig": {
-		"access": "public"
-	},
 	"scripts": {
 		"build": "tsc --build",
 		"dev": "tsc --watch",
@@ -36,10 +36,20 @@
 		"typescript": "^5.6.0",
 		"vitest": "^4.1.4"
 	},
-	"packageManager": "pnpm@10.33.0",
+	"keywords": [
+		"kurot",
+		"cli",
+		"game-engine",
+		"exml",
+		"typescript"
+	],
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/kurot-engine/kurot.git",
 		"directory": "packages/cli"
+	},
+	"packageManager": "pnpm@10.33.0",
+	"publishConfig": {
+		"access": "public"
 	}
 }

package/templates/empty/src/Main.ts

@@ -1,10 +1,10 @@
 /**
- * Kurot 空白项目模板
+ * Kurot empty project template.
  *
- * 最小化入口，只依赖 @kurot/core，不含 UI 组件。
- * 适用于纯 Canvas 渲染、自定义绘制、动画实验等场景。
+ * A minimal entry point that depends only on @kurot/core and contains no UI components.
+ * Suitable for Canvas rendering, custom drawing, and animation experiments.
  *
- * 生命周期：constructor → ADDED_TO_STAGE → $onAddToStage
+ * Lifecycle: constructor → ADDED_TO_STAGE → $onAddToStage
  */
 import { createPlayer, Sprite, Event } from '@kurot/core';
 
@@ -15,12 +15,12 @@ class Main extends Sprite {
 	}
 
 	private onAddedToStage(_event: Event): void {
-		// 在这里编写你的游戏逻辑
+		// Add your game logic here.
 		console.log('Kurot game started');
 	}
 }
 
-// ── 启动 ──────────────────────────────────────────────────────────────────
+// ── Bootstrap ─────────────────────────────────────────────────────────────
 const app = createPlayer({
 	canvas: document.getElementById('gameCanvas') as HTMLCanvasElement,
 	contentWidth: 640,

package/templates/empty/tsconfig.json

@@ -3,6 +3,9 @@
 		"target": "ES2022",
 		"module": "ESNext",
 		"moduleResolution": "bundler",
+		"paths": {
+			"@/*": ["./src/*"]
+		},
 		"strict": true,
 		"skipLibCheck": true,
 	},

package/templates/game/kurot.config.ts

@@ -12,5 +12,8 @@ export default {
 	},
 	exml: {
 		themeFile: 'resource/default.thm.json',
+		namespaces: {
+			game: 'src/game-components.ts',
+		},
 	},
 };

package/templates/game/src/AssetAdapter.ts

@@ -0,0 +1,25 @@
+import { Texture, resource } from '@kurot/core';
+import { DefaultAssetAdapter, type IAssetAdapter } from '@kurot/ui';
+
+/**
+ * Connects UI asset sources to the project's resource system.
+ */
+export class AssetAdapter implements IAssetAdapter {
+
+	private readonly fallback = new DefaultAssetAdapter();
+
+	getAsset(
+		source: string,
+		callback: (content: Texture | undefined, source: string) => void,
+	): void {
+		const cached = resource.get<Texture>(source);
+		if (cached) {
+			callback(cached, source);
+			return;
+		}
+
+		resource.load<Texture>(source)
+			.then(content => callback(content, source))
+			.catch(() => this.fallback.getAsset(source, callback));
+	}
+}

package/templates/game/src/LifecycleHandler.ts

@@ -0,0 +1,39 @@
+import { Event, type Stage } from '@kurot/core';
+
+/**
+ * Manages application-specific foreground and background behavior.
+ *
+ * Kurot pauses and resumes its ticker automatically. Add project-level
+ * behavior such as music, network, or worker handling to this class.
+ */
+export class LifecycleHandler {
+
+	private static _stage?: Stage;
+
+	static init(stage: Stage): void {
+		if (this._stage === stage) return;
+
+		this.clear();
+		this._stage = stage;
+		this._stage.addEventListener(Event.DEACTIVATE, this.onPause);
+		this._stage.addEventListener(Event.ACTIVATE, this.onResume);
+	}
+
+	static clear(): void {
+		if (!this._stage) return;
+
+		this._stage.removeEventListener(Event.DEACTIVATE, this.onPause);
+		this._stage.removeEventListener(Event.ACTIVATE, this.onResume);
+		this._stage = undefined;
+	}
+
+	private static onPause = (): void => {
+		// Add application-specific background behavior here.
+		console.log('paused');
+	};
+
+	private static onResume = (): void => {
+		// Add application-specific foreground behavior here.
+		console.log('resumed');
+	};
+}

package/templates/game/src/Main.ts

@@ -1,138 +1,145 @@
 /**
- * Kurot 标准游戏模板
+ * Kurot game project template.
  *
- * 使用 @kurot/core 进行 Canvas 绘制 + @kurot/game 补间动画。
- * 通过 Shape、TextField 等基础显示对象构建游戏场景。
+ * Builds a responsive interface with @kurot/ui and plays tween animations with @kurot/game.
  *
- * 生命周期：constructor → ADDED_TO_STAGE → $onAddToStage → runGame → loadResource → createGameScene → startAnimation
+ * Lifecycle: constructor → ADDED_TO_STAGE → $onAddToStage → runGame → load → createGameScene → startAnimation
  */
-import { createPlayer, TextField, Shape, Event, Stage, Texture, resource } from '@kurot/core';
-import { Button, DefaultAssetAdapter, Theme, UILayer, setAssetAdapter } from '@kurot/ui';
+import { createPlayer, Event, resource } from '@kurot/core';
+import { Button, Label, Rect, Theme, UILayer, setAssetAdapter } from '@kurot/ui';
 import { Tween } from '@kurot/game';
-import { LoadingUI } from './LoadingUI';
+import { AssetAdapter } from '@/AssetAdapter';
+import { LifecycleHandler } from '@/LifecycleHandler';
+import { Preloader } from '@/Preloader';
 
 class Main extends UILayer {
+	private readonly _preloader = new Preloader();
+
 	createChildren(): void {
 		super.createChildren();
 
 		const stage = this.stage;
 		if (!stage) return;
 
-		this.runGame(stage).catch(e => {
-			console.log(e);
+		setAssetAdapter(new AssetAdapter());
+		LifecycleHandler.init(stage);
+
+		void this.runGame().catch(error => {
+			console.error('[Main] Unable to start game:', error);
 		});
 	}
 
-	private async runGame(stage: Stage): Promise<void> {
-		await this.loadResource(stage);
-		this.installResourceAssetAdapter();
-		await this.loadTheme();
-		this.createGameScene(stage);
+	private async runGame(): Promise<void> {
+		await this.createPreloader();
+		await this.load();
+		this._preloader.destroy();
+		this.createGameScene();
 		this.startAnimation();
 	}
 
-	/**
-	 * 让 EXML 中的 source="button_up_png" 优先解析为预加载图集的子纹理，
-	 * 普通 URL 图片仍交给默认适配器加载。
-	 */
-	private installResourceAssetAdapter(): void {
-		const fallback = new DefaultAssetAdapter();
-		setAssetAdapter({
-			getAsset: (source, callback) => {
-				const texture = resource.get<Texture>(source);
-				if (texture) {
-					callback(texture, source);
-					return;
-				}
-				fallback.getAsset(source, callback);
-			},
-		});
-	}
+	private async load(): Promise<void> {
+		await this.updatePreloader('Loading resource configuration...', 1, 2);
+		await resource.loadConfig('resource/default.res.json', 'resource/');
 
-	private async loadResource(stage: Stage): Promise<void> {
-		const loadingView = new LoadingUI();
-		stage.addChild(loadingView);
+		await this.updatePreloader('Loading theme...', 2, 2);
+		await this.loadTheme();
 
-		try {
-			await resource.loadConfig('resource/default.res.json', 'resource/');
-			if (resource.hasGroup('preload')) {
-				await resource.loadGroup('preload', 0, (loaded, total) => {
-					loadingView.onProgress(loaded, total);
-				});
-			}
-		} catch {
-			// 资源配置文件不存在时静默跳过（纯代码项目无需资源配置）
+		if (resource.hasGroup('preload')) {
+			this._preloader.updateText('Loading resources...');
+			await resource.loadGroup('preload', 0, (loaded, total) => {
+				this._preloader.onProgress(loaded, total);
+			});
 		}
+	}
+
+	private async createPreloader(): Promise<void> {
+		await this._preloader.init();
+		this.addChild(this._preloader);
+	}
 
-		stage.removeChild(loadingView);
+	private async updatePreloader(message: string, current: number, total: number): Promise<void> {
+		this._preloader.updateText(message);
+		this._preloader.updateProgress(current, total);
+		await this.wait(0.1);
 	}
 
 	private async loadTheme(): Promise<void> {
-		// 加载主题（UI 组件默认皮肤映射）
+		// Load the theme and its default UI skin mappings.
 		const theme = new Theme('resource/default.thm.json');
 		await new Promise<void>(resolve => theme.addEventListener(Event.COMPLETE, () => resolve()));
 	}
 
-	private textfield!: TextField;
+	private wait(timeout: number): Promise<void> {
+		return new Promise<void>(resolve => {
+			setTimeout(resolve, timeout * 1000);
+		});
+	}
+
+	private textfield!: Label;
 
 	/**
-	 * 创建游戏场景
+	 * Create the game scene.
 	 *
-	 * 使用 Shape（矢量绘制）和 TextField（文本）等基础显示对象搭建画面。
+	 * Build a responsive view with EUI components and constraint-based layout.
 	 */
-	private createGameScene(stage: Stage): void {
-		const stageW = stage.stageWidth;
-		const stageH = stage.stageHeight;
-
-		// 背景色块
-		const sky = new Shape();
-		sky.graphics.beginFill(0x2d3436, 1);
-		sky.graphics.drawRect(0, 0, stageW, stageH);
-		sky.graphics.endFill();
+	private createGameScene(): void {
+		// Responsive background
+		const sky = new Rect();
+		sky.left = 0;
+		sky.right = 0;
+		sky.top = 0;
+		sky.bottom = 0;
+		sky.fillColor = 0x2d3436;
 		this.addChild(sky);
 
-		// 半透明顶栏
-		const topMask = new Shape();
-		topMask.graphics.beginFill(0x000000, 0.5);
-		topMask.graphics.drawRect(0, 0, stageW, 172);
-		topMask.graphics.endFill();
-		topMask.y = 33;
+		// Translucent header
+		const topMask = new Rect();
+		topMask.left = 0;
+		topMask.right = 0;
+		topMask.top = 33;
+		topMask.height = 172;
+		topMask.fillColor = 0x000000;
+		topMask.fillAlpha = 0.5;
 		this.addChild(topMask);
 
-		// 标题文本
-		const colorLabel = new TextField();
+		// Title
+		const colorLabel = new Label();
 		colorLabel.textColor = 0xffffff;
-		colorLabel.width = stageW;
+		colorLabel.left = 0;
+		colorLabel.right = 0;
+		colorLabel.top = 80;
+		colorLabel.height = 48;
 		colorLabel.textAlign = 'center';
+		colorLabel.verticalAlign = 'middle';
 		colorLabel.text = 'Hello Kurot';
 		colorLabel.size = 36;
-		colorLabel.x = 0;
-		colorLabel.y = 80;
 		this.addChild(colorLabel);
 
-		// 描述文本（用于动画）
-		const textfield = new TextField();
+		// Animated description
+		const textfield = new Label();
 		this.addChild(textfield);
 		textfield.alpha = 0;
-		textfield.width = stageW;
+		textfield.left = 0;
+		textfield.right = 0;
+		textfield.top = 135;
+		textfield.height = 36;
 		textfield.textAlign = 'center';
+		textfield.verticalAlign = 'middle';
 		textfield.size = 24;
 		textfield.textColor = 0xffffff;
-		textfield.x = 0;
-		textfield.y = 135;
 		this.textfield = textfield;
 
-		// UI 按钮示例（需要默认主题）
+		// UI button using the default theme
 		const button = new Button();
 		button.label = 'Click Me';
-		button.x = (stageW - 200) / 2;
-		button.y = 200;
+		button.horizontalCenter = 0;
+		button.top = 200;
 		button.width = 200;
 		this.addChild(button);
 	}
 
 	/**
-	 * 播放文本淡入淡出动画
+	 * Play a looping text fade animation.
 	 */
 	private startAnimation(): void {
 		const texts = ['Open-source, Free, Multi-platform', 'Push Game Forward', 'HTML5 Game Engine'];
@@ -153,7 +160,7 @@ class Main extends UILayer {
 	}
 }
 
-// ── 启动 ──────────────────────────────────────────────────────────────────
+// ── Bootstrap ─────────────────────────────────────────────────────────────
 const app = createPlayer({
 	canvas: document.getElementById('gameCanvas') as HTMLCanvasElement,
 	contentWidth: 640,

package/templates/game/src/Preloader.ts

@@ -0,0 +1,112 @@
+import { Group, Label, Rect, UILayer } from '@kurot/ui';
+
+/**
+ * Displays project startup and resource-loading progress.
+ */
+export class Preloader extends UILayer {
+
+	private readonly _background = new Rect();
+	private readonly _title = new Label();
+	private readonly _tip = new Label();
+	private readonly _progress = new Group();
+	private readonly _track = new Rect();
+	private readonly _thumb = new Rect();
+	private readonly _thumbMask = new Rect();
+
+	init(): Promise<void> {
+		this.createBackground();
+		this.createTitle();
+		this.createProgress();
+		this.createTip();
+		return Promise.resolve();
+	}
+
+	onProgress(current: number, total: number): void {
+		if (total <= 0) return;
+		const width = this.getMaskMaxWidth();
+		this._thumbMask.width = width * 0.7 + width * 0.3 * (current / total);
+	}
+
+	updateProgress(current: number, total: number): void {
+		if (total <= 0) return;
+		this._thumbMask.width = this.getMaskMaxWidth() * 0.7 * current / total;
+	}
+
+	updateText(text: string): void {
+		this._tip.text = text;
+	}
+
+	destroy(): void {
+		if (this.parent) {
+			this.parent.removeChild(this);
+		}
+	}
+
+	private createBackground(): void {
+		this.addChild(this._background);
+		this._background.left = 0;
+		this._background.right = 0;
+		this._background.top = 0;
+		this._background.bottom = 0;
+		this._background.fillColor = 0x2d3436;
+	}
+
+	private createTitle(): void {
+		this.addChild(this._title);
+		this._title.text = 'KUROT';
+		this._title.size = 48;
+		this._title.bold = true;
+		this._title.width = 400;
+		this._title.height = 64;
+		this._title.textAlign = 'center';
+		this._title.verticalAlign = 'middle';
+		this._title.horizontalCenter = 0;
+		this._title.verticalCenter = -80;
+	}
+
+	private createProgress(): void {
+		this.addChild(this._progress);
+		this._progress.width = 520;
+		this._progress.height = 24;
+		this._progress.horizontalCenter = 0;
+		this._progress.verticalCenter = 10;
+
+		this._progress.addChild(this._track);
+		this._track.left = 0;
+		this._track.right = 0;
+		this._track.top = 0;
+		this._track.bottom = 0;
+		this._track.fillColor = 0xffffff;
+
+		this._progress.addChild(this._thumb);
+		this._thumb.left = 4;
+		this._thumb.right = 4;
+		this._thumb.top = 4;
+		this._thumb.bottom = 4;
+		this._thumb.fillColor = 0x00a8ff;
+
+		this._progress.addChild(this._thumbMask);
+		this._thumbMask.left = 4;
+		this._thumbMask.top = 4;
+		this._thumbMask.bottom = 4;
+		this._thumbMask.width = 0;
+		this._thumb.mask = this._thumbMask;
+	}
+
+	private createTip(): void {
+		this.addChild(this._tip);
+		this._tip.text = 'Starting...';
+		this._tip.size = 20;
+		this._tip.width = 520;
+		this._tip.height = 40;
+		this._tip.textAlign = 'center';
+		this._tip.verticalAlign = 'middle';
+		this._tip.horizontalCenter = 0;
+		this._tip.verticalCenter = 60;
+	}
+
+	private getMaskMaxWidth(): number {
+		const inset = Number(this._thumbMask.left) || 0;
+		return this._progress.width - inset * 2;
+	}
+}

package/templates/game/src/game-components.ts

@@ -0,0 +1,6 @@
+/**
+ * Central export entry for custom EXML components.
+ *
+ * Export components used as `<game:ComponentName />` in EXML from this file.
+ * This entry is configured by `exml.namespaces.game` in `kurot.config.ts`.
+ */

package/templates/game/tsconfig.json

@@ -3,6 +3,9 @@
 		"target": "ES2022",
 		"module": "ESNext",
 		"moduleResolution": "bundler",
+		"paths": {
+			"@/*": ["./src/*"]
+		},
 		"strict": true,
 		"skipLibCheck": true,
 	},

package/templates/game/src/LoadingUI.ts

@@ -1,27 +0,0 @@
-/**
- * 资源加载进度界面
- *
- * 在资源加载期间显示 "Loading...current/total" 文本。
- * 对应 Egret 的 LoadingUI。
- */
-import { Sprite, TextField } from '@kurot/core';
-
-class LoadingUI extends Sprite {
-	private textField: TextField;
-
-	public constructor() {
-		super();
-		this.textField = new TextField();
-		this.addChild(this.textField);
-		this.textField.y = 300;
-		this.textField.width = 480;
-		this.textField.height = 100;
-		this.textField.textAlign = 'center';
-	}
-
-	public onProgress(current: number, total: number): void {
-		this.textField.text = `Loading...${current}/${total}`;
-	}
-}
-
-export { LoadingUI };