unity-yooasset

name: unity-yooasset description: Automate YooAsset hot-update and asset bundles — build bundles, run Editor simulate builds, manage Collector groups, analyze BuildReport, and validate runtime. Use when building or simulating YooAsset bundles, configuring collectors, or validating hot-update assets, even if the user just says "热更" or "打AB包". 自动化 YooAsset 热更新与资源包(构建 bundle、编辑器模拟构建、管理 Collector 分组、分析 BuildReport、运行时校验);当用户要构建或模拟 YooAsset 资源包、配置 collector、或校验热更资源时使用。

Unity YooAsset Skills

Editor-side automation for the YooAsset hot-update framework — build pipeline orchestration, Collector configuration CRUD, BuildReport analysis, PlayMode runtime validation, and companion YooAsset tools. Every skill wraps a concrete YooAsset Editor/runtime API path validated against 2.3.18 source. When the package is absent, every skill except yooasset_check_installed returns a NoYooAsset() error with install instructions.

Requires: com.tuyoogame.yooasset ≥ 2.3.15, Unity 2022.3+ (validated against 2.3.18). Strongly recommended: before writing ANY YooAsset runtime code, load yooasset-design. PlayMode / parameter-class / handle-lifecycle pitfalls are strict, and only the advisory module surfaces them.

Guardrails

Operating Mode (v1.9 three-tier):

• Approval (default): query/list/read skills (yooasset_check_installed, yooasset_get_default_paths, yooasset_get_build_settings, yooasset_list_collector_packages, yooasset_list_collector_rules, yooasset_list_assetart_scanners, yooasset_runtime_get_validation_result, yooasset_load_build_report, yooasset_list_report_bundles, yooasset_get_bundle_detail, yooasset_list_report_assets, yooasset_get_asset_detail, yooasset_get_dependency_graph, yooasset_compare_build_reports, yooasset_list_independ_assets) run directly. Builders / Collector mutators / scanner runs / window-openers are FullAuto — on MODE_RESTRICTED, run the grant protocol.

• Auto / Bypass: SemiAuto and FullAuto run directly.

• Auto-forbidden in this module:

  • MayEnterPlayMode = true → yooasset_runtime_validate_package, yooasset_runtime_cleanup
  • SkillOperation.Delete → yooasset_remove_collector_package, yooasset_remove_collector_group, yooasset_remove_collector

  Reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow returns MODE_FORBIDDEN. Note yooasset_build_bundles runs heavy disk I/O but has no Reload/PlayMode flag, so it stays grantable.

• When com.tuyoogame.yooasset is missing, every skill except yooasset_check_installed returns a NoYooAsset() error with install instructions.

DO NOT (common hallucinations):

• yooasset_initialize / yooasset_load_asset / yooasset_create_downloader — do NOT exist as general-purpose REST skills. Runtime APIs (YooAssets.Initialize, default-package YooAssets.LoadAssetAsync, ResourcePackage.LoadAssetAsync, RequestPackageVersionAsync, CreateResourceDownloader) belong in game code. Use yooasset-design when writing runtime code.
• yooasset_modify_group / yooasset_delete_collector / yooasset_open_scanner_window — wrong names. Use the exact schema names below or query GET /skills/schema?category=YooAsset.
• yooasset_install — NOT a skill. Package install is a Package Manager user action.
• Do NOT pass timeout to yooasset_build_bundles — the property was removed in YooAsset 2.3.16. Runtime watchdog now lives on CacheFileSystemParameters.DOWNLOAD_WATCH_DOG_TIME (runtime concern, not a build parameter).
• Do NOT call yooasset_build_bundles while EditorUserBuildSettings.isBuildingPlayer == true — BuildParameters.CheckBuildParameters throws.

Routing:

• Collector configuration (packages, groups, collectors, rules) → this module.
• Actual bundle build + simulate + paths → this module.
• Build report analysis (bundle size, asset list/detail, dependency graph, report compare, orphan) → this module.
• Runtime validation in Editor PlayMode → yooasset_runtime_validate_package + polling/cleanup skills in this module.
• Runtime code generation/design (Initialize / Load / Download / Scene in game scripts) → write it yourself using yooasset-design.
• YooAsset companion windows and AssetArtScanner config/runs → this module.
• Version-policy decisions (2.x vs pre-2.3.15 manifest, FindAssetType on IFilterRule) → yooasset-design/PITFALLS.md.

Skills

Environment (1)

Build pipeline (7)

YooAsset tools (8)

Runtime validation (3)

Collector configuration (13)

Build report analysis (8)

Quick Start

import unity_skills as u

# 0. Probe installation (works even if package is missing)
u.call_skill("yooasset_check_installed")
# -> { installed, packageVersion, availablePipelines: [...], editorAvailable, ... }

# 1. Configure collectors (end-to-end)
u.call_skill("yooasset_list_collector_rules", ruleKind="all")  # discover available rule class names
u.call_skill("yooasset_create_collector_package", packageName="DefaultPackage")
u.call_skill("yooasset_create_collector_group",
    packageName="DefaultPackage", groupName="UI", activeRule="EnableGroup",
    assetTags="ui")
u.call_skill("yooasset_add_collector",
    packageName="DefaultPackage", groupName="UI",
    collectPath="Assets/GameRes/UI",
    collectorType="MainAssetCollector",
    addressRule="AddressByFileName",
    packRule="PackDirectory",
    filterRule="CollectAll")
u.call_skill("yooasset_modify_collector_package",
    packageName="DefaultPackage",
    enableAddressable=True,
    supportExtensionless=True,
    locationToLower=False)
u.call_skill("yooasset_save_collector_config", fixErrors=True)

# 2. Simulate build (EditorSimulateMode) — fast, no file I/O
u.call_skill("yooasset_simulate_build", packageName="DefaultPackage")
# -> { packageRootDirectory: ".../Bundles/DefaultPackage/Simulate" }

# 3. Real build
result = u.call_skill("yooasset_build_bundles",
    packageName="DefaultPackage",
    packageVersion="1.0.0",
    pipeline="ScriptableBuildPipeline",
    compression="LZ4",
    fileNameStyle="HashName",
    verifyBuildingResult=True)

# 4. Analyze the report
import os
report_path = os.path.join(
    result["outputDirectory"],
    f"{result['packageName']}_{result['packageVersion']}.report")
u.call_skill("yooasset_load_build_report", reportPath=report_path)
u.call_skill("yooasset_list_report_bundles", reportPath=report_path, sortBy="size", limit=20)
u.call_skill("yooasset_list_report_assets", reportPath=report_path, search="UI", limit=20)
u.call_skill("yooasset_get_dependency_graph", reportPath=report_path, maxNodes=100)
u.call_skill("yooasset_list_independ_assets", reportPath=report_path)

# 5. Optional PlayMode runtime validation
job = u.call_skill("yooasset_runtime_validate_package",
    packageName="DefaultPackage",
    assetLocation="ui/example",
    restoreEditMode=True,
    cleanup=True)
u.call_skill("yooasset_runtime_get_validation_result", jobId=job["jobId"])

Critical Rules (must read)

1. yooasset_check_installed is the ONLY skill that works without YOO_ASSET compile define. Every other skill returns NoYooAsset() — correct the environment (install or upgrade the package, then let Unity recompile) before retrying.
2. Pipeline ↔ Parameters pairing is enforced. yooasset_build_bundles pipeline=ScriptableBuildPipeline uses ScriptableBuildParameters; pipeline=RawFileBuildPipeline uses RawFileBuildParameters. EditorSimulateBuildPipeline is rejected here — use yooasset_simulate_build. BuiltinBuildPipeline is legacy and explicitly rejected.
3. packageVersion="auto" fills DateTime.UtcNow.ToString("yyyyMMddHHmm"). Pass a semver string when you want deterministic versioning.
4. yooasset_add_collector validates collectPath via AssetDatabase.LoadAssetAtPath. Paths must be under Assets/...; absolute or relative ../ paths will fail.
5. Rule names in Create Skills are CLASS names, not display names. Use yooasset_list_collector_rules to discover valid values (e.g. EnableGroup, AddressByFileName, PackDirectory, CollectAll, NormalIgnoreRule).
6. Collector mutations can save immediately or be batched. Create skills mark IsDirty=true; modify/remove skills expose save=true. For bulk edits, pass save=false and finish with yooasset_save_collector_config.
7. yooasset_build_bundles is NOT undo-tracked (external file I/O, not scene/asset state). clearBuildCache=true re-runs the full pipeline; defaults avoid it for incremental speed.
8. BuildReport lives next to bundles as a .report file — YooAsset 2.3.18 writes it as <BuildOutputRoot>/<BuildTarget>/<PackageName>/<Version>/<PackageName>_<PackageVersion>.report. Do not pass BuildReport.json, <PackageName>_<PackageVersion>.json, or buildlogtep.json: the .json file is the package manifest and buildlogtep.json is the Scriptable Build Pipeline trace log. yooasset_list_report_bundles reads the .report file standalone, so you can also point it at an archived copy.
9. Runtime validation may enter PlayMode. yooasset_runtime_validate_package is intentionally async; poll the job result and use yooasset_runtime_cleanup if the editor is left in a state you do not want.
10. yooasset_list_independ_assets identifies assets not referenced by any main asset — candidates for the Collector to drop. Verify manually before removing; a main asset created later could still need them.

Version Scope

• Target: YooAsset 2.3.18 (published 2025-12-04). Source anchors use this version.
• Minimum: 2.3.15 (enforced by the asmdef versionDefines entry). Earlier versions use an incompatible manifest format and pre-FindAssetType IFilterRule (would not compile against this Skill module).
• 2.3.17 fixed a critical CRC validation bug; users on 2.3.15/2.3.16 should upgrade before relying on verifyBuildingResult=true.
• Runtime-side rules (PlayMode mapping, handle lifecycle, update flow, legacy-API migration) → yooasset-design/SKILL.md.

Exact Signatures

For authoritative parameter names, defaults, and return fields, query GET /skills/schema?category=YooAsset or unity_skills.get_skill_schema(). This document is a routing / best-practice guide, not the signature source.