NSGo Game

快速开始

创建一个 NSGo 游戏项目,在桌面端、Web、iOS 和 Android 上运行它,在固定步长循环中绘制带动画的精灵、处理触控和鼠标输入,并用混音器播放音效与音乐。

环境要求

  • Go 1.27 或更高版本。
  • NSGo v0.2 或更高版本,作为 Go 工具安装(go tool nsgo)。
  • 构建 iOS 目标:需要 macOS 和 Xcode。
  • 在 Android 真机或模拟器上运行:需要 adb(Android SDK Platform-Tools)。仅构建 android_arm64 的 APK 只需要 Go。

在项目目录中运行 go tool nsgo doctor,可以检查当前机器已安装的工具链。

创建项目

你可以直接复制仓库中的 template/ 目录作为起手模板,也可以在空目录里用 nsgo init 初始化一个新项目。

从空目录创建:

mkdir mygame && cd mygame
go mod init example.com/mygame
go get github.com/nsgo-dev/nsgo@latest
go get -tool github.com/nsgo-dev/nsgo/cmd/nsgo@latest
go tool nsgo init
go get github.com/nsgo-dev/game/packages/game

nsgo init 会生成 nsgo.yaml、app.go 和 app_test.go。添加 resources/ 目录存放游戏运行时加载的资源(asset: 图片和音频),添加 assets/ 目录存放打包时使用的项目文件(例如应用图标,不会直接原样复制到资源目录):

mygame/
├─ go.mod
├─ nsgo.yaml
├─ app.go
├─ app_test.go
├─ resources/
│  ├─ hero.png
│  ├─ hero.json
│  ├─ jump.wav
│  └─ theme.m4a
└─ assets/
   └─ Icon.png

resources/ 下的所有文件都会随各平台安装包一起打包,并在代码中通过 "asset:<路径>" 访问(例如 "asset:hero.png" 或 "asset:sounds/jump.wav")。图集 JSON 可以直接用 //go:embed 嵌入到 Go 二进制中。

在各平台运行

nsgo dev 会构建并启动应用,保存代码时自动热重载。

桌面端(使用当前机器的原生后端,也是 nsgo.yaml 的默认目标):

go tool nsgo dev

Web(在 8080 端口启动本地开发服务器并自动打开浏览器):

go tool nsgo dev -target web

iOS(模拟器,或已连接的 iPhone;真机可用 -team 指定开发者团队,默认沿用 Xcode 上次使用的团队):

go tool nsgo dev -target ios_simulator
go tool nsgo dev -target ios

Android(已连接的真机或运行中的模拟器;连接多台设备时用 -device 指定):

go tool nsgo dev -target android

给任意 nsgo dev 命令加上 -fps,可以在运行中的游戏画面上叠加 NSGo 的性能监视器。

用 Loop 和 sprite.Batch 绘制精灵

游戏就是一个 NSGo 组件。它在自己的作用域上启动 game.Loop,在 Update 中以固定频率(默认每秒 60 次)推进状态,在 Draw 中更新 core.Signal,让 core.Canvas 重绘而不必重新提交整个视图树。

用 TexturePacker 或 Aseprite 导出图集(关闭旋转),把 PNG 放到 resources/hero.png,用 //go:embed 嵌入 JSON。如果还没有导出图集,也可以按 sprite 指南中的方式手写 *sprite.Atlas 字面量。

package main

import (
	_ "embed"
	"math"
	"time"

	"github.com/nsgo-dev/game/packages/game"
	"github.com/nsgo-dev/game/packages/game/sprite"
	"github.com/nsgo-dev/nsgo"
	"github.com/nsgo-dev/nsgo/core"
)

//go:embed resources/hero.json
var heroJSON []byte

func Game(cx *core.Scope) core.Node {
	atlas, err := sprite.LoadAtlas(core.Src("asset:hero.png"), heroJSON)
	if err != nil {
		panic(err)
	}

	walk := atlas.Animations["walk"]
	hero := sprite.NewSprite(walk.Frame())
	hero.OriginX = hero.Frame.Width / 2
	hero.OriginY = hero.Frame.Height / 2
	hero.X, hero.Y = 160, 120

	batch := &sprite.Batch{
		Atlas:   atlas,
		Sprites: []*sprite.Sprite{&hero},
	}

	x, y := hero.X, hero.Y
	lastX, lastY := x, y
	targetX, targetY := x, y
	alpha := core.NewSignal(cx, 0.0)

	loop := &game.Loop{
		Rate: 60,
		Update: func(dt time.Duration) {
			lastX, lastY = x, y
			dx, dy := targetX-x, targetY-y
			if dist := float32(math.Hypot(float64(dx), float64(dy))); dist > 1 {
				step := min(dist, 180*float32(dt.Seconds()))
				x += dx / dist * step
				y += dy / dist * step
				hero.FlipX = dx < 0
				walk.Update(dt)
				hero.Frame = walk.Frame()
			}
		},
		Draw: func(a float64) {
			alpha.Set(a)
		},
	}
	loop.Run(cx)

	return core.Canvas{
		Style: core.Style{FlexGrow: 1, FlexShrink: 1, Background: core.RGB(0x181c24)},
		OnPress: func(e core.PressEvent) {
			targetX = float32(e.Position.X)
			targetY = float32(e.Position.Y)
		},
		Draw: func(d *core.Drawing, _ core.Size) {
			a := float32(alpha.Get())
			hero.X = lastX + (x-lastX)*a
			hero.Y = lastY + (y-lastY)*a
			batch.Draw(d)
		},
	}
}

func main() { nsgo.Run(Game) }

因为 Draw 读取了 alpha.Get(),NSGo 每个显示帧只重绘 Canvas。在 (lastX, lastY) 与 (x, y) 之间按 alpha 插值,可以让画面在 60 Hz、120 Hz 或可变刷新率显示器上都保持顺滑,同时逻辑模拟固定在 60 Hz。

处理触控与鼠标输入

core.Canvas.OnPress 同时处理手机上的点击和桌面端、Web 上的鼠标点击,提供的 e.Position 以画布自身的点(points)为单位。

如果需要连续追踪指针、拖拽或多点触控,可以用一个 core.View 包裹 Canvas,监听 NSGo 的指针与触控事件(OnPressDown、OnPressUp、OnMouseMove、OnTouch、OnPan),并用 core.Absolute 在上面叠加原生 HUD 视图:

return core.View{
	Style: core.Style{FlexGrow: 1, FlexShrink: 1},
	OnMouseMove: func(e core.MouseEvent) {
		if e.PressedButton == core.MouseButtonLeft {
			targetX, targetY = float32(e.Position.X), float32(e.Position.Y)
		}
	},
	OnTouch: func(e core.TouchEvent) {
		if len(e.Touches) > 0 {
			targetX = float32(e.Touches[0].Position.X)
			targetY = float32(e.Touches[0].Position.Y)
		}
	},
	Children: []core.Node{
		canvas,
		core.View{
			Style: core.Style{
				Position:   core.Absolute,
				Top:        core.Pt(12),
				Left:       core.Pt(12),
				PaddingEnv: core.EnvAll(core.EnvSafeArea),
			},
			Children: []core.Node{
				core.Text{Content: "Score: 0", Style: core.Style{Color: core.RGB(0xffffff)}},
			},
		},
	},
}

键盘和手柄的输入动作映射计划在 game/input 包中提供(#3)。

用 sound.Mixer 播放声音

在组件作用域上创建一个 sound.Mixer。它会把主音量和各分组音量保存在 core.Storage 中,应用切入后台时自动静音,并统一管理短音效(Effect)和流式背景音乐(Music)。

将音频以 WAV、AAC(.m4a)或 MP3 格式放入 resources/:

mixer := sound.NewMixer(cx, "sound")
music := mixer.Music("music")
music.Loop = true

var jump *sound.Effect
audio.LoadSound(cx, audio.Source{URI: "asset:jump.wav"}, func(s *audio.Sound, err error) {
	if err != nil {
		return
	}
	jump = mixer.Effect(s, "effects", 4)
})

在玩家按下时播放音效并启动背景音乐(在 Web 上,浏览器要求在首次用户手势之后才允许播放音频):

started := false
// 在 OnPress 中:
if !started {
	started = true
	music.Play(audio.Source{URI: "asset:theme.m4a"}, 2*time.Second)
}
if jump != nil {
	jump.Play(audio.Voice{Volume: 0.8})
}

下一步

  • 阅读各个包的详细指南:Loop、sprite 和 sound,或查阅汇总的包参考。
  • 准备好检查所有目标平台并构建 macOS、Windows、Linux、Web、iOS 和 Android 发布包时,阅读构建与发布。
编辑此页