tyhuynh-laya-cmd

Fast, incremental UI build tool for LayaAir 2 projects — replaces layaair2-cmd.

Thay thế layaair2-cmd với build nhanh hơn, hỗ trợ incremental build, watch mode thông minh và migrate assets tự động.

Tính năng

• ⚡ Incremental build — chỉ rebuild những file thay đổi, không rebuild toàn bộ
• 🎨 Atlas generation — đóng gói sprite atlas tối ưu với maxrects-packer + sharp
• 📄 UI code generation — tạo layaMaxUI.ts từ .scene files
• 👀 Watch mode thông minh — phân biệt .scene (code only) vs ảnh (atlas only) vs XML (full rebuild)
• 🔍 Auto-detect — tự tìm thư mục laya/ từ thư mục hiện tại, không cần chỉ định -p
• 📦 Migrate assets — phát hiện và di chuyển ảnh lạc loài trong bin/ vào laya/assets/

Cài đặt

npm install --save-dev tyhuynh-laya-cmd

Sử dụng

Chạy từ thư mục gốc dự án (nơi chứa thư mục laya/). Tool sẽ tự tìm laya/.

Build UI (atlas + code)

# Build một lần
tyhuynh-laya-cmd ui -a -d

# Build + clear cache (full rebuild)
tyhuynh-laya-cmd ui -a -d -c

# Chỉ build atlas
tyhuynh-laya-cmd ui -a

# Chỉ build UI code (layaMaxUI.ts)
tyhuynh-laya-cmd ui -d

# Watch mode — tự rebuild khi có thay đổi
tyhuynh-laya-cmd ui -a -d -w

| Flag | Tác dụng | |------|----------| | -a | Generate atlas sprite sheets | | -d | Generate TypeScript UI code (layaMaxUI.ts) | | -c | Clear cache, force full rebuild | | -w | Watch mode | | -p <dir> | Chỉ định thủ công đường dẫn laya/ (mặc định: auto-detect) |

Migrate stray assets

Dùng khi có ảnh nằm trực tiếp trong bin/res/image/ nhưng chưa được quản lý bởi laya/assets/.

# Xem trước — không thay đổi gì
tyhuynh-laya-cmd migrate --dry-run

# Thực hiện migrate
tyhuynh-laya-cmd migrate

Script sẽ:

1. Tìm ảnh trong bin/res/image/ không có tương ứng trong laya/assets/
2. Copy chúng sang laya/assets/
3. Thêm entry vào styles.xml:
   • Thư mục mới hoàn toàn → pack="2" (dir rule, raw copy)
   • Thư mục đã tồn tại → từng file lẻ (giữ nguyên cấu hình atlas cũ)

Tích hợp vào package.json

{
  "scripts": {
    "exportui":       "tyhuynh-laya-cmd ui -a -d && npm run compile",
    "exportuic":      "tyhuynh-laya-cmd ui -c -a -d",
    "exportui:watch": "tyhuynh-laya-cmd ui -a -d -w",
    "export":         "tyhuynh-laya-cmd ui -c -a -d && npm run compile",
    "migrate":        "tyhuynh-laya-cmd migrate",
    "migrate:dry":    "tyhuynh-laya-cmd migrate --dry-run",
    "dev":            "npm run nginx && concurrently \"npm run watch\" \"npm run exportui:watch\""
  }
}

Watch mode — Log output

Khi chạy watch mode, output được phân loại rõ ràng với prefix [UI]:

╔════════════════════════════════════════╗
║  🎨 UI Build Tool (tyhuynh-laya-cmd)   ║
╚════════════════════════════════════════╝
[UI] Project: D:\project\client\laya
[UI] ✅ 12:00:00 — Build complete in 0.18s
[UI] 👀 Watching pages/ & assets/ — Ctrl+C để dừng
[UI]    .scene → code   |   image → atlas   |   .xml → full rebuild

# Khi sửa file .scene:
[UI] 📝 Đã sửa:
[UI]    • pages/res/image/com/config/copy/CopyDoor.scene
[UI]   📄 UI Code: 1 built, 823 skipped
[UI] ✅ 12:01:30 — Build complete in 0.16s

# Khi sửa ảnh:
[UI] 📝 Đã sửa:
[UI]    • assets/res/image/com/bag/icon_gold.png
[UI]   🖼  Atlas: done
[UI] ✅ 12:02:00 — Build complete in 0.45s

Cấu trúc dự án

custom-cmd/
├── index.js                        # CLI entry point
├── build-dist.js                   # Build script (minify → dist/)
├── scripts/
│   └── migrate-stray-assets.js     # Migrate tool
└── src/
    ├── config/
    │   └── ProjectConfig.js        # Đọc .laya config
    ├── generators/
    │   ├── AtlasGen.js             # Atlas generation
    │   ├── UICodeGen.js            # layaMaxUI.ts generation
    │   └── SceneJsonGen.js         # Scene JSON generation
    ├── parsers/
    │   ├── StylesParser.js         # Parse styles.xml
    │   ├── PageParser.js           # Parse pageStyles.xml
    │   └── SceneParser.js          # Parse .scene files
    └── utils/
        ├── BuildCache.js           # Incremental build cache
        ├── FileUtils.js
        └── XmlUtils.js

Publish lên npm

# Bump version
npm version patch   # hoặc minor / major

# Build (minify) + publish tự động
npm publish --access public

Script prepublishOnly sẽ tự chạy build-dist.js để minify code vào dist/ trước khi publish.
Source gốc (src/, scripts/, index.js) không được upload lên npm.

Yêu cầu

• Node.js >= 16.0.0
• LayaAir 2 project với cấu trúc laya/ tiêu chuẩn (có file .laya config)