# Emberveil

**Repository Path**: FSW_ei/emberveil

## Basic Information

- **Project Name**: Emberveil
- **Description**: ESP32S3独立游戏
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

<img src="art/标题页/TitleScreen.png" alt="Emberveil" width="320" />

# 🔥 Emberveil · 芯火

**横版像素叙事解谜游戏 · ESP32-S3 嵌入式平台**

用最小的硬件，沉浸式的叙事体验。

[English](README.md)

![Platform](https://img.shields.io/badge/Platform-ESP32--S3-blue?style=flat-square&logo=espressif)
![Display](https://img.shields.io/badge/Display-ST7789%20240×240-orange?style=flat-square)
![Framework](https://img.shields.io/badge/Framework-PlatformIO-blueviolet?style=flat-square&logo=platformio)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)

[![GitHub Stars](https://img.shields.io/github/stars/FSWei/Emberveil?style=flat-square&logo=github)](https://github.com/FSWei/Emberveil)
[![Gitee Star](https://gitee.com/FSW_ei/emberveil/widgets/widget_card.svg?theme=dark)](https://gitee.com/FSW_ei/emberveil)

</div>

---

## 🎮 项目简介

**Emberveil（芯火）** 是一款运行在 **ESP32-S3** 上的横版叙事解谜游戏，搭配 **240×240 ST7789** 小屏幕，目标是用最小的硬件实现沉浸式的像素叙事体验。

- 🎨 **像素风场景** — 多层视差背景，实时合成渲染
- 📖 **叙事驱动玩法** — 对话系统、分支事件、九动物解救任务链
- ⚡ **性能优化** — 脏矩形局部刷新、场景缓存、`.raw` 快速加载
- 🔧 **开发友好** — PlatformIO 一键构建、串口调试、Aseprite 导出脚本

## 📸 截图

<div align="center">

<img src="img/1.jpg" alt="标题画面" width="360" />

<img src="img/2.jpg" alt="游戏场景" width="360" />

</div>

## 🛠️ 硬件清单

| 部件 | 型号 |
|------|------|
| 主控 | ESP32-S3 DevKitC-1 **N16R8 或以上**（16MB Flash + 8MB PSRAM） |
| 屏幕 | ST7789 240×240 SPI TFT |
| 输入 | 摇杆（VRx + VRy + SW） |
| 存储 | SPIFFS（片上 Flash） |
| 可选 | SDMMC 1-bit |

引脚定义：[`include/board_pins.h`](include/board_pins.h)

## 🚀 快速开始

```bash
# 1. 克隆仓库
git clone https://github.com/FSWei/Emberveil.git
# 或
git clone https://gitee.com/FSW_ei/emberveil.git

cd Emberveil

# 2. 安装 PlatformIO
pip install platformio

# 3. 编译
pio run

# 4. 刷入固件 + SPIFFS 资源（推荐）
pio run -e flash-with-resources -t flash-all

# 5. 打开串口监视器
pio device monitor
```

## 🎨 美术资源管线

```
Aseprite (.aseprite)
  │
  ▼  运行 export_scene_raw.lua
export/
  ├── 0/   e_0_s1_1.png + .raw
  ├── 1/   ...
  └── 31/  ...
  │
  ▼  复制到 data/assets/y/
  ▼  pio run -e flash-with-resources -t flash-all
ESP32-S3 (SPIFFS)
```

| 脚本 | 输出 | 说明 |
|------|------|------|
| [`export_scene_raw.lua`](art/aseprite_scripts/export_scene_raw.lua) | PNG + RAW | ✅ 推荐 — 一步到位 |
| [`export_scene_enhanced.lua`](art/aseprite_scripts/export_scene_enhanced.lua) | 仅 PNG | 需配合 `scripts/png_to_raw.py --all` 转换 |

详细说明：[`art/aseprite_scripts/README.md`](art/aseprite_scripts/README.md)

## 🎮 操作方式

| 输入 | 行为 | 说明 |
|------|------|------|
| 摇杆左右 | 移动 | VRX 横向控制 |
| 摇杆按键 / `A` | 交互 | 调查、确认、推进对话 |
| `B`（串口） | 取消 | 关闭对话 |
| `L` / `R`（串口） | 移动 | 串口调试 |
| `1` / `2` / `3`（串口） | 切换章节 | prologue / chapter1 / chapter2 |
| `4` / `5`（串口） | 切换场景 | scene2 / scene1 |

## 📂 项目结构

```
Emberveil/
├── src/
│   ├── app/           # 入口胶水层
│   ├── core/          # 主循环、场景管理、输入
│   ├── content/       # 场景与 meta JSON 解析
│   ├── gameplay/      # 事件总线、任务逻辑
│   ├── platform/      # 硬件抽象：显示、Flash、SD、USB
│   └── render/        # PNG 解码、精灵缓存
├── data/assets/       # SPIFFS 资源（精灵、图层、字体）
├── art/               # Aseprite 源文件 + 导出脚本
├── docs/              # 设计文档（架构、美术、玩法、剧情）
├── scripts/           # 构建与转换工具
├── font_generate/     # 点阵字体生成器
└── platformio.ini     # 构建配置
```

## 📚 文档索引

| 主题 | 链接 |
|------|------|
| 架构设计 | [docs/架构/游戏程序架构文档_v1.md](docs/架构/游戏程序架构文档_v1.md) |
| 美术规范 | [docs/美术/场景绘制文档_v1.md](docs/美术/场景绘制文档_v1.md) |
| 玩法设计 | [docs/玩法/玩法核心循环文档_v1.md](docs/玩法/玩法核心循环文档_v1.md) |
| 剧情大纲 | [docs/剧情/主线三幕大纲_v1.md](docs/剧情/主线三幕大纲_v1.md) |
| 开发指南 | [开发指南.md](开发指南.md) |

## ⚠️ 约束条件

- **ESP32-S3 嵌入式平台**：RAM 有限，无 STL 异常，无 RTTI
- **SPIFFS 路径限制**：OBJ_NAME_LEN=32，路径 ≤ 31 字符
- **PNG 解码**：行缓冲模式（PNG_MAX_BUFFERED_PIXELS=4096）
- **手动 JSON 解析**：不依赖 JSON 库，使用自研 `extractJsonValue()`

## 🤝 参与贡献

欢迎贡献代码！提交前请阅读 [开发指南](开发指南.md)。

## 📄 开源协议

本项目基于 **MIT 许可证** 开源 — 详见 [LICENSE](LICENSE) 文件。

---

<div align="center">

**Made with 🔥 by 芯火XH**

</div>