# BeanPudding-LevelEditor

**Repository Path**: bqsj00/BeanPudding-LevelEditor

## Basic Information

- **Project Name**: BeanPudding-LevelEditor
- **Description**: 《拼豆手工》游戏-关卡编辑器
- **Primary Language**: TypeScript
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 《拼豆手工》关卡编辑器

### 导出游戏可用的关卡数据 · 与原格式一致 · 支持画廊 CSV 导入

在微信中搜索小程序 **「拼豆手工」** 体验游戏。

[![License](https://img.shields.io/badge/License-AGPL%20v3-blue?style=for-the-badge)](./LICENSE)
[![Upstream](https://img.shields.io/badge/上游-perler--beads-informational?style=for-the-badge)](https://github.com/Zippland/perler-beads)

</div>

<p align="center">
  <img src="./宣传二维码.png" alt="拼豆手工微信小程序：微信搜一搜" width="560" />
  <br />
  <sub>微信小程序「拼豆手工」宣传图 · 微信搜一搜</sub>
</p>

---

本项目是微信小游戏 **《拼豆手工》** 的**关卡编辑器网页端**（见上方二维码，微信内搜一搜即可），基于开源项目 **[perler-beads](https://github.com/Zippland/perler-beads)**（拼豆智能图纸生成器）二次开发。在保留原项目「任意图片 → 拼豆底稿」能力的同时，增补了与游戏流水线对齐的关卡导入与导出。

## 关卡编辑特点

| 能力 | 说明 |
|------|------|
| **导出游戏关卡** | 将当前像素画布导出为游戏可直接使用的关卡 **JSON**（含 `editorVersion`、`level`、`initialPegColors`、`scramble` 等结构），可先预览打乱效果再导出。 |
| **格式对齐** | 导出数据与《拼豆手工》关卡管线一致；支持同步导出 **`Level<id>_Complete.txt`**（目标局面与初始打乱两段网格 + 第三段 Meta），便于存档与校对。 |
| **画廊 CSV 互通** | 可直接导入**源项目 / 画廊导出的 CSV**（拼豆色号网格），在无原图的情况下继续调色、合并颜色、导出关卡。 |
| **关卡 TXT 回灌** | 支持导入已有 **`Level*_Complete.txt`**，读取关卡 Id、打乱种子等信息，便于在编辑器中迭代微调后再次导出。 |

工作流示例：**画廊 CSV → 本工具精修 → 导出 JSON / TXT → 填入游戏关卡资源**。亦支持：**参考图 JPG/PNG → 像素化 → 导出关卡**，与原作流程兼容。

---

## 功能概览（继承 + 扩展）

**继承自上游（拼豆图纸生成）：**

- 智能像素化（主导色映射，减轻灰边）
- 多品牌色号体系（MARD / COCO / 漫漫 / 盼盼 / 咪小窝等）
- 区域颜色合并、背景剔除、颜色排除与重映射
- 手动改色、图纸与采购清单类导出

**本仓库侧重：**

- 关卡 **JSON / TXT** 导出，适配《拼豆手工》
- **CSV / TXT / 图片** 多入口导入，服务关卡制作闭环

---

## 快速开始

```bash
git clone https://github.com/<你的用户名>/BeanPudding-LevelEditor.git
cd BeanPudding-LevelEditor
npm install
npm run dev
```

浏览器访问 `http://localhost:3000`。在界面中导入 **图片、画廊 CSV 或关卡 TXT**，编辑完成后使用 **「导出游戏关卡 JSON」** 等功能下载产物。

---

## 技术栈

| 层 | 技术 |
|---|------|
| 框架 | Next.js（React）+ TypeScript |
| 样式 | Tailwind CSS |
| 图像与网格 | Canvas API（浏览器端） |

---

## 核心算法（上游论文档摘要）

关卡编辑器复用上游的像素化与调色板管线，其核心步骤为：**主导色 → 调色板映射**、**相似色 BFS 区域合并**、**边界洪水填充去背景**、**排除颜色时的受限重映射**。色板数据见 [`src/app/colorSystemMapping.json`](src/app/colorSystemMapping.json)；色板选项见 [`src/app/page.tsx`](src/app/page.tsx) 中的 `paletteOptions`。

---

## 上游与致谢

算法与基底 UI 源自 **[Zippland/perler-beads](https://github.com/Zippland/perler-beads)**（在线体验：[移动端](https://perlerbeads.zippland.com) / [桌面端](https://perlerbeadsnew.zippland.com)）。二次开发聚焦于《拼豆手工》关卡资源生产；感谢原作者开源与共创声明。

欢迎提交 Issue 与 Pull Request：Fork → 分支开发 → PR。

---

## 共建与许可证

使用与分发须遵守 **[AGPL-3.0](./LICENSE)**：保留版权声明，衍生作品在相同条件下开源。**请勿将本仓库或上游代码恶意抄袭并闭源商用。**