godot-gdscript-mastery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GDScript Mastery

GDScript 精通指南

Expert guidance for writing performant, maintainable GDScript following official Godot standards.

遵循官方Godot标准，编写高性能、可维护GDScript的专业指导。

NEVER Do

绝对不要做的事

NEVER use dynamic typing for performance-critical code —
```
var x = 5
```
is 20-40% slower than
```
var x: int = 5
```
. Type everything.
NEVER call parent methods from children ("Call Up") — Use "Signal Up, Call Down". Children emit signals, parents call child methods.

NEVER use
get_node()
in
_process()
or
_physics_process()
— Caches with

@onready var sprite = $Sprite

. get_node() is slow in loops.

NEVER access dictionaries without
.get()
default —
```
dict["key"]
```
crashes if missing. Use
```
dict.get("key", default)
```
for safety.
NEVER skip
class_name
for reusable scripts — Without
```
class_name
```
, you can't use as type hints (
```
var item: Item
```
). Makes code harder to maintain.

性能关键代码绝对不要使用动态类型 ——
```
var x = 5
```
比
```
var x: int = 5
```
慢20-40%。所有变量都要声明类型。
绝对不要从子节点调用父节点方法（“向上调用”） —— 使用“信号向上，调用向下”模式。子节点发送信号，父节点调用子节点方法。
绝对不要在
_process()
或
_physics_process()
中调用
get_node()
—— 使用
```
@onready var sprite = $Sprite
```
进行缓存。循环中调用get_node()速度很慢。
绝对不要不使用
.get()
默认值访问字典 —— 如果键不存在，
```
dict["key"]
```
会导致崩溃。使用
```
dict.get("key", default)
```
以保证安全。
可复用脚本绝对不要省略
class_name
—— 没有
```
class_name
```
，你无法将其用作类型提示（如
```
var item: Item
```
），会让代码更难维护。

Available Scripts

可用脚本

MANDATORY: Read the appropriate script before implementing the corresponding pattern.

强制要求：在实现对应模式前，请先阅读相应的脚本。

advanced_lambdas.gd

Higher-order functions in GDScript: filter/map with lambdas, factory functions returning Callables, typed array godot-composition, and static utility methods.

GDScript中的高阶函数：结合lambda表达式的过滤/映射、返回Callable的工厂函数、类型化数组的Godot组合，以及静态工具方法。

type_checker.gd

Scans codebase for missing type hints. Run before releases to enforce static typing standards.

扫描代码库中缺失的类型提示。在发布前运行以强制执行静态类型标准。

performance_analyzer.gd

Detects performance anti-patterns: get_node() in loops, string concat, unsafe dict access.

检测性能反模式：循环中的get_node()、字符串拼接、不安全的字典访问。

signal_architecture_validator.gd

Enforces "Signal Up, Call Down" pattern. Detects get_parent() calls and untyped signals.

Do NOT Load performance_analyzer.gd unless profiling hot paths or optimizing frame rates.

强制执行“信号向上，调用向下”模式。检测get_parent()调用和未类型化的信号。

注意：除非分析热点路径或优化帧率，否则不要加载performance_analyzer.gd。

Core Directives

核心准则

1. Strong Typing

1. 强类型

Always use static typing. It improves performance and catches bugs early. Rule: Prefer

var x: int = 5

over

var x = 5

. Rule: Always specify return types for functions:

func _ready() -> void:

始终使用静态类型。它能提升性能并提前捕获bug。规则：优先使用

var x: int = 5

而非

var x = 5

。规则：始终为函数指定返回类型：

func _ready() -> void:

。

2. Signal Architecture

2. 信号架构

Connect in
_ready()
: Preferably connect signals in code to maintain visibility, rather than just in the editor.
Typed Signals: Define signals with types:
```
signal item_collected(item: ItemResource)
```
.
Pattern: "Signal Up, Call Down". Children should never call methods on parents; they should emit signals instead.

在
_ready()
中连接信号：优先在代码中连接信号以保持可见性，而不只是在编辑器中操作。
类型化信号：定义带类型的信号：
```
signal item_collected(item: ItemResource)
```
。
模式：“信号向上，调用向下”。子节点绝对不要调用父节点的方法；相反，子节点应发送信号。

3. Node Access

3. 节点访问

Unique Names: Use
```
%UniqueNames
```
for nodes that are critical to the script's logic.
Onready Overrides: Prefer
```
@onready var sprite = %Sprite2D
```
over calling
```
get_node()
```
in every function.

唯一名称：对脚本逻辑至关重要的节点使用
```
%UniqueNames
```
。
@onready 替代方案：优先使用
```
@onready var sprite = %Sprite2D
```
，而非在每个函数中调用
```
get_node()
```
。

4. Code Structure

4. 代码结构

Follow the standard Godot script layout:

```
extends
```
```
class_name
```
```
signals
```
/
```
enums
```
/
```
constants
```
```
@export
```
/
```
@onready
```
/
```
properties
```
```
_init()
```
/
```
_ready()
```
/
```
_process()
```
Public methods
Private methods (prefixed with
```
_
```
)

遵循标准的Godot脚本布局：

```
extends
```
```
class_name
```
```
signals
```
/
```
enums
```
/
```
constants
```
```
@export
```
/
```
@onready
```
/
```
properties
```
```
_init()
```
/
```
_ready()
```
/
```
_process()
```
公共方法
私有方法（以
```
_
```
开头）

Common "Architect" Patterns

常见“架构师”模式

The "Safe" Dictionary Lookup

“安全”字典查找

Avoid

dict["key"]

if you aren't 100% sure it exists. Use

dict.get("key", default)

如果你不能100%确定键存在，避免使用

dict["key"]

。使用

dict.get("key", default)

。

Scene Unique Nodes

场景唯一节点

When building complex UI, always toggle "Access as Scene Unique Name" on critical nodes (Labels, Buttons) and access them via

%Name

构建复杂UI时，始终为关键节点（标签、按钮）开启“作为场景唯一名称访问”，并通过

%Name

访问它们。

Reference

参考资料

Official Docs:

tutorials/scripting/gdscript/gdscript_styleguide.rst

Official Docs:

tutorials/best_practices/logic_preferences.rst

官方文档：

tutorials/scripting/gdscript/gdscript_styleguide.rst

官方文档：

tutorials/best_practices/logic_preferences.rst

godot-gdscript-mastery

Original

Translation

GDScript Mastery

GDScript 精通指南

NEVER Do

绝对不要做的事

Available Scripts

可用脚本

advanced_lambdas.gd

advanced_lambdas.gd

type_checker.gd

type_checker.gd

performance_analyzer.gd

performance_analyzer.gd

signal_architecture_validator.gd

signal_architecture_validator.gd

Core Directives

核心准则

1. Strong Typing

1. 强类型

2. Signal Architecture

2. 信号架构

3. Node Access

3. 节点访问

4. Code Structure

4. 代码结构

Common "Architect" Patterns

常见“架构师”模式

The "Safe" Dictionary Lookup

“安全”字典查找

Scene Unique Nodes

场景唯一节点

Reference

参考资料

Related

相关内容