学术喵关卡协作与素材提交指南

Copy First

先把这段话发给你的 AI agent

如果你不知道怎么开始，直接复制下面这段。它会先让 AI 学习项目页面，再验证官方角色 API 能不能在你的本地跑起来，最后再进入个人关卡设计。

https://efv.tju2025mem3.me/llms.txt
https://efv.tju2025mem3.me/contribution_guide.html
https://efv.tju2025mem3.me/gdd_scope_review.html
https://efv.tju2025mem3.me/index.html

是我们小组作业总体项目，你学习一下。然后我想先试一下官方角色能不能拉到我本地开始测试，然后我们再策划我的关卡怎么设计。

我的学号是 2540732。你来组织文件结构，目前先看看官方 API 成不成，让角色在我电脑上能做动作。

如果本地没有 Python，请你帮我安装 3.10/3.11 以及必要的环境；如果网络连接不好，请使用国内镜像。

当能看到官方角色在我本地跑起来时，我们开始讨论我的关卡设计。

给同学的提醒 学号要改成自己的学号。搜索引擎收录需要时间，不要依赖搜索；让 AI 优先读取 https://efv.tju2025mem3.me/llms.txt 和本页。临时 HTML 可以用于本地测试，但正式提交时只保留个人 JS、assets、data。

如果 AI 仍然打不开网页 这通常是 AI 平台自己的网络出站限制，不是项目页面失效。请打开或下载 ai_context.txt，把全文复制给 AI，再继续本地测试和关卡规划。若浏览器打开 txt 出现乱码，再使用 UTF-8 备用页：ai_context.html。

01 Collaboration Model

主项目保持稳定，同学内容以“关卡包”形式接入

当前最适合小组协作的方式，不是让每个人都改主程序，而是让每个人提交一个边界清楚的内容包。内容包可以很小：一个怪物、一个 NPC、一个地图角落、一组 props、一个触发事件，或者这些内容的组合。

1

一个来源

每位同学只在自己的学号文件夹里工作。最终合并时可以一眼看出内容来自谁。

3

三个必需项

一个独立 JS、一个 assets/、一个 data/。不要直接覆盖 app.js 或公共素材。

API

统一入口

官方主角、动作规格、风格提示和内容注册都从 official-api.js 读取。

ID

独立命名

所有怪物、NPC、事件、点位、素材 key 都用 s学号_ 前缀，减少合并冲突。

本阶段不需要后台服务 当前协作重点是“可合并的静态内容包”。官方主角、素材规格、风格提示和内容注册都通过前端 JS 提供。以后如果要做在线上传、账号、存档、排行榜或多人同步，再新增后端 API。

Markdown 版本 如果要把规范发给 AI agent，建议直接使用 contribution_guide.md。Markdown 版本更详细，网页版本更适合查看美术参考图。

02 Tech Stack

先让 AI 了解项目技术栈和提交边界

这个项目目前是静态前端游戏测试页。你可以让 AI 写 JS、JSON、Markdown 和素材清单；不要让 AI 引入新框架、改主程序结构或提交临时测试 HTML。

当前技术栈

页面：HTML、CSS、原生 JavaScript。
游戏运行：Phaser，文件在 vendor/phaser.min.js。
主程序：app.js，同学不要直接覆盖。
官方协作 API：official-api.js。

资源和数据

图片素材放在个人包的 assets/。
触发点、对话、碰撞、传送点放在个人包的 data/。
地图和主角参考可以读取公共 assets/，但不要覆盖公共文件。

本地验证方式

可以临时写一个 local-preview.html 自测。
可以用本地静态服务打开页面测试资源路径。
提交时不要提交 HTML 测试页，只提交 JS、assets、data。

03 Package Contract

每个人用自己的学号命名一个文件夹

请统一放在 contrib/ 下面。文件夹内只保留三类正式交付：一个 JS 入口、一个素材目录、一个数据目录。你可以在本地写 HTML 测试页帮助自己预览，但提交前要删掉 HTML。

contrib/2025000000/ 2025000000-level.js assets/ sprites/ portraits/ tilesets/ props/ enemies/ npc/ data/ manifest.json points.json triggers.json dialogue.json collisions.json test_report.md

JS 入口写什么

只做注册，不改主程序。把自己的内容包挂到 window.EFVContrib.register(...)，以后主程序或测试页就能读取。

2025000000-level.js

assets 放什么

精灵图、头像、瓦片、props、怪物图、NPC 图、预览图。路径必须写进 manifest.json，不要只把图丢进去。

spritespropstilesets

data 放什么

触发器、出生点、对话、碰撞建议、传送点、奖励草案、测试记录。能被程序读取的用 JSON，说明类用 Markdown。

triggerspointsdialogue

HTML 只用于自测

可以临时建 local-preview.html 验证你的 JS 和素材路径。最终交付时不要提交 HTML，避免每个人的页面结构互相冲突。

local onlydo not submit

提交前保留这三项 2025000000-level.js、assets/、data/。如果你让 AI 生成了临时 HTML、临时截图、临时调试脚本，请在 test_report.md 里记录测试结果，但不要把临时文件一起提交。

命名对象	推荐格式	例子
内容包 ID	`s学号_英文短名`	`s2025000000_leaf_courtyard`
怪物 / NPC / 物件 ID	`s学号_类型_名字`	`s2025000000_monster_book_mite`
事件 / 触发点 ID	`s学号_event_名字`	`s2025000000_event_library_gate`
素材文件名	英文小写、数字、连字符	`book-mite-sprites-v1.png`

04 Data Schema

数据要能读、能测、能合并

所有数据都先用草案级 JSON，不要求一次做成完整系统。关键是把“它是什么、资源在哪里、想出现在什么位置、触发什么事件”讲清楚。

manifest.json 最小模板

{
  "studentId": "2025000000",
  "id": "s2025000000_leaf_courtyard",
  "title": "叶影庭院小关卡",
  "type": "level-pack",
  "zone": "zhonghe-plaza",
  "entry": "2025000000-level.js",
  "assets": {
    "monsters": ["assets/enemies/book-mite-sprites-v1.png"],
    "npcs": ["assets/npc/archive-senior-portrait-v1.png"],
    "props": ["assets/props/notice-board-v1.png"],
    "tilesets": []
  },
  "data": {
    "points": "data/points.json",
    "triggers": "data/triggers.json",
    "dialogue": "data/dialogue.json"
  }
}

points.json 与 triggers.json

{
  "spawnPoints": [
    {
      "id": "s2025000000_spawn_main",
      "x": 4800,
      "y": 3600,
      "facing": "S",
      "note": "玩家进入庭院后的测试点"
    }
  ],
  "triggers": [
    {
      "id": "s2025000000_event_first_note",
      "type": "dialogue",
      "x": 4920,
      "y": 3520,
      "radius": 96,
      "target": "s2025000000_dialogue_note_01"
    }
  ]
}

坐标怎么定 目前衷和广场测试地图是大图坐标，主角出生点在地图中央附近。你可以先用近似坐标描述点位，并在 test_report.md 里写“需要技术组合并时微调坐标”。不要因为坐标不完美就不提交。

05 Official API

需要官方主角时，统一读取 `official-api.js`

不要复制莉娜素材路径，也不要自己猜动作行。让 AI 先读取 official-api.js，再用下面这些方法拿主角、武器、风格提示和内容包注册入口。

1. 读主角资料

const lina = window.EFVOfficial.getMainCharacter();
console.log(lina.assets.sprite);
console.log(lina.actions);

2. 注册内容包

window.EFVContrib.register({
  studentId: "2025000000",
  id: "s2025000000_leaf_courtyard",
  title: "叶影庭院小关卡",
  type: "level-pack",
  entry: "2025000000-level.js"
});

3. Phaser 中生成莉娜

preload() {
  EFVOfficial.preloadPhaserAssets(this);
}

create() {
  const lina = EFVOfficial.createLina(this, 480, 320, {
    scale: 1,
    action: "idle"
  });
}

本地 HTML 自测时这样引用

如果你的临时测试页放在 contrib/2025000000/local-preview.html，可以这样引用公共库和自己的 JS。提交前删除这个 HTML。

<script src="../../vendor/phaser.min.js"></script>
<script src="../../official-api.js"></script>
<script src="2025000000-level.js"></script>

让 AI 先检查 API

把这句话发给你的 AI：先读取 official-api.js，列出 EFVOfficial 和 EFVContrib 能提供什么，再决定我的关卡包需要调用哪些方法。

请先不要写代码。
请读取 official-api.js，
解释 EFVOfficial 和 EFVContrib 的用途，
然后给我一份适合我学号文件夹的接入步骤。

API	用途
`EFVOfficial.getMainCharacter()`	读取莉娜资料、头像、精灵表路径、动作规格。
`EFVOfficial.getWeapons()`	读取三把官方法杖、攻击精灵表、飞弹帧和冷却参数。
`EFVOfficial.getStylePrompt()`	给 AI agent 或图像生成工具使用的官方风格提示词。
`EFVContrib.register(pack)`	同学把自己的内容包注册到统一列表，后续测试页可以读取。

不要把前端 API 理解成后台接口 official-api.js 是静态前端文件，作用是统一读取主角和注册内容包；它不负责上传、登录、数据库或云存档。

06 Visual Reference

制作素材前，把这些参考图交给你的 AI

请让 AI 先观察官方角色、精灵表、地图、props 和怪物参考，再生成新素材。目标不是复制某一张图，而是保持同一套“同济校园 + 樱花季 + 学术幻想 + 轻量 JRPG”的视觉语言。

衷和广场游戏视角 — **游戏实际视角**让 AI 理解素材最终会出现在俯视 2D 场景里，要服务行走、碰撞、互动点和镜头跟随。

莉娜官方精灵表 — **官方主角规格**莉娜使用 8 列 × 8 行、每格 147 × 147 的完整精灵表。这是官方主角参考，不是所有投稿素材的硬性要求。

莉娜官方头像 — **角色气质**柔和粉紫、白色长发、学术幻想气质。NPC 和头像可以参考这种清爽、明亮、偏校园幻想的表达。

莉娜飞弹图集 — **技能反馈**紫晶、樱花、星光三类飞弹。技能、掉落、机关反馈可以参考这种明亮、轻量、边缘清楚的效果。

衷和广场地面风格参考 — **地图材质**俯视 2D、清爽校园、石砖、绿化、水体。地图素材要能切片，不要复杂透视。

衷和广场地面材质图集 — **瓦片图集**地砖、草地、边界和过渡块要可重复拼接。让 AI 输出时说明每块素材适合放在哪里。

衷和广场 props 图集 — **Props 图集**灯、花坛、树、长椅、路牌等物件要能独立摆放，并在 data 里写碰撞建议。

叶团怪物头像 — **怪物方向**可爱但有玩法辨识度，轮廓清楚，攻击方式、出现区域和掉落物要写进 data。

叶团怪物精灵表 — **怪物精灵**怪物、NPC、技能特效不强制 8 帧。根据 AI 稳定性和设计对象特点选择帧数，但要写清每个动作对应哪几帧。

低门槛帧数

适合大多数同学和普通图像 agent：待机 2-4 帧，移动 2-4 帧，攻击或触发 3-4 帧。先保证稳定、干净、能读懂。

中等帧数

适合主要角色、重要 NPC 或小怪：每个动作 4-6 帧。可以表现更多动作细节，但要避免角色体型和五官每帧漂移。

完整帧数

只有在模型稳定、参考充足、确实需要时再做 8 帧或更多。不要为了追求帧数牺牲一致性。

提交时必须说明帧数 不论是 2 帧、4 帧、6 帧还是 8 帧，都要在 manifest.json 或素材说明里写清楚：每格尺寸、行列数、动作名称、每个动作使用的帧序号、是否循环、推荐播放速度。

可以直接发给 AI 的参考素材路径

assets/portraits/lina.png：角色头像气质。
assets/sprites/lina-sprites-v10-anchored-expanded.png：官方主角精灵表规格。
assets/effects/lina-projectiles-atlas-v1.png：法术效果和色彩反馈。
assets/maps/playable/previews/zhonghe-plaza-tilemap-playtest-v1-game-view.png：游戏实际视角。
assets/maps/playable/previews/zhonghe-plaza-ground-material-atlas-imagegen-v1.png：地图瓦片材质。
assets/maps/props/zhonghe-plaza-props-atlas-v1.png：props 形状和摆放风格。
assets/enemies/leaf-poring-portrait-v2.png、assets/enemies/leaf-poring-sprites-v2.png：怪物头像和动作参考。

发给 AI 的正向风格词

同济校园、樱花季、学术幻想、轻量 JRPG、清晰线稿、柔和高明度色彩、透明背景精灵、俯视 2D 瓦片地图、边缘干净、适合切片。

请 AI 避免这些方向

不要使用真实校徽、商业商标、照片质感、厚重暗黑风、文字糊成一团的贴图、难以切片的复杂透视、带水印素材。

07 AI Workflow

和 AI 对话时，按“读规范、出方案、生成包”三步走

如果你不熟悉代码，不要直接让 AI “帮我接入游戏”。先让它读本页、读 official-api.js、解释规则，再让它帮你生成文件清单和内容。这样不容易改坏主项目。

第 1 步：让 AI 读项目规则

目标是让 AI 先知道技术栈、文件边界、素材风格和官方 API。

read first

第 2 步：让 AI 先出方案

先确认要做怪物、NPC、props、地图角落还是触发事件，再列文件清单。

plan first

第 3 步：生成并自检

最后生成 JS、JSON、Markdown 和素材说明；本地可以用 HTML 预览，但不要提交 HTML。

check before submit

提示词 1：让 AI 先读规范

你正在为《学术喵的奇幻之旅：樱花同济篇》制作一个同学关卡内容包。
请先读取 contribution_guide.html 和 official-api.js。
我的学号是【2025000000】。
请先不要写代码。
请用简短清单告诉我：
1. 本项目技术栈是什么；
2. 我能提交哪些文件；
3. 哪些文件不能改；
4. 官方 API 能提供什么；
5. 美术风格要参考哪些素材。

提示词 2：让 AI 规划内容包

请帮我规划 contrib/2025000000/ 内容包。
我想做【怪物/NPC/地图角落/props/触发事件】。
正式提交只能包含：
1. 2025000000-level.js
2. assets/
3. data/

请先输出 manifest.json、points.json、triggers.json、素材清单、测试清单。
不要修改 app.js，不要覆盖公共 assets，不要提交 HTML。

提示词 3：生成美术素材说明

请根据 EFVOfficial.getStylePrompt() 和下面参考素材，
帮我写一份给图像生成模型使用的素材提示词。
目标风格：同济校园、樱花季、学术幻想、轻量 JRPG。
要求：角色和怪物透明背景；地图素材适合俯视 2D 瓦片；
props 要能独立摆放；每张图都要说明用途和推荐文件名。
怪物、NPC、技能特效不强制 8 帧，请根据稳定性选择 1、2-4、4-6 或 8 帧。

请参考：
assets/portraits/lina.png
assets/sprites/lina-sprites-v10-anchored-expanded.png
assets/maps/props/zhonghe-plaza-props-atlas-v1.png
assets/enemies/leaf-poring-portrait-v2.png
assets/maps/playable/previews/zhonghe-plaza-tilemap-playtest-v1-game-view.png

提示词 4：让 AI 帮你自检

请检查我的 contrib/2025000000/ 内容包是否符合规范。
重点检查：
1. 是否只提交 JS、assets、data；
2. ID 是否全部使用 s2025000000_ 前缀；
3. manifest.json 是否列出所有素材路径；
4. 是否错误修改 app.js 或公共 assets；
5. test_report.md 是否说明本地测试结果。

不同水平的同学都可以参与 不会写代码也可以提交素材、对话、点位和测试记录；会写代码的同学可以补 JS 注册和本地验证。关键不是一次做完整功能，而是把内容整理成统一结构。

08 Merge Checklist

交给主线前，先按这张清单自查

结构检查

文件夹名是自己的学号。
只有一个独立 JS 入口，不直接修改 app.js。
assets/ 和 data/ 路径都写进 manifest.json。
没有提交临时 HTML 测试页。

素材检查

PNG/WebP 能打开，没有水印和无关文字。
角色、怪物、props 边缘干净，透明背景优先。
精灵表写清每格尺寸、行列数、动作顺序、帧数和帧序号。

数据检查

所有 ID 使用 s学号_ 前缀。
触发点、出生点、传送点有坐标和说明。
对话、奖励、碰撞建议能独立阅读。

最后合并方式 测试通过后，主线只需要接入这个学号文件夹，读取 manifest.json 和注册后的 EFVContrib 内容包。这样即使某个内容包暂时不合格，也可以只暂停那个包，不影响其他同学和主程序。

先把这段话发给你的 AI agent

主项目保持稳定，同学内容以“关卡包”形式接入

一个来源

三个必需项

统一入口

独立命名

先让 AI 了解项目技术栈和提交边界

当前技术栈

资源和数据

本地验证方式

每个人用自己的学号命名一个文件夹

JS 入口写什么

assets 放什么

data 放什么

HTML 只用于自测

数据要能读、能测、能合并

manifest.json 最小模板

points.json 与 triggers.json

需要官方主角时，统一读取 official-api.js

1. 读主角资料

2. 注册内容包

3. Phaser 中生成莉娜

本地 HTML 自测时这样引用

让 AI 先检查 API

制作素材前，把这些参考图交给你的 AI

低门槛帧数

中等帧数

完整帧数

发给 AI 的正向风格词

请 AI 避免这些方向

和 AI 对话时，按“读规范、出方案、生成包”三步走

第 1 步：让 AI 读项目规则

第 2 步：让 AI 先出方案

第 3 步：生成并自检

提示词 1：让 AI 先读规范

提示词 2：让 AI 规划内容包

提示词 3：生成美术素材说明

提示词 4：让 AI 帮你自检

交给主线前，先按这张清单自查

结构检查

素材检查

数据检查

需要官方主角时，统一读取 `official-api.js`