用户可通过该项目在 HarmonyOS NEXT 设备上启动已移植的经典游戏，如仙剑奇侠传等。它作为统一游戏入口，采用分层架构设计，封装 Vulkan 和鸿蒙原生 API，提供跨平台运行能力，支持多种输入与渲染方式。【此简介由AI生成】

文件	最后提交记录	最后更新时间
AppScope	initial commit	2 个月前
Engine	Update monogame_framework submodule pointer Signed-off-by: funbocchi <funbocchi@noreply.gitcode.com>	12 天前
GameSource	# 同步代码进度	17 天前
hvigor	initial commit	2 个月前
products	# 新建测试用、UholyHeights占位模块 - 针对MonoGame相关接口测试将基于test模块进行 - 当前未确定游戏整体声明周期的控制主题	26 天前
scripts	添加窗口配置模块 & 着色器资源 & 编译脚本 - 新增 window_config 窗口配置模块（hpp/cpp） - 添加 test_triangle 着色器（vert/frag） - 添加 HarmonyOS_Sans_SC 字体资源 - 添加 shader 编译脚本（bat/sh） - 更新 .gitignore 忽略 IDE/工具本地配置 - 更新 napi_init.cpp / Index.d.ts / game_screen.ets - 更新 CMakeLists.txt 添加新源文件 Co-Authored-By: AtomCode (deepseek-v4-flash) <noreply@atomgit.com>	1 个月前
.gitignore	# 将 monogame_framework 引擎模块转换为独立 git submodule # - 新增 .gitmodules，engine/monogame_framework 指向 roger_bh/monogame_framework 仓库 # - 主仓库以 gitlink(160000) 记录子模块提交 50120a2 # - 移除主仓库对该目录内文件的直接跟踪 # - 同步 monogame_contente_pipeline 目录重命名为 monogame_content_pipeline	1 个月前
.gitmodules	# 同步子模块版本 + 路径大小写统一 - monogame_framework: 389f27f → bf416dd（xnb 加载链 + ContentReader 泛型化 + 链接修复 + 14 交接文档 + notes 清理） - .gitmodules: path 大小写统一为 Engine/（与 gitlink 记录一致）	26 天前
ARCHITECTURE.md	BHRender 实现 Vulkan 创建链（Instance → Device → Queue） ## BHRender 核心实现 - CreateInstance: VK_API_1_4 降级支持 + 扩展列表（Surface/OHOS/Debug） - CreateSurface: vkCreateSurfaceOHOS 封装 - PickPhysicalDevice: GPU 评分择优（独显 100/集显 50/虚拟 10） - CreateLogicalDeviceAndQueue: set<uniqueFamilies> 去重 + float16Int8/shaderInt16/samplerAnisotropy 启用 - FindQueueFamilies: 图形 + present 队列族查询 - CheckDeviceExtensionSupport: 扩展支持检测 - QuerySwapchainSupport: Surface 能力/格式/呈现模式查询 - IsDeviceSuitable: 四关综合评估（队列族 + 扩展 + swapchain 格式） ## 文档更新 - README/ARCHITECTURE: BHRender 架构 + 当前进度更新	1 个月前
LICENSE-2.0	# 添加了许可证信息	2 个月前
NOTICE	# 修正了版权格式问题	2 个月前
README.md	# 更新仓库远端地址为 roger_bh 组织 # - README: clone/issues/shields 链接由 funbocchi 更新为 roger_bh/bocchi_house Co-Authored-By: AtomCode (deepseek-v4-flash) <noreply@atomgit.com>	1 个月前
build-profile.json5	# 同步代码进度	17 天前
code-linter.json5	initial commit	2 个月前
hvigorfile.ts	initial commit	2 个月前
local.properties	initial commit	2 个月前
oh-package-lock.json5	# 更新了harmonyos_utils版本到1.4.2	1 个月前
oh-package.json5	# 更新了harmonyos_utils版本到1.4.2	1 个月前
paths.cmake	# 更新了cmake	2 个月前

Bocchi House

基于 HarmonyOS NEXT 的游戏移植与启动平台

Bocchi House

一个用于启动各个移植游戏的平台应用
探索项目架构文档 »

查看游戏 · 报告Bug · 提出新特性

本篇 README.md 面向开发者。

项目简介

Bocchi House 是一个运行在 HarmonyOS NEXT 平台上的游戏引擎适配层，旨在将经典游戏（如 Paladin、Unholy Heights）移植到鸿蒙平台。它提供了一套从底层 Vulkan 封装到上层 2D 渲染引擎的完整图形管线。

当前规划移植的游戏：

Paladin (仙剑奇侠传) — 经典中文 RPG，原作为 C 语言编写，由社区大佬移植为 C++ 版本 (pal_harmony)
Unholy Heights (房东是魔王大人) — 魔物公寓经营模拟 + 塔防，原作为 C# XNA 4.0

项目采用分层架构设计：底层通过 platform_abstraction 封装 Vulkan 和鸿蒙原生 API，中间层通过 graphics_adapter 提供 2D 渲染引擎（SpriteBatch、纹理管理、字体渲染），上层游戏模块调用这些接口实现跨平台运行。

技术栈：ArkTS + C++ (NAPI) + Vulkan + HarmonyOS SDK 6.1.0

上手指南

开发前的配置要求

DevEco Studio NEXT 版本 (支持 API 13)
HarmonyOS SDK 6.1.0(23) 及以上
CMake 3.5.0 及以上 (通常随 DevEco Studio 内置)
一台搭载 HarmonyOS NEXT 的真机或模拟器 (手机/平板/2in1)

安装步骤

克隆项目仓库（含子模块）

git clone --recurse-submodules https://gitcode.com/roger_bh/bocchi_house.git

若已克隆过旧版本，请补拉子模块：
git submodule update --init --recursive

使用 DevEco Studio 打开项目根目录，等待依赖同步完成
在运行配置中选择入口模块：
- mobile — 手机/平板设备
- laptop — 2in1 设备
连接设备，点击 Run 编译安装启动器
在启动器首页选择要启动的游戏

文件目录说明

bocchi_house/
├── AppScope/                           # 应用级配置 (bundleName, 图标, 版本)
│   └── app.json5
│
├── products/                           # 产品层 — 启动器入口 (HAP)
│   ├── mobile/                         # 手机/平板入口
│   └── laptop/                         # 2in1 入口
│
├── game_sources/                       # 游戏层 — 各游戏模块 (Feature HAP)
│   ├── paladin/                        # 仙剑奇侠传 (C++ 移植，骨架)
│   └── unholy_heights/                 # 房东是魔王大人 (C++ 移植，测试页)
│
├── features/                           # 适配层 — 引擎级封装 (HAR)
│   ├── game_framework/                  # 游戏框架 — 生命周期桥接 + 窗口控制
│   │   ├── src/main/ets/common/        #   BaseGameAbility 模板
│   │   ├── src/main/cpp/include/       #   BHFrameworkCore 核心编排器
│   │   └── src/main/cpp/types/         #   NAPI d.ts 接口声明
│   ├── graphics_adapter/               # 图形适配器 — 核心渲染引擎
│   │   ├── src/main/ets/screens/       #   GameScreen ArkTS 组件
│   │   ├── src/main/cpp/include/engine/#   BHGraphicsCore 渲染编排器
│   │   ├── src/main/cpp/include/gfx/   #   渲染器/精灵批处理/纹理/字体
│   │   ├── src/main/cpp/include/render/#   BHRender（HelloVK 模式）
│   │   └── src/main/cpp/source/        #   C++ 实现
│   ├── audio_adapter/                  # 音频适配器 (框架)
│   └── input_adapter/                  # 输入适配器 (框架)
│
├── engine/                             # 引擎层 — 引擎模块 (HAR)
│   ├── monogame_framework/             # MonoGame (XNA) 引擎 C++ 移植（git submodule）
│   └── monogame_content_pipeline/      # 内容管线工具
│
├── common/                             # 公共层 — 底层平台封装 (HAR)
│   └── platform_abstraction/           # 窗口管理 + 原生节点 + Vulkan RAII + 日志
│       ├── include/bh_window/          #   BHWindowManager 窗口控制
│       ├── include/node_content/       #   NodeContentHandleTool 节点管理
│       ├── include/system/             #   日志宏 (bh_log)
│       └── include/vulkan/             #   Vulkan RAII 基础封装（12 类）
│
├── build-profile.json5                 # 构建配置 (模块注册, SDK 版本)
├── oh-package.json5                    # 根依赖声明
├── README.md                           # 本文件
├── ARCHITECTURE.md                     # 详细架构设计文档
├── paths.cmake                         # CMake 全局路径变量
└── bocchi_house_session_export.md      # 会话交接文档

架构说明

本项目采用四层分层架构，从底层到顶层依次为：

products (启动器)
    │ startAbility()
    ▼
game_sources (游戏)  ←── 调用 ──►  features/adapters (图形/音频/输入)
    │                                   │ 调用
    ├── 生命周期事件                    │
    ▼                                   ▼
features/game_framework              common (平台封装)
    │ 转发事件                          │ 封装
    ▼                                   ▼
features/adapters                   HarmonyOS / Vulkan

各层职责

层	模块	职责
启动器	`products/laptop`, `products/mobile`	游戏列表 + `startAbility()` 启动游戏
游戏	`game_sources/paladin`, `game_sources/unholy_heights`	游戏核心逻辑
生命周期桥接	`features/game_framework`	`BHFrameworkCore` 单例：接收 ArkTS Ability 生命周期事件（onCreate/onDestroy/onBackground/onForeground），统一转发给各 adapter；管理 App 级窗口控制（窗口装饰/拖拽）
游戏框架	`features/game_framework`	`Game` 类（XNA 风格 Initialize/LoadContent/Update/Draw）、`ScreenManager`（屏幕堆栈）、`GameScreen`（屏幕基类）、`GameTime`（帧时间）
适配层	`features/graphics_adapter`	`VulkanRenderer` 编排器（真机验证 ~30fps）、`SpriteBatch` 2D 渲染、`TextureManager` 纹理加载、`SpriteFont` 字体渲染
适配层	`features/audio_adapter`	`AudioCore` BGM/SE 播放 + 音量控制（框架设计完成，待实现）
适配层	`features/input_adapter`	`InputState`（last/current 双缓冲模式 + IsKeyDown/IsKeyPressed/鼠标查询）（框架设计完成，待实现）
平台封装	`common/platform_abstraction`	Vulkan RAII 封装（12 个类）、窗口管理（`BHWindowManager`）、节点内容管理（`NodeContentHandleTool`）、日志（`bh_log`）

生命周期事件流

ArkTS Ability 生命周期
    │
    ▼
game_framework (BHFrameworkCore)
    │ OnCreate(rm) / OnDestroy() / OnBackground() / OnForeground()
    │
    └──→ Game::Run()
           ├─ Game::LoadContent()         ← 加载纹理/音频
           ├─ [帧循环]                     ← 驱动 ScreenManager
           │    ├─ InputState::BeginFrame()
           │    ├─ Game::Update(time)
           │    │    └─ ScreenManager::Update(time) + HandleInput(input)
           │    ├─ Game::Draw(time)
           │    │    └─ ScreenManager::Draw(time)
           │    │         └─ SpriteBatch + TextureManager
           │    └─ InputState::EndFrame()
           └─ Game::UnloadContent()       ← 清理资源

Vulkan 初始化序列（已验证）

VulkanInstance::Create()     → VkInstance (API 1.3 降级支持)
VulkanSurface::Create()      → VkSurfaceKHR (vkCreateSurfaceOHOS)
VulkanDevice::Create()       → VkDevice + Queue (GPU: Maleoon 916)
VulkanSwapchain::Create()    → VkSwapchainKHR + ImageViews
VulkanCommand::Create()      → CommandPool + CommandBuffer[]
VulkanSync::Create()         → Semaphore[] + Fence[]
VulkanRenderPass::Create()   → RenderPass + Framebuffer[]

游戏列表

游戏	原作	原始语言	移植语言	渲染方式	状态
Paladin (仙剑奇侠传)	SDLPal / pal_harmony	C	C++	CPU 软件渲染 (320x200)	规划中
Unholy Heights (房东是魔王大人)	Petit Depotto	C# (XNA 4.0)	C++	Vulkan GPU 2D 精灵	移植中

当前进度

更新时间: 2026-08-12（基于代码检阅，README 与代码保持同步）

已完成

✅ game_framework 生命周期桥接层：BHFrameworkCore + NapiBridge 拆分（NAPI 静态方法 / 实例方法分离）；注册 15+ NAPI 接口（create / destroy / onBackground / onForeground / 窗口控制 9 个 / 帧生成 2 个）
✅ 窗口控制：BHWindowManager 封装 WindowInfo 结构体（window_id / env / window_ref），SetDecorVisible / SetResizeByDrag 已实现 napi 调用；P1 扩展（SetFullScreen / Minimize 等 6 个）占位
✅ Vulkan RAII 封装（12 个类）：Instance / Surface / Device / Swapchain / Command / Sync / RenderPass / Shader / Pipeline / Buffer / Image / Descriptor
✅ BHNodeContentTool 完整实现：Bind(handle, tag) → NodeContent 回调（SetUserData 存 this+tag）→ ON_ATTACH_TO_WINDOW → CreateXComponent（SurfaceHolder + Surface 回调注册）；Surface 回调通过 SetUserData(holder, this) 取回实例 → OnSurfaceCreated / OnSurfaceChanged / OnSurfaceDestroyed 实例方法分发
✅ graphics_adapter 结构对齐 game_framework：bridge/ 目录 + GraphicsBridge 类（NAPI 参数解析 → 转发 BHGraphicsCore）；engine/ 目录 + BHGraphicsCore 编排器（BindMainContentHandle / InitRender）；BHRender（SetupVKContext(window) 骨架，参照 HelloVK + EGLRender 设计）
✅ platform_abstraction 重构：common/ → types/ 目录重命名；bh_window/ → window/；node_content/ 下 BHNodeContentTool 替代旧的 NodeContentHandleTool
✅ Laptop 启动器 UI：Navigation 组件 + expandSafeArea 沉浸式 + Swiper 轮播推荐 + 游戏卡片列表（纯 UI，业务逻辑待接入）
✅ 命名规范 + 移植方案：docs/NAMING_CONVENTIONS.md、docs/PORTING_PLAN.md、docs/GAME_ENGINE_ARCHITECTURE.md

进行中

🔄 BHRender 实现：SetupVKContext(window) → CreateInstance（API 版本降级支持）+ CreateSurface（OHOS）+ PickPhysicalDevice（独显评分择优）+ CreateLogicalDeviceAndQueue（float16Int8/shaderInt16/samplerAnisotropy 启用）；FindQueueFamilies + CheckDeviceExtensionSupport + QuerySwapchainSupport 设备检测链已完成
🔄 BHGraphicsCore::InitRender：创建 BHRender 实例 + 启动渲染线程（待 BHRender 实现后接线）
🔄 SpriteBatch 完整管线：着色器/顶点缓冲已建，Flush 未实现
🔄 TextureManager：VkImage/View/Sampler 已建，staging upload 未实现
🔄 SpriteFont：DrawString 已实现，依赖 SpriteBatch::Flush

待实现

⬜ namespace 迁移：PlatformAbstraction → bh::platform、GraphicsAdapter → bh::gfx、BH::Framework → bh::framework（参考 docs/NAMING_CONVENTIONS.md 迁移路线图）
⬜ InputAdapter：仅 NAPI 模板占位（input_state.hpp 无实现）
⬜ AudioAdapter：仅 NAPI 模板占位
⬜ Mobile 启动器 UI：当前为 Hello World 模板页
⬜ Paladin 集成 GameScreen：当前为 @Component V1 模板页，未集成渲染组件
⬜ Paladin 游戏移植：~27000 行 C++ 代码适配
⬜ Unholy Heights 游戏移植：C# → C++ 翻译（页面已集成 GameScreen）

部署

暂无。项目尚处于开发阶段。

使用到的技术与框架

HarmonyOS NEXT — 华为鸿蒙操作系统
ArkTS — 鸿蒙声明式 UI 开发语言
Vulkan — GPU 图形渲染 API
NAPI (Node-API) — ArkTS 与 C/C++ 桥接接口
XComponent — 原生渲染表面组件
SurfaceHolderNDK — 新版 Surface 生命周期管理 API

贡献者

请阅读 CONTRIBUTING.md 查阅为该项目做出贡献的开发者。

如何参与开源项目

贡献使开源社区成为一个学习、激励和创造的绝佳场所。你所作的任何贡献都是非常感谢的。

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

版本控制

该项目使用 Git 进行版本管理。您可以在 repository 参看当前可用版本。

作者

FunBocchi

您也可以在贡献者名单中参看所有参与该项目的开发者。

版权说明

该项目签署了 Apache-2.0 授权许可，详情请参阅 LICENSE。

各移植游戏的版权归原作者所有，本项目仅用于技术交流与学习。

鸣谢

pal_harmony — 鸿蒙版仙剑移植项目，为本项目的 Paladin 模块提供了重要参考
SDLPal — 仙剑奇侠传跨平台重制引擎
HarmonyOS Codelabs — 鸿蒙官方示例代码
- XEngine-Codelab-VulkanDemo — Vulkan 渲染参考
- FrameGenerationVulkan — Vulkan 帧生成参考
Img Shields — README 徽章
Choose an Open Source License — 开源协议选择

项目介绍

Apache-2.0 C++188提交数atomcode 应用 typescript openharmony

定制我的领域

README

规则集

bocchi_house:基于 HarmonyOS NEXT 的游戏移植与启动平台项目

Bocchi House

Bocchi House

目录

项目简介

上手指南

开发前的配置要求

安装步骤

文件目录说明

架构说明

各层职责

生命周期事件流

Vulkan 初始化序列（已验证）

游戏列表

当前进度

已完成

进行中

待实现

部署

使用到的技术与框架

贡献者

如何参与开源项目

版本控制

作者

版权说明

鸣谢

项目介绍