fast-cocos 1.0.8 → 1.1.1

package/copy-assets.json

@@ -3,6 +3,14 @@
     {
       "from": "src/xlsx/template",
       "to": "dist/xlsx/template"
+    },
+    {
+      "from": "src/ttf/jar",
+      "to": "dist/ttf/jar"
+    },
+    {
+      "from": "src/ttf/py",
+      "to": "dist/ttf/py"
     }
   ]
 }

package/dist/audio/src/audio.js

@@ -10,6 +10,10 @@ const xlsx_1 = __importDefault(require("xlsx"));
 const logger_1 = __importDefault(require("../../logger"));
 const utils_1 = require("../../utils");
 class Audio {
+    /**
+     * 根据音频配置表复制 mp3 文件，并生成对应的 TypeScript 引用配置。
+     * @param options 音频导出选项
+     */
     parse(options) {
         const files = utils_1.utils.findFiles(options.source, [".xlsx"]);
         for (const filePath of files) {
@@ -27,6 +31,7 @@ class Audio {
             const fileName = xlsxName.charAt(0).toUpperCase() + xlsxName.slice(1) + "Audio";
             let str = `export const ${fileName} = {`;
             const lastIndex = json.length - 1;
+            // 将每一行配置转换成资源复制动作和 TS 映射项。
             json.forEach((item, index) => {
                 const fileName = item["文件名"];
                 const refName = item["引用名"];
@@ -59,7 +64,9 @@ class Audio {
             utils_1.utils.writeFileSync(tsFilePath, str);
             // 删除未使用mp3文件
             oldMp3
+                // 找出本次导出结果中已经不存在的旧音频文件。
                 .filter((v) => !newMp3.includes(v))
+                // 同步删除音频文件及其 Cocos meta 文件。
                 .forEach((v) => {
                 utils_1.utils.rmSync(v);
                 utils_1.utils.rmSync(v + ".meta");

package/dist/audio/src/index.js

@@ -11,6 +11,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const audio_1 = require("./audio");
+/**
+ * 解析音频导出命令参数，并启动音频配置生成流程。
+ */
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
         commander_1.program
@@ -31,6 +34,7 @@ function main() {
         });
     });
 }
+// 捕获入口异步异常并以非零状态码退出。
 void main().catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/bmfont/src/BMFont.js

@@ -21,10 +21,17 @@ class BMFont {
             // 所有字体目录
             utils_1.utils
                 .getSubDirsSync(dir)
+                // 只处理包含 png 字符图片的字体目录。
                 .filter((dir) => utils_1.utils.containsFileExt(dir, ".png"))
+                // 为每个字体目录生成对应的 png 图集和 fnt 描述文件。
                 .forEach((fontDir) => this.run(fontDir, outputDir));
         }
     }
+    /**
+     * 将单个字体目录中的字符图片打包成 BMFont 文件。
+     * @param fontDir 字符图片所在目录
+     * @param outputDir 输出目录
+     */
     run(fontDir, outputDir) {
         const fontName = path_1.default.basename(fontDir);
         const pngPath = path_1.default.join(outputDir, `${fontName}.png`);
@@ -36,6 +43,7 @@ class BMFont {
             },
             algorithm: "left-right"
         };
+        // SpriteSmith 完成图集生成后，同步写入图片和 fnt 字符映射。
         spritesmith_1.default.run(config, (err, result) => {
             if (err) {
                 console.log(err);
@@ -102,6 +110,7 @@ class BMFont {
             }
             a[i] = code;
         }
+        // 按十六进制位权累计每一位数值。
         return a.reduce(function (acc, c) {
             acc = 16 * acc + c;
             return acc;

package/dist/bmfont/src/index.js

@@ -11,6 +11,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const BMFont_1 = require("./BMFont");
+/**
+ * 解析 BMFont 导出命令参数，并启动字体图集生成流程。
+ */
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
         commander_1.program
@@ -27,6 +30,7 @@ function main() {
         });
     });
 }
+// 捕获入口异步异常并以非零状态码退出。
 void main().catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/index.js

@@ -15,24 +15,44 @@ fast-cocos audio        export audio config spreadsheet
 fast-cocos ttf          export ttf fonts
 fast-cocos robot        send dingtalk / feishu (lark) messages
 fast-cocos bmfont       export bmfont fonts
-fast-cocos xxteakey     generate xxteakey`;
+fast-cocos xxteakey     generate xxteakey
+fast-cocos json         json operations`;
+/**
+ * 打印 CLI 的命令使用说明。
+ */
 function printUsage() {
     console.info(USAGE);
 }
+/**
+ * 从包信息中读取并打印当前工具版本。
+ */
 function printVersion() {
     const packageJsonPath = path_1.default.join(__dirname, "..", "package.json");
     const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, "utf8"));
     console.info(packageJson.version);
 }
+/**
+ * 输出未知命令提示，引导用户查看帮助。
+ * @param cmd 用户输入的命令名
+ */
 function printUnknownCommandHint(cmd) {
     console.error(`Unknown command: "${cmd}"`);
     console.error("");
     console.error("To see a list of supported fast-cocos commands, run:");
     console.error("fast-cocos help");
 }
+/**
+ * 判断子命令编译后的入口文件是否存在。
+ * @param absPathWithoutExt 不带扩展名的绝对路径
+ */
 function commandModuleJsExists(absPathWithoutExt) {
     return fs_1.default.existsSync(`${absPathWithoutExt}.js`);
 }
+/**
+ * 校验并加载子命令入口模块。
+ * @param cmd 用户输入的命令名
+ * @param absPathWithoutExt 不带扩展名的子命令入口绝对路径
+ */
 function requireCommand(cmd, absPathWithoutExt) {
     if (!commandModuleJsExists(absPathWithoutExt)) {
         printUnknownCommandHint(cmd);
@@ -40,6 +60,9 @@ function requireCommand(cmd, absPathWithoutExt) {
     }
     require(absPathWithoutExt);
 }
+/**
+ * 解析根命令参数，并将执行权交给对应子命令模块。
+ */
 function main() {
     const [, , cmd] = process.argv;
     if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {

package/dist/json/src/JsonUtils.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonUtils = void 0;
+const path_1 = __importDefault(require("path"));
+const utils_1 = require("../../utils");
+const DEFAULT_MERGE_FILE = "merge.json";
+class JsonUtils {
+    /**
+     * 合并 JSON 文件并写入输出目录。
+     * @param options JSON 合并选项
+     */
+    merge(options) {
+        utils_1.utils.writeJson(this.getOutputPath(options), this.mergeJsonFiles(options));
+    }
+    /**
+     * 获取合并结果的输出路径。
+     * @param options JSON 合并选项
+     */
+    getOutputPath(options) {
+        return path_1.default.join(options.output, options.file || DEFAULT_MERGE_FILE);
+    }
+    /**
+     * 从 JSON 文件路径中提取合并后的对象 key。
+     * @param filePath JSON 文件路径
+     */
+    getJsonFileKey(filePath) {
+        return path_1.default.basename(filePath, path_1.default.extname(filePath));
+    }
+    /**
+     * 递归读取目录中的 JSON 文件，并按文件名合并为一个对象。
+     * @param options JSON 合并选项
+     */
+    mergeJsonFiles(options) {
+        const outputPath = this.getOutputPath(options);
+        const sourceFiles = utils_1.utils.findFiles(options.source, [".json"]);
+        const merged = {};
+        // 将每个 JSON 文件内容挂到对应文件名 key 下。
+        sourceFiles
+            .filter((filePath) => path_1.default.resolve(filePath) !== path_1.default.resolve(outputPath))
+            .forEach((filePath) => {
+            const json = utils_1.utils.readJson(filePath);
+            merged[this.getJsonFileKey(filePath)] = json;
+        });
+        return merged;
+    }
+}
+exports.jsonUtils = new JsonUtils();

package/dist/json/src/index.js

@@ -10,23 +10,26 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const JSON_1 = require("./JSON");
+const JsonUtils_1 = require("./JsonUtils");
+/**
+ * 解析 JSON 合并命令参数，并将目录中的 JSON 文件合并输出。
+ */
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
         commander_1.program
-            .name("bmfont")
-            .description("bmfont parser")
+            .name("merge-json")
+            .description("merge json utility")
             .version("1.0.0")
             .requiredOption("-s, --source <source>", "source directory")
             .requiredOption("-o, --output <output>", "output directory")
+            .option("-m, --merge <merge>")
+            .option("-f, --file <file name>", "file name")
             .parse(process.argv);
         const options = commander_1.program.opts();
-        JSON_1.bmfont.parse({
-            source: options.source,
-            output: options.output
-        });
+        JsonUtils_1.jsonUtils.merge(options);
     });
 }
+// 捕获入口异步异常并以非零状态码退出。
 void main().catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/logger.js

@@ -8,24 +8,45 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 class Logger {
+    /**
+     * 以默认颜色输出普通日志。
+     * @param args 日志内容
+     */
     log(...args) {
         console.log("\x1b[37m%s\x1b[0m", this.format(...args));
     }
+    /**
+     * 以红色输出错误日志。
+     * @param args 日志内容
+     */
     error(...args) {
         console.log("\x1b[31m%s\x1b[0m", this.format(...args));
     }
+    /**
+     * 以黄色输出警告日志。
+     * @param args 日志内容
+     */
     warn(...args) {
         console.log("\x1b[33m%s\x1b[0m", this.format(...args));
     }
+    /**
+     * 以绿色输出提示日志。
+     * @param args 日志内容
+     */
     info(...args) {
         console.log("\x1b[32m%s\x1b[0m", this.format(...args));
     }
+    /**
+     * 将任意日志参数格式化为带时间前缀的字符串。
+     * @param args 日志内容
+     */
     format(...args) {
         let preStr = "";
         while (args[0] == "\n") {
             preStr += args.shift();
         }
         let message = "";
+        // 将数组、对象和基础类型统一转成可读文本。
         args.forEach((arg) => {
             if (Array.isArray(arg)) {
                 message += JSON.stringify(arg) + " ";

package/dist/robot/src/Robot.js

@@ -13,6 +13,7 @@ class Robot {
      * @param content 内容
      */
     sendToDingTalk(url, content) {
+        // 包装为 Promise，保证调用方可以等待请求完成或失败处理结束。
         return new Promise((resolve) => {
             if (!url) {
                 logger_1.default.warn("未配置钉钉机器人地址");
@@ -43,7 +44,9 @@ class Robot {
             // 创建并发送请求
             const req = https_1.default.request(options, (res) => {
                 let data = "";
+                // 累积响应体，便于日志中输出机器人接口返回内容。
                 res.on("data", (chunk) => (data += chunk));
+                // 响应结束后记录结果并释放等待方。
                 res.on("end", () => {
                     logger_1.default.log("成功发送到钉钉:", data);
                     resolve();
@@ -60,11 +63,12 @@ class Robot {
         });
     }
     /**
-     * 发送内容到钉钉
-     * @param url 机器人地址
+     * 发送内容到飞书
+     * @param url 飞书机器人地址
      * @param text 内容
      */
     sendToFeiShu(url, text) {
+        // 包装为 Promise，保证调用方可以等待请求完成或失败处理结束。
         return new Promise((resolve) => {
             if (!url) {
                 logger_1.default.warn("未配置飞书机器人地址");
@@ -74,7 +78,7 @@ class Robot {
             logger_1.default.info("发送飞书消息:");
             logger_1.default.info(url);
             logger_1.default.info(text);
-            // 发送的数据，钉钉机器人支持多种格式，例如 text、markdown、link 等
+            // 发送的数据，飞书机器人使用 msg_type 和 content 描述消息体
             const message = JSON.stringify({
                 msg_type: "text",
                 content: {
@@ -99,7 +103,9 @@ class Robot {
             // 创建并发送请求
             const req = https_1.default.request(options, (res) => {
                 let data = "";
+                // 累积响应体，便于日志中输出机器人接口返回内容。
                 res.on("data", (chunk) => (data += chunk));
+                // 响应结束后记录结果并释放等待方。
                 res.on("end", () => {
                     logger_1.default.log("成功发送到飞书:", data);
                     resolve();

package/dist/robot/src/index.js

@@ -11,6 +11,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const Robot_1 = require("./Robot");
+/**
+ * 解析机器人消息命令参数，并按类型发送到对应平台。
+ */
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
         commander_1.program
@@ -34,6 +37,7 @@ function main() {
         }
     });
 }
+// 捕获入口异步异常并以非零状态码退出。
 void main().catch((err) => {
     console.error(err);
     process.exit(1);

package/dist/ttf/py/modify_fonts.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+from fontTools.ttLib import TTFont
+import os
+import sys
+import re
+
+def get_font_info(font_path):
+    """获取字体的原始信息"""
+    font = TTFont(font_path)
+    name_table = font['name']
+
+    info = {
+        'family': None,
+        'subfamily': None,
+        'fullname': None,
+        'postscript': None,
+        'weight': 400
+    }
+
+    # 获取字体信息
+    for record in name_table.names:
+        if record.nameID == 1:  # Family name
+            info['family'] = record.toUnicode()
+        elif record.nameID == 2:  # Subfamily
+            info['subfamily'] = record.toUnicode()
+        elif record.nameID == 4:  # Full name
+            info['fullname'] = record.toUnicode()
+        elif record.nameID == 6:  # PostScript name
+            info['postscript'] = record.toUnicode()
+
+    # 获取字重
+    if 'OS/2' in font:
+        info['weight'] = font['OS/2'].usWeightClass
+
+    font.close()
+    return info
+
+def detect_weight_from_font(font_path):
+    """从字体文件的OS/2表获取实际字重"""
+    font = TTFont(font_path)
+    weight = 400  # 默认
+
+    if 'OS/2' in font:
+        weight = font['OS/2'].usWeightClass
+
+    font.close()
+
+    # 根据字重值返回对应的样式名
+    if weight <= 100:
+        return weight, 'Thin'
+    elif weight <= 200:
+        return weight, 'ExtraLight'
+    elif weight <= 300:
+        return weight, 'Light'
+    elif weight <= 400:
+        return weight, 'Regular'
+    elif weight <= 500:
+        return weight, 'Medium'
+    elif weight <= 600:
+        return weight, 'SemiBold'
+    elif weight <= 700:
+        return weight, 'Bold'
+    elif weight <= 800:
+        return weight, 'ExtraBold'
+    else:
+        return weight, 'Black'
+
+def generate_unique_family_name(original_family, weight_style, index):
+    """基于索引生成唯一的字体家族名"""
+    # 移除原始家族名中的非ASCII字符和特殊字符
+    clean_name = re.sub(r'[^\w]', '', original_family)
+    clean_name = ''.join(c for c in clean_name if ord(c) < 128)  # 只保留ASCII字符
+
+    # 如果清理后为空，使用默认名称
+    if not clean_name:
+        clean_name = "Font"
+
+    # 生成简短的唯一标识
+    if len(clean_name) > 8:
+        clean_name = clean_name[:8]
+
+    # 基于索引和字重生成唯一名称
+    return f"{clean_name}{weight_style}{index}"
+
+def modify_font_complete(font_path, output_dir=None, new_family_name=None, weight_value=None, style_name=None, index=1):
+    """完全修改字体的所有相关元数据"""
+    # 如果没有提供参数，自动检测
+    if not all([new_family_name, weight_value, style_name]):
+        font_info = get_font_info(font_path)
+
+        # 从字体文件获取实际字重
+        detected_weight, detected_style = detect_weight_from_font(font_path)
+
+        # 如果没有提供参数，使用检测到的值
+        if not new_family_name:
+            new_family_name = generate_unique_family_name(font_info['family'], detected_style, index)
+        if not weight_value:
+            weight_value = detected_weight
+        if not style_name:
+            style_name = "Regular"  # iOS推荐所有独立字体都使用Regular
+
+    print(f"\n处理字体: {os.path.basename(font_path)}")
+    print(f"新家族名: {new_family_name}")
+    print(f"字重: {weight_value}")
+    print(f"样式: {style_name}")
+
+    font = TTFont(font_path)
+
+    # 获取name表
+    name_table = font['name']
+
+    # 需要修改的所有nameID
+    # 1 = Family name
+    # 2 = Subfamily name
+    # 3 = Unique identifier
+    # 4 = Full name
+    # 6 = PostScript name
+    # 16 = Typographic Family name (Preferred family)
+    # 17 = Typographic Subfamily name (Preferred subfamily)
+
+    postscript_name = f"{new_family_name.replace(' ', '')}-{style_name.replace(' ', '')}"
+    full_name = f"{new_family_name} {style_name}"
+
+    # 创建新的name记录
+    name_updates = {
+        1: new_family_name,  # Family
+        2: style_name,       # Subfamily
+        3: f"{new_family_name} {style_name}",  # Unique ID
+        4: full_name,        # Full name
+        6: postscript_name,  # PostScript name
+        16: new_family_name, # Preferred Family
+        17: style_name,      # Preferred Subfamily
+    }
+
+    # 更新所有相关的name记录
+    for record in name_table.names:
+        if record.nameID in name_updates:
+            old_value = record.toUnicode()
+            new_value = name_updates[record.nameID]
+            try:
+                if record.platformID == 3:  # Windows
+                    record.string = new_value.encode('utf-16-be')
+                elif record.platformID == 1:  # Mac
+                    record.string = new_value.encode('mac_roman')
+                else:
+                    record.string = new_value.encode('utf-8')
+                print(f"NameID {record.nameID}: {old_value} -> {new_value}")
+            except:
+                # 如果编码失败，尝试使用原始编码
+                record.string = new_value.encode(record.getEncoding())
+
+    # 修改OS/2表
+    if 'OS/2' in font:
+        os2_table = font['OS/2']
+        old_weight = os2_table.usWeightClass
+        os2_table.usWeightClass = weight_value
+        print(f"OS/2 Weight: {old_weight} -> {weight_value}")
+
+        # 设置字体选择标志
+        os2_table.fsSelection = 0
+        if weight_value == 700:  # Bold
+            os2_table.fsSelection |= 0x20  # Bold flag
+        elif weight_value == 400:  # Regular
+            os2_table.fsSelection |= 0x40  # Regular flag
+
+    # 修改head表中的macStyle
+    if 'head' in font:
+        head_table = font['head']
+        head_table.macStyle = 0
+        if weight_value >= 700:
+            head_table.macStyle |= 0x01  # Bold
+
+    # 保存修改后的字体到out文件夹
+    if output_dir is None:
+        # 如果没有指定输出目录，使用脚本所在目录下的out文件夹
+        script_dir = os.path.dirname(os.path.abspath(__file__))
+        output_dir = os.path.join(script_dir, 'out')
+
+    os.makedirs(output_dir, exist_ok=True)
+
+    font_basename = os.path.basename(font_path)
+    output_path = os.path.join(output_dir, font_basename)
+    font.save(output_path)
+    print(f"Saved to: {output_path}\n")
+    font.close()
+
+    return output_path
+
+def find_font_files(font_dir):
+    """查找指定目录下的所有TTF字体文件"""
+    font_files = []
+    if not os.path.exists(font_dir):
+        print(f"错误: 目录不存在: {font_dir}")
+        return font_files
+
+    for filename in os.listdir(font_dir):
+        if filename.lower().endswith('.ttf'):
+            font_path = os.path.join(font_dir, filename)
+            font_files.append(font_path)
+
+    return sorted(font_files)
+
+def main():
+    # 获取脚本所在目录
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    font_dir = os.path.join(script_dir, 'font')
+
+    # 如果提供了命令行参数，使用命令行参数；否则自动扫描font文件夹
+    if len(sys.argv) >= 2:
+        font_files = []
+        for arg in sys.argv[1:]:
+            if os.path.isfile(arg) and arg.lower().endswith('.ttf'):
+                font_files.append(arg)
+            elif os.path.isdir(arg):
+                font_files.extend(find_font_files(arg))
+            else:
+                print(f"跳过无效路径: {arg}")
+    else:
+        # 自动扫描font文件夹
+        print(f"自动扫描字体文件夹: {font_dir}")
+        font_files = find_font_files(font_dir)
+
+    if not font_files:
+        print("未找到任何TTF字体文件")
+        print("\n用法:")
+        print("  python modify_fonts_complete.py                    # 自动处理font文件夹下的所有字体")
+        print("  python modify_fonts_complete.py <字体文件1> ...    # 处理指定的字体文件")
+        print("  python modify_fonts_complete.py <文件夹路径>       # 处理指定文件夹下的所有字体")
+        sys.exit(1)
+
+    print(f"\n找到 {len(font_files)} 个字体文件，开始处理...\n")
+
+    # 处理所有字体文件
+    success_count = 0
+    error_count = 0
+
+    for index, font_path in enumerate(font_files, 1):
+        try:
+            modify_font_complete(font_path, index=index)
+            success_count += 1
+        except Exception as e:
+            print(f"处理 {font_path} 时出错: {e}\n")
+            error_count += 1
+
+    # 输出处理结果统计
+    print("=" * 50)
+    print(f"处理完成: 成功 {success_count} 个, 失败 {error_count} 个")
+    print("=" * 50)
+
+if __name__ == "__main__":
+    main()