NSGo Game

assets

game/assets 在后台 goroutine 异步加载精灵图集、音效、图片、原始字节与自定义游戏数据而不阻塞显示帧,按场景组织成带响应式进度的资源组,在场景结束时统一释放,并提供开箱即用的 LoadingScreen 组件。

import "github.com/nsgo-dev/game/packages/game/assets"

Manager 与 Group 的方法均在引擎 goroutine 上调用;文件读取与解析在后台执行,并通过 core.Scope.Post 回到引擎 goroutine,确保动画与 game.Loop 不会卡顿。

创建 Manager 并定义资源组

在 *core.Scope(通常是游戏根组件的作用域)下创建 Manager。通过 WithFS 让 "asset:" URI 从 embed.FS 或 os.DirFS 读取,或通过 WithReadAsset 自定义读取方式:

//go:embed assets/*
var assetFS embed.FS

mgr := assets.NewManager(cx, assets.WithFS(assetFS))

// 按场景注册命名资源组
level1 := mgr.Group("level1").
	AddAtlas("hero", "asset:hero.json", core.Src("asset:hero.png")).
	AddSound("jump", audio.Source{URI: "asset:sounds/jump.wav"}).
	AddImage("bg", core.Src("asset:bg.png")).
	AddCustom("map", "asset:maps/level1.tmj", parseMap, nil)

*Group 支持的链式添加方法:

方法 加载内容
AddAtlas(name, jsonURI, img) 后台读取并用 sprite.LoadAtlas 解析,若 img 为 URI 则同时预取图片。
AddSound(name, src) 通过 audio.LoadSound 解码短音效。
AddImage(name, src) 通过 core.Scope.PrefetchImage 预取 URI 图片源。
AddBytes(name, uri) 后台读取 uri 的原始字节。
AddCustom(name, uri, parse, release) 后台读取并调用 parse 解析;释放资源组或取消加载时调用 release(val)。
AddCustomLoader(name, uri, load, release) 与 AddCustom 相同,并向 load 传入可取消的 context.Context。

对于不需要分组的单次加载,Manager 也提供 LoadAtlas、LoadSound、LoadBytes 和 LoadCustom。

加载、响应式进度与读取资源

调用 mgr.LoadGroup("level1", onDone) 或 level1.Load(onDone) 开始异步加载。Load 是幂等的:已加载完成的组会立刻触发 onDone(nil),正在加载中的组会把回调排入当前加载队列。

*Group 的状态方法均由 core.Signal 驱动,在 NSGo 视图中读取即可自动订阅变化:

  • g.Progress()([0, 1] 范围的 float64)
  • g.Loaded() 与 g.Total()(int)
  • g.Loading()、g.Done()(bool)与 g.Err()(error)

加载完成后,可从资源组或 Manager 按类型读取(Manager 会从最近注册且包含该名称的组中查找):

heroAtlas, ok := mgr.Atlas("hero")
jumpSound, ok := mgr.Sound("jump")
bgImage, ok := mgr.Image("bg")
rawLevel, ok := mgr.Get("map")

释放资源组

离开场景时调用 mgr.ReleaseGroup("level1")(或 level1.Release()、mgr.ReleaseAll()):

mgr.ReleaseGroup("level1")

释放操作会关闭组内所有已加载的 *audio.Sound,执行自定义 release 回调,丢弃图集、图片与字节引用供 GC 回收,取消尚未完成的加载,并将进度重置为 0 以便日后重新加载。当 Manager 所属的 cx 作用域销毁时,所有资源组也会自动释放,延迟返回的结果会被安全丢弃而不会泄漏。

将解码后的图集图片固定在 NSGo 的 64 源画布缓存之外由 nsgo#1127 跟踪。

LoadingScreen

将 assets.LoadingScreen(或 assets.LoadingView(cx, props))直接放入组件树,即可在挂载时启动加载、展示响应式进度条并在就绪后跳转:

return assets.LoadingScreen{
	Manager: mgr,
	Group:   "level1",
	Title:   "正在加载洞窟",
	OnReady: func() {
		stage.Set("play")
	},
	OnError: func(err error) {
		loadErr.Set(err)
	},
}

设置 LoadingScreen.View(或 LoadingScreenProps.Render)为 func(progress float64, err error) core.Node 可完全替换默认进度条界面。

编辑此页