Skip to content

Architecture

Jump to bottom
qingchenyouforcc edited this page Mar 11, 2026 · 6 revisions

架构概览 / Architecture

本文档介绍 NeurolingsCE 的整体代码架构和核心组件。

This document provides an overview of the NeurolingsCE codebase architecture and core components.

目录结构 / Directory Structure

NeurolingsCE/
├── src/app/                    # Qt 应用层（按职责分层）
│   ├── core/                   # 基础能力：资源加载、音效、HTTP API、导入、shijima引擎
│   │   └── shijima-engine/     # 集成的看板娘模拟引擎（原 libshijima）
│   ├── runtime/                # 运行时：环境同步、生命周期、导入流程
│   └── ui/                     # 界面：管理器窗口、托盘、看板娘窗口、对话框
│
├── src/platform/Platform/      # 平台抽象层（Windows/Linux/macOS）
├── include/shijima-qt/         # 公共头文件
│
├── libshimejifinder/           # [子模块] 资源包解压导入
├── cpp-httplib/                # [子模块] HTTP 服务器（header-only）
│
├── cmake/                      # CMake 辅助脚本
├── src/assets/                 # 内置默认看板娘资源
├── src/packaging/              # 桌面入口、图标、安装包配置
├── licenses/                   # 第三方许可证文本
├── dev-docker/                 # Docker 交叉编译环境
└── .github/workflows/          # CI/CD 配置

架构分层 / Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                        应用层 / App Layer                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │     UI      │  │   Runtime   │  │        Core         │  │
│  │  界面渲染    │  │  生命周期    │  │  资源/HTTP/引擎      │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
└─────────┼────────────────┼────────────────────┼─────────────┘
          │                │                    │
┌─────────┼────────────────┼────────────────────┼─────────────┐
│         │        平台抽象层 / Platform Layer   │             │
│         │     ┌─────────────────────────┐      │             │
│         └────►│   Platform (Windows/    │◄─────┘             │
│               │   Linux/macOS)          │                    │
│               └─────────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘

核心组件 / Core Components

1. ShijimaManager（应用管理器）

位置: src/app/runtime/Manager*.cc + include/shijima-qt/ShijimaManager.hpp

全局单例，继承 PlatformWidget<QMainWindow>，是整个应用的中央控制器。

职责切片文件:

文件 职责
ManagerWindowSetup.cc 管理器窗口初始化
ManagerLifecycle.cc 看板娘生成/销毁
ManagerMascotRuntime.cc 看板娘运行时调度
ManagerEnvironmentSync.cc 多屏幕环境同步
ManagerImportWorkflow.cc 资源包导入流程
ManagerTickLoop.cc 主循环定时器

核心功能:

方法 说明
spawn(name) 生成指定看板娘
killAll() 销毁所有看板娘
tick() 主循环回调（25 FPS）
import(path) 导入资源包

2. ShijimaWidget（看板娘窗口）

位置: src/app/ui/mascot/MascotWidget*.cc + include/shijima-qt/ShijimaWidget.hpp

每个看板娘实例对应一个透明无边框窗口，继承 PlatformWidget<QWidget>。

职责切片:

文件 职责
MascotWidgetRendering.cc 渲染与绘制
MascotWidgetInteraction.cc 鼠标交互、右键菜单
MascotWidgetTick.cc 帧更新、状态推进

特性:

  • 渲染: paintEvent() 绘制精灵图，支持镜像
  • 交互: 拖拽移动、右键菜单
  • Hit 测试: pointInside() 精确点击检测
  • Fall-Through: 坠落超过 700px 时穿越任务栏

3. shijima-engine（模拟引擎）

位置: src/app/core/shijima-engine/

集成的看板娘行为模拟引擎（原 libshijima），负责：

  • XML 行为定义解析
  • JavaScript 脚本执行（duktape）
  • 物理模拟（重力、碰撞）
  • 行为树执行

命名空间: shijima::mascot::

包含路径: #include <shijima/...>

注：上游 libshijima 不接受外部贡献，本项目将引擎集成在源码树内，便于本地修复。

4. 支持组件 / Supporting Components

组件 位置 说明
MascotData src/app/core/mascot/ 单个资源包的数据封装
AssetLoader src/app/core/assets/ 精灵图加载与缓存
ShijimaHttpApi src/app/core/http/ HTTP REST API 服务器
SoundEffectManager src/app/core/audio/ 音效播放（可选）
SimpleZipImporter src/app/core/import/ ZIP 资源包导入

数据流 / Data Flow

启动流程

main()
  │
  ├── 单实例检查 (HTTP ping :32456)
  │   ├── 成功 → 退出
  │   └── 失败 → 继续
  │
  ├── Platform::initialize()
  ├── QApplication 创建
  │
  ├── ShijimaManager::defaultManager()->show()
  │   ├── 加载默认看板娘
  │   ├── 扫描 mascots/ 目录
  │   ├── 启动 HTTP API
  │   └── 启动 tick 循环 (25 FPS)
  │
  └── app.exec()

Tick 循环

timerEvent() [每 40ms = 25 FPS]
  │
  ├── updateEnvironment()      # 同步屏幕/窗口信息
  │
  ├── 对每个 ShijimaWidget:
  │   └── tick()
  │       ├── m_mascot->tick() # 引擎状态推进
  │       └── repaint()        # 重绘
  │
  └── 处理 tickCallbacks       # HTTP API 回调

资源包导入流程

用户拖拽 .zip
  │
  ├── SimpleZipImporter::import()
  │   ├── 解压 ZIP
  │   ├── 识别布局
  │   └── 复制到 mascots/<name>/
  │
  ├── loadData(MascotData*)
  │   └── m_factory.load_template()  # 引擎加载
  │
  └── refreshListWidget()            # 刷新 UI

代码组织约定 / Code Conventions

文件命名

采用 "主体 + 职责" 模式拆分大型类：

模式 示例 所属类
Manager*.cc ManagerImportWorkflow.cc ShijimaManager
MascotWidget*.cc MascotWidgetRendering.cc ShijimaWidget

包含风格

// 项目头文件
#include "shijima-qt/Foo.hpp"

// 引擎头文件
#include <shijima/mascot.hpp>

// 平台头文件
#include "Platform/Platform.hpp"

条件编译宏

宏 说明
SHIJIMA_USE_QTMULTIMEDIA 启用音效
SHIJIMA_WITH_SHIMEJIFINDER 启用 libshimejifinder
WIN32 / __linux__ / __APPLE__ 平台判断

外部依赖 / Dependencies

NeurolingsCE
  │
  ├── shijima-engine (集成)      # 看板娘模拟引擎
  │
  ├── libshimejifinder [子模块]   # 资源包解压
  │   └── 依赖 libunarr + libarchive
  │
  └── cpp-httplib [子模块]        # HTTP 服务器

相关页面 / Related Pages

NeurolingsCE Wiki

用户入口

资源包与模板

开发者入口

Clone this wiki locally