163 lines
5.1 KiB
Markdown
163 lines
5.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
gen2d — AI 驱动的 2D 游戏素材生成工具。用户通过文本提示词或可视化参数，生成风格一致、管线友好的 Sprite、背景、UI 元素与动画帧。目标是无缝融入 Unity / Godot 等主流 2D 游戏引擎的工作流。
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
gen2d/
|
||
├── backend/ # Go + Gin API 服务
|
||
│ ├── cmd/ # 入口 (main.go)
|
||
│ ├── internal/ # 业务逻辑（不对外暴露）
|
||
│ │ ├── handler/ # HTTP handlers
|
||
│ │ ├── service/ # 业务 service 层
|
||
│ │ ├── model/ # 数据模型 / DTO
|
||
│ │ ├── middleware/
|
||
│ │ └── config/
|
||
│ ├── pkg/ # 可复用的公共库
|
||
│ ├── go.mod
|
||
│ └── go.sum
|
||
├── frontend/ # Vite + React 前端
|
||
│ ├── src/
|
||
│ │ ├── components/
|
||
│ │ ├── pages/
|
||
│ │ ├── hooks/
|
||
│ │ ├── services/ # API 调用层
|
||
│ │ ├── stores/ # 状态管理
|
||
│ │ ├── types/
|
||
│ │ └── utils/
|
||
│ ├── public/
|
||
│ ├── index.html
|
||
│ ├── vite.config.ts
|
||
│ ├── tsconfig.json
|
||
│ └── package.json
|
||
└── CLAUDE.md
|
||
```
|
||
|
||
## Common Commands
|
||
|
||
### Backend (Go + Gin)
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# 安装依赖
|
||
go mod tidy
|
||
|
||
# 运行开发服务器
|
||
go run cmd/main.go
|
||
|
||
# 构建
|
||
go build -o bin/gen2d cmd/main.go
|
||
|
||
# 运行全部测试
|
||
go test ./...
|
||
|
||
# 运行单个包的测试
|
||
go test ./internal/service/...
|
||
|
||
# 运行单个测试函数
|
||
go test -run TestFunctionName ./internal/service/
|
||
|
||
# 代码检查
|
||
golangci-lint run
|
||
```
|
||
|
||
### Frontend (Vite + React)
|
||
|
||
```bash
|
||
cd frontend
|
||
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 开发服务器
|
||
npm run dev
|
||
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 预览生产构建
|
||
npm run preview
|
||
|
||
# 类型检查
|
||
npm run typecheck
|
||
|
||
# Lint
|
||
npm run lint
|
||
|
||
# 运行测试
|
||
npm run test
|
||
|
||
# 运行单个测试文件
|
||
npm run test -- src/components/AssetCard.test.tsx
|
||
```
|
||
|
||
## Architecture
|
||
|
||
### 后端分层
|
||
|
||
- **Handler** — 解析 HTTP 请求，调用 service，返回响应。不包含业务逻辑。
|
||
- **Service** — 核心业务逻辑：提示词处理、AI 模型调用、素材后处理。
|
||
- **Model** — 请求/响应 DTO、数据库实体（如有）。
|
||
- **Pkg** — 通用工具：图片处理、颜色分析、sprite 切片等。
|
||
|
||
### 前端架构
|
||
|
||
- 使用 React + TypeScript，状态管理使用 zustand 或 React Context。
|
||
- API 调用集中在 `services/` 目录，组件不直接发请求。
|
||
- 素材预览和参数调整是核心交互，需要关注 Canvas/WebGL 渲染性能。
|
||
|
||
### 前后端通信
|
||
|
||
- RESTful API，JSON 格式。
|
||
- 前端开发时通过 Vite proxy 转发到后端 `localhost:PORT`。
|
||
- 图片素材通过 base64 或对象存储 URL 传输，大文件走 OSS/COS。
|
||
|
||
## 2D 游戏素材生成约束
|
||
|
||
### 素材类型
|
||
|
||
项目需要覆盖以下常见 2D 游戏素材类型：
|
||
|
||
- **Sprite / 角色** — 像素风、卡通、手绘风等，需支持多帧动画序列
|
||
- **Tilemap / 地形瓦片** — 可无缝拼接的地形纹理（草地、水域、道路等）
|
||
- **UI 元素** — 按钮、血条、对话框、图标等
|
||
- **背景 / 场景** — 横版卷轴背景、俯视视角场景
|
||
- **特效** — 火焰、烟雾、魔法等粒子效果帧
|
||
|
||
### 风格一致性
|
||
|
||
- 提供**风格种子 (Style Seed)** 机制：用户选定一套风格后，后续生成继承相同的色板、线条风格、分辨率。
|
||
- 支持**参考图上传**：以已有素材作为风格参考。
|
||
- 生成时返回**风格向量 / 特征参数**，可用于后续生成的风格锁定。
|
||
|
||
### 管线兼容性
|
||
|
||
生成的素材需满足主流游戏引擎的导入要求：
|
||
|
||
- **Sprite Sheet** — 输出标准的 spritesheet 拆分格式，附带 JSON/CSV 元数据（frame 位置、锚点、碰撞框）。
|
||
- **透明通道** — PNG 格式，带 alpha 通道，背景透明。
|
||
- **尺寸规范** — 支持常见尺寸（16×16, 32×32, 48×48, 64×64, 128×128, 256×256），可自定义。
|
||
- **命名规范** — 输出文件遵循 `{category}_{name}_{index}.png` 格式，便于引擎批量导入。
|
||
- **Unity / Godot 导出** — 可选生成 `.aseprite` 元数据或 Unity Sprite Editor 兼容的 `.meta` 信息。
|
||
|
||
### 生成效率与成本
|
||
|
||
- 支持**批量生成**：一次请求生成多个变体（如角色的行走 8 方向 × 4 帧）。
|
||
- 提供**低分辨率预览 → 高分辨率出图**的两阶段流程，减少无效生成。
|
||
- 后端应做**请求去重与缓存**：相同提示词 + 参数的结果缓存复用。
|
||
- AI 模型调用支持**异步队列**，前端轮询或 WebSocket 获取结果。
|
||
|
||
## Conventions
|
||
|
||
- 后端 Go 代码遵循 [Effective Go](https://go.dev/doc/effective_go) 和 Go 官方 style。
|
||
- 前端使用 ESLint + Prettier，提交前自动格式化。
|
||
- API 路径统一使用 `/api/v1/` 前缀。
|
||
- 错误响应统一格式：`{"code": int, "message": string, "data": any}`。
|
||
- Git commit message 使用中文或英文均可，但需要清晰描述变更内容。
|