# pixel-forge

**Repository Path**: xanor/pixel-forge

## Basic Information

- **Project Name**: pixel-forge
- **Description**: 一款强大的 2D 游戏素材生成工具，由 AI 驱动。通过文本描述轻松生成像素风格的游戏素材。
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-23
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PixelForge

一款强大的 2D 游戏素材生成工具，由 AI 驱动。通过文本描述轻松生成像素风格的游戏素材。

## 功能特点

- **AI 驱动生成** - 使用 AI 生成像素风格素材（支持智谱 GLM-4、OpenAI DALL-E 3 或本地 Stable Diffusion）
- **多种素材类型** - 角色、瓦片、道具、特效、场景、UI 元素
- **多种导出格式** - 支持导出到 Godot、Unity、GameMaker 或通用 PNG 格式
- **配置文件管理** - 安全地将 API 密钥存储在本地配置文件中
- **多语言支持** - 支持中英文提示词

## 软件架构

```
┌─────────────────────────────────────────────────────────────┐
│                      PixelForge                            │
├─────────────────────────────────────────────────────────────┤
│                     前端 (React + TypeScript)                │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │  Generator  │  │   Canvas    │  │      Settings       │ │
│  │   Panel     │  │   Preview   │  │      Modal          │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│         │                │                  │              │
│         └────────────────┼──────────────────┘              │
│                          │                                 │
│              ┌───────────┴───────────┐                     │
│              │   Zustand Store        │                     │
│              │  (状态管理+持久化)      │                     │
│              └───────────┬───────────┘                     │
│                          │                                 │
│              ┌───────────┴───────────┐                     │
│              │     Tauri IPC         │                     │
│              │   (前后端通信)         │                     │
└──────────────┼───────────────────────┼─────────────────────┘
               │                       │
┌──────────────┼───────────────────────┼─────────────────────┐
│              │   Rust 后端 (Tauri)   │                      │
├──────────────┼───────────────────────┼─────────────────────┤
│  ┌───────────┴───────────┐  ┌───────┴────────┐            │
│  │      AI Engine        │  │   Config      │            │
│  │  ┌─────┬─────┬─────┐ │  │  Manager     │            │
│  │  │Local│OpenAI│Zhipu│ │  └─────────────┘            │
│  │  │ SD  │     │     │ │                                  │
│  │  └──┬──┴──┬──┴──┬──┘ │  ┌─────────────┐             │
│  │     │     │     │    │  │   Exporter   │             │
│  └─────┼─────┼─────┼────┘  │  ┌─────────┐ │             │
│        │     │     │       │  │Godot    │ │             │
│        └─────┴─────┴───────┘  │Unity    │ │             │
│              │                 │GameMaker│ │             │
│              │                 │Generic  │ │             │
│              │                 └─────────┘ │             │
│              └───────────────────────────┘             │
└─────────────────────────────────────────────────────────┘
```

### 前端架构 (src/)

```
src/
├── components/          # React 组件
│   ├── canvas/         # 画布预览组件
│   ├── common/         # 通用组件 (Header, Sidebar, Settings)
│   └── generator/      # 生成器面板组件
├── hooks/              # 自定义 React Hooks
├── lib/                # 工具库 (Tauri API 封装)
├── stores/             # Zustand 状态管理
│   └── generatorStore.ts  # 生成器状态 (持久化)
├── types/              # TypeScript 类型定义
├── App.tsx             # 应用主组件
└── main.tsx            # 入口文件
```

### 后端架构 (src-tauri/src/)

```
src-tauri/src/
├── ai/                 # AI 引擎模块
│   ├── engine.rs       # AI 引擎核心 (调度、生成)
│   ├── cloud.rs        # 云端 AI 接口
│   └── local.rs        # 本地 SD 接口
├── config.rs           # 配置文件管理
├── exporter/           # 导出器模块
│   ├── godot.rs       # Godot 格式导出
│   ├── unity.rs       # Unity 格式导出
│   ├── gamemaker.rs   # GameMaker 格式导出
│   └── generic.rs     # 通用 PNG 导出
├── generator/          # 素材生成器模块
│   ├── character.rs    # 角色生成
│   ├── scene.rs       # 场景生成
│   ├── item.rs        # 道具生成
│   ├── effect.rs      # 特效生成
│   └── ui.rs          # UI 生成
└── main.rs             # Tauri 主入口
```

### 核心模块说明

| 模块 | 职责 |
|------|------|
| AI Engine | 统一调度 AI 提供商，按优先级自动选择可用服务 |
| Config Manager | 管理系统配置，支持 JSON 文件持久化 |
| Exporter | 处理素材导出，兼容多种游戏引擎格式 |
| Generator | 针对不同素材类型的生成逻辑 |
| Zustand Store | 前端状态管理，支持 LocalStorage 持久化 |

## 支持的 AI 提供商

| 提供商 | 优先级 | 说明 |
|--------|--------|------|
| 本地 Stable Diffusion | 1 | 本地运行，地址 http://localhost:7860 |
| OpenAI DALL-E 3 | 2 | 需要 OpenAI API 密钥 |
| 智谱 cogview-4 | 3 | 国产 AI，需要智谱 API 密钥 |
| 演示模式 | 99 | 兜底模式（无需 API 密钥） |

## 安装

1. 安装 Node.js 18+
2. 安装 Rust 和 Cargo
3. 安装 WebView2（Windows）或 WebKit（Linux/macOS）

```bash
# 克隆仓库
git clone https://gitee.com/xanor/pixel-forge.git
cd pixel-forge

# 安装依赖
npm install

# 开发模式运行
npm run tauri dev

# 生产环境构建
npm run tauri build
```

## 配置

配置文件位置：
- **Windows**: `%APPDATA%\PixelForge\config.json`
- **Linux**: `~/.config/pixel-forge/config.json`

配置格式：

```json
{
  "openai_api_key": "",
  "zhipu_api_key": "",
  "default_ai_provider": "auto",
  "default_export_format": "generic"
}
```

您也可以通过应用内的设置对话框进行配置。

## 智谱 API 密钥申请

1. 访问 [智谱 AI 开放平台](https://open.bigmodel.cn/)
2. 注册并获取 API 密钥
3. 在设置中或配置文件中输入密钥
4. cogview-4 模型支持的图片尺寸：512-2880像素，必须是32的倍数

## API 密钥验证

使用提供的测试脚本验证您的 API 密钥：

```bash
# Windows
test_zhipu_key.bat

# 输入您的智谱 API 密钥
# 脚本将测试与 API 的图像生成
```

### 预期响应

成功：
```json
{"created":..., "data": [{"url": "https://..."}]}
```

错误 (401/403)：
```json
{"error": {"code": "...", "message": "..."}}
```

## 技术栈

- **前端**: React 18 + TypeScript + Vite
- **后端**: Rust + Tauri 2.x
- **状态管理**: Zustand（带持久化）
- **AI 集成**: Reqwest 异步 HTTP 请求

## 快捷键

| 操作 | 快捷键 |
|------|--------|
| 生成 | Ctrl/Cmd + G |
| 保存 | Ctrl/Cmd + S |
| 设置 | Ctrl/Cmd + , |

## 许可证

MIT 许可证

---

*为游戏开发者而构建* ❤️