Back to Details

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

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

type_checker.gd

Scans codebase for missing type hints. Run before releases to enforce static typing standards.
扫描代码库中缺失的类型提示。在发布前运行以强制执行静态类型标准。

performance_analyzer.gd

performance_analyzer.gd

Detects performance anti-patterns: get_node() in loops, string concat, unsafe dict access.
检测性能反模式：循环中的get_node()、字符串拼接、不安全的字典访问。

signal_architecture_validator.gd

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:
  1. extends
  2. class_name
  3. signals
    / 
    enums
    / 
    constants
  4. @export
    / 
    @onready
    / 
    properties
  5. _init()
    / 
    _ready()
    / 
    _process()
  6. Public methods
  7. Private methods (prefixed with 
    _
    )
遵循标准的Godot脚本布局：
  1. extends
  2. class_name
  3. signals
    / 
    enums
    / 
    constants
  4. @export
    / 
    @onready
    / 
    properties
  5. _init()
    / 
    _ready()
    / 
    _process()
  6. 公共方法
  7. 私有方法（以
    _
    开头）

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

Related

相关内容

  • Master Skill: godot-master
  • 精通技能：godot-master