# YYKACCG

**Repository Path**: YYKACN/YYKACCG

## Basic Information

- **Project Name**: YYKACCG
- **Description**: No description available
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 16
- **Forks**: 11
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YYKA Cocos Component Generator

面向 **Cocos Creator 3.x** 的 2D 游戏场景组件生成器 —— 以瓦片地图编辑器为基底的「瓦片 + 实体」一体化编辑与导出工具。

> **完全免费 · 开源**。做 2D 游戏时「瓦片地图 / 自动地形 / 实体摆放 / 碰撞遮挡 / 寻路避障」这一整摊最累、最不炫耀、又最逃不掉的活，交给它；省下来的时间，拿去打磨真正好玩的玩法。

---

## 目录

- [它解决什么问题](#它解决什么问题)
- [目标用户](#目标用户)
- [核心特性](#核心特性)
- [双运行时导出](#双运行时导出)
- [数据模型](#数据模型)
- [内置示例工程](#内置示例工程)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [工作流程](#工作流程)
- [目录结构](#目录结构)
- [设计约束与实现说明](#设计约束与实现说明)
- [开源与联系](#开源与联系)
- [License](#license)

---

## 它解决什么问题

做 2D 游戏，有一摊子事情特别烦人，但绕不开 —— 就是地图：

- 瓦片地图要一张张抠、一格格摆，自动地形全手动拼、拼出来还是接缝；
- 图层一多遮挡就乱：角色走在房子后面该被挡住，屋顶一揭又得看到里面的人；
- 寻路避障基本靠硬写，A*、流场、RVO 每次都要重来；
- NPC、怪物、道具摆在哪全靠心里记，素材库、配置、导出格式串成一片乱麻。

YYKA 的目的很单纯：把「地图骨架（瓦片、地形、实体、碰撞、遮挡、寻路）」这一摊最累最乱的活整包接管，输出可用的资源、配置数据与基础管理框架；**战斗、对话、AI 等业务逻辑仍需你在 Cocos 里实现** —— 它不打算冒充引擎。

## 目标用户

- Cocos Creator 3.x 独立开发者；
- 小型游戏开发团队、外包工作室；
- 适用游戏类型：RPG、ARPG、SLG 战棋、肉鸽（Roguelike）、塔防、模拟经营；
- 覆盖两类技术栈：传统组件式项目、Cocos ECS 高性能项目。

## 核心特性

### 1. 多网格原生支持
正交（塔防 / 横版）、斜 45° 等轴测（模拟经营）、六边形（战棋 SLG）三种网格类型，一套工具全部覆盖，无需为不同玩法切换软件。

### 2. 增强版 Autotile 自动地形
- 多地形集管理，多地形之间互相**混合过渡**（草地、泥土、水边自动缝合）；
- **自定义掩码规则**，正交 / 等轴测 / 六边形各自独立规则，互不混用；
- **瓦片锁定**：不想参与自动重算的格子可以锁住；
- 地形集支持导入 / 导出，跨工程复用。

### 3. 瓦片与实体一体化编辑
- **瓦片层**负责美术地表（地面、墙体、植被），按业务分层管理遮挡层级；
- **对象实体层**直接摆放 NPC、怪物、可拾取道具、交互建筑、传送点、刷怪触发器、出生点；
- 实体基于**模板库**：模板定义类型、碰撞、自定义属性、事件、AI 标记；地图上是**实例**，可局部覆写模板属性；
- 模板更新支持两种同步策略：**批量同步全部实例** / **保留实例本地修改**。

### 4. 多层遮挡 + Y 排序
图层分组管着渲染层级：地面 → 地表装饰 → 建筑底层 → 角色实体 → 屋顶树冠 → 前景。屋顶这层能挡住角色，运行时可**半透明揭开**看到底下的人；角色前后互相遮挡的**动态 Y 排序**在图层上开关即可，编辑器内即可预览验证。

### 5. 双网格寻路系统
- **美术瓦片网格**与**独立导航网格**粒度解耦，互不干扰；
- 导航网格支持**自动烘焙** + 笔刷**手动编辑**，可保留手工修改；
- 内置算法：**A\*、JPS、Dijkstra、BFS 洪泛、流场 FlowField、RVO2 避障、路径平滑**；
- 编辑器内**可视化预览**和动态障碍模拟，导出时**按需勾选**，只输出选中算法源码，控制包体积。

### 6. SQLite 本地素材与模板库
- 图集 PNG/WebP 导入、自动切块、支持手动调整切分网格；
- 图块元数据（通行、地形代价、碰撞、遮挡、分类）统一入库；
- 支持全局公共素材与**工程私有素材隔离**，复制工程时可打包私有素材。

### 7. 多种持久化与恢复
`.yyka` 工程文件、SQLite 数据库、自动保存与崩溃恢复，工程文件以**明文 JSON** 存储，便于版本管理与协作。

## 双运行时导出

导出时二选一，输出整套地图资源、实体数据、管理框架与示例场景：

| 模式 | 适用场景 | 说明 |
|---|---|---|
| 传统组件模式 | 中小型项目 / 原型 | Cocos 传统 Node + Component |
| ECS 高性能模式 | 塔防 / RTS / 大量实体群战 | 基于 Cocos ECS 框架，System + 组件定义 |

两套模式**共享同一个寻路内核**，仅上层 Manager / System 封装不同 —— 用哪套跑，同一张地图的行为保持一致。此外支持 **TMX / TSX 标准兼容导出**，方便对接不在这套工具里的流程。

## 数据模型

| 文件 / 存储 | 说明 |
|---|---|
| `xxx.yyka` | 编辑器工程：瓦片图层、实体实例、导航网格修改、地图配置（明文 JSON） |
| SQLite 数据库 | `material` 图集表、`tiles` 图块元数据表、`entity_template` 实体模板表、`autotile_set` 地形集表 |
| `*.tmx / *.tsx` | 兼容导出的标准 Tiled 格式 |
| `navgrid.json` | 独立导航网格数据 |
| `navconfig.json` | 寻路全局参数配置 |

> 坐标约定：编辑器内部 Y 轴向下（PixiJS），Cocos Creator Y 轴向上，导出层统一封装坐标转换，业务数据不散落转换逻辑。

## 内置示例工程

软件内置三套完整的 `.yyka` 示例工程，开箱可编辑 / 预览 / 导出，每套均含图层、Autotile 地形集、实体、碰撞遮挡、寻路配置：

| 网格类型 | 场景 | 演示能力 |
|---|---|---|
| 正交 | RPG 村庄 | 遮挡、屋顶揭开、NPC / 怪物 / 触发器 |
| 斜 45° 等轴测 | 模拟经营小镇 | 等轴 Autotile、建筑实体、动态障碍 |
| 六边形 | SLG 战棋战场 | 六边形 Autotile、战棋单位、移动范围寻路 |

## 技术栈

- **前端**：Tauri 2 · React 19 · TypeScript · Vite · YYKAUI · Zustand
- **渲染**：PixiJS v8（自研 Chunk 瓦片渲染，不依赖第三方 tilemap 插件）
- **后端**：Rust · SQLite（rusqlite bundled）
- **导出**：代码模板生成器驱动，运行时组件 / ECS 双套产物

## 快速开始

**环境要求**：Node.js 18+、Rust toolchain、[Tauri 2 系统依赖](https://v2.tauri.app/start/prerequisites/)（Windows/Linux/macOS 略有差异）。

```bash
# 1. 安装前端依赖
npm install

# 2. 运行开发版（自动编译 Rust 后端并弹出桌面窗口）
npm run tauri dev

# 3. 构建发布版（生成安装包 / 可执行文件）
npm run tauri build
```

纯前端调试（浏览器预览，无 Rust 原生能力）：

```bash
npm run dev
```

## 工作流程

1. **新建 / 打开地图**：选择网格类型（创建后不可改动），面板提供三层对象等推荐图层模板；
2. **绘制**：瓦片笔刷（铅笔 / 矩形填充 / 油漆桶 / 橡皮 / 图章）+ 增强 Autotile 自动接缝；
3. **摆放实体**：从模板库拖入 NPC / 怪物 / 道具 / 建筑 / 触发器，实例级覆写属性；
4. **配置碰撞与遮挡**：瓦片 / 实体碰撞、遮挡标记、屋顶半透明揭开、图层 Y 排序；
5. **导航网格**：自动烘焙或笔刷修正，编辑器内预览算法路径与避障效果；
6. **导出**：选择组件 / ECS模式，TMX 或 YYKA 完整运行时，勾选所需寻路算法，输出运行时代码与示例场景。

## 目录结构

```
YYKACocosComponentGenerator/
├── README.md                 # 本文档
├── .gitignore
├── package.json              # 前端工程配置（vite / tauri scripts）
├── index.html
├── vite.config.ts
├── tsconfig.json / node
│
├── src/                      # React 前端源码
│   ├── main.tsx / App.tsx / routes.tsx
│   ├── pages/                # Editor 地图编辑器 · Dashboard 控制台 · Data · Materials · Objects · Assets · Settings · About
│   ├── editor/               # 核心：渲染(Pixi) / 寻路 / Autotile / 导出脚本 / 工程 IO(mapIO)
│   ├── components/           # 布局壳 / 窗口控制 / 全局弹窗
│   ├── store/                # Zustand 状态
│   ├── api/                  # Tauri 命令封装（db / config / file / log / system / yyka）
│   └── assets/               # 静态资源（示例图、关注二维码）
│
├── src-tauri/                # Rust 后端
│   ├── src/
│   │   ├── main.rs           # 应用入口 + invoke_handler 注册
│   │   └── api/              # db.rs · config.rs · file.rs · log.rs · system.rs · yyka.rs
│   ├── tauri.conf.json
│   ├── Cargo.toml / Cargo.lock
│   ├── capabilities/         # Tauri ACL 权限
│   └── icons/                # 应用图标
│
└── docs/
    ├── 开发文档.md            # 产品规划 / 分阶段开发 / 数据约束
    └── 公众号文案.md          # 面向开发者的发布文案
```

> 根目录下的 `*.html / *.mjs / *.cjs` 探针调试脚本与 `node_modules / dist / src-tauri/target` 等产物均未纳入版本库（见 `.gitignore`）。

## 设计约束与实现说明

- **渲染可降级**：PixiJS 按 WebGPU → WebGL2 → Canvas 2D 自动选用后端，适配不同环境的 WebView；
- **渲染与业务解耦**：渲染层只绘制不持有状态，业务状态统一放 Zustand / SQLite / `.yyka` 工程；
- **分块渲染控制显存**：Chunk 使用 RenderTexture 分块渲染，视口外销毁纹理；
- **导出体积可控**：寻路算法由代码模板按勾选生成，不硬编码全量；
- **组件 / ECS 行为对齐**：同一套地图数据 + 共用寻路内核，保证两套运行时行为一致。

## 开源与联系

- **开源仓库**：[Gitee · YYKACN](https://gitee.com/YYKACN)
- **官网**：[www.yyka.cn](http://www.yyka.cn)
- **邮箱**：[yykacn@qq.com](mailto:yykacn@qq.com)
- **哔哩哔哩**：[YYKA游戏工坊](https://space.bilibili.com/437551796)

### 扫码关注

| 微信公众号 | 个人微信 | 小程序 |
|---|---|---|
| ![公众号二维码](src/assets/gongzhong-qrcode.jpg) | ![个人微信二维码](src/assets/wechat-qrcode.jpg) | ![小程序二维码](src/assets/miniapp.jpg) |

欢迎点 star、提 issue、提交 PR。工具由做游戏的人一起共建。

## License

开源版本采用 **MIT License**，详见根目录 [LICENSE](LICENSE)。