Agent Skills › ProwlEngine/Prowl › prowl-assets

prowl-assets

GitHub

说明 Prowl 引擎中资源(纹理、材质等)的生命周期管理、引用方式及加载卸载机制,指导开发者正确使用 AssetRef 和字段引用。

Prowl.Editor/Resources/Agent/Skills/prowl-assets/SKILL.md ProwlEngine/Prowl

触发场景

脚本引用纹理或材质 运行时加载资源 处理资源未加载或缺失问题

安装

npx skills add ProwlEngine/Prowl --skill prowl-assets -g -y
更多选项

非标准路径

npx skills add https://github.com/ProwlEngine/Prowl/tree/main/Prowl.Editor/Resources/Agent/Skills/prowl-assets -g -y

不安装直接使用

npx skills use ProwlEngine/Prowl@prowl-assets

指定 Agent (Claude Code)

npx skills add ProwlEngine/Prowl --skill prowl-assets -a claude-code -g -y

安装 repo 全部 skill

npx skills add ProwlEngine/Prowl --all -g -y

预览 repo 内 skill

npx skills add ProwlEngine/Prowl --list

SKILL.md

Frontmatter
{
    "name": "prowl-assets",
    "description": "How Prowl assets work for scripts. Use when a script references textures, materials, meshes, prefabs, clips, scenes or other assets, chooses between a plain field and AssetRef, loads assets by path at runtime, creates assets in code, or when assets unload, go missing, or are not in a build."
}

Prowl assets

The model

  • Every asset derives from Asset (an EngineObject). A database asset has a GUID (AssetID), a path (AssetPath) and a Name taken from its file name, or the part after # for a sub asset.
  • One object per GUID for the whole session. Unloading frees the data but keeps the object, and loading, reimporting or reverting refills that same object. So a reference you hold never goes stale or gets swapped for another object.
  • asset.State is an AssetState (a top level enum in Prowl.Runtime): Loaded, Unloaded, Loading, Missing or Failed. An unloaded or missing asset is still IsValid(). Check IsLoaded or IsMissing when the content matters.
  • Reading an asset's data loads it on demand, blocking. A missing or failed asset reads as empty and logs one warning.
  • A runtime asset made with new Material(shader), new Mesh() or Clone() has no GUID. It is always loaded, never unloaded by the engine, and belongs to whoever made it. Dispose it when done.
  • Never call Dispose() or Destroy() on a database asset, it throws. Use AssetDatabase.Unload if you really must.

Referencing assets from a script

Plain field: public Material Mat; public AssetRef<Material> Mat;
Saved as the GUID the GUID
Keeps the asset loaded yes, while the object holding it is reachable no
Loaded with the scene yes no, call Load() or LoadAsync()
Shipped in builds yes yes

Use a plain field for almost everything. Use AssetRef<T> only for things needed maybe later, such as a list of levels or an optional high resolution texture.

using Prowl.Runtime;
using Prowl.Runtime.Resources;

public class Spawner : Component
{
    public PrefabAsset Enemy;                // held and loaded with the scene
    public AssetRef<Scene> NextLevel;        // only a reference, loads when asked
    [NotHeld] public Texture2D DebugTex;     // referenced, but allowed to unload

    public override void Start()
    {
        var level = NextLevel.Get();         // never loads, may be unloaded
        var loaded = NextLevel.Load();       // blocks until loaded
    }
}

AssetRef<T>: Get() never loads, Load() blocks, LoadAsync() is async, IsEmpty, AssetID, and it converts implicitly from T. Wrapping a runtime asset (no GUID) gives an empty ref and a warning.

What keeps an asset loaded

A background walk starts from every live world, loads in progress, held assets, roots added with AssetDatabase.AddRoot, and statics marked [HeldStatic]. It follows instance fields (collections too). Anything it reaches stays loaded. An asset it does not reach for two walks and longer than the grace period (10 seconds by default) is unloaded.

The walk does not see static fields (unless [HeldStatic]), lambda captures, delegates or locals in async methods. An asset kept only there will unload. Put it in a field, mark the static [HeldStatic], or call AssetDatabase.Hold(asset, owner), which holds it until owner is garbage collected or you call Release.

If a field points at an asset that was unloaded, the next read reloads it (blocking) and logs a warning telling you to keep it in a field or hold it.

AssetDatabase

Call Loads?
AssetDatabase.Get(guid), Get<T>(guid) never
AssetDatabase.Load<T>(guid) blocks
await AssetDatabase.LoadAsync<T>(guid) async
AssetDatabase.FindResource<T>("Textures/Paint") blocks
await AssetDatabase.FindResourceAsync<T>("Sfx/Hit") async
AssetDatabase.FindAllResources<T>("Folder") blocks, and the results are not held afterwards
AssetDatabase.LoadGroup(assets), Preload(sceneAsset) returns an awaitable AssetGroup with Progress
AssetDatabase.Explain(asset) reports state, size and what holds it, for debugging

Loading by path at runtime

A load path is the path below the nearest Resources folder, without the extension: Assets/Enemies/Resources/Textures/Paint.png loads as Textures/Paint. Sub assets add #Name.

Builds only ship the scenes in the build, everything they reference (plain fields and AssetRef), everything inside Resources folders, and what those reference. Assets under Editor folders are left out. An asset you only load by path or GUID must be in a Resources folder, or a player build reports it is not in the asset manifest.

Sub assets, prefabs and scenes

  • A model file imports as a PrefabAsset with sub assets: meshes, materials, the avatar and animation clips. Address one as Models/Hero.fbx#Run. Library/prowl command asset info --path Models/Hero.fbx lists them.
  • Spawn a prefab with GameObject.Instantiate(prefab), with overloads for position, rotation, parent and scene.
  • Prefabs do not nest. A prefab instance inside another prefab is flattened into plain objects when the outer prefab is saved.
  • The prefab a model imports as is read only. To change it, instantiate it, edit the instance, and save a new prefab with prefab create.
  • Scene is the saved scene asset. SceneInstance is a live world. level.Load() replaces Main's content with the level, level.LoadAdditive() adds it as another section, level.Open() makes a new dormant world from it. Each returns a SceneLoad: await it for the loaded SceneSection, read Phase and Progress, or call Wait() to block until it is ready. Loads apply at the end of the frame. AssetRef<Scene> has the same three methods.

Creating and saving assets (editor code only)

EditorAssetBackend.Instance.CreateAsset(asset, "Materials/New.mat") writes the file, imports it and turns that same object into the database asset. SaveAsset(asset) writes changes back. Files like .fbx and .png are imported, not saved, so they can not be written this way. From the CLI use asset create, set, material and importer instead.

Gotchas

  • Never use ?., ??, ??=, == null, != null, is null or is not null on an asset or any EngineObject. They are compile errors (PROWLEO001, PROWLEO002, PROWLEO003). Use x.IsValid() and x.IsNotValid().
  • A scene field on a component is AssetRef<Scene>. A plain Scene field loads the scene and everything it uses with the component (warning PROWLSC002).
  • Never block on a task in a script with .Result, .Wait() or GetAwaiter().GetResult() (PROWLTH001). Loads finish on the main thread, so the wait never returns. await instead, or call the blocking Load().
  • Blocking loads hitch the frame. Use the async calls or LoadGroup for large content.
  • Material.LoadDefault(...) returns a new copy you own. The other built in LoadDefault calls return a shared asset.

版本历史

  • f68efb0 当前 2026-11-21 16:08

同 Skill 集合

Prowl.Editor/Resources/Agent/Skills/prowl-animation/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-cli/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-paper/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-physics/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-profiler/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-rendering/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-scenes/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-serialization/SKILL.md
Prowl.Editor/Resources/Agent/Skills/prowl-ui/SKILL.md

元信息

文件数
0
版本
12b6b29
Hash
8c781f5e
收录时间
2026-11-21 16:08

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-22 04:53
浙ICP备14020137号-1