游戏客户端架构 / 系统课时

哪些资源检查最适合脚本自动做

哪些资源检查最适合脚本自动做

资源检查自动化的价值不在于把所有美术审核都交给程序,而是先拿走那些重复、确定、容易漏检的工作。本节会建立自动化边界,并实现一个可重复运行的检查脚本,用于发现命名、格式、尺寸和重复文件等常见问题。

学习目标

  • 判断一项资源检查是否适合自动化
  • 用脚本检查命名、扩展名、图片尺寸和重复文件
  • 知道哪些质量问题仍需要人工判断

优先自动化确定性高的检查

最值得脚本化的规则有三个共同特征:输入能够被程序读取,判断标准明确,相同输入必须得到相同结论。例如文件名是否符合规范、图片是否超过 4096×4096,都不依赖审美判断。

适合自动执行的高频项目通常包括:文件名和目录路径是否合法、扩展名是否在白名单中、纹理尺寸是否超限、必需文件是否存在、内容是否重复、配置中引用的文件是否缺失。它们既可以在开发机运行,也可以放进 CI,在资源进入主分支前阻止明显错误。

相反,“角色轮廓是否有辨识度”“音效是否足够有冲击力”“材质看起来是否符合世界观”没有稳定的机器判定标准,即使未来加入 AI 辅助,也更适合作为提示而不是硬性构建门禁。

资源检查自动化的判定与执行流程

一个可重复运行的检查脚本

下面的 Python 示例遍历资源目录,检查文件名、允许格式、PNG/JPEG 图片尺寸以及内容完全相同的重复文件。图片尺寸读取使用 Pillow,因此运行前需要安装依赖 python -m pip install Pillow。脚本本身只报告问题,不修改源文件,适合作为本地检查或 CI 的第一道门禁。

python
from __future__ import annotations

import hashlib
import re
import sys
from pathlib import Path

from PIL import Image

ALLOWED_EXTENSIONS = {".png", ".jpg", ".jpeg", ".fbx", ".wav", ".ogg"}
NAME_PATTERN = re.compile(r"^[a-z0-9][a-z0-9_-]*$")
MAX_IMAGE_SIZE = 4096


def sha256(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as file:
        for chunk in iter(lambda: file.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def inspect(root: Path) -> list[str]:
    issues: list[str] = []
    hashes: dict[str, Path] = {}

    for path in sorted(p for p in root.rglob("*") if p.is_file()):
        relative = path.relative_to(root)
        extension = path.suffix.lower()

        # 命名规则只检查不带扩展名的文件名,避免大小写和空格进入资源标识。
        if not NAME_PATTERN.fullmatch(path.stem):
            issues.append(f"NAME {relative}")

        if extension not in ALLOWED_EXTENSIONS:
            issues.append(f"FORMAT {relative}")
            continue

        # 只有可安全读取尺寸的常规图片进入尺寸检查。
        if extension in {".png", ".jpg", ".jpeg"}:
            try:
                with Image.open(path) as image:
                    width, height = image.size
                if width > MAX_IMAGE_SIZE or height > MAX_IMAGE_SIZE:
                    issues.append(f"SIZE {relative} {width}x{height}")
            except OSError:
                issues.append(f"BROKEN_IMAGE {relative}")

        digest = sha256(path)
        if digest in hashes:
            issues.append(f"DUPLICATE {relative} == {hashes[digest].relative_to(root)}")
        else:
            hashes[digest] = path

    return issues


def main() -> int:
    root = Path(sys.argv[1] if len(sys.argv) > 1 else "Assets")
    if not root.is_dir():
        print(f"ERROR directory not found: {root}")
        return 2

    issues = inspect(root)
    for issue in issues:
        print(issue)

    print(f"checked={sum(1 for p in root.rglob('*') if p.is_file())} issues={len(issues)}")
    return 1 if issues else 0


if __name__ == "__main__":
    raise SystemExit(main())

预期输出会随实际资源变化。例如目录中存在一个命名不规范的图片、一个超尺寸图片和一组内容完全相同的重复文件时,输出形式如下:

text
NAME <PATH>
SIZE <PATH> <WIDTH>x<HEIGHT>
DUPLICATE <PATH> == <PATH>
checked=<N> issues=<N>

其中 <PATH>、<WIDTH>、<HEIGHT> 和 <N> 由实际扫描结果决定。脚本发现问题时返回退出码 1,没有问题时返回 0,目录不存在时返回 2,因此 CI 可以直接根据退出码决定是否继续构建。

缺失引用需要从“文件检查”升级到“关系检查”

单纯扫描目录可以判断文件是否存在,却无法知道某个场景、材质或配置究竟应该引用谁。要检查缺失引用,脚本必须获得可靠的依赖关系来源,例如项目自己的资源清单、引擎提供的编辑器 API,或者能够稳定解析的资产描述文件。

因此不要用正则表达式盲扫二进制资产,再声称已经完成引用检查。比较稳妥的做法是让各引擎适配器导出标准化依赖列表,再由通用检查器验证目标文件和资源标识是否存在。这样“通用规则”和“引擎内部资产解析”仍然保持解耦。

自动化检查应该只报告可行动的问题

检查项越多并不代表工具越有价值。如果规则经常误报,开发者很快就会忽略整个报告。一个适合进入硬性门禁的规则,应当能明确指出文件、违反的约束以及修复方向。

例如 SIZE characters/hero_basecolor.png 8192x8192 可以直接行动;而“这个纹理可能不够优化”没有明确阈值,不适合作为失败条件。对于耗时较大的重复内容哈希、模型结构解析或全项目依赖扫描,还可以分成快速检查和完整检查:提交前运行快速规则,夜间或 CI 阶段再执行完整扫描。

资源自动化最可靠的边界可以概括为:机器负责确定性事实,人负责质量判断,引擎适配器负责解析引擎内部关系。先把高频、低争议的检查做稳定,再逐步扩大覆盖范围,比一次性构建一个“什么都检查”的复杂工具更容易真正落地。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

哪些资源检查最适合脚本自动做

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通