GDScript для начинающих: основы языка Godot на примерах

Встроенный язык Godot GDScript задаёт блоки отступами, как Python. Разбираем переменные, типы, условия, циклы, функции, узлы и сигналы на примерах с выводом Godot 4.7.2 и пять ошибок, из-за которых чаще всего не работает первый скрипт, включая код из уроков по Godot 3.

Статью написал:
Ваня Буявец, продюсер, основатель Checkroi
Ваня Буявец
Основатель Checkroi, продюсер, эксперт в выборе онлайн-курсов
Все 3308 статей автора Подписаться на Телеграм-канал
Одобрено экспертом:
Наташа Буявец, основатель Checkroi, эксперт по онлайн-курсам
Наташа Буявец
Основательница Checkroi, продюсер Youtube-каналов, эксперт по онлайн-курсам
Все 3962 экспертных мнения Подписаться на Телеграм-канал
Обложка: GDScript для начинающих: основы языка Godot на примерах

GDScript — встроенный язык программирования движка Godot. Синтаксис похож на Python: блоки задаются отступами, а не фигурными скобками. Код живёт в скрипте, прикреплённом к узлу сцены. Первая строка такого скрипта говорит, от какого узла он наследуется, например extends Node2D, а дальше идут переменные и функции, которые движок вызывает сам.

Ниже основы языка на примерах для Godot 4: переменные и типы, условия, циклы, функции, узлы и сигналы. Под каждым фрагментом стоит вывод, который он печатает в Godot 4.7.2. Если вы ещё выбираете движок, сначала посмотрите разбор Unity и его особенностей, а готовый проект на GDScript разобран в статье о том, как сделать визуальную новеллу в Godot.

CheckroiCheckroiПодборка курсов по Godot1 курс • 1 школаСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Что такое GDScript и чем он отличается от Python

Рой пишет первый скрипт на GDScript в редакторе Godot

«Справочник по GDScript» называет его высокоуровневым объектно-ориентированным языком, созданным для Godot. Новичкам разработчики советуют начинать именно с него: по их словам, GDScript проще универсальных языков вроде C# и быстрее осваивается («Учимся программировать на GDScript»).

Официальных языков у движка четыре: GDScript, C#, а также C и C++ через GDExtension (раздел о языках). Для C# на странице загрузки лежит отдельная сборка Godot .NET, обычная сборка работает с GDScript без дополнительных установок.

Что сравниваем GDScript Python C# в Godot
Блоки кода отступы, по стилю Godot табы отступы, обычно 4 пробела фигурные скобки
Типы по желанию: var hp: int подсказки типов, интерпретатор их не проверяет обязательны
Где пишут код встроенный редактор Godot любая IDE обычно внешняя IDE
Сборка движка стандартная не связан с Godot Godot .NET

Сходство с Python поверхностное. Библиотеки Python в GDScript не подключаются, зато в языке сразу есть типы движка: Vector2, Color, узлы и сигналы. Если Python вам знаком, пригодится разбор синтаксиса Python: правила отступов там почти те же.

Первый скрипт: как прикрепить код к узлу

Скрипт в Godot не существует сам по себе. Он расширяет конкретный узел и получает доступ к его свойствам: позиции, тексту, видимости.

  1. Создайте сцену с корневым узлом Node2D.
  2. Щёлкните по узлу правой кнопкой и выберите «Прикрепить скрипт».
  3. В окне «Прикрепить скрипт узла» оставьте язык GDScript, путь вида res://hello.gd и нажмите «Создать».
  4. Замените текст в редакторе на код ниже и сохраните сцену.
  5. Запустите сцену командой «Запустить текущую сцену» и откройте внизу панель «Вывод».
extends Node2D

func _ready():
	print("Привет, Godot!")

В панели «Вывод» появится строка:

Привет, Godot!

_ready() движок вызывает один раз, когда узел и все его дочерние узлы уже в дереве сцены (справка по классу Node). Это место для начальной настройки. Если на компьютере нет Godot, тот же код можно запустить в веб-редакторе прямо в браузере.

Канал основателя Checkroi Вани Буявца3 800 человек читают мой Телеграм-канал про нейросетиСобрал промпты для Claude Code и ChatGPT, разборы ИИ-инструментов и лайфхаки по продвижению бизнеса в одном местеПрисоединиться

Переменные, константы и типы данных

Переменная объявляется словом var, константа словом const. Тип можно не указывать, указать явно или попросить язык вывести его из значения оператором :=. Как устроены переменные в целом, мы разбирали в статье о переменных в программировании.

extends Node

var health = 100
var speed: float = 250.0
var player_name := "Рой"
const MAX_HEALTH = 100

func _ready():
	print(typeof(health) == TYPE_INT)
	print(player_name, " бежит со скоростью ", speed)
	print(7 / 2, " и ", 7 / 2.0)
	print("Здоровье: %d из %d" % [health, MAX_HEALTH])
	health = "много"
	print(health)

Вывод:

true
Рой бежит со скоростью 250.0
3 и 3.5
Здоровье: 100 из 100
много

Обратите внимание на две строки. Деление двух целых даёт целое: 7 / 2 равно 3, дробь получится, только если одно из чисел записано как 2.0. А переменной health без типа можно присвоить строку, и язык не возразит.

С типизированной переменной так не выйдет. Если в скрипте с var player_name := "Рой" написать player_name = 5, Godot 4.7.2 откажется загружать файл:

Parse Error: Value of type "int" cannot be assigned to a variable of type "String".

Про типизацию в разных языках у нас есть отдельный разбор. По документации о статической типизации, GDScript с типами находит больше ошибок, даже не запуская код, а типизированный код получает прирост производительности за счёт оптимизированных опкодов. Новичку стоит писать с типами с первого скрипта: строку в числовой переменной редактор покажет ещё до запуска.

Основные встроенные типы, с которыми вы столкнётесь в первую неделю:

Тип Пример значения Для чего
int 100 очки, жизни, счётчики
float 250.0 скорость, время, масштаб
bool true флаги: на земле, жив, открыта ли дверь
String "Рой" имена, реплики, подписи
Vector2 Vector2(3, 4) позиция и направление в 2D
Array ["меч", "щит"] инвентарь, список врагов
Dictionary {"сила": 5} характеристики, настройки

Массивы и словари

Массив в GDScript ведёт себя почти как список в Python: отрицательный индекс берёт элемент с конца. Тип элементов можно закрепить записью Array[int].

var inventory = ["меч", "щит"]
inventory.append("зелье")
print(inventory.size(), " ", inventory[0], " ", inventory[-1])

var stats = {"сила": 5, "ловкость": 8}
stats["удача"] = 3
print(stats["ловкость"], " ", stats.has("магия"))

var scores: Array[int] = [10, 20, 30]
print(scores)
3 меч зелье
8 false
[10, 20, 30]

Как называть переменные, функции и классы

Компилятор примет любое допустимое имя, но у Godot есть соглашение, и встроенные классы движка написаны по нему. В руководстве по стилю сводная таблица выглядит так:

Что называем Формат Пример
файлы скриптов snake_case yaml_parser.gd
классы и узлы PascalCase class_name YAMLParser, Player
функции, переменные, сигналы snake_case func load_level(), signal door_opened
константы CONSTANT_CASE const MAX_SPEED = 200

Если смешивать стили, ваш код будет выбиваться из кода движка, и через месяц станет неясно, где ваша функция, а где встроенная. Комментарии в GDScript начинаются с символа #, как в Python.

Условия, циклы и match

Условия пишутся через if, elif и else, как в условиях Python. Цикл for перебирает массив, словарь или диапазон range(), while крутится, пока условие истинно.

func describe(hp: int) -> String:
	if hp <= 0:
		return "погиб"
	elif hp < 30:
		return "ранен"
	else:
		return "в строю"

func _ready():
	for hp in [100, 25, 0]:
		print(hp, ": ", describe(hp))
	for i in range(3):
		print("Волна ", i + 1)
	var stats = {"сила": 5, "ловкость": 8, "удача": 3}
	for key in stats:
		print(key, " = ", stats[key])
	var ammo = 3
	while ammo > 0:
		ammo -= 1
	print("Патронов: ", ammo)
100: в строю
25: ранен
0: погиб
Волна 1
Волна 2
Волна 3
сила = 5
ловкость = 8
удача = 3
Патронов: 0

Для выбора из нескольких вариантов в GDScript есть match. Через запятую можно перечислить несколько значений, а _ ловит всё остальное.

var weapon = "лук"
match weapon:
	"меч":
		print("Ближний бой")
	"лук", "арбалет":
		print("Дальний бой")
	_:
		print("Голыми руками")
Дальний бой

Функции и встроенные методы движка

Функция объявляется словом func. У параметров бывают значения по умолчанию, тип результата пишется после стрелки ->.

var health = 80
const MAX_HEALTH = 100

func heal(amount: int = 10) -> int:
	health = min(health + amount, MAX_HEALTH)
	return health

func _ready():
	print(heal())
	print(heal(50))
90
100

Кроме своих функций в скрипте есть методы, которые Godot вызывает сам. Их имена начинаются с подчёркивания:

  • _ready() срабатывает один раз, когда узел готов;
  • _process(delta) вызывается каждый кадр, delta хранит время с прошлого кадра в секундах;
  • _physics_process(delta) идёт с фиксированным шагом, туда кладут движение физических тел;
  • _input(event) получает нажатия клавиш, клики и касания.

Скорость в играх умножают на delta, иначе на мощном компьютере персонаж побежит быстрее, чем на слабом. Скрипт ниже двигает спрайт вправо на 200 пикселей в секунду, а с зажатой стрелкой вправо ещё на 200:

extends Sprite2D

var speed := 200.0

func _process(delta):
	position.x += speed * delta
	if Input.is_action_pressed("ui_right"):
		position.x += speed * delta

Без нажатий спрайт за первую секунду уходит примерно на 200 пикселей, чуть дальше или ближе: кадры не делят секунду ровно.

Узлы, сигналы и обращение к сцене

Дерево узлов сцены, связанных светящимися линиями сигналов

Из узлов и сигналов собрана любая сцена, поэтому с них начинаются курсы игрового программирования. Игра в Godot собирается из дерева узлов. Скрипт достаёт соседа по пути: $HUD/HealthLabel делает то же, что get_node("HUD/HealthLabel"). Такие переменные объявляют с аннотацией @onready, тогда значение берётся в момент готовности узла, а не раньше.

Сигнал — сообщение, которое узел отправляет при событии, например при нажатии кнопки. Документация называет сигналы встроенным механизмом делегирования: один объект реагирует на изменение другого, и им не нужно хранить ссылки друг на друга (урок о сигналах).

Пример из двух скриптов. Игрок объявляет сигнал и отправляет его, когда получает урон:

extends Node2D

signal health_changed(new_health)

var health := 100

func take_damage(amount: int) -> void:
	health -= amount
	health_changed.emit(health)

Главная сцена подписывается на сигнал и выводит здоровье в надпись:

extends Node2D

@onready var player = $Player
@onready var label: Label = $HUD/HealthLabel

func _ready():
	player.health_changed.connect(_on_health_changed)
	player.take_damage(15)

func _on_health_changed(new_health):
	label.text = "HP: %d" % new_health
	print(label.text)
HP: 85

Свой класс через class_name

Строка class_name регистрирует скрипт как новый тип. Если классы и объекты для вас пока абстракция, начните с разбора основ программирования. После этого его можно создавать через new() в любом другом скрипте проекта и проверять оператором is.

class_name Enemy
extends Node2D

var hp := 30

func greet() -> String:
	return "%s: %d HP" % [name, hp]

В скрипте главной сцены:

var orc = Enemy.new()
orc.name = "Орк"
add_child(orc)
print(orc.greet(), " ", orc is Enemy)
Орк: 30 HP true
Ваня БуявецКанал основателя Checkroi Вани БуявцаЗабирайте промпты и обучение по нейросетям в моём Телеграм-каналеБольше 3 800 человек уже применяют Claude Code, ChatGPT и другие нейросети в работе, учёбе, бизнесе и жизниПерейти в канал

Частые ошибки новичка в GDScript

Рой уверенно перешагивает грабли с чек-листом в лапе

Тексты ошибок ниже приведены так, как их печатает Godot 4.7.2.

  1. Пробелы вперемешку с табами. Симптом: Used space character for indentation instead of tab as used before in the file. Причина: часть строк скопирована из браузера или другого редактора с пробелами. Решение: выровнять отступы одним символом. Руководство по стилю Godot советует табы, и встроенный редактор ставит их сам (руководство по стилю GDScript).
  2. Узел ищут до _ready(). Симптом: строка var label = $HUD/HealthLabel на уровне класса даёт ошибку The default value uses "$" which won't return nodes in the scene tree before "_ready()" is called. Решение: дописать @onready перед var.
  3. Целое деление. Симптом: процент здоровья всегда 0. Причина: hp / max_hp при двух int отбрасывает дробь, как и у целых чисел в Python при операторе //. Решение: привести одно из чисел к float или умножить на 100 до деления.
  4. Сравнение дробных чисел через ==. Симптом: условие не срабатывает. 0.1 + 0.2 == 0.3 возвращает false, а is_equal_approx(0.1 + 0.2, 0.3) возвращает true. Решение: для float сравнивать через is_equal_approx().
  5. Движение без delta. Симптом: скорость персонажа зависит от частоты кадров. Решение: умножать скорость на delta в _process() или _physics_process().

Код из уроков по Godot 3

Много старых уроков и ответов на форумах написано для Godot 3. В Godot 4 часть синтаксиса убрали, и такой скрипт просто не загрузится. Вот что Godot 4.7.2 пишет на старые конструкции:

Godot 3 Godot 4 Сообщение Godot 4.7.2
export var speed = 10 @export var speed = 10 The "export" keyword was removed in Godot 4.
onready var label = $Label @onready var label = $Label The "onready" keyword was removed in Godot 4.
yield(timer, "timeout") await timer.timeout "yield" was removed in Godot 4. Use "await" instead.
connect("hit", self, "_on_hit") hit.connect(_on_hit) argument 2 should be "Callable"
extends KinematicBody2D extends CharacterBody2D Could not find base class "KinematicBody2D".

Полный список переименованных классов и изменений синтаксиса есть в официальном руководстве по переходу с Godot 3 на Godot 4. Перед тем как копировать чужой код, проверьте, для какой версии он написан.

Где учить GDScript дальше

Справочник по языку переведён на русский. Для старта хватит четырёх источников:

  • «Справочник по GDScript»: все ключевые слова, операторы и встроенные типы с примерами;
  • Learn GDScript From Zero: курс с открытым исходным кодом и интерактивными заданиями в браузере, на него ссылается сама документация Godot;
  • страница о статической типизации: когда писать типы и какие ошибки они ловят;
  • веб-редактор Godot, чтобы проверять примеры без установки.

Справочник подряд читать не нужно. Возьмите маленький проект и ищите в документации то, что понадобилось прямо сейчас. Подойдёт визуальная новелла или аркада на один экран. Если хочется понять, куда этот навык ведёт в карьере, почитайте, кто такой разработчик игр и чем живёт инди-разработчик, который делает игру один.

Где освоить Godot и разработку игр системно

Синтаксиса из этой статьи хватит на первый прототип. Дальше начинаются архитектура сцен, физика, анимация, интерфейс и публикация, и здесь помогает программа с наставником и проверкой домашних заданий. Курсы по движку собраны на странице курсов по Godot, программы шире собраны в разделе «Разработка игр».

КурсШколаСтоимость со скидкойВ рассрочкуДлитель­ностьОбзор курса от Checkroi
Профессия «Разработчик игр на Unity с нуля»
Перейти на сайт курса
SkillboxSkillbox132 445 ₽3679 ₽/мес.10 месяцевОбзор курса
Разработчик игр на Unity
Перейти на сайт курса
SkillFactorySkillFactory132 840 ₽3690 ₽/мес.12 месяцевОбзор курса
ДО Профессия Разработчик игр на Unreal Engine 5 с нуля
Перейти на сайт курса
GeekBrainsGeekBrains174 536 ₽4849 ₽/мес.6 месяцевОбзор курса
VR-разработчик на Unreal Engine 4
Перейти на сайт курса
SkillboxSkillbox31 273 ₽4588 ₽/мес.1 месяцОбзор курса
Разработчик игр на Unreal Engine
Перейти на сайт курса
Академия ЭдюсонЭдюсон135 720 ₽5655 ₽/мес.9 месяцевОбзор курса

Больше программ — в полном каталоге курсов по разработке игр

CheckroiCheckroiПодборка курсов по игровому программированию28 курсов • 14 школСравните цены, школы, программу и найдите выгодные предложения по обучениюСравнить→

Если язык для первой игры ещё не выбран, сравните варианты по списку языков программирования: там видно, где GDScript стоит рядом с C#, C++ и Python.

Часто задаваемые вопросы

GDScript похож на Python?

Похож синтаксисом: блоки задаются отступами, функции объявляются коротким словом, а условия и циклы выглядят почти так же. Библиотеки Python в GDScript не работают, зато в языке сразу есть узлы, сигналы и типы движка вроде Vector2. Если Python знаком, разберитесь сначала с его синтаксисом: многое перенесётся напрямую.

Нужно ли учить Python перед GDScript?

Нет. Документация Godot советует новичкам начинать прямо с GDScript: разработчики сделали его проще универсальных языков вроде C#. Переменные, условия и циклы можно осваивать сразу на нём.

Где найти документацию GDScript на русском?

На сайте Godot есть русский «Справочник по GDScript» с ключевыми словами, операторами и встроенными типами. Для изучения с нуля документация предлагает интерактивный курс Learn GDScript From Zero, задания которого выполняются прямо в браузере.

Можно ли писать игры на Godot на C# вместо GDScript?

Можно. C# входит в число официальных языков движка, но для него нужна отдельная сборка Godot .NET со страницы загрузки. В одном проекте можно смешивать языки: например, логику игры писать на GDScript, а тяжёлые алгоритмы на C#.

Можно ли попробовать GDScript без установки Godot?

Да. У Godot есть официальный веб-редактор, который запускается в браузере, и курс Learn GDScript From Zero с заданиями прямо на странице. Для большого проекта всё равно лучше поставить обычный редактор.

Почему код из старого урока по Godot не работает?

Скорее всего, урок написан для Godot 3. В Godot 4 убрали ключевые слова export, onready и yield, их заменили @export, @onready и await, а сигналы подключают через сигнал.connect(метод). Ошибка парсера обычно прямо называет, что заменить.

Читайте Checkroi первым в Google
Добавьте Checkroi в избранные источники — и наши разборы курсов и обзоры школ будут показываться выше в вашей выдаче Google.
Оставить комментарий
0 комментариев
Форма комментария

Оставьте комментарий

Напишите, что думаете. Нам важно ваше мнение!