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)

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)

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 和 Go 官方 style。
前端使用 ESLint + Prettier，提交前自动格式化。
API 路径统一使用 /api/v1/ 前缀。
错误响应统一格式：{"code": int, "message": string, "data": any}。
Git commit message 使用中文或英文均可，但需要清晰描述变更内容。

5.1 KiB Raw Blame History Unescape Escape