godot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Godot craft

Godot 开发技艺

Build the way a Godot developer working in the editor builds: scene-first. Every visible thing is a node in a scene, every reusable thing is its own scene, events travel on signals, and motion is owned by the node that moves. Reach for the native primitive — the one the engine ships for the job — and code only what no primitive covers.

Check the version before trusting any advice: most Godot material online is Godot 3. The reference is the Godot 4 best practices; read the project's pinned version from

project.godot

and use that version's docs.

像在 Godot 编辑器中工作的开发者那样构建：遵循 scene-first（场景优先）。每个可见对象都是场景中的一个节点，每个可复用对象都应是独立场景，事件通过 signal 传递，移动由实际移动的节点负责。选择原生机制——即引擎为当前任务提供的机制——只编写原生机制无法覆盖的代码。

在采信任何建议之前，先检查版本：网上的大多数 Godot 资料都基于 Godot 3。参考内容是 Godot 4 best practices；从

project.godot

读取项目锁定的版本，并使用该版本的文档。

Steps

步骤

Sketch the scene tree. Before writing code for anything visible, write its node tree: which nodes, which are their own
```
.tscn
```
, which script owns which job, which signals go up and which calls go down, which
```
Resource
```
s hold data. Done when every element of the spec or mock maps to a node in the sketch. At design time, the sketch is the ticket's Godot structure section — template in references/ticket-section.md.
Pick each primitive from the table below. Where a row points at a reference, read it before building that part.
Build in scenes. Author node trees in
```
.tscn
```
files; scripts instance scenes and set state on them. Styles, fonts and colours live in the project
```
Theme
```
.
Verify by looking. Run
```
scripts/smell_check.py
```
over the game code (it reads
```
.gd
```
and
```
.tscn
```
) and clear every finding, either by switching to the native primitive or by tagging a deliberate exception
```
# godot-ok: <reason>
```
(
```
; godot-ok: <reason>
```
in a
```
.tscn
```
) on or above the line. Wire it into validation so a non-zero exit fails the build. Then capture frames of every state and a motion clip of every transition (
```
--write-movie out.png --fixed-fps 30 --quit-after N
```
), open the frames, and compare each against the spec or mock. Attach them wherever the work is reported. Done when the check fails the build on a finding and is green, and you have looked at a frame of every state and transition and each one matches. A report that the game "boots" or "runs" is not verification; a frame you have looked at is.

勾勒场景树。 在为任何可见内容编写代码前，先写出其节点树：包含哪些节点、哪些节点应各自成为独立的
```
.tscn
```
、哪个脚本负责哪项工作、哪些 signal 向上传递、哪些调用向下传递，以及哪些
```
Resource
```
保存数据。当规范或设计稿中的每个元素都能映射到草图中的节点时，即完成。设计阶段，这张草图就是工单中的 Godot structure 章节——模板见 references/ticket-section.md。
选择各项原生机制。 从下表中为每项任务选择原生机制。如果表中某行提供了参考资料，请先阅读相应资料，再构建该部分。
在场景中构建。 在
```
.tscn
```
文件中编写节点树；脚本负责实例化场景并为其设置状态。样式、字体和颜色存放在项目
```
Theme
```
中。
通过查看结果进行验证。 对游戏代码运行
```
scripts/smell_check.py
```
（它会读取
```
.gd
```
和
```
.tscn
```
），并解决每一项发现：要么改用原生机制，要么在相关行上或其上方添加有意为之的例外标记
```
# godot-ok: <reason>
```
（在
```
.tscn
```
中使用
```
; godot-ok: <reason>
```
）。将其接入验证流程，使非零退出码导致构建失败。然后捕获每个状态的帧，以及每次转场的动态片段（
```
--write-movie out.png --fixed-fps 30 --quit-after N
```
），打开这些帧，并将每一帧与规范或设计稿进行比对。把这些材料附到工作成果汇报的相应位置。完成标准是：检查在发现问题时会让构建失败，并且当前检查结果为绿色；你还必须查看过每个状态和每次转场的一帧，并确认每一帧都匹配。仅仅报告游戏“能启动”或“能运行”并不构成验证；只有实际查看过的帧才算。

Primitives

原生机制

Job	Native primitive	Red flag
A game object (field, unit, pickup, card)	Its own scene, instanced; state set through a typed method	One `_draw()` painting every object
Clicking or hovering a world object	`Area2D` + `CollisionShape2D` , `input_pickable` , `mouse_entered` / `input_event`	`Rect2(...).has_point(mouse)` with literal sizes
Text	`Label` / `RichTextLabel` , styled by the theme	`draw_string` , `ThemeDB.fallback_font`
Panels, badges, button looks	`StyleBox` in the `Theme` , or a theme type variation	`StyleBoxFlat.new()` in script
Static UI layout	Containers and anchors in a `.tscn`	`Label.new()` / `add_child` building UI in `_ready`
Overlays on a container (badge, border, pip)	A plain `Control` root holding the container and the overlays as siblings	Children placed by offsets inside a container, which stretches them to fill it
Art on a card or panel	`StyleBoxTexture` in the theme, `NinePatchRect` for frames, `TextureRect` for pictures — references/art.md	`Sprite2D` inside the UI tree
Art in the world	`Sprite2D` , `AnimatedSprite2D` , `TileMapLayer` — references/art.md	`Polygon2D` placeholders standing in for finished art
A layout whose children animate (card hand, radial menu)	A custom `Control` computing target transforms; children ease toward them — references/motion.md	Animated children inside a `BoxContainer`
Reacting to game events	Signals from the model, connected by the view	Polling every frame and diffing arrays to guess what changed
A list that changes (hand, inventory)	One persistent view per item, keyed by the item; add and remove singly	Freeing every child and re-instancing on each change
One-shot motion (pop, shake, fly-to)	`Tween` from `create_tween()` on the moving node	Countdown floats passed down through refresh calls
Authored, multi-track motion	`AnimationPlayer`	Hand-sequenced timers
World objects that move	Move in `_physics_process` with physics interpolation on	Transforms set in `_process` on interpolated nodes
UI easing and view refresh	`_process`	Visual work in `_physics_process`
Framing the world	`Camera2D`	World laid out against literal viewport sizes
Tooltips	`_make_custom_tooltip()` returning a scene	Default `tooltip_text` for game content
Tunable data, card and item definitions	`Resource` subclasses saved as `.tres`	Dictionaries of constants in scripts
Per-object state	Typed `var` s	`set_meta` / `get_meta`
Node references	`@onready var x: Type = %Name` ; `class_name` on scripts others reference	Untyped `@onready var x = $Path`

Custom

_draw()

is the native primitive for three jobs only: many simple repeated shapes (a grid, a board), shapes no node provides (trails, arcs, procedural polygons), and the non-text face of a custom control. Everything else is a node.

任务	原生机制	风险信号
游戏对象（场地、单位、拾取物、卡牌）	独立场景并进行实例化；通过类型化方法设置状态	使用一个 `_draw()` 绘制所有对象
点击或悬停世界对象	`Area2D` + `CollisionShape2D` ，配合 `input_pickable` 、 `mouse_entered` / `input_event`	使用 `Rect2(...).has_point(mouse)` ，并硬编码尺寸
文本	`Label` / `RichTextLabel` ，通过 `Theme` 设置样式	`draw_string` 、 `ThemeDB.fallback_font`
面板、徽章和按钮外观	`Theme` 中的 `StyleBox` ，或主题类型变体（theme type variation）	在脚本中调用 `StyleBoxFlat.new()`
静态 UI 布局	`.tscn` 中的 `Container` 和锚点（anchors）	在 `_ready` 中通过 `Label.new()` / `add_child` 构建 UI
容器上的叠加层（徽章、边框、小圆点）	使用普通 `Control` 作为根节点，将容器和叠加层作为同级节点	在容器内部按偏移量放置子节点，导致容器将其拉伸至填满自身
卡牌或面板上的美术资源	在 `Theme` 中使用 `StyleBoxTexture` ，边框使用 `NinePatchRect` ，图片使用 `TextureRect`	在 UI 树中使用 `Sprite2D`
世界场景中的美术资源	`Sprite2D` 、 `AnimatedSprite2D` 、 `TileMapLayer` ——references/art.md	用 `Polygon2D` 占位图代替最终美术资源
子节点带动画的布局（手牌、径向菜单）	自定义 `Control` 计算目标 transform；子节点缓动至目标	在 `BoxContainer` 中为子节点添加动画
响应游戏事件	由模型发出 signal，再由视图建立连接	每帧轮询并比较数组，以猜测发生了什么变化
会变化的列表（手牌、库存）	每个条目对应一个持久化视图，并以该条目为键（key）；逐个添加和移除	每次变化都释放所有子节点并重新实例化
一次性动作（弹出、抖动、飞向目标）	在移动节点上通过 `create_tween()` 创建 `Tween`	在刷新调用中向下传递倒计时浮点值
手工编排的多轨动画	`AnimationPlayer`	手动依次编排计时器
移动的世界对象	在 `_physics_process` 中移动，并开启物理插值（physics interpolation）	在已启用插值的节点上通过 `_process` 设置 transform
UI 缓动和视图刷新	`_process`	在 `_physics_process` 中执行视觉工作
世界取景	`Camera2D`	按硬编码的视口（viewport）尺寸布置世界
工具提示	`_make_custom_tooltip()` 返回一个场景	对游戏内容直接使用默认 `tooltip_text`
可调数据、卡牌和物品定义	保存为 `.tres` 的 `Resource` 子类	在脚本中以字典存放常量
每个对象的状态	带类型的 `var`	`set_meta` / `get_meta`
节点引用	`@onready var x: Type = %Name` ；其他脚本会引用的脚本应声明 `class_name`	未加类型的 `@onready var x = $Path`

自定义

_draw()

仅适用于三类任务：大量简单重复的形状（网格、棋盘）、没有任何节点提供的形状（轨迹、弧线、程序化多边形），以及自定义控件的非文本绘制部分。其他一切均应使用节点。

Communication

通信

Call down, signal up. A parent calls methods on its children; a child emits signals and never reaches for its parent. A scene receives what it needs through a setter or

bind()

from the scene that owns it, and runs on its own when opened alone.

方法调用向下，signal 向上。父节点调用子节点的方法；子节点发出 signal，绝不主动访问父节点。场景从拥有它的场景通过 setter 或

bind()

接收所需内容，并且在单独打开时也能独立运行。

References

参考资料

references/ticket-section.md — the Godot structure section every Godot ticket carries.
references/motion.md — target-easing layouts, tweens, drag and snap-back.
references/ui.md — themes, containers, input routing between UI and world.
references/art.md — where art goes in UI versus world, and pixel-art settings.

references/ticket-section.md——每个 Godot 工单都应包含的 Godot structure 章节。
references/motion.md——目标缓动布局、Tween、拖拽和回弹。
references/ui.md——
```
Theme
```
、
```
Container
```
，以及 UI 与世界之间的输入路由。
references/art.md——UI 与世界场景中美术资源的使用位置，以及像素画设置。