下载 App

开发者docs文档模板分享

03/25339 浏览开发交流
包含7类常见开发文档模板,可供开发者/ai参考。
(可直接喂给嗒啦啦)
TapTap
文档模板库
> **用途**:为项目中不同类型的文档提供标准结构模板。新建文档时复制对应模板,填充内容。
> **设计哲学**:本项目的文档遵循"决策导向"写作风格——每个章节回答一个决策问题,而非描述一个概念。读者读完应该知道"该怎么做",而非"这是什么"。
---
导览目录
- [写作原则](#写作原则) — 所有文档类型的通用写作规范
- [模板 1: 大纲](#模板-1-大纲) — 系统/功能的设计方向文档
- [模板 2: 待办](#模板-2-待办) — 开发进度追踪文档
- [模板 3: 规范](#模板-3-规范) — 编码/设计的约束性规则文档
- [模板 4: 系统(技术实现指南)](#模板-4-系统技术实现指南) — 指导 AI 实现某个系统的技术文档
- [模板 5: 陷阱记录](#模板-5-陷阱记录) — bug 教训与踩坑记录
- [模板 6: 参考表](#模板-6-参考表) — 术语表、字段表等查阅型文档
- [附录: 文档类型选择指南](#附录-文档类型选择指南) — 不确定该写哪种文档时看这里
---
写作原则
### 原则 1: 决策导向,不要描述导向
```
❌ 描述导向(回答"是什么"):
  "存档系统是一个用于保存和加载游戏进度的模块,它将玩家的状态数据序列化后
   存储到持久化存储中,并在游戏启动时反序列化恢复状态。"
✅ 决策导向(回答"怎么做"和"为什么"):
  "使用 clientCloud 云变量存储,不用本地 File API。
   原因:WASM 平台本地文件在刷新/清缓存后丢失,这是决定性因素。"
```
### 原则 2: 信息密度优先
- 一句话能说清的不用一段话
- 表格优于段落(便于扫描)
- 决策表优于 if-else 文字(便于查找)
- 删掉"众所周知"、"一般来说"、"需要注意的是"等填充词
### 原则 3: 对比优于单边论述
给出方案时,同时展示被否决的方案和理由:
```markdown
| 因素 | 方案 A | 方案 B(采用) |
|------|--------|--------------|
| 优点 | ...    | ...          |
| 缺点 | ...    | ...          |
| 结论 | 不采用,因为 X | ✅ 采用 |
```
### 原则 4: 用 ✅/❌ 标注对错
对于容易踩坑的写法,始终提供正反对比:
```lua
-- ❌ 错误
local x = eventData["X"]  -- 缺少类型转换
-- ✅ 正确
local x = eventData["X"]:GetInt()
```
### 原则 5: 标注权威范围
每个文档头部声明:
- **用途**:一句话说明文档目的
- **权威范围**:哪些主题以本文档为准
- **配套文档**:相关文档链接
- **依赖/被依赖**(系统类文档):声明上下游关系
### 原则 6: 标注待定项
未确定的内容用 `[待定]` 标记,不要编造或留空:
```markdown
- 弩箭上限:[待定,数值平衡后填入]
- 背包容量:无限制(已确定)
```
---
模板 1: 大纲
**用途**:为一个系统/功能确定设计方向。回答"做什么"和"为什么这样做",不涉及技术实现细节。
**典型文件名**:`大纲/XXX大纲.md`
**代表作**:`大纲/背包系统大纲.md`
---
````markdown
# [系统名称]大纲
> **用途**:指导新对话理解[系统名称]的设计决策与实现方向。
> **权威范围**:[列举本文档管辖的主题]。[系统名称]相关设计的唯一权威;当与其他文档冲突时,以本文档为准。
> 配套文档:[游戏大纲](游戏大纲.md) | [玩法大纲](玩法大纲.md) | [相关文档]
>
> **依赖**:[本系统依赖哪些系统,各依赖什么]
> **被依赖**:[哪些系统依赖本系统,各依赖什么]
> **详见**:[跨系统依赖表](../系统/跨系统依赖表.md#N-系统名)
---
## 导览目录
- [1. 系统定义与边界](#1-系统定义与边界) — 做什么、不做什么
- [2. 核心设计决策](#2-核心设计决策) — 关键选择及理由
- [3. 分类/模型](#3-分类模型) — 核心概念的分类体系
- [4. 交互方式](#4-交互方式) — 玩家如何与系统互动
- [5. 与其他系统的衔接](#5-与其他系统的衔接) — 跨系统接口约定
- [6. 未确定事项](#6-未确定事项) — 待讨论的设计问题
---
## 1. 系统定义与边界
### 1.1 功能链
[系统名称]的完整功能链:**[动作1] → [动作2] → ... → [动作N]**。
### 1.2 系统边界
[系统名称]**不包含**以下内容(它们是独立系统):
| 独立系统 | 说明 | 与本系统的关系 |
|---------|------|--------------|
| [系统A] | [一句话说明] | [如何交互] |
---
## 2. 核心设计决策
<!-- 每个决策单独一个小节,说明"选了什么"和"为什么不选另一个" -->
### 2.1 [决策主题]
**选择**:[方案名称]
| 因素 | 方案 A | 方案 B(采用) |
|------|--------|--------------|
| [比较维度1] | ... | ... |
| [比较维度2] | ... | ... |
**采用理由**:[一句话说明决定性因素]
---
## 3. 分类/模型
<!-- 将核心概念分类,用表格呈现 -->
| 分类 | 特征 | 典型实例 | 规则 |
|------|------|---------|------|
| [类型A] | [特征描述] | [具体例子] | [处理规则] |
| [类型B] | [特征描述] | [具体例子] | [处理规则] |
---
## 4. 交互方式
<!-- 玩家视角的操作流程 -->
---
## 5. 与其他系统的衔接
<!-- 明确接口:本系统向外暴露什么、从外部获取什么 -->
| 方向 | 系统 | 接口 | 说明 |
|------|------|------|------|
| 本系统 → | [系统A] | [函数/数据] | [什么时候调用] |
| → 本系统 | [系统B] | [函数/数据] | [什么时候被调用] |
---
## 6. 未确定事项
<!-- 用 checkbox 列出待讨论的设计问题 -->
- [ ] [问题1]:[简述问题,列出可能的方案]
- [ ] [问题2]:[简述问题]
---
## 变更日志
| 日期 | 变更内容 |
|------|---------|
| YYYY-MM-DD | 初版 |
---
*创建日期:YYYY-MM-DD*
````
---
模板 2: 待办
**用途**:追踪某个领域的开发进度。回答"做了什么"、"还差什么"、"接下来做什么"。
**典型文件名**:`待办/XXX待办.md`
**代表作**:`待办/玩法待办.md`
---
````markdown
# [领域名称]待办
> **用途**:追踪[领域名称]的开发完成度、待规划问题和推进方向,供后续对话核实进度。
> **定位**:进度追踪文档,不是设计权威。记录各系统的规划状态和待讨论要点,具体设计内容以对应的专项文档为准。
> 配套文档:[相关大纲] | [相关规范]
>
> **更新规则**:每次[领域名称]相关的讨论或开发后同步更新本文档,将已完成项从"待完成"移至"已完成",更新完成度百分比。
---
## 导览目录
- [1. 各模块完成度总览](#1-各模块完成度总览)
- [2. 待完成模块(按优先级)](#2-待完成模块按优先级)
- [3. 已完成模块](#3-已完成模块)
- [4. 推进方向建议](#4-推进方向建议)
---
## 1. 各模块完成度总览
| 模块 | 完成度 | 状态 | 说明 |
|------|-------|------|------|
| **[模块A]** | 100% | ✅ 完成 | [一句话总结] |
| **[模块B]** | 60% | 🔧 进行中 | [已完成什么、还差什么] |
| **[模块C]** | 15% | 📐 设计完成 | [设计方案见XX文档,代码未写] |
| **[模块D]** | 0% | ⬜ 未开始 | [简要说明] |
**状态图例**:
- ✅ 完成:代码已写、已测试、可运行
- 🔧 进行中:部分代码已写
- 📐 设计完成:设计方案已确定,代码未写
- ⬜ 未开始:设计和代码都未开始
---
## 2. 待完成模块(按优先级)
### P0 — [优先级描述,如"基础设施/后续所有模块的前置依赖"]
#### 2.1 [模块名称]
- **角色**:[一句话说明为什么重要]
- **依赖**:[前置依赖,或"无硬前置依赖"]
- **被依赖**:[哪些模块在等这个]
- **设计状态**:✅ 设计完成 / ⬜ 未设计,详见 [相关文档]
- **已解决的设计决策**:
  - [x] [决策1] → [结论]
  - [x] [决策2] → [结论]
- **待实现任务**:
  - [ ] [具体任务1]
  - [ ] [具体任务2]
### P1 — [优先级描述]
#### 2.2 [模块名称]
<!-- 同上结构 -->
---
## 3. 已完成模块
### [模块名称](YYYY-MM-DD 完成)
- **实现内容**:[简要说明做了什么]
- **代码位置**:`scripts/[路径]`
- **已知限制**:[如果有的话]
---
## 4. 推进方向建议
<!-- 下一步应该做什么、为什么这样排序 -->
**建议顺序**:[模块A] → [模块B] → [模块C]
**理由**:[为什么按这个顺序]
---
*创建日期:YYYY-MM-DD*
*最后更新:YYYY-MM-DD*
````
---
模板 3: 规范
**用途**:为某个领域制定约束性规则。回答"必须怎么做"和"为什么必须这样"。
**典型文件名**:`规范/XXX规范.md`
**代表作**:`规范/代码书写规范.md`、`规范/存档设计规范.md`
**子类型**:
- **编码规范**(如代码书写规范):规则密集、条目式、每条带优先级
- **方案规范**(如存档设计规范):方案选型 + 详细机制 + 防御措施
---
````markdown
# [领域名称]规范
> **用途**:[一句话说明本规范约束什么行为]。
> **权威范围**:[列举管辖主题]。[主题]的唯一权威;当与其他文档冲突时,以[优先级说明]。
> 配套文档:[相关文档链接]
>
> **依赖**:[如果有的话]
> **被依赖**:[如果有的话]
---
## 导览目录
<!-- 各节按重要性排列,标注优先级 -->
- [1. [主题A](P0)](#1-主题ap0) — [一句话简介]
- [2. [主题B](P1)](#2-主题bp1) — [一句话简介]
- [N. 配套文件清单](#n-配套文件清单)
---
## 文档编写规则
<!-- 可选章节。用于规定本文档自身的更新规则 -->
### 写入规则
1. [规则1]
2. [规则2]
### 当前状态
**已完成**:
- [已完成的章节]
**待补充(随开发进度)**:
- [待补充的内容]
---
## 1. [主题A](P0)
<!-- P0 = 最高优先级,违反会导致严重后果 -->
### 1.1 [规则名称]
[规则描述]
```lua
-- ❌ 错误
[错误示例]
-- ✅ 正确
[正确示例]
```
**为什么**:[一句话说明理由]
### 1.2 [规则名称]
| 场景 | 做法 | 说明 |
|------|------|------|
| [场景1] | [做法] | [补充说明] |
| [场景2] | [做法] | [补充说明] |
---
## 2. [主题B](P1)
<!-- P1 = 重要但非致命,违反会增加维护成本 -->
---
## N. 配套文件清单
| 文件 | 状态 | 说明 |
|------|------|------|
| [文件名] | 已编写 / 待编写 | [一句话说明] |
---
## 变更日志
| 日期 | 变更内容 |
|------|---------|
| YYYY-MM-DD | 初版 |
---
*创建日期:YYYY-MM-DD*
````
---
模板 4: 系统(技术实现指南)
**用途**:指导 AI(新对话)将某个系统集成到游戏中。回答"代码怎么写"和"集成时注意什么"。
**典型文件名**:`系统/XXX系统.md`
**代表作**:`系统/背包系统.md`、`系统/呼吸系统.md`
**与大纲的区别**:大纲说"做什么",系统文档说"怎么做"。大纲面向决策者,系统文档面向实现者。
---
````markdown
# [系统名称] - 技术实现指南
> 为《游戏》提供[功能描述]。
> 本文档用于指导新对话将[系统名称]集成到游戏中。
>
> **依赖**:[系统A]([依赖什么])、[系统B]([依赖什么])
> **被依赖**:[系统C]([提供什么])
> **详见**:[跨系统依赖表](跨系统依赖表.md#N-系统名)
---
## 目录
1. [系统概述](#1-系统概述)
2. [核心架构](#2-核心架构)
3. [数据定义](#3-数据定义)
4. [核心逻辑](#4-核心逻辑)
5. [集成步骤](#5-集成步骤)
6. [常见问题与陷阱](#6-常见问题与陷阱)
---
## 1. 系统概述
<!-- 一段话说明系统做什么,包含哪些功能块 -->
| 功能块 | 职责 | 说明 |
|--------|------|------|
| [功能A] | [做什么] | [补充] |
| [功能B] | [做什么] | [补充] |
---
## 2. 核心架构
### 2.1 模块划分
```
scripts/
  [SystemName]/
    [ModuleA].lua    -- [职责]
    [ModuleB].lua    -- [职责]
```
### 2.2 数据流
```
[触发源] → [模块A] → [模块B] → [输出/效果]
```
---
## 3. 数据定义
### 3.1 [数据结构名称]
```lua
local data = {
    field1 = "",     -- [类型] [说明]
    field2 = 0,      -- [类型] [说明]
    field3 = {},     -- [类型] [说明]
}
```
### 3.2 [配置/常量]
| 常量 | 值 | 说明 |
|------|-----|------|
| `CONSTANT_A` | `5.0` | [含义] |
---
## 4. 核心逻辑
### 4.1 [逻辑主题A]
<!-- 用伪代码或关键代码片段说明算法/流程 -->
```lua
-- 关键逻辑
function SystemName.update(dt)
    -- [步骤说明]
end
```
### 4.2 [逻辑主题B]
---
## 5. 集成步骤
### 5.1 GameState 字段
<!-- 需要在 GameState 中添加的字段 -->
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `fieldName` | `number` | `0` | [说明] |
### 5.2 初始化
```lua
-- 在 main.lua 的 enterGame() 中:
local SystemName = require("scripts/[Path]/[Module]")
SystemName.init(scene_, gameState_)
```
### 5.3 每帧更新
```lua
-- 在 HandleUpdate 中:
SystemName.update(dt)
```
### 5.4 存档衔接
```lua
-- 存档写入时:
saveData.systemField = SystemName.getState()
-- 存档读取后:
SystemName.restoreState(saveData.systemField)
```
---
##  6. 常见问题与陷阱
<!-- 引用 bug.md 中的相关陷阱,或记录本系统特有的坑 -->
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| [现象] | [原因] | [做法] |
详见:[bug.md 陷阱 N](../检查/bug.md#陷阱-n-标题)
---
*创建日期:YYYY-MM-DD*
````
---
模板 5: 陷阱记录
**用途**:记录开发中遇到的 bug 教训,避免重复踩坑。每条陷阱是一个独立的"经验胶囊"。
**典型文件名**:`检查/bug.md`(全项目共用一份)
**代表作**:`检查/bug.md`
**单条陷阱模板**:
---
````markdown
### 陷阱 N: [简短标题]
**现象**:[描述出现的错误行为或异常表现,越具体越好]
**原因**:[为什么会出现这个问题,根因分析]
**错误写法**:
```lua
-- 导致问题的代码
```
**正确写法**:
```lua
-- 修复后的代码
```
**规则**:[一句话总结,方便快速扫描]
````
**编写要点**:
| 字段 | 要求 |
|------|------|
| 标题 | 动词短语或名词短语,一眼看出问题类型 |
| 现象 | 描述玩家/开发者能观察到的外在表现,不是代码分析 |
| 原因 | 必须追到根因,不能停留在"改了就好了" |
| 错误写法 | 可运行的代码片段,标注 ❌ |
| 正确写法 | 可运行的代码片段,标注 ✅ |
| 规则 | 一句话,能贴在显示器上当便签的那种 |
---
模板 6: 参考表
**用途**:集中存放需要频繁查阅的结构化数据。纯查询导向,不需要叙述。
**典型文件名**:`公共/XXX表.md`
**代表作**:`公共/术语表.md`、`公共/GameState字段表.md`
---
````markdown
# [领域名称]表
> **用途**:[一句话说明查阅场景]。
> **更新规则**:[何时更新,谁负责更新]。
> 配套文档:[相关文档]
---
## 格式说明
| 字段 | 含义 | 示例 |
|------|------|------|
| [字段1] | [含义] | [示例] |
| [字段2] | [含义] | [示例] |
---
## [分类A]
| [字段1] | [字段2] | [字段3] | [字段4] |
|---------|---------|---------|---------|
| ... | ... | ... | ... |
---
## [分类B]
| [字段1] | [字段2] | [字段3] | [字段4] |
|---------|---------|---------|---------|
| ... | ... | ... | ... |
---
*创建日期:YYYY-MM-DD*
*最后更新:YYYY-MM-DD*
````
---
附录: 文档类型选择指南
不确定该写哪种文档时,用这张决策表:
| 你要回答的问题 | 文档类型 | 存放目录 |
|--------------|---------|---------|
| 这个功能**做什么**、为什么这样设计? | 大纲 | `大纲/` |
| 这个功能**怎么做**、代码怎么写? | 系统(技术实现指南) | `系统/` |
| 写代码时**必须遵守**什么规则? | 规范 | `规范/` |
| 开发**做到哪了**、还差什么? | 待办 | `待办/` |
| 遇到了 bug,怎么**避免再犯**? | 陷阱记录 | `检查/bug.md` |
| 某个术语/字段的**定义是什么**? | 参考表 | `公共/` |
**文档之间的典型关系**:
```
大纲(设计方向)
  ↓ 设计确定后
系统(技术实现指南)
  ↓ 开发过程中
待办(追踪进度)
  ↓ 踩坑时
陷阱记录(避免再犯)
规范(跨系统的约束规则,与上述流程并行)
参考表(随时查阅的结构化数据)
```
猜你想搜
taptap 制造开发文档模板
03:06
为了不被斩杀,我只能做到这些了截图
为了不被斩杀,我只能做到这些了
之前一直申请不到计划3,之前说太花哨,后面说体量完成度不足,在我一番小作文下,编辑终于给了我解答,什么原生质感,玩家开局体验啥的。 本来计划2也够用,准备以后再优化了,结果计划2赠送的积分要砍半了,学生党实在消费不起,于是只能再冲一波计划3了 从周六中午到现在一天半时间,优化了一遍角色卡,战斗卡,还有抽卡界面,优化了新手教程,该说不说确实比之前要舒服些。 前半部分为新版,后半部分为旧版。 明天再次
44 赞
9 回复
【新游上线】末日100天截图
【新游上线】末日100天
大家好,我们是《末日100天》的开发者Paul~ 这是一款围绕「生存-经营-轮回」展开的废土策略小游戏:白天分配 3 点行动力经营据点,夜里迎接十天一循环的尸潮,每张地图第 100 天还有一场首领战等着你。五张地图、五大区域机制、可继承的轮回遗产,以及钻石商城里的抽奖机——我们希望每次重开都有一点点新意。 以下是游戏简单介绍: 1.游戏背景 废土历元年,未知病毒席卷全球,城市化为死地。幸存者们退守
9 赞
6 回复
别再烧积分了!从每次 2000 到每次 50 的血泪经验截图
别再烧积分了!从每次 2000 到每次 50 的血泪经验
适用场景:所有在用 TapTap Code 开发游戏的小白 难度:★☆☆☆☆ 背景最近群里总有人"炫耀"一次操作花了几千积分,说实话这不是值得高兴的事——这是在告诉所有人你的开发方式有根本性问题。我也走过这条弯路,所以来说说怎么改。 积分消耗的本质是什么积分 = AI 处理的 token 数量 = 你发给 AI 的内容 + AI 回给你的内容所以烧积分的本质只有两种: 你让 AI 做了大量无效/重
精华
69 赞
21 回复
如何提升你游戏中的UI美术水平截图
如何提升你游戏中的UI美术水平
一、请为你的游戏挑选一款合适的字体 很多开发者没有注意到其实UI界面中最重要的元素是字体,一款合适的字体能给整个游戏的界面感官带来蜕变。 请看案例 那么如何挑选适合自己的字体呢? 我总结出了一些小经验可供参考: 黑体:通用 宋体:古风、武侠、修仙 楷体:古风、武侠、修仙 圆体:卡通、动漫、Q版 科技:科幻、未来、电子 顺手分享一个免费可商用字体网站: 当然 如果你不知道自己的游戏适合什么风格
精华
124 赞
44 回复
【开发日记】从深蓝到羊皮纸:UI预览大改造截图
【开发日记】从深蓝到羊皮纸:UI预览大改造
作为零代码小白,之前深蓝底色的预览图看久了太累眼。文字RPG核心是阅读,我的想法是这样的: 1. 配色:抛弃深蓝,改米白羊皮纸底色(#FDFBF7)配深褐文字,营造书卷气。 2. 布局:竖屏极简风。顶部仅留状态栏,中间65%纯净无边框叙事,底部20%留一个超大输入框和“行动”按钮。 3. 交互:删掉所有“攻击”等预设按钮,只留“描述你的行动...”,全凭玩家自由输入,沉浸感拉满。 让页面画风变柔,
1 回复
一个类LOL带有合成树的装备商店系统文档截图
一个类LOL带有合成树的装备商店系统文档
可复用于其他需要类似功能的项目,减少沟通的积分消耗,分享给大家: 1. 整体架构equip_defs.lua 数据层 — 装备定义、合成配方、价格、属性、工具函数 equip_shop.lua UI 层 — NanoVG 渲染、交互逻辑、合成树可视化 2.2 装备分类类型值名称说明1武器—2衣甲—3头盔—4腰带—5靴子—6项链—7戒指—8饰品—2.3 阶级体系阶级颜色说明T1灰白 (180,180
精华
6 赞
2 回复
制造做《布衣江湖》踩过的5个大坑截图
制造做《布衣江湖》踩过的5个大坑
#开发心得 大家好,我是《布衣江湖》的开发者。 先坦白:我是个游戏小白,第一次做游戏,什么都不懂。今天借这个帖子,把这一路踩的坑写出来,希望能帮到同样在TapTap制造上摸索的兄弟们,也给自己留个记录。 **坑一**:玩家面板和怪物属性“各过各的” 刚开始做的时候,我花了好几天调玩家属性,把攻击、防御、气血都配得很漂亮。结果去打副本发现——怪物只有21点血,玩家一刀就能秒。 原因是:AI只改了玩
2D 等轴测视角:完整理论截图
2D 等轴测视角:完整理论
2D 等轴测视角:完整理论 一、视角的本质 什么是等轴测 人站在高处斜着往下看地面,地面上的方格子不再是正方形,而变成了菱形。这就是等轴测的视觉本质。 俯视(正上方看下去): 等轴测(斜上方看下去): ┌──┬──┬──┐ ◇ ├──┼──┼──┤ ◇ ◇ ├──┼──┼──┤ ◇ ◇ ◇ └──┴──┴──┘ ◇ ◇ ◇ 正方形网格经过旋转 + 压缩,变成了菱形网格。 为什么是 2:1
6 赞
【UI教程】如何将已有的效果图应用为实际的UI界面截图
【UI教程】如何将已有的效果图应用为实际的UI界面
在经过了一些折腾和比较折磨的尝试后,我总算是摸清楚了嗒啦啦怎么把UI效果图转换为实际游戏中的UI组件,今天就给大家带来这部分的经验分享。 tips:1.本篇教程需要各位掌握最基本的ps使用,具体的操作部分我会大致讲解,但仍需各位自行学习ps的基本操作,部分可以由ai代劳的环节我会注明。 2.本篇教程需要在以我前两篇教程作为前置环节,请在阅读这两篇前置教程后再进行本篇教程内容的学习 在按照前
11 赞
5 回复
开发心得-界面布局心得截图
开发心得-界面布局心得
大家好,我正在用 TapTap 制造制作一款2D 治愈林间徒步旅行游戏《徒步荒野》。 我分享一下我的开发心得,希望能有用,下面是一些界面布局的心得。 第一步:定版式、操作 先确定游戏是横版还是竖版、需要哪些操作按钮,敲定整体玩法思路。 我的玩法灵感参考《边境之旅》,主打散步看风景、沿途触发随机事件。 原版是 3D,考虑到自己是新手,选择2D 横版街机式来做,制作更简单、好上手。 第二步:敲定全局美
6 赞
3 回复