# 游戏素材预览

**Repository Path**: defiphoenix/game-asset-preview

## Basic Information

- **Project Name**: 游戏素材预览
- **Description**: 用来预览游戏开发过程中ai生成的游戏素材
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AssetHub · 游戏素材库

AI 辅助游戏开发过程中的素材集中展示与检索工具。**零依赖**（只用 Node 内置模块）、**零构建**（无 npm install）、**素材原地引用**（不移动、不复制你的文件）。

```
node server.mjs          # 启动 → http://localhost:5678
```

## 它解决什么问题

用 AI 做游戏会在目录里堆出大量图片 / 序列图 / 音效 / 视频 / SVG 特效，散落各处无法集中查看；人和 AI 也都不知道"已经有什么"，导致重复生成。AssetHub 把这些素材做成：

- **给人**：画廊式网页 —— 缩略图网格、类型/目录/标签筛选、搜索、详情大图、序列图帧播放器、音频波形、变体对比、收藏与采用标记。
- **给 AI**：同一份机器可读清单（`/api/assets` 或 `.asset-hub/manifest.json` + `llms.txt`），AI 生成新素材前先查库存，打标签、标记采用均可通过 HTTP 或直接写文件完成。

## 快速开始

```bash
cd asset-hub
node server.mjs
# 打开 http://localhost:5678
```

首次运行会生成 `asset-hub.config.json`，默认指向自带的 `demo-assets/`（含程序生成的爆炸序列图、SVG 图标、合成音效，可直接删掉）。把它改成你的游戏素材目录即可：

```json
{
  "port": 5678,
  "title": "我的游戏素材库",
  "roots": ["../my-game/assets", "../my-game/audio"],
  "includeExts": [],      // 追加收录的扩展名，如 ["prefab","fire","tscn"]
  "excludeExts": [],      // 排除
  "ignoreDirs": ["node_modules", ".git", "dist", "build", "out", ".asset-hub", "tmp"],
  "maxDepth": 8
}
```

文件增删改会被自动监听，清单与页面实时刷新，无需重启。

## 支持的素材类型

| 类型 | 格式 | 额外能力 |
|---|---|---|
| 图片 | png jpg webp gif bmp | 尺寸解析、透明棋盘格、像素级缩放 |
| 序列图 | png + 同名 `.json` 图集（TexturePacker hash/array、Phaser） | 帧数/帧尺寸解析、帧播放器（FPS 可调、逐帧拖动） |
| 网格序列图 | 任意图片 | 在 sidecar 写 `"grid": [列, 行]` 即可按网格切帧播放 |
| SVG / 特效 | svg（含 SMIL/CSS 动画） | 动画预览、源码查看 |
| 音频 | mp3 wav | 时长解析（wav 精确、mp3 含 VBR）、波形图 |
| 视频 | mp4 webm mov | 时长解析（mp4）、悬停预览、Range 流式播放 |
| 文本/代码 | glsl frag vert particle fire json md 等 | 源码预览 |
| 字体 | ttf otf woff | 实时渲染预览 |

未列出的扩展名默认不收录，用 `includeExts` 追加；任何类型都会进清单，只是没有富预览。

## 与 AI 协作（核心玩法）

给 AI（ZCode / Claude Code / Cursor 等）这两入口：

- `http://localhost:5678/llms.txt` —— 字段说明与工作约定
- `.asset-hub/manifest.json` 或 `GET /api/assets` —— 完整清单

推荐写进 `AGENTS.md` 的约定：

1. 生成素材前先查清单：`group` 相同或 `tags` 命中说明已有同类素材，先复用。
2. 新素材存入根目录后自动入库（或让 AI `POST /api/meta` 打标签）。
3. 采用的素材标记 `status: "adopted"`，代码里只用已采用的。
4. AI 也可以直接写 sidecar 文件（与服务端写入等价）：
   `.asset-hub/meta/<root>/<相对路径>.json`
   ```json
   { "tags": ["fire"], "status": "adopted", "prompt": "pixel art explosion, 8 frames", "note": "..." }
   ```
   重扫描不会丢失这些标注。

页面深链：`#a=<素材id>` 直达某个素材，`#q=explosion&type=spritesheet` 直达某组筛选。

## 命令

```bash
node server.mjs                  # 启动服务（--port N / --root 路径 / --no-watch）
node server.mjs scan             # 只扫描，写 .asset-hub/manifest.json
node server.mjs export ./dist    # 导出静态站点（只读快照，可扔 GitHub Pages / 任意静态托管）
node demo/gen.mjs                # 重新生成示例素材（可删除整个 demo-assets）
```

## 设计原则

- **一份数据、两类读者**：网页 UI 和 AI 读同一份清单，不存在两套体系。
- **原地引用**：素材永远留在项目目录里，AssetHub 只读元数据。
- **sidecar 分离**：自动扫描信息与人工/AI 标注分开存放，重扫不丢数据。
- **变体折叠**：AI 反复迭代出的 `xxx_v2 / xxx final / xxx(1)` 自动归组，画廊默认只显示最新一个。

## 已知限制

- ogg / webm / flac 时长服务端不解析（页面加载后由浏览器显示）。
- Cocos `.plist`（XML）图集暂不解析帧数据，文件本身仍会收录展示。
- 大文件指纹用 `大小+mtime` 近似，极端情况下"重复"标记可能误报。