@kurot/cli 3.2.0 → 3.3.0

package/docs/label-text-layout.md

@@ -1,6 +1,6 @@
 # Label text compilation
 
-CLI 3.2.0 consumes ui-document 0.10.x and compiles KUI text-fitting properties
+CLI 3.3.0 consumes ui-document 0.11.x and compiles KUI text-fitting properties
 through the existing UIDocument → SkinIR → ESM factory pipeline. The semantic
 document format remains version 2.
 
@@ -27,6 +27,11 @@ The compiler does not measure fonts or change `size` based on text length,
 currency, locale or display bounds. Source XML remains authored data; neither
 derived sizes nor fitting diagnostics are persisted by compilation.
 
+Label presets supply baseline appearance before local and state fields are
+applied. They do not own wrapping or fitting policy, and preset expansion never
+introduces build-time text measurement. See the
+[shared style contract](../../ui-document/docs/project-styles.md).
+
 ## Runtime boundary
 
 - The application must install UI `^3.1.0` and Core `^2.1.0` for shrinking.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.2.0",
+	"version": "3.3.0",
 	"description": "Kurot CLI - build tool for Kurot Editor KUI XML workflows",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"kurot": "tsx src/index.ts"
 	},
 	"dependencies": {
-		"@kurot/ui-document": "^0.10.0",
+		"@kurot/ui-document": "^0.11.0",
 		"commander": "^13.0.0",
 		"esbuild": "^0.25.0"
 	},

package/templates/game/package.json

@@ -11,7 +11,8 @@
 	"dependencies": {
 		"@kurot/core": "latest",
 		"@kurot/game": "latest",
-		"@kurot/ui": "latest"
+		"@kurot/ui": "latest",
+		"@kurot/ui-document": "latest"
 	},
 	"devDependencies": {
 		"@kurot/cli": "latest"

package/templates/game/resource/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/templates/game/resource/config/locale.json

@@ -0,0 +1,4 @@
+{
+	"locale": [{ "code": "en_US", "name": "English" }],
+	"defaultLocale": "en_US"
+}

package/templates/game/resource/config/style.json

@@ -0,0 +1,16 @@
+{
+	"schemaVersion": 1,
+	"fonts": {
+		"default": "primary",
+		"families": {
+			"primary": {
+				"fallback": ["Arial", "sans-serif"],
+				"faces": [
+					{ "url": "assets/fonts/ChakraPetch-Regular.ttf", "weight": 400 },
+					{ "url": "assets/fonts/ChakraPetch-Bold.ttf", "weight": 700 }
+				]
+			}
+		}
+	},
+	"colors": { "disabled-text": "#999999" }
+}

package/templates/game/resource/default.res.json

@@ -1,7 +1,7 @@
 {
 	"groups": [
 		{
-			"keys": "eui",
+			"keys": "eui,locale_json,lang_en_US_properties",
 			"name": "preload"
 		}
 	],
@@ -10,6 +10,16 @@
 			"name": "eui",
 			"type": "sheet",
 			"url": "assets/ui/eui/eui.json"
+		},
+		{
+			"name": "locale_json",
+			"type": "json",
+			"url": "config/locale.json"
+		},
+		{
+			"name": "lang_en_US_properties",
+			"type": "text",
+			"url": "lang/lang_en_US.properties"
 		}
 	]
 }

package/templates/game/resource/lang/lang_en_US.properties

@@ -0,0 +1,5 @@
+label.title=Hello Kurot
+label.button=Click Me
+label.description.open_source=Open-source, Free, Multi-platform
+label.description.push_forward=Push Game Forward
+label.description.engine=HTML5 Game Engine

package/templates/game/resource/ui/skins/ButtonSkin.kui.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ButtonSkin" states="disabled,down,up" minHeight="50" minWidth="100">
     <Image height="100%" scale9Grid="1,3,8,8" source="button_up_png" width="100%" alpha.disabled="0.5" source.down="button_down_png" />
-    <Label id="labelDisplay" bottom="8" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" top="8" verticalAlign="middle" />
+    <Label id="labelDisplay" bottom="8" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" textColor.disabled="@style:colors:disabled-text" top="8" verticalAlign="middle" />
     <Image id="iconDisplay" horizontalCenter="0" verticalCenter="0" />
 </Skin>

package/templates/game/resource/ui/skins/CheckBoxSkin.kui.xml

@@ -5,6 +5,6 @@
             <HorizontalLayout verticalAlign="middle" />
         </layout>
         <Image alpha="1" fillMode="scale" source="checkbox_unselect_png" alpha.disabled="0.5" source.disabledAndSelected="checkbox_select_disabled_png" alpha.down="0.7" source.downAndSelected="checkbox_select_down_png" source.upAndSelected="checkbox_select_up_png" />
-        <Label id="labelDisplay" fontFamily="Tahoma" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
+        <Label id="labelDisplay" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
     </Group>
 </Skin>

package/templates/game/resource/ui/skins/ComboBoxSkin.kui.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ComboBoxSkin" states="disabled,normal,open" minHeight="36" minWidth="100">
     <Rect fillColor="#1A1A2E" height="36" strokeColor="#0F3460" strokeWeight="1" width="100%" fillColor.disabled="#16213E" strokeColor.disabled="#4A5459" fillColor.open="#16213E" strokeColor.open="#6C5CE7" />
-    <Label id="labelDisplay" height="36" left="10" right="36" size="14" textColor="#DFE6E9" top="0" verticalAlign="middle" textColor.disabled="#636E72" />
+    <Label id="labelDisplay" height="36" left="10" right="36" size="14" textColor="#DFE6E9" top="0" verticalAlign="middle" textColor.disabled="@style:colors:disabled-text" />
     <Label height="36" right="4" size="10" text="▼" textAlign="center" textColor="#636E72" top="0" verticalAlign="middle" width="24" textColor.open="#6C5CE7" />
     <Scroller id="dropDown" height="180" left="0" right="0" top="36" visible="false">
         <List id="list" height="180" width="100%" />

package/templates/game/resource/ui/skins/ItemRendererSkin.kui.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ItemRendererSkin" states="disabled,down,up" minHeight="50" minWidth="100">
     <Image height="100%" scale9Grid="1,3,8,8" source="button_up_png" width="100%" alpha.disabled="0.5" source.down="button_down_png" />
-    <Label id="labelDisplay" bottom="8" fontFamily="Tahoma" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" top="8" verticalAlign="middle" />
+    <Label id="labelDisplay" bottom="8" left="8" right="8" size="20" textAlign="center" textColor="#FFFFFF" top="8" verticalAlign="middle" />
 </Skin>

package/templates/game/resource/ui/skins/PanelSkin.kui.xml

@@ -3,7 +3,7 @@
     <Image bottom="0" left="0" right="0" scale9Grid="2,2,12,12" source="border_png" top="0" />
     <Group id="moveArea" height="45" left="0" right="0" top="0">
         <Image bottom="0" left="0" right="0" scale9Grid="2,2,12,12" source="header_png" top="0" />
-        <Label id="titleDisplay" fontFamily="Tahoma" left="15" right="5" size="20" textColor="#FFFFFF" verticalCenter="0" wordWrap="false" />
+        <Label id="titleDisplay" left="15" right="5" size="20" textColor="#FFFFFF" verticalCenter="0" wordWrap="false" />
     </Group>
     <Button id="closeButton" bottom="5" horizontalCenter="0" label="close" />
 </Skin>

package/templates/game/resource/ui/skins/ProgressBarSkin.kui.xml

@@ -2,5 +2,5 @@
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ProgressBarSkin" minHeight="18" minWidth="30">
     <Image height="100%" scale9Grid="1,1,4,4" source="track_pb_png" verticalCenter="0" width="100%" />
     <Image id="thumb" height="100%" scale9Grid="1,1,4,4" source="thumb_pb_png" width="100%" />
-    <Label id="labelDisplay" fontFamily="Tahoma" horizontalCenter="0" size="15" textAlign="center" textColor="#707070" verticalAlign="middle" verticalCenter="0" />
+    <Label id="labelDisplay" horizontalCenter="0" size="15" textAlign="center" textColor="#707070" verticalAlign="middle" verticalCenter="0" />
 </Skin>

package/templates/game/resource/ui/skins/RadioButtonSkin.kui.xml

@@ -5,6 +5,6 @@
             <HorizontalLayout verticalAlign="middle" />
         </layout>
         <Image alpha="1" fillMode="scale" source="radiobutton_unselect_png" alpha.disabled="0.5" source.disabledAndSelected="radiobutton_select_disabled_png" alpha.down="0.7" source.downAndSelected="radiobutton_select_down_png" source.upAndSelected="radiobutton_select_up_png" />
-        <Label id="labelDisplay" fontFamily="Tahoma" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
+        <Label id="labelDisplay" size="20" textAlign="center" textColor="#707070" verticalAlign="middle" />
     </Group>
 </Skin>

package/templates/game/resource/ui/skins/TextInputSkin.kui.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.TextInputSkin" states="disabled,disabledWithPrompt,normal,normalWithPrompt" minHeight="40" minWidth="300">
     <Rect fillColor="#FFFFFF" height="100%" width="100%" alpha.disabled="0.5" />
-    <EditableText id="textDisplay" height="24" left="10" right="10" size="20" textColor="#000000" verticalAlign="middle" verticalCenter="0" textColor.disabled="#FF0000" />
+    <EditableText id="textDisplay" height="24" left="10" right="10" size="20" textColor="#000000" verticalAlign="middle" verticalCenter="0" textColor.disabled="@style:colors:disabled-text" />
     <Label id="promptDisplay" height="24" left="10" multiline="false" right="10" size="20" textColor="#A9A9A9" touchEnabled="false" verticalAlign="middle" verticalCenter="0" visible="false" wordWrap="false" visible.disabledWithPrompt="true" visible.normalWithPrompt="true" />
 </Skin>

package/templates/game/resource/ui/skins/ToggleButtonSkin.kui.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Skin xmlns="https://kurot.dev/ui/1" class="skins.ToggleButtonSkin" states="disabled,disabledAndSelected,down,downAndSelected,up,upAndSelected" minHeight="50" minWidth="100">
     <Rect fillColor="#636E72" height="100%" strokeColor="#4A5459" strokeWeight="1" width="100%" fillColor.disabled="#2D3436" fillColor.disabledAndSelected="#2D3436" fillColor.down="#4A5459" fillColor.downAndSelected="#5A4BD1" fillColor.upAndSelected="#6C5CE7" />
-    <Label id="labelDisplay" bottom="8" left="8" right="8" size="16" textAlign="center" textColor="#DFE6E9" top="8" verticalAlign="middle" textColor.disabled="#636E72" textColor.upAndSelected="#FFFFFF" />
+    <Label id="labelDisplay" bottom="8" left="8" right="8" size="16" textAlign="center" textColor="#DFE6E9" top="8" verticalAlign="middle" textColor.disabled="@style:colors:disabled-text" textColor.upAndSelected="#FFFFFF" />
 </Skin>

package/templates/game/src/LocaleManager.ts

@@ -0,0 +1,109 @@
+/**
+ * preload 完成后注册项目翻译。URL 的 lang 优先，缺失翻译回退英语，再回退键名。
+ * 不监听 UI、不自动重写文本；界面创建时主动调用 getString。
+ */
+export class LocaleManager {
+	private static _locales = new Map<string, ReadonlyMap<string, string>>();
+	private static _currentLocale = '';
+
+	public static get currentLocale(): string {
+		return this._currentLocale;
+	}
+
+	/**
+	 * 先验证整份配置及语言资源，成功后一起替换，避免加载失败留下半套翻译。
+	 */
+	public static init(config: unknown, readResource: (name: string) => unknown, requestedLocale = ''): void {
+		const locales = new Map<string, ReadonlyMap<string, string>>();
+		let defaultLocale = '';
+		if (config !== undefined) {
+			if (!isRecord(config) || !Array.isArray(config.locale)) {
+				throw new Error('locale.json must contain a locale array.');
+			}
+			for (const entry of config.locale as unknown[]) {
+				if (
+					!isRecord(entry) ||
+					typeof entry.code !== 'string' ||
+					!/^[a-z]{2}_[A-Z]{2}$/.test(entry.code) ||
+					typeof entry.name !== 'string' ||
+					entry.name.trim() === ''
+				) {
+					throw new Error('Each project language must have a language code and name.');
+				}
+				if (locales.has(entry.code)) {
+					throw new Error(`Duplicate project language: ${entry.code}.`);
+				}
+				const source = readResource(`lang_${entry.code}_properties`);
+				if (typeof source !== 'string') {
+					throw new Error(`Language resource is unavailable: ${entry.code}.`);
+				}
+				locales.set(entry.code, this._parse(source));
+			}
+			const configuredDefault =
+				config.defaultLocale === undefined ? (locales.has('en_US') ? 'en_US' : '') : config.defaultLocale;
+			if (
+				typeof configuredDefault !== 'string' ||
+				(configuredDefault !== '' && !locales.has(configuredDefault))
+			) {
+				throw new Error('defaultLocale must name an enabled language or be empty.');
+			}
+			defaultLocale = configuredDefault;
+		}
+
+		const normalized = requestedLocale.trim().replace(/-/g, '_').toLowerCase();
+		const codes = [...locales.keys()];
+		const exact = codes.find(code => code.toLowerCase() === normalized);
+		const base = normalized.split('_')[0];
+		this._currentLocale = exact ?? codes.find(code => code.toLowerCase().split('_')[0] === base) ?? defaultLocale;
+		this._locales = locales;
+	}
+
+	public static getString(key: string, ...args: Array<string | number>): string {
+		const text = this._locales.get(this._currentLocale)?.get(key) ?? this._locales.get('en_US')?.get(key) ?? key;
+		return text.replace(/\{(\d+)\}/g, (placeholder: string, index: string) => {
+			const argument = args[Number(index)];
+			return argument === undefined ? placeholder : String(argument);
+		});
+	}
+
+	private static _parse(source: string): ReadonlyMap<string, string> {
+		const values = new Map<string, string>();
+		for (const line of source.split(/\r?\n/)) {
+			const content = line.trim();
+			if (!content || content.startsWith('#') || content.startsWith('!')) {
+				continue;
+			}
+			const split = line.indexOf('=');
+			if (split < 0) {
+				continue;
+			}
+			const key = line.slice(0, split).trim();
+			if (key) {
+				values.set(key, this._decodeValue(line.slice(split + 1).trim()));
+			}
+		}
+		return values;
+	}
+
+	private static _decodeValue(value: string): string {
+		return value.replace(/\\(u[0-9a-fA-F]{4}|[nrt\\=: ])/g, (_match: string, escape: string) => {
+			if (escape.startsWith('u')) {
+				return String.fromCharCode(Number.parseInt(escape.slice(1), 16));
+			}
+			switch (escape) {
+				case 'n':
+					return '\n';
+				case 'r':
+					return '\r';
+				case 't':
+					return '\t';
+				default:
+					return escape;
+			}
+		});
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/templates/game/src/Main.ts

@@ -5,15 +5,18 @@
  *
  * Lifecycle: constructor → ADDED_TO_STAGE → $onAddToStage → runGame → load → createGameScene → startAnimation
  */
-import { createPlayer, Event, resource } from '@kurot/core';
+import { createPlayer, Event, resource, TextField } from '@kurot/core';
 import { Button, Label, Rect, Theme, UILayer, setAssetAdapter } from '@kurot/ui';
 import { Tween } from '@kurot/game';
 import { AssetAdapter } from '@/AssetAdapter';
 import { LifecycleHandler } from '@/LifecycleHandler';
 import { Preloader } from '@/Preloader';
+import { LocaleManager } from '@/LocaleManager';
+import { StyleManager } from '@/StyleManager';
 
 class Main extends UILayer {
 	private readonly _preloader = new Preloader();
+	private _description!: Label;
 
 	createChildren(): void {
 		super.createChildren();
@@ -24,25 +27,25 @@ class Main extends UILayer {
 		setAssetAdapter(new AssetAdapter());
 		LifecycleHandler.init(stage);
 
-		void this.runGame().catch(error => {
+		void this._runGame().catch(error => {
 			console.error('[Main] Unable to start game:', error);
 		});
 	}
 
-	private async runGame(): Promise<void> {
-		await this.createPreloader();
-		await this.load();
+	private async _runGame(): Promise<void> {
+		await this._createPreloader();
+		await this._load();
 		this._preloader.destroy();
-		this.createGameScene();
-		this.startAnimation();
+		this._createGameScene();
+		this._startAnimation();
 	}
 
-	private async load(): Promise<void> {
-		await this.updatePreloader('Loading resource configuration...', 1, 2);
+	private async _load(): Promise<void> {
+		await this._updatePreloader('Loading resource configuration...', 1, 2);
 		await resource.loadConfig('resource/default.res.json', 'resource/');
 
-		await this.updatePreloader('Loading theme...', 2, 2);
-		await this.loadTheme();
+		await this._updatePreloader('Loading theme...', 2, 2);
+		await this._loadTheme();
 
 		if (resource.hasGroup('preload')) {
 			this._preloader.updateText('Loading resources...');
@@ -50,39 +53,44 @@ class Main extends UILayer {
 				this._preloader.onProgress(loaded, total);
 			});
 		}
+
+		// 翻译依赖 preload 中的文本资源；加载完毕后再创建业务界面。
+		LocaleManager.init(
+			resource.get('locale_json'),
+			name => resource.get(name),
+			new URLSearchParams(window.location.search).get('lang') ?? '',
+		);
 	}
 
-	private async createPreloader(): Promise<void> {
+	private async _createPreloader(): Promise<void> {
 		await this._preloader.init();
 		this.addChild(this._preloader);
 	}
 
-	private async updatePreloader(message: string, current: number, total: number): Promise<void> {
+	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);
+		await this._wait(0.1);
 	}
 
-	private async loadTheme(): Promise<void> {
+	private async _loadTheme(): Promise<void> {
 		// 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 wait(timeout: number): Promise<void> {
+	private _wait(timeout: number): Promise<void> {
 		return new Promise<void>(resolve => {
 			setTimeout(resolve, timeout * 1000);
 		});
 	}
 
-	private textfield!: Label;
-
 	/**
 	 * Create the game scene.
 	 *
 	 * Build a responsive view with EUI components and constraint-based layout.
 	 */
-	private createGameScene(): void {
+	private _createGameScene(): void {
 		// Responsive background
 		const sky = new Rect();
 		sky.left = 0;
@@ -111,7 +119,7 @@ class Main extends UILayer {
 		colorLabel.height = 48;
 		colorLabel.textAlign = 'center';
 		colorLabel.verticalAlign = 'middle';
-		colorLabel.text = 'Hello Kurot';
+		colorLabel.text = LocaleManager.getString('label.title');
 		colorLabel.size = 36;
 		this.addChild(colorLabel);
 
@@ -127,11 +135,11 @@ class Main extends UILayer {
 		textfield.verticalAlign = 'middle';
 		textfield.size = 24;
 		textfield.textColor = 0xffffff;
-		this.textfield = textfield;
+		this._description = textfield;
 
 		// UI button using the default theme
 		const button = new Button();
-		button.label = 'Click Me';
+		button.label = LocaleManager.getString('label.button');
 		button.horizontalCenter = 0;
 		button.top = 200;
 		button.width = 200;
@@ -141,16 +149,20 @@ class Main extends UILayer {
 	/**
 	 * Play a looping text fade animation.
 	 */
-	private startAnimation(): void {
-		const texts = ['Open-source, Free, Multi-platform', 'Push Game Forward', 'HTML5 Game Engine'];
+	private _startAnimation(): void {
+		const texts = [
+			LocaleManager.getString('label.description.open_source'),
+			LocaleManager.getString('label.description.push_forward'),
+			LocaleManager.getString('label.description.engine'),
+		];
 		let count = -1;
 		const change = () => {
 			count++;
 			if (count >= texts.length) {
 				count = 0;
 			}
-			this.textfield.text = texts[count];
-			const tw = Tween.get(this.textfield);
+			this._description.text = texts[count];
+			const tw = Tween.get(this._description);
 			tw.to({ alpha: 1 }, 200);
 			tw.wait(2000);
 			tw.to({ alpha: 0 }, 200);
@@ -161,12 +173,24 @@ class Main extends UILayer {
 }
 
 // ── Bootstrap ─────────────────────────────────────────────────────────────
-const app = createPlayer({
-	canvas: document.getElementById('gameCanvas') as HTMLCanvasElement,
-	contentWidth: 640,
-	contentHeight: 1136,
-	scaleMode: 'showAll',
-	frameRate: 60,
-});
+async function start(): Promise<void> {
+	// 包括 Preloader 在内的所有 Label 首次测量都使用已就绪的项目字体。
+	await StyleManager.init();
+	TextField.default_fontFamily = StyleManager.fontFamily;
+	const canvas = document.getElementById('gameCanvas');
+	if (!(canvas instanceof HTMLCanvasElement)) {
+		throw new Error('Missing gameCanvas.');
+	}
+	const app = createPlayer({
+		canvas,
+		contentWidth: 640,
+		contentHeight: 1136,
+		scaleMode: 'showAll',
+		frameRate: 60,
+	});
+	app.start(new Main());
+}
 
-app.start(new Main());
+void start().catch(error => {
+	console.error('[Main] Unable to start project:', error);
+});

package/templates/game/src/StyleManager.ts

@@ -0,0 +1,57 @@
+import { getUIStyleColor, getUIStyleFontAlias, getUIStyleFontFamily, parseUIStyleSheet } from '@kurot/ui-document';
+import type { UIStyleFontFace } from '@kurot/ui-document';
+
+/**
+ * 项目启动时加载固定样式表，字体全部就绪后再创建 Player 和 UI。
+ * 字体别名保持稳定，换字体文件不需要逐个修改皮肤。
+ */
+export class StyleManager {
+	private static _colors: Readonly<Record<string, number>> = Object.freeze({});
+	private static _fontFamily?: string;
+
+	public static get fontFamily(): string {
+		if (this._fontFamily === undefined) {
+			throw new Error('Project styles are not initialized.');
+		}
+		return this._fontFamily;
+	}
+
+	public static async init(): Promise<void> {
+		const resourceRoot = new URL('resource/', document.baseURI);
+		const response = await fetch(new URL('config/style.json', resourceRoot));
+		if (!response.ok) {
+			throw new Error(`Unable to load resource/config/style.json: HTTP ${response.status}.`);
+		}
+		const stylesheet = parseUIStyleSheet(await response.json());
+		const loading = Object.entries(stylesheet.fonts.families).flatMap(([key, family]) =>
+			family.faces.map(face => this._loadFace(key, face, resourceRoot)),
+		);
+		const faces = await Promise.all(loading);
+
+		// 全部成功后一次性发布，失败时不留下半套字体或新的默认值。
+		for (const face of faces) {
+			document.fonts.add(face);
+		}
+		this._fontFamily = getUIStyleFontFamily(stylesheet);
+		this._colors = stylesheet.colors;
+	}
+
+	/**
+	 * 业务代码需要动态设置文字颜色时，读取与皮肤编译相同的颜色表。
+	 */
+	public static getColor(key: string): number {
+		return getUIStyleColor(this._colors, key);
+	}
+
+	private static async _loadFace(key: string, definition: UIStyleFontFace, resourceRoot: URL): Promise<FontFace> {
+		const url = new URL(definition.url.split('/').map(encodeURIComponent).join('/'), resourceRoot);
+		const face = new FontFace(getUIStyleFontAlias(key), `url("${url.href}")`, {
+			weight: String(definition.weight),
+		});
+		try {
+			return await face.load();
+		} catch (cause) {
+			throw new Error(`Unable to load project font ${key} (${definition.weight}): ${definition.url}.`, { cause });
+		}
+	}
+}