Godotline模板手册

Godotline 模板 V2.3 使用手册

适用版本：最新版 Godotline 模板 V2.3

前置要求：本手册仅讲解模板特有的使用方法，不涵盖 Godot 基础操作。若对 Godot 编辑器尚不熟悉，建议先掌握基础操作后再阅读本教程。

对比参考：本手册仅列出与「冰焰模板」不同的部分，冰焰模板的完整教程请访问 https://maxiceflame.github.io/tutorial/ 和 【筱夕/教程】冰焰模板修改版 EP.0 基础环境搭建 https://www.bilibili.com/video/BV1ZpHRewEtv/
移植版本：https://github.com/XGames-Studio/DLMTP-Template
Deepwiki: 使用前注意对比wiki更新时间与模板更新时间 https://deepwiki.com/meny2333/godot-line

特色功能

插件面板 & 插件商城

模板内置了可视化的插件管理面板，提供以下核心能力：

• 新建关卡：一键创建标准化关卡目录结构
• 排序引导线：辅助关卡元素的对齐与布局

检查点自动获取复活参数

模板中的检查点系统会自动记录并获取复活所需的参数，无需手动配置，降低了关卡设计的门槛。

内置示例场景（Sample.tscn）

模板附带一个可正常通关的示例场景，帮助用户快速概览模板功能并上手实践。

• Default：最小可玩场景，仅包含核心框架
• Sample：完整示例场景，包含典型用法演示

Unity 风格的 Add Component 按钮

模板引入了类似 Unity 的 Add Component 交互风格，让习惯 Unity 的开发者能够快速适应 Godotline 的工作流。

---

初始化项目

首次打开项目时，面对空白的场景可能会感到无从下手。按以下步骤快速创建第一个关卡：

1. 点击编辑器右上角的 「模板」 字样按钮

   

2. 在弹出的面板中填写关卡信息：

   • 关卡名称：你的关卡标识名
   • 模板场景：选择 Default（最小框架）或 Sample（完整示例）
   • 关卡 ID：任意填写，用于内部标识

   

3. 点击确认，模板将自动生成标准化的关卡目录结构。

---

项目结构管理规范

核心原则：所有关卡相关资源（场景、脚本、音频、材质等）统一归置在 [Scenes]/关卡目录 下，便于集中管理与版本控制。

✅ 推荐做法

• 按关卡维度组织资源：每个关卡拥有独立的子目录，场景、脚本、音频、材质等资源全部放在该目录下。
• 保持项目根目录简洁：根目录仅保留全局配置和框架代码。

⚠️ 重要禁区

禁区	说明
不要直接修改 #Template 目录	导出时 #Template 目录会被自动排除，直接修改会导致关卡无法被合集收录。
不要在根目录随意放置资源	冰焰模板的场景原位于 #Template/[Scenes]/，本模板已将其迁移至 /[Scenes]/。如需添加新材质，必须在新建关卡的场景目录下创建。

📌 总结

所有新增内容只能放在新建关卡的目录内。

---

动画系统：从 Timeline 到 AnimationPlayer

Godot 的 AnimationPlayer 在制作动画方面非常强大，但与 Unity 的 Timeline 相比，AnimationPlayer 未暴露自定义动画轨道的 API。这导致 #TimelineExpandPack 中的部分功能目前无法实现。

当前方案：考虑通过重写插件来模拟 Unity Timeline 的行为，以弥补这一差距。

---

场景环境设置

注意：本模板所有代码修改的都是 Camera3D 节点下的 Environment 资源。确保你在调整环境参数时选中的是正确的节点路径。

---

为模型创建碰撞体积

为 MeshInstance3D 添加碰撞体积的步骤如下：

步骤 1：选中目标模型

在场景树中点击你想要添加碰撞的 MeshInstance3D 节点。

步骤 2：打开网格工具

点击编辑器顶部的 「网格」 按钮。

步骤 3：创建碰撞形状

点击 「创建碰撞形状」。

步骤 4：配置碰撞参数

在弹出的对话框中设置：

• 碰撞形状位置：静态物体子节点
• 碰撞形状类型：
  • 单一凸形状（推荐，性能较好）
  • 三角网格（适用于极不规则的模型，或凸形状效果不理想时）

点击 「创建」 按钮。

步骤 5：设置碰撞层

1. 选中刚创建的 MeshInstance3D 下的 StaticBody3D 节点

   

2. 在检查器中展开 「碰撞」 一栏

   

3. 设置碰撞层：

   • 层 2：地板
   • 层 3：墙壁

   建议：每个碰撞体只设置一个碰撞层。多个碰撞层叠加的效果未经充分测试，行为可能不可预期。

---

运行时场景预览与实时修改

与 Unity 的核心差异

维度	Unity	Godot
运行时 Inspector	只读	可读写，支持嵌入视图中直接操控
场景树同步	需第三方插件	内置「同步场景修改」一键开启
编辑 ↔ 运行切换	修改后需停止运行	双向无缝切换

操作步骤

1. 切换 3D 交互模式

项目运行后，在顶部工具栏点击 3D 按钮，将交互模式从「输入」切换为 3D：

• 输入：默认模式，游戏正常接收输入，无法选中节点。
• 3D：禁用游戏输入，允许在嵌入视图中选择 Node3D 节点并操控 3D 摄像机。

2. 启用摄像机 Override

点击工具栏中的 摄像机 Override 按钮（摄像机图标），即可在运行中的游戏画面里自由移动视角、选中节点，并在 Inspector 面板中实时修改属性。

⚠️ 注意：以这种方式对运行中的游戏所做的更改，在游戏停止时不会被保留。

3. 开启同步场景修改

若要使修改在游戏停止后依然保留，或让编辑器中的调整实时同步到运行中的游戏，勾选：

• ✅ 同步场景修改 — 编辑器中对场景的任何调整都会实时反映到运行中的项目。

4. 双向无缝切换

启用后，你可以：

• 在嵌入视图中直接选中运行中的节点并修改属性；
• 随时切回编辑器「本地场景树」调整场景；
• 修改即时生效，无需停止运行即可迭代。

---

RoadPaver 的保存（将分支保存为场景）

使用 RoadPaver 铺完路后，需要将生成的道路分支保存为独立场景文件：

操作步骤

1. 暂停游戏，切换到编辑器的 「远程」 面板

2. 找到 「Roads」 分支，右键选择 「将分支保存为场景」

   

3. 停止游戏

4. 将保存好的 Roads.tscn 拖入场景中

5. 删除场景中的 RoadPaver 组件（避免运行时重复生成）

6. （可选） 将 Roads 节点 「转为本地」，使其成为场景的一部分

移动端 Godot 编辑器提示：手机端可能需要在每个步骤后重新点击游戏面板，才能刷新显示正常状态。

---

后处理效果（Post Processing）

不同渲染后端对后处理特性的支持情况如下：

特性	Forward+	Mobile	Compatibility
Tone Mapping（ACES / AgX / Filmic…）	✅	✅	✅
Fog（Depth / Height）	✅	✅	✅
Volumetric Fog / FogVolume	✅	❌	❌
Glow / Bloom	✅ 完整	✅ 简化/重写版	✅ 简化版
Adjustments（亮度/对比度/饱和/LUT）	✅	✅	✅
DOF（CameraAttributes）	✅	✅	✅
Auto Exposure	✅	✅	⚠️ 受限
SSAO	✅ 完整（Adaptive HBAO）	❌	✅ 简化版（4.6+，仅 Radius/Intensity）
SSIL	✅	❌	❌
SSR	✅	❌	❌
SDFGI	✅	❌	❌
VoxelGI	✅	❌	❌
LightmapGI（烘焙需 RD，运行三端可用）	✅	✅	✅（无降噪器）
ReflectionProbe	✅ 无限	✅ 8/mesh	✅ 2/mesh
TAA	✅	❌（4.7 有相关修复但非完整）	❌
Procedural Sky / Sky 背景	✅	✅	✅

图例说明

• ✅ = 完整支持
• ⚠️ = 部分支持 / 功能受限
• ❌ = 不支持

补充说明

• Compatibility SSAO：自 Godot 4.6 起加入（GLES3 简易实现），观感与 Forward+ 差异较大，仅支持调节 Radius 和 Intensity。
• Mobile 后端：明确不支持 SSAO、SSIL、SSR、Volumetric Fog、SDFGI、VoxelGI。
• 切换渲染后端：Project Settings → Rendering → Renderer → Rendering Method，可按 .mobile / .web 后缀分别覆盖。

---

画面雾效：灰蒙蒙 vs. Unity 式雾气

问题描述

开启 Fog 后，画面整体发灰，缺乏远近景的层次感，呈现「蒙灰」效果。

解决方案

将 Fog 的 模式（Mode） 切换为 Depth。

参考案例

Inverted World 的开头场景即采用 Depth Fog 实现远近景分离，避免了全局雾效导致的画面发灰问题：

---

如何更新模板

由于模板迭代速度较快，用户通常希望及时使用新功能，而非像冰焰模板那样固定在特定版本（如冰 3 或冰 4.7.2）。以下是三种更新方案：

方法 1：使用 Git Merge Upstream（⭐ 推荐）

适合：已使用 Git 管理项目的用户

1. 在 GitHub 上新建一个仓库，将本地项目推上去
2. 将模板的官方仓库设为 upstream：

   git remote add upstream https://github.com/godotline/godot-line
   

3. 需要更新时，执行：

   git fetch upstream
   git merge upstream/main
   

   遇到冲突时，以远端（upstream）为准解决。

提示：也可以直接询问 AI：「将当前仓库的 upstream 设为 https://github.com/godotline/godot-line」，或「合并 upstream，遇到冲突时以远端为准」。

手动 Merge（备选）

git merge upstream

出现冲突后手动解决。

方法 2：将最新模板直接覆盖本地

不推荐。直接覆盖可能导致资源冗余、路径冲突或旧文件残留。

方法 3：将关卡复制到最新模板

成功率高于方法 2，但仍可能出现依赖缺失的问题。若弹出缺少依赖的对话框，手动选择对应资源即可。

---

毁灭性更改问题

模板在快速迭代过程中，可能会引入破坏性变更（Breaking Changes），导致旧项目无法正常打开或运行。

遇到此类问题时，请留意更新日志中的破坏性变更说明，并根据指引进行迁移。

---

文档版本：V2.3 | 最后更新：2026-08