快速开始
创建一个 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})
}