【OpenHarmony/HarmonyOS】从零拆解一款 ArkTS 迷宫坦克游戏：Stage 模型、ArkUI 与 Canvas 分层架构

【OpenHarmony/HarmonyOS】从零拆解一款 ArkTS 迷宫坦克游戏Stage 模型、ArkUI 与 Canvas 分层架构本文以一个真实的 HarmonyOS 横屏游戏项目“迷宫坦克派对”为例梳理从应用启动、页面组织到游戏引擎运行的完整技术架构。文章不会罗列全部源码而是选择最关键的代码解释为什么这样分层以及这种结构如何支撑后续扩展。一、项目要解决什么问题“迷宫坦克派对”是一款俯视角 2D 游戏。玩家需要在随机迷宫中移动、射击、收集晶石并面对 AI 坦克或附近设备上的其他玩家。项目同时包含PvE 波次挑战、脑力迷宫、限时收集和近场对战四种模式随机迷宫、可破坏墙体、弹射子弹、传送门和强化道具Canvas 2D 实时绘制与 ArkUI HUD 叠加SoundPool、AVPlayer、振动反馈、Preferences 本地持久化手机、平板、横屏以及折叠屏半折叠形态适配Distributed Device Manager 与 UDP 局域网通信原型。这类项目与普通信息展示应用最大的区别是界面刷新由状态变化驱动而游戏世界必须按照稳定帧率持续更新。如果把坦克、子弹、墙体全部做成 ArkUI 组件并用State在每一帧驱动几百个节点刷新组件树重建、布局和属性同步的成本会快速上升。因此项目采用“ArkUI 管界面、Canvas 管战场、GameEngine 管规则”的三层结构。二、工程结构总览 项目采用 HarmonyOS Stage 模型主要目录可以归纳为entry/src/main/ets/├── entryability/# UIAbility 生命周期与全局管理器初始化├── pages/# 启动页、主页、设置、商城、排行榜等页面├── engine/# 游戏主循环与 GameEngine├── modules/# Tank、Bullet、Maze、Portal 等游戏对象├── common/ │ ├── constants/# 可缩放的游戏常量│ ├── managers/# 音频、数据、用户、升级、近场连接│ ├── models/ # 云数据/房间等结构化模型 │ ├── types/# 模式、统计等类型│ └── utils/# Vector2、A*、对象池└── ui/components/# 摇杆、结算弹窗、星空背景等组件从职责上看调用链如下flowchartTDA[EntryAbility]--B[初始化 Manager 单例]A-- C[加载 StartPage]C -- D[Index 游戏主页]D -- E[ArkUI HUD 与页面状态]D -- F[CanvasRenderingContext2D]F -- G[GameEngine]G -- H[GameLoop]G --I[Tank / Bullet / Enemy / Portal]G -- J[Audio / Vibration / Upgrade / P2P]这里最重要的边界是Index.ets不直接计算碰撞GameEngine.ets也不负责设置页或排行榜的布局。页面层只向引擎传入输入并读取结果引擎层只维护世界状态和输出画面。三、Stage 模型如何完成应用启动应用入口在EntryAbility。它负责初始化跨页面共享的管理器、设置沉浸式横屏窗口并加载第一个页面export defaultclassEntryAbility extends UIAbility { onWindowStageCreate(windowStage:window.WindowStage): void {AudioManager.getInstance().init(this.context);DataManager.getInstance().init(this.context);ScoreManager.getInstance().init(this.context);UpgradeManager.getInstance().init(this.context);UserManager.getInstance().init(this.context); windowStage.getMainWindow().then((win) { win.setWindowLayoutFullScreen(true); win.setWindowSystemBarEnable([]); win.setWindowBackgroundColor(#0B0D17); }); windowStage.loadContent(pages/StartPage); } }这段代码体现了两个设计选择。第一管理器在 Ability 创建窗口时统一初始化。Preferences、音频资源等能力都需要UIAbilityContext如果每个页面各自初始化容易发生重复加载、实例状态不一致和页面退出后资源丢失。第二窗口从一开始就进入全屏模式。游戏采用横屏沉浸式布局如果等到战斗页面才隐藏系统栏路由切换时会出现明显的尺寸跳变和白屏闪烁。module.json5中还限定了设备与方向{deviceTypes: [phone,tablet],orientation:auto_rotation_landscape,requestPermissions: [ {name:ohos.permission.VIBRATE}, {name:ohos.permission.INTERNET} ] }只声明真正需要的权限是移动端项目的基本原则。这个项目不依赖定位、通讯录等敏感权限近场发现与网络通信也不应该顺手扩大权限范围。四、页面层为什么使用“状态机式”组织主页面Index.ets内部维护home、difficulty、game三个主状态同时维护暂停、结算和过场浮层状态StatecurrentPage:home|game|difficultyhome;StateisGameRunning: boolean false;StateisPaused: boolean false;StateisGameOver: boolean false;StategameMode: GameModeType pve;StategameDifficulty:easy|normal|nightmarenormal;对于战斗内的短流程使用页面内部状态切换比频繁路由更合适Canvas 上下文可以保留减少重新创建资源暂停菜单和结算弹窗天然适合叠加在战场之上难度选择到游戏开始可以共享参数无需进行复杂序列化状态切换可直接搭配transition与animateTo。而设置页、商城、排行榜和组队页属于独立业务界面使用 Router 进入独立页面更清晰。也就是说项目没有机械地坚持“全部单页”或“每一屏一个路由”而是根据生命周期选择边界。五、ArkUI 与 Canvas 如何协作战斗页面的核心结构是一个Stack底层 Canvas 绘制世界上层 ArkUI 绘制计时器、积分、虚拟摇杆、射击键和弹窗。Stack() { Canvas(this.context) .width(100%) .height(this.isHoverMode() ?50%:100%) .onAreaChange((oldArea, newArea) {constwidth newArea.widthasnumber;constheight newArea.heightasnumber;if(width 0 height 0this.gameEngine) {this.gameEngine.initGame( width, height,this.gameMode,this.gameDifficulty ); } });// 上层继续构建 HUD、摇杆、暂停菜单和结算组件}为什么不在Canvas.onReady中立刻初始化引擎因为onReady只代表绘图上下文可用不一定代表最终布局尺寸已经稳定。项目在onAreaChange收到有效宽高后再初始化地图能避免宽高为 0、地图尺寸错误或者旋转后画面裁切。Canvas 层适合高频移动的坦克、子弹、粒子大量重复的迷宫格子摄像机平移、裁剪、批量路径绘制不需要单独无障碍语义的纯视觉对象。ArkUI 层适合可点击按钮、滑块、开关、列表与弹窗需要状态绑定、资源国际化和无障碍能力的控件页面路由、设置与用户资料。六、GameEngine 的聚合职责GameEngine是运行时核心它持有迷宫、坦克、AI、子弹、粒子、道具、传送门、晶石和远端玩家并把逻辑更新与渲染交给GameLoop调度constructor(context: CanvasRenderingContext2D) {this.context context;this.context.imageSmoothingEnabledfalse;this.bulletPoolnewObjectPoolBullet(() newBullet(),(bullet) { bullet.isDeadfalse; } );this.gameLoopnewGameLoop((deltaTime:number) this.update(deltaTime),() this.render() ); }这里没有把每一种规则都写成独立系统属于适合中小体量游戏的“聚合引擎”设计。优点是调用关系直观、调试成本低当功能继续增长时可以再把碰撞、生成、结算、联网同步拆成系统而不必一开始就引入过度复杂的 ECS 框架。七、全局管理器为什么采用单例音频、用户、升级和分数等能力都采用getInstance()单例。它们具有三个共同点生命周期长于单个页面需要共享同一份状态或底层资源初始化依赖 Ability Context但业务调用不应该反复传递 Context。例如升级数据在商城页面被修改在进入游戏后又被GameEngine读取。如果两侧各自创建实例就可能出现 UI 已升级而引擎仍读取旧值的问题。当然单例并非没有代价。它会隐藏依赖让单元测试替换实现更加困难。后续如果工程规模扩大可以在 Ability 层创建统一的应用容器并通过构造参数向引擎注入接口当前规模下单例是成本和清晰度之间合理的折中。八、一次完整运行流程从用户点击“开始游戏”到结算数据流大致如下EntryAbility初始化 Manager 并加载启动页启动页检查协议状态创建本地用户并进入主页用户选择模式和难度Index切换到战斗状态Canvas 获得真实尺寸创建并初始化GameEngineGameEngine生成迷宫、出生点、AI、传送门和晶石GameLoop按固定步长调用update随后调用renderArkUI 虚拟摇杆把归一化方向传给引擎射击按钮触发开火引擎完成碰撞、AI、计分和音效反馈结束时通过回调通知页面页面展示GameOverDialog分数、用户统计和晶石通过 Preferences 持久化。九、这套架构还可以怎样演进 如果项目继续扩展建议优先处理以下方向将GameEngine中的碰撞、模式结算与网络同步拆为独立系统将 Manager 抽象成接口便于在测试中注入假的音频或存储实现为游戏状态定义显式枚举和转换函数避免多个布尔值组合出非法状态为地图生成加入随机种子支持关卡复现、问题回放和联机一致性给 UDP 数据包增加版本、序号、时间戳和校验字段对 Ability 前后台切换建立统一的“暂停/恢复/释放”策略。十、总结HarmonyOS 游戏项目并不需要把所有内容都塞进 Canvas也不应该让 ArkUI 承担每帧游戏实体的高频刷新。更实用的做法是Stage 模型负责应用生命周期与系统能力初始化ArkUI 负责页面、HUD、设置与交互Canvas 负责高频战场渲染GameLoop 负责时间推进GameEngine 负责实体、规则与反馈Preferences 和各类 Manager 负责跨页面持久状态。当这些边界清晰后随机迷宫、AI、物理、音频乃至近场联机都能在同一工程中稳定协作。这也是从一个 Demo 走向完整 HarmonyOS 游戏应用最关键的一步。✨推荐标签OpenHarmonyHarmonyOSArkTSArkUICanvas游戏开发