GDScriptスタイルガイド

このスタイルガイドには、エレガントなGDScriptを作成するための規則が記載されています。目標は、クリーンで読みやすいコードの作成を奨励し、プロジェクト、ディスカッション、およびチュートリアル間の一貫性を促進することです。うまくいけば、これも自動フォーマットツールの開発を促進するでしょう。

GDScriptはPythonに近いので、このガイドはPythonの PEP 8 プログラミングスタイルガイドに触発されています。

スタイルガイドは、厳密なルールブックを意味するものではありません。時には以下のガイドラインの一部を適用できない場合があります。その場合は、最善であるように判断を下すと共に、仲間の開発者に洞察を求めてください。

一般に、プロジェクト内およびチーム内でコードの一貫性を保つことは、このガイドに完璧に従うよりも重要です。

注釈

Godotのビルトインスクリプトエディタは、デフォルトでこれらの規則を多く使用します。それをあなたの役に立つようにしてください。

これらのガイドラインに基づいた完全なクラスの例を次に示します:

class_name StateMachine
extends Node
# Hierarchical State machine for the player.
# Initializes states and delegates engine callbacks
# (_physics_process, _unhandled_input) to the state.


signal state_changed(previous, new)

export var initial_state = NodePath()
var is_active = true setget set_is_active

onready var _state = get_node(initial_state) setget set_state
onready var _state_name = _state.name


func _init():
    add_to_group("state_machine")


func _ready():
    connect("state_changed", self, "_on_state_changed")
    _state.enter()


func _unhandled_input(event):
    _state.unhandled_input(event)


func _physics_process(delta):
    _state.physics_process(delta)


func transition_to(target_state_path, msg={}):
    if not has_node(target_state_path):
        return

    var target_state = get_node(target_state_path)
    assert target_state.is_composite == false

    _state.exit()
    self._state = target_state
    _state.enter(msg)
    Events.emit_signal("player_state_changed", _state.name)


func set_is_active(value):
    is_active = value
    set_physics_process(value)
    set_process_unhandled_input(value)
    set_block_signals(not value)


func set_state(value):
    _state = value
    _state_name = _state.name


func _on_state_changed(previous, new):
    print("state changed")
    emit_signal("state_changed")

書式設定

エンコードと特殊文字

  • CRLFやCRではなく、改行(LF)文字を使用して改行します。(エディタのデフォルト)
  • 各ファイルの最後に1つの改行文字を使用します。(エディタのデフォルト)
  • バイトオーダーマーク<https://en.wikipedia.org/wiki/Byte_order_mark> なしで UTF-8 エンコーディングを使用します。(エディタのデフォルト)
  • インデントにはスペースの代わりに タブ を使用します。(エディタのデフォルト)

インデント

各インデントレベルは、それを含むブロックより1つ大きくなければなりません。

良い例

for i in range(10):
    print("hello")

悪い例

for i in range(10):
  print("hello")

for i in range(10):
        print("hello")

継続行と通常のコードブロックを区別するには、2つのインデントレベルを使用します。

良い例

effect.interpolate_property(sprite, "transform/scale",
            sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
            Tween.TRANS_QUAD, Tween.EASE_OUT)

悪い例

effect.interpolate_property(sprite, "transform/scale",
    sprite.get_scale(), Vector2(2.0, 2.0), 0.3,
    Tween.TRANS_QUAD, Tween.EASE_OUT)

この規則の例外は、配列、辞書、および列挙型です。単一のインデントレベルを使用して、継続行を区別します。

良い例

var party = [
    "Godot",
    "Godette",
    "Steve",
]

var character_dir = {
    "Name": "Bob",
    "Age": 27,
    "Job": "Mechanic",
}

enum Tiles {
    TILE_BRICK,
    TILE_FLOOR,
    TILE_SPIKE,
    TILE_TELEPORT,
}

悪い例

var party = [
        "Godot",
        "Godette",
        "Steve",
]

var character_dir = {
        "Name": "Bob",
        "Age": 27,
        "Job": "Mechanic",
}

enum Tiles {
        TILE_BRICK,
        TILE_FLOOR,
        TILE_SPIKE,
        TILE_TELEPORT,
}

末尾のコンマ

配列、辞書、および列挙型の最後の行に末尾のコンマを使用します。これにより、新しい要素を追加するときに最後の行を変更する必要がないため、リファクタリングが容易になり、バージョン管理の差分が改善されます。

良い例

enum Tiles {
    TILE_BRICK,
    TILE_FLOOR,
    TILE_SPIKE,
    TILE_TELEPORT,
}

悪い例

enum Tiles {
    TILE_BRICK,
    TILE_FLOOR,
    TILE_SPIKE,
    TILE_TELEPORT
}

単一行リストでは末尾のコンマは不要なので、この場合は追加しないでください。

良い例

enum Tiles {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT}

悪い例

enum Tiles {TILE_BRICK, TILE_FLOOR, TILE_SPIKE, TILE_TELEPORT,}

空白行

関数とクラスの定義は2つの空白行で囲んで下さい:

func heal(amount):
    health += amount
    health = min(health, max_health)
    emit_signal("health_changed", health)


func take_damage(amount, effect=null):
    health -= amount
    health = max(0, health)
    emit_signal("health_changed", health)

論理セクションを区切るには、関数内で1行の空白行を使用します。

行の長さ

コードの個々の行を100文字以内に保ちます。

可能であれば、行を80文字未満に保つようにしてください。これにより、小さなディスプレイでコードを読む場合や、2つのスクリプトを外部テキスト エディタで並べて開くときに役立ちます。たとえば、差分リビジョンを見る場合などです。

1行につき1つのステートメント

複数のステートメントを1行にまとめないでください。Cプログラミングで可能な、1行での条件付きステートメントもありません。

良い例

if position.x > width:
    position.x = 0

if flag:
    print("flagged")

悪い例

if position.x > width: position.x = 0

if flag: print("flagged")

その規則の唯一の例外は三項演算子です:

next_state = "fall" if not is_on_floor() else "idle"

不要なかっこ()を入れない

式や条件文に括弧を付けないでください。 操作の順序に必要な場合を除き、可読性が低下するだけです。

良い例

if is_colliding():
    queue_free()

悪い例

if (is_colliding()):
    queue_free()

ブール演算子

最もアクセスしやすいように、ブール演算子のプレーンな英語バージョンを優先します:

  • && の代わりに and を使用します。
  • || の代わりに or を使用します。

また、ブール演算子をかっこで囲んであいまいさを解消することもできます。これにより、長い式が読みやすくなります。

良い例

if (foo and bar) or baz:
    print("condition is true")

悪い例

if foo && bar || baz:
    print("condition is true")

コメントスペース

通常のコメントはスペースで始まる必要がありますが、コメントアウトしたコードにはスペースは付けません。これにより、テキストコメントと無効化したコードを区別できます。

良い例

# This is a comment.
#print("This is disabled code")

悪い例

#This is a comment.
# print("This is disabled code")

注釈

スクリプトエディタで、選択したコードのコメント化の状態を切り替えるには、<kbd>Ctrl</kbd> <kbd>K</kbd> を押します。この機能は、選択した行の先頭に単一の#記号を追加します(逆に#記号があれば削除します)。

スペース

演算子の前後およびコンマの後には常に1つのスペースを使用します。また、辞書参照や関数呼び出しに余分なスペースを入れないでください。

良い例

position.x = 5
position.y = target_position.y + 10
dict["key"] = 5
my_array = [4, 5, 6]
print("foo")

悪い例

position.x=5
position.y = mpos.y+10
dict ["key"] = 5
myarray = [4,5,6]
print ("foo")

式を垂直方向に揃えるためにスペースを使用しないでください:

x        = 100
y        = 100
velocity = 500

引用符

シングルクォートを使えばエスケープする文字数を減らせる場合以外は、なるべくダブルクォートを使用するようにします。下記の例を見てください。

# Normal string.
print("hello world")

# Use double quotes as usual to avoid escapes.
print("hello 'world'")

# Use single quotes as an exception to the rule to avoid escapes.
print('hello "world"')

# Both quote styles would require 2 escapes; prefer double quotes if it's a tie.
print("'hello' \"world\"")

命名規則

これらの命名規則は、Godot Engineスタイルに従います。これらを壊すと、コードが組み込みの命名規則と衝突し、コードの一貫性が失われます。

クラスとノード

クラス名とノード名には PascalCase を使用します:

extends KinematicBody

クラスを定数または変数にロードするときにもPascalCaseを使用します:

const Weapon = preload("res://weapon.gd")

関数と変数

関数と変数に名前を付けるには、snake_caseを使用します:

var particle_effect
func load_level():

ユーザーがオーバーライドする必要がある仮想メソッド関数、プライベート関数、およびプライベート変数の前に単一のアンダースコア(_)を追加します:

var _counter = 0
func _recalculate_path():

シグナル

過去形を使用してシグナルに名前を付けます:

signal door_opened
signal score_changed

定数と列挙型

CONSTANT_CASEで定数を記述します。つまり、すべて大文字でアンダースコア(_)を使用して単語を区切ります:

const MAX_SPEED = 200

列挙型の名前にはPascalCaseを、そのメンバーには定数なのでCONSTANT_CASEを使用します:

enum Element {
    EARTH,
    WATER,
    AIR,
    FIRE,
}

コードの順序

この最初のセクションでは、コードの順序に焦点を当てます。書式設定については、書式設定 を参照してください。命名規則については、命名規則 を参照してください。

次のようにGDScriptコードを整理することをお勧めします:

01. tool
02. class_name
03. extends
04. # docstring

05. signals
06. enums
07. constants
08. exported variables
09. public variables
10. private variables
11. onready variables

12. optional built-in virtual _init method
13. built-in virtual _ready method
14. remaining built-in virtual methods
15. public methods
16. private methods

順序を最適化して、コードを上から下に読みやすくし、コードを初めて読む開発者がどのように機能するかを理解しやすくし、変数宣言の順序に関連するエラーを回避します。

このコードの順序は、次の4つの経験則に従います:

  1. プロパティとシグナルが最初に来て、メソッドがそれに続きます。
  2. パブリックはプライベートの前に来ます。
  3. 仮想コールバックは、クラスのインターフェースの前に来ます。
  4. オブジェクトの構築関数と初期化関数、_init_ready は実行時にオブジェクトを変更する関数の前に来ます。

クラス宣言

コードがエディタで実行されることを意図している場合、スクリプトの最初の行に tool キーワードを置きます。

必要に応じて、class_name を続けます。この機能を使用して、プロジェクト内でGDScriptファイルをグローバルタイプに変換できます。詳細については、GDScriptの基本 を参照してください。

次に、クラスが組み込み型を拡張する場合は、extends キーワードを追加します。

それに続いて、クラスに関する追加ドキュメントをコメントとして指定する必要があります。これを使用して、クラスの役割をチームメイトに説明したり、それがどのように機能するか、他の開発者がどのように使用するかなどを説明したりできます。

class_name MyNode
extends Node
# A brief description of the class's role and functionality.
# Longer description.

シグナルとプロパティ

追加ドキュメントの後に、シグナル宣言、続いてプロパティ、つまりメンバー変数を記述します。

列挙型は、他のプロパティのエクスポートヒントとして使用できるため、シグナルの後に来る必要があります。

次に、定数、エクスポートされた変数、public、private、およびonready変数をこの順序で記述します。

enum Jobs {KNIGHT, WIZARD, ROGUE, HEALER, SHAMAN}

const MAX_LIVES = 3

export(Jobs) var job = Jobs.KNIGHT
export var max_health = 50
export var attack = 5

var health = max_health setget set_health

var _speed = 300.0

onready var sword = get_node("Sword")
onready var gun = get_node("Gun")

注釈

GDScriptコンパイラは、_ready コールバックの直前にonready変数を評価します。これを使用して、ノードの依存関係をキャッシュしたり、クラスが依存しているシーン内の子ノードを取得したりできます。これは上記の例が示すものです。

メソッドと静的関数

クラスのプロパティの後にメソッドが続きます。

エンジンがメモリ内にオブジェクトを作成するときに呼び出す _init() コールバックメソッドで開始します。 そしてGodotがノードをシーンツリーに追加するときに呼び出す _ready() コールバックを続けます。

これらの関数は、オブジェクトの初期化方法を示すため、最初に来る必要があります。

_unhandled_input()_physics_process のような、その他の組み込みの仮想コールバックが次に来る必要があります。これらは、オブジェクトのメインループとゲームエンジンとの相互作用を制御します。

クラスの残りのインターフェイスであるパブリックメソッドとプライベートメソッドは、この順序でその後に続きます。

func _init():
    add_to_group("state_machine")


func _ready():
    connect("state_changed", self, "_on_state_changed")
    _state.enter()


func _unhandled_input(event):
    _state.unhandled_input(event)


func transition_to(target_state_path, msg={}):
    if not has_node(target_state_path):
        return

    var target_state = get_node(target_state_path)
    assert target_state.is_composite == false

    _state.exit()
    self._state = target_state
    _state.enter(msg)
    Events.emit_signal("player_state_changed", _state.name)


func _on_state_changed(previous, new):
    print("state changed")
    emit_signal("state_changed")

静的型付け

Godot 3.1から、GDScriptはオプショナルな静的型付けをサポートしています。

タイプヒント

変数名の後にコロンをスペースを挟まずに配置し、可能ならばGDScript コンパイラに変数の型を推測させます。

良い例

onready var health_bar: ProgressBar = get_node("UI/LifeBar")

var health := 0 # The compiler will use the int type.

悪い例

# The compiler can't infer the exact type and will use Node
# instead of ProgressBar.
onready var health_bar := get_node("UI/LifeBar")

コンパイラにタイプヒントを推測させる場合、コロンとイコールは一緒に書いて下さい: :=

var health := 0 # The compiler will use the int type.

関数の定義をする時の戻り値の型の矢印の両側にスペースを追加します。

func heal(amount: int) -> void: