@export และ Annotation ใน Godot 4

บทนำ: จากคีย์เวิร์ดสู่ Annotation

Godot 4 ได้แทนที่คีย์เวิร์ดหลายตัวของ GDScript ด้วย annotation ที่ขึ้นต้นด้วย @ ซึ่งเป็นส่วนหนึ่งของความพยายามครั้งใหญ่ในการทำให้ไวยากรณ์ของ GDScript สะอาดตาและสอดคล้องกันมากขึ้น การเปลี่ยนแปลงที่สำคัญที่สุดสามอย่างคือ:

• export → @export
• onready → @onready
• tool → @tool

Annotation จะถูกวางไว้ในบรรทัดก่อนหน้า (หรือบรรทัดเดียวกันกับ) การประกาศที่มันปรับแต่ง Godot 4 ยังได้เพิ่มรูปแบบ annotation ใหม่จำนวนมาก เช่น @export_range, @export_group และ @export_category ที่ไม่มีอยู่ใน Godot 3 คู่มือนี้จะครอบคลุมทั้งหมด

@export พื้นฐาน

Annotation @export เปิดเผยตัวแปรใน Godot Inspector ทำให้คุณกำหนดค่าได้โดยไม่ต้องแก้ไขโค้ด Godot จะเลือกวิดเจ็ตของเอดิเตอร์ที่เหมาะสมโดยอัตโนมัติตามชนิดข้อมูลของตัวแปร

@export var speed: float = 300.0
@export var player_name: String = "Player"
@export var health: int = 100
@export var color: Color = Color.WHITE
@export var texture: Texture2D
@export var scene: PackedScene

เคล็ดลับ: ควรเพิ่มการระบุชนิดข้อมูลให้กับตัวแปรที่ export เสมอ สิ่งนี้ช่วยให้ Inspector แสดงวิดเจ็ตที่ถูกต้อง (เช่น ตัวเลือกสีสำหรับ Color, ช่องรีซอร์สสำหรับ Texture2D)

@export_range — แถบเลื่อนค่าตัวเลข

@export_range จำกัดค่าตัวเลขให้อยู่ระหว่างค่าต่ำสุดและสูงสุด โดยแสดงเป็นแถบเลื่อนใน Inspector คุณยังสามารถระบุขนาดขั้น (step) และคำใบ้อย่าง "or_greater" หรือ "or_less" ได้ด้วย

@export_range(0, 100) var health: int = 100
@export_range(0.0, 1.0, 0.01) var volume: float = 0.8
@export_range(0, 1000, 1, "or_greater") var damage: int = 10

คำใบ้ "or_greater" อนุญาตให้พิมพ์ค่าที่มากกว่าค่าสูงสุดได้ ในขณะที่ยังคงช่วงของแถบเลื่อนไว้ ในทำนองเดียวกัน "or_less" อนุญาตให้ใช้ค่าที่ต่ำกว่าค่าต่ำสุดได้

@export_enum — เมนูแบบดรอปดาวน์

@export_enum สร้างดรอปดาวน์ใน Inspector เมื่อใช้กับ String จะเก็บชื่อของตัวเลือกที่เลือกไว้ เมื่อใช้กับ int คุณสามารถกำหนดค่าที่ชัดเจนได้

# Stores the string name: "Warrior", "Mage", or "Rogue"
@export_enum("Warrior", "Mage", "Rogue") var character_class: String

# Stores the integer value: 0, 1, or 2
@export_enum("Easy:0", "Normal:1", "Hard:2") var difficulty: int = 1

@export_file และ @export_dir — พาธของไฟล์/ไดเรกทอรี

@export_file แสดงกล่องโต้ตอบเลือกไฟล์ใน Inspector คุณสามารถกรองตามนามสกุลไฟล์ได้ ส่วน @export_dir แสดงกล่องโต้ตอบเลือกไดเรกทอรี

@export_file("*.tscn") var next_level: String
@export_dir var save_directory: String

สตริงตัวกรองใช้รูปแบบ glob สามารถแยกหลายตัวกรองด้วยเครื่องหมายจุลภาคได้: "*.png,*.jpg"

@export_multiline และ @export_placeholder

@export_multiline ให้พื้นที่ข้อความขนาดใหญ่สำหรับสตริงหลายบรรทัด (เหมาะสำหรับบทสนทนาหรือคำอธิบาย) ส่วน @export_placeholder แสดงข้อความคำใบ้ภายในช่องเมื่อช่องว่างเปล่า

@export_multiline var description: String
@export_placeholder("Enter name...") var player_name: String

@export_group และ @export_subgroup — จัดระเบียบพร็อพเพอร์ตีใน Inspector

@export_group สร้างส่วนหัวกลุ่มที่ยุบ/ขยายได้ใน Inspector ตัวแปร @export ทั้งหมดที่ตามมาจะอยู่ในกลุ่มนั้นจนกว่าจะถึงกลุ่มหรือหมวดหมู่ถัดไป ส่วน @export_subgroup จะซ้อนอยู่ภายในกลุ่มปัจจุบัน

@export_group("Movement")
@export var speed: float = 300.0
@export var jump_force: float = 400.0

@export_group("Combat")
@export var attack_damage: int = 10
@export var defense: int = 5

@export_subgroup("Ranged")
@export var projectile_speed: float = 500.0

กลุ่มและกลุ่มย่อยมีไว้เพื่อการจัดระเบียบล้วน ๆ — ไม่ส่งผลต่อการเข้าถึงตัวแปรในโค้ด มีผลเฉพาะการแสดงพร็อพเพอร์ตีใน Inspector เท่านั้น

@export_category — ส่วนหัวหมวดหมู่ตัวหนา

@export_category สร้างส่วนหัวหมวดหมู่ระดับบนสุดแบบตัวหนาใน Inspector ต่างจากกลุ่มตรงที่หมวดหมู่ไม่สามารถยุบได้ และทำหน้าที่เป็นตัวแบ่งทางสายตาที่ชัดเจนระหว่างชุดพร็อพเพอร์ตีที่ไม่เกี่ยวข้องกัน

@export_category("Player Stats")
@export var level: int = 1
@export var experience: int = 0

@export กับการอ้างอิง Node

คุณสามารถ export NodePath เพื่อให้ดีไซเนอร์เลือก node จากซีนทรีได้ ใน Godot 4.2+ คุณสามารถ export การอ้างอิง node แบบมีชนิดข้อมูลได้โดยตรง — ไม่จำเป็นต้องใช้ NodePath

# Classic NodePath export
@export var target_path: NodePath

# Godot 4.2+: typed node export (direct reference, no NodePath needed)
@export var sprite: Sprite2D
@export var collision: CollisionShape2D

การ export node แบบมีชนิดข้อมูลเป็นแนวทางที่แนะนำใน Godot 4 ยุคใหม่ Inspector จะแสดงตัวเลือก node ที่กรองตามชนิดที่ระบุ และคุณจะได้รับการเติมข้อความอัตโนมัติอย่างครบถ้วนในเอดิเตอร์สคริปต์

@export_flags — เช็กบ็อกซ์บิตมาสก์

@export_flags สร้างชุดเช็กบ็อกซ์ที่แต่ละตัวเลือกสอดคล้องกับบิตหนึ่งบิตในจำนวนเต็ม Godot ยังมี flag export ในตัวสำหรับเลเยอร์ฟิสิกส์และเลเยอร์เรนเดอร์ด้วย

# Custom flags: Fire=1, Water=2, Earth=4, Wind=8
@export_flags("Fire", "Water", "Earth", "Wind") var elements: int

# Built-in physics layer flags
@export_flags_2d_physics var collision_layers: int
@export_flags_2d_render var render_layers: int
@export_flags_3d_physics var collision_layers_3d: int

@onready — การกำหนดค่าเริ่มต้นแบบหน่วงเวลา

@onready หน่วงการกำหนดค่าเริ่มต้นของตัวแปรจนกว่า node จะเข้าสู่ซีนทรี (เทียบเท่ากับการกำหนดค่าใน _ready()) สิ่งนี้จำเป็นอย่างยิ่งเมื่ออ้างอิง node ลูกด้วย $ เพราะ node ลูกยังไม่พร้อมใช้งานในเวลาแยกวิเคราะห์ (parse time)

# Godot 3 (old syntax):
# onready var sprite = $Sprite2D

# Godot 4:
@onready var sprite: Sprite2D = $Sprite2D
@onready var anim: AnimationPlayer = $AnimationPlayer
@onready var label: Label = $UI/ScoreLabel

แนวปฏิบัติที่ดีที่สุด: ระบุชนิดข้อมูลให้กับตัวแปร @onready ของคุณเสมอ สิ่งนี้เปิดใช้งานการเติมข้อความอัตโนมัติ และดักจับข้อผิดพลาดด้านชนิดข้อมูลในเวลาแยกวิเคราะห์แทนที่จะเป็นเวลารันไทม์

@tool — รันสคริปต์ในเอดิเตอร์

@tool ทำให้สคริปต์ทำงานภายในเอดิเตอร์ของ Godot (ไม่ใช่แค่ตอนรันไทม์) สิ่งนี้ทรงพลังสำหรับการสร้างพรีวิว กิซโม และพร็อพเพอร์ตีที่อัปเดตแบบเรียลไทม์ ให้วางไว้ที่ด้านบนสุดของสคริปต์ ก่อน extends

@tool
extends Node2D

@export var radius: float = 100.0:
    set(value):
        radius = value
        queue_redraw()  # Redraw in editor when value changes

func _draw() -> void:
    draw_circle(Vector2.ZERO, radius, Color.WHITE)

คำเตือน: ระวังการใช้สคริปต์ @tool โค้ดใน _process() และ _physics_process() จะทำงานในเอดิเตอร์ ใช้ Engine.is_editor_hint() เพื่อป้องกันตรรกะที่ใช้เฉพาะในเกม

Annotation อื่น ๆ

@icon

กำหนดไอคอนกำหนดเองสำหรับชนิด node ของสคริปต์ใน Scene dock และกล่องโต้ตอบ Create Node

@icon("res://icons/enemy.svg")
extends CharacterBody2D

@warning_ignore

ระงับคำเตือน GDScript ที่ระบุสำหรับคำสั่งถัดไป มีประโยชน์เมื่อคุณตั้งใจบดบัง (shadow) ตัวแปร หรือมีพารามิเตอร์ที่ไม่ได้ใช้งาน

@warning_ignore("unused_parameter")
func _on_body_entered(body: Node2D) -> void:
    queue_free()

@warning_ignore("shadowed_variable")
var size: int = 10

@static_unload

ทำเครื่องหมายสคริปต์เพื่อให้ Godot สามารถยกเลิกการโหลดออกจากหน่วยความจำได้เมื่อไม่มีอินสแตนซ์อยู่ สิ่งนี้ช่วยลดการใช้หน่วยความจำสำหรับสคริปต์ที่ใช้เพียงชั่วคราว สคริปต์ต้องไม่มีตัวแปรสแตติกหรือข้อมูลใด ๆ ที่จำเป็นต้องคงอยู่

@static_unload
extends RefCounted

# This script can be safely unloaded when not in use

แนวปฏิบัติที่ดีที่สุดสำหรับการระบุชนิดข้อมูลแบบสแตติก

แม้จะไม่ใช่ annotation แต่คำใบ้ชนิดข้อมูลแบบสแตติกก็มีความเกี่ยวข้องอย่างใกล้ชิดและได้รับการแนะนำอย่างยิ่งใน Godot 4 มันช่วยปรับปรุงการเติมข้อความอัตโนมัติ เปิดใช้การตรวจสอบข้อผิดพลาดในเวลาคอมไพล์ และช่วยเพิ่มประสิทธิภาพได้

# Variable type annotations
var speed: float = 300.0
var player: CharacterBody2D = null
var items: Array[String] = []
var scores: Dictionary = {}

# Function return types and parameter types
func get_damage() -> int:
    return attack - defense

func apply_force(direction: Vector2, strength: float) -> void:
    velocity += direction * strength

# Type inference with :=
var pos := Vector2(100, 200)  # Inferred as Vector2

หมายเหตุ: ระวังการใช้ := ในลูป for เมื่อวนซ้ำอาร์เรย์ที่ไม่มีชนิดข้อมูล ให้ใช้การระบุชนิดข้อมูลอย่างชัดเจนแทน: for item: String in array

ชีตสรุปการย้าย: Godot 3 ไป 4

ข้อมูลอ้างอิงอย่างย่อสำหรับการแปลงไวยากรณ์ export ของ Godot 3 เป็น annotation ของ Godot 4: