Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(tools): add asset-meta.js generator

esengine8d5eedb7d1c5
diff --git a/examples/audio-demo/assets/scenes/main.esscene.meta b/examples/audio-demo/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..6662dda96
--- /dev/null
+++ b/examples/audio-demo/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "cff10d6f-1f59-4d0f-8de3-71f128f4acd1",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/audio-demo/thumbnail.png.meta b/examples/audio-demo/thumbnail.png.meta
new file mode 100644
index 000000000..e3bc6ac85
--- /dev/null
+++ b/examples/audio-demo/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "b5fab6fb-9a8e-469c-8641-a2c7762b82d2",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/collision-layers/assets/scenes/main.esscene.meta b/examples/collision-layers/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..c2f7250da
--- /dev/null
+++ b/examples/collision-layers/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "d3ba054e-19be-4a3d-824f-8de2fc5be177",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/collision-layers/thumbnail.png.meta b/examples/collision-layers/thumbnail.png.meta
new file mode 100644
index 000000000..81c15c035
--- /dev/null
+++ b/examples/collision-layers/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "bb13495c-a178-4f34-991f-68e2650efd59",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/ecs-basics/assets/scenes/main.esscene.meta b/examples/ecs-basics/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..7704f68e9
--- /dev/null
+++ b/examples/ecs-basics/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "89b4b7c0-2558-4946-b861-89d84433523f",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/ecs-basics/thumbnail.png.meta b/examples/ecs-basics/thumbnail.png.meta
new file mode 100644
index 000000000..336b89a99
--- /dev/null
+++ b/examples/ecs-basics/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "918b254e-521c-4a5e-8a34-2771d8fb56c2",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/event-system/assets/scenes/main.esscene.meta b/examples/event-system/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..e20e29e73
--- /dev/null
+++ b/examples/event-system/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "3393ce7f-819a-4ba2-b307-1bac4cee38f1",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/event-system/thumbnail.png.meta b/examples/event-system/thumbnail.png.meta
new file mode 100644
index 000000000..082b02350
--- /dev/null
+++ b/examples/event-system/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "c87a1215-7003-47dd-9d0b-6069e13423c0",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/hello-world/assets/scenes/main.esscene.meta b/examples/hello-world/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..29ee19120
--- /dev/null
+++ b/examples/hello-world/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "11110905-e25d-486c-b92c-8a46af7e5cac",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/hello-world/thumbnail.png.meta b/examples/hello-world/thumbnail.png.meta
new file mode 100644
index 000000000..9fd38f0ce
--- /dev/null
+++ b/examples/hello-world/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "97879b83-094b-49d3-85eb-d1f91fa9d166",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/input-demo/assets/scenes/main.esscene.meta b/examples/input-demo/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..100bdd6a9
--- /dev/null
+++ b/examples/input-demo/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "edfca09d-35d9-4230-a635-542b3f0d4b2e",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/input-demo/thumbnail.png.meta b/examples/input-demo/thumbnail.png.meta
new file mode 100644
index 000000000..53c6181ce
--- /dev/null
+++ b/examples/input-demo/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "a4750870-a618-402c-93d0-bc3fa4aaa39d",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/particle-demo/assets/scenes/main.esscene.meta b/examples/particle-demo/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..ebc341fc4
--- /dev/null
+++ b/examples/particle-demo/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "7ad6ad60-649f-4573-b7f2-e6c0f517ea70",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/particle-demo/thumbnail.png.meta b/examples/particle-demo/thumbnail.png.meta
new file mode 100644
index 000000000..f32229f4e
--- /dev/null
+++ b/examples/particle-demo/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "9e89662f-a9cb-442c-9c2d-807374ed795f",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/physics-playground/assets/scenes/main.esscene.meta b/examples/physics-playground/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..56fc05551
--- /dev/null
+++ b/examples/physics-playground/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "6ee97d71-5610-422f-aa69-0b6fb4f058be",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/physics-playground/thumbnail.png.meta b/examples/physics-playground/thumbnail.png.meta
new file mode 100644
index 000000000..75c516cc1
--- /dev/null
+++ b/examples/physics-playground/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "3747e027-4da3-4aa7-95eb-a27d1070e122",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/physics-spinner/assets/scenes/main.esscene.meta b/examples/physics-spinner/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..d73db8531
--- /dev/null
+++ b/examples/physics-spinner/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "6765345d-95f4-484e-857e-d923f85e3973",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/physics-spinner/thumbnail.png.meta b/examples/physics-spinner/thumbnail.png.meta
new file mode 100644
index 000000000..8ca666ce2
--- /dev/null
+++ b/examples/physics-spinner/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "a481d240-cf0d-4af2-ae29-e8663aa5b05b",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/platformer/assets/scenes/main.esscene.meta b/examples/platformer/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..9a2e8f7aa
--- /dev/null
+++ b/examples/platformer/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "1ef4ddaa-5868-4e7b-a68d-10fc54a54590",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/platformer/thumbnail.png.meta b/examples/platformer/thumbnail.png.meta
new file mode 100644
index 000000000..61912b454
--- /dev/null
+++ b/examples/platformer/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "416a8e48-781e-40d0-893d-ca3d48048731",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/postprocess-effects/assets/scenes/main.esscene.meta b/examples/postprocess-effects/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..e3a47e061
--- /dev/null
+++ b/examples/postprocess-effects/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "ed934c38-c223-4c2a-8f39-2ab68572dc85",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/postprocess-effects/thumbnail.png.meta b/examples/postprocess-effects/thumbnail.png.meta
new file mode 100644
index 000000000..27edd28b4
--- /dev/null
+++ b/examples/postprocess-effects/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "37a154b0-f6ac-4902-939f-94358c8abd59",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/space-shooter/thumbnail.png.meta b/examples/space-shooter/thumbnail.png.meta
new file mode 100644
index 000000000..837b5660f
--- /dev/null
+++ b/examples/space-shooter/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "59ee957a-82fe-41e8-aa26-6150d43abcd0",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/sprite-animation/assets/scenes/main.esscene.meta b/examples/sprite-animation/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..208e6e8af
--- /dev/null
+++ b/examples/sprite-animation/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "e0a7b54e-aac3-4c42-bd57-880f016d5edc",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/sprite-animation/thumbnail.png.meta b/examples/sprite-animation/thumbnail.png.meta
new file mode 100644
index 000000000..533629cc7
--- /dev/null
+++ b/examples/sprite-animation/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "31e3c8bf-1e8b-42bf-b3e2-a912ccf178b6",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/sprite-rendering/assets/scenes/main.esscene.meta b/examples/sprite-rendering/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..5080eca2f
--- /dev/null
+++ b/examples/sprite-rendering/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "2afac873-adfe-4460-8c63-98db1d7961e7",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/sprite-rendering/thumbnail.png.meta b/examples/sprite-rendering/thumbnail.png.meta
new file mode 100644
index 000000000..4d4b5372c
--- /dev/null
+++ b/examples/sprite-rendering/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "ae6aaac0-e2bd-4e4c-a495-e5d55496f110",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/tween-animation/assets/scenes/main.esscene.meta b/examples/tween-animation/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..289e806d6
--- /dev/null
+++ b/examples/tween-animation/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "6e57c5f0-327d-4e9c-bf1f-6ee3dbfa2399",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/tween-animation/thumbnail.png.meta b/examples/tween-animation/thumbnail.png.meta
new file mode 100644
index 000000000..e9e3c1501
--- /dev/null
+++ b/examples/tween-animation/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "d5b4893a-7482-447e-bcfb-9bf782beabfa",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/ui-controls/assets/scenes/main.esscene.meta b/examples/ui-controls/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..a82406f99
--- /dev/null
+++ b/examples/ui-controls/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "0f324270-e837-41de-ba7f-3555d43f836f",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/ui-controls/thumbnail.png.meta b/examples/ui-controls/thumbnail.png.meta
new file mode 100644
index 000000000..52f473c17
--- /dev/null
+++ b/examples/ui-controls/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "93cd260e-e1c9-4642-af66-bf5e9bad45fd",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/ui-interaction/assets/scenes/main.esscene.meta b/examples/ui-interaction/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..1f451c33c
--- /dev/null
+++ b/examples/ui-interaction/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "f97b75b8-0d91-45fe-8475-3a17fe871a3e",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/ui-interaction/thumbnail.png.meta b/examples/ui-interaction/thumbnail.png.meta
new file mode 100644
index 000000000..c25eee83a
--- /dev/null
+++ b/examples/ui-interaction/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "88a30251-9960-4034-ada1-63ea67891858",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/ui-layout/assets/scenes/main.esscene.meta b/examples/ui-layout/assets/scenes/main.esscene.meta
new file mode 100644
index 000000000..230e68c3b
--- /dev/null
+++ b/examples/ui-layout/assets/scenes/main.esscene.meta
@@ -0,0 +1,8 @@
+{
+ "uuid": "48032b8e-c92c-44d4-b47f-fff10a1327b7",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {
+ "autoMigrate": true
+ }
+}
diff --git a/examples/ui-layout/thumbnail.png.meta b/examples/ui-layout/thumbnail.png.meta
new file mode 100644
index 000000000..cf81b2780
--- /dev/null
+++ b/examples/ui-layout/thumbnail.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "6ed4f519-59ea-4471-868b-21fb319e336f",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "repeat",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/package.json b/package.json
index 2fc263757..52aaab045 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
"dev": "node build-tools/cli.js watch",
"clean": "node build-tools/cli.js clean -a",
"eht": "node build-tools/cli.js eht",
- "sync": "node build-tools/cli.js sync"
+ "sync": "node build-tools/cli.js sync",
+ "asset-meta": "node tools/asset-meta.js"
},
"dependencies": {
"chalk": "^5.3.0",
diff --git a/tools/asset-meta.js b/tools/asset-meta.js
new file mode 100644
index 000000000..134bab8e7
--- /dev/null
+++ b/tools/asset-meta.js
@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * @file asset-meta.js
+ * @brief Generate .meta sidecar files for assets (UUID v4 + importer defaults).
+ *
+ * Each asset file (texture, audio, prefab, scene, etc.) gets a JSON sidecar
+ * `<file>.meta` with a stable UUID and type-appropriate importer defaults.
+ * Already-present .meta files are never overwritten — the UUID is the stable
+ * identity for scene/prefab references and must survive across runs.
+ *
+ * Usage:
+ * node tools/asset-meta.js <dir>... # generate missing metas
+ * node tools/asset-meta.js <dir> --dry-run # preview only
+ * node tools/asset-meta.js <dir> --check # exit 1 if any missing (CI)
+ * node tools/asset-meta.js <dir> --verbose
+ *
+ * Exit codes:
+ * 0 — success; all assets have meta (or --dry-run preview)
+ * 1 — --check mode: one or more assets missing .meta
+ * 2 — usage / IO error
+ */
+
+import { readdir, stat, readFile, writeFile, access } from 'node:fs/promises';
+import { join, extname, basename, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseArgs } from 'node:util';
+
+const META_VERSION = '2.0';
+
+// Directories to skip when scanning.
+const SKIP_DIRS = new Set([
+ 'node_modules', '.git', 'dist', 'build', 'out',
+ '.cache', '.turbo', '.vscode', '__pycache__',
+]);
+
+// Files to skip (besides *.meta itself).
+const SKIP_FILES = new Set([
+ '.DS_Store', 'Thumbs.db', 'desktop.ini',
+ '.gitkeep', '.gitignore', '.gitattributes',
+]);
+
+// Extension → asset type mapping.
+// Extensions are matched case-insensitively; dot included.
+const EXT_TO_TYPE = Object.freeze({
+ // Textures
+ '.png': 'texture',
+ '.jpg': 'texture',
+ '.jpeg': 'texture',
+ '.webp': 'texture',
+ '.bmp': 'texture',
+ // Audio
+ '.wav': 'audio',
+ '.mp3': 'audio',
+ '.ogg': 'audio',
+ '.aac': 'audio',
+ '.flac': 'audio',
+ '.m4a': 'audio',
+ '.webm': 'audio',
+ // Engine data
+ '.esprefab': 'prefab',
+ '.esscene': 'scene',
+ '.esshader': 'shader',
+ '.esmaterial': 'material',
+ '.esmat': 'material',
+ '.estl': 'timeline',
+ '.esanim': 'animation',
+ '.esanimclip': 'animation',
+ // Fonts
+ '.fnt': 'bitmapFont',
+ '.bmfont': 'bitmapFont',
+ '.ttf': 'font',
+ '.otf': 'font',
+ '.woff': 'font',
+ '.woff2': 'font',
+ // Tilemap
+ '.tmx': 'tilemap',
+ '.tmj': 'tilemap',
+ // Spine (skel / atlas — .png pair handled by the texture entry)
+ '.skel': 'spine',
+ '.atlas': 'spine',
+});
+
+/**
+ * Default `importer` settings per type. Shapes match the examples/ meta
+ * files that existed before this tool landed; new types err on the side
+ * of an empty object so future importer fields can be added additively.
+ */
+function getImporterDefaults(type) {
+ switch (type) {
+ case 'texture':
+ return {
+ maxSize: 2048,
+ filterMode: 'linear',
+ wrapMode: 'repeat',
+ premultiplyAlpha: false,
+ sliceBorder: { left: 0, right: 0, top: 0, bottom: 0 },
+ };
+ case 'prefab':
+ case 'scene':
+ return { autoMigrate: true };
+ case 'spine':
+ return { defaultSkin: 'default', premultiplyAlpha: false, scale: 1 };
+ case 'audio':
+ case 'shader':
+ case 'material':
+ case 'timeline':
+ case 'animation':
+ case 'bitmapFont':
+ case 'font':
+ case 'tilemap':
+ return {};
+ default:
+ return {};
+ }
+}
+
+/** Returns the asset type for a path, or null if the extension is unknown. */
+function getAssetType(filePath) {
+ const ext = extname(filePath).toLowerCase();
+ return EXT_TO_TYPE[ext] ?? null;
+}
+
+/** Builds the meta object (JSON-shape) for a given type. */
+function buildMeta(type) {
+ return {
+ uuid: randomUUID(),
+ version: META_VERSION,
+ type,
+ importer: getImporterDefaults(type),
+ };
+}
+
+function formatMeta(meta) {
+ return JSON.stringify(meta, null, 2) + '\n';
+}
+
+async function exists(path) {
+ try {
+ await access(path);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function* walk(dir) {
+ const entries = await readdir(dir, { withFileTypes: true });
+ for (const entry of entries) {
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) {
+ if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+ yield* walk(full);
+ } else if (entry.isFile()) {
+ if (SKIP_FILES.has(entry.name) || entry.name.startsWith('.')) continue;
+ if (entry.name.endsWith('.meta')) continue;
+ yield full;
+ }
+ }
+}
+
+/**
+ * Scan `dir` recursively and generate .meta files for any asset that
+ * doesn't already have one. Returns a summary.
+ *
+ * Options:
+ * dryRun — don't write files
+ * check — collect missing but also don't write (for CI)
+ * verbose — log every skip and every create
+ * onCreate(absPath, meta) — optional callback per created meta
+ */
+export async function generateMetaForDir(dir, options = {}) {
+ const { dryRun = false, check = false, verbose = false, onCreate } = options;
+ const root = resolve(dir);
+
+ try {
+ const s = await stat(root);
+ if (!s.isDirectory()) {
+ throw new Error(`Not a directory: ${root}`);
+ }
+ } catch (err) {
+ throw new Error(`Cannot read directory "${root}": ${err.message}`);
+ }
+
+ const created = [];
+ const alreadyPresent = [];
+ const skipped = [];
+
+ for await (const filePath of walk(root)) {
+ const type = getAssetType(filePath);
+ if (type === null) {
+ if (verbose) skipped.push({ path: filePath, reason: 'unknown extension' });
+ continue;
+ }
+
+ const metaPath = filePath + '.meta';
+ if (await exists(metaPath)) {
+ alreadyPresent.push({ path: filePath, metaPath });
+ continue;
+ }
+
+ const meta = buildMeta(type);
+ created.push({ path: filePath, metaPath, meta });
+
+ if (!dryRun && !check) {
+ await writeFile(metaPath, formatMeta(meta), 'utf8');
+ if (onCreate) await onCreate(metaPath, meta);
+ }
+ }
+
+ return { root, created, alreadyPresent, skipped };
+}
+
+function printSummary(results, { verbose, dryRun, check }) {
+ let totalCreated = 0;
+ let totalPresent = 0;
+ let totalSkipped = 0;
+
+ for (const r of results) {
+ const rel = (p) => relative(process.cwd(), p) || '.';
+ totalCreated += r.created.length;
+ totalPresent += r.alreadyPresent.length;
+ totalSkipped += r.skipped.length;
+
+ if (verbose) {
+ for (const s of r.skipped) {
+ console.log(` skip: ${rel(s.path)} (${s.reason})`);
+ }
+ for (const p of r.alreadyPresent) {
+ console.log(` exists: ${rel(p.metaPath)}`);
+ }
+ }
+
+ for (const c of r.created) {
+ const prefix = dryRun || check ? ' would: ' : ' wrote: ';
+ console.log(`${prefix}${rel(c.metaPath)} (type: ${c.meta.type}, uuid: ${c.meta.uuid})`);
+ }
+ }
+
+ const verb = dryRun ? 'would create' : check ? 'missing' : 'created';
+ console.log(
+ `\n${verb}: ${totalCreated}` +
+ ` | already present: ${totalPresent}` +
+ (verbose ? ` | skipped (unknown ext): ${totalSkipped}` : ''),
+ );
+}
+
+async function main() {
+ const { values, positionals } = parseArgs({
+ options: {
+ 'dry-run': { type: 'boolean', default: false },
+ 'check': { type: 'boolean', default: false },
+ 'verbose': { type: 'boolean', short: 'v', default: false },
+ 'help': { type: 'boolean', short: 'h', default: false },
+ },
+ allowPositionals: true,
+ });
+
+ if (values.help || positionals.length === 0) {
+ console.log(`Usage: node tools/asset-meta.js <dir>... [options]
+
+Options:
+ --dry-run Show what would be created, write nothing
+ --check Exit 1 if any asset is missing .meta (CI mode)
+ -v, --verbose Log every asset considered
+ -h, --help Show this help`);
+ process.exit(values.help ? 0 : 2);
+ }
+
+ const results = [];
+ for (const dir of positionals) {
+ try {
+ results.push(await generateMetaForDir(dir, {
+ dryRun: values['dry-run'],
+ check: values.check,
+ verbose: values.verbose,
+ }));
+ } catch (err) {
+ console.error(`error: ${err.message}`);
+ process.exit(2);
+ }
+ }
+
+ printSummary(results, {
+ verbose: values.verbose,
+ dryRun: values['dry-run'],
+ check: values.check,
+ });
+
+ if (values.check) {
+ const anyMissing = results.some(r => r.created.length > 0);
+ process.exit(anyMissing ? 1 : 0);
+ }
+}
+
+// Run as CLI when invoked directly; skip when imported as a module.
+const isMain = import.meta.url === `file://${process.argv[1]}`
+ || import.meta.url.endsWith(process.argv[1].replace(/\\/g, '/'));
+if (isMain) {
+ main().catch(err => {
+ console.error(err);
+ process.exit(2);
+ });
+}
+
+// Exports for reuse (e.g., migration script).
+export { EXT_TO_TYPE, META_VERSION, getAssetType, getImporterDefaults, buildMeta };