When to Use This vs Others
- Use this (
godot) for hands-on Godot engine execution: Scene/Node architecture, GDScript coding, export/debug workflows. - Use
game-designwhen you need to define the game concept, loops, and system design before implementation. - Use
game-dev-rust-godotwhen you need full pipeline governance across assets/tests/shipping, not only engine-specific guidance.
A comprehensive guide for Godot 4.x game engine development. Supports the entire process from project creation to build, GDScript coding, Scene/Node system, and 2D/3D game development.
🚀 Quick Start
Create New Project (CLI)
# MiniPC에서 실행 (Godot 4.6 설치됨)
cd $HOME/
godot4 --headless --path . --create-project "MyGame"
### 프로젝트 구조
MyGame/ ├── project.godot # Project settings ├── scenes/ # Scene files (.tscn) │ ├── main.tscn │ ├── player.tscn │ └── enemy.tscn ├── scripts/ # GDScript files │ ├── player.gd │ └── enemy.gd ├── assets/ # Assets (textures, sounds, etc.) │ ├── sprites/ │ ├── sounds/ │ └── fonts/ └── export_presets.cfg # Build settings
### 첫 씬 생성
1. **Node2D** (2D 게임) 또는 **Node3D** (3D 게임) 루트 노드 생성
2. 자식 노드 추가 (Sprite2D, CharacterBody2D, Camera2D 등)
3. 스크립트 첨부 (Attach Script)
4. `_ready()`, `_process(delta)` 함수 작성
## 📚 GDScript Basics
### 핵심 라이프사이클 함수
```gdscript
extends Node2D
# 씬 트리 진입 시 1회 호출
func _ready():
print("Ready!")
# 매 프레임 호출 (delta = 프레임 시간)
func _process(delta):
position.x += 100 * delta # 초당 100픽셀 이동
# 물리 프레임마다 호출 (고정 간격)
func _physics_process(delta):
move_and_slide()
Variables & Types
# 타입 추론
var speed := 200.0 # float
var health := 100 # int
var player_name := "Hero" # String
# 명시적 타입
var velocity: Vector2 = Vector2.ZERO
var sprite: Sprite2D
# @export로 에디터 노출
@export var max_speed: float = 300.0
@export_range(0, 100) var hp: int = 100
Signal
# 신호 정의
signal health_changed(new_health)
signal player_died
# 신호 발생
func take_damage(amount):
health -= amount
health_changed.emit(health)
if health <= 0:
player_died.emit()
# 다른 스크립트에서 연결
func _ready():
$Player.health_changed.connect(_on_player_health_changed)
func _on_player_health_changed(new_health):
print("Health: ", new_health)
Node Access
# 자식 노드 가져오기
var sprite = $Sprite2D
var label = get_node("Label")
# 부모/형제 접근
var parent = get_parent()
var sibling = get_parent().get_node("OtherNode")
# 씬 전역 접근 (Autoload)
GlobalScript.some_function()
🎮 2D Game Workflows
Player Movement (8-directional)
extends CharacterBody2D
@export var speed = 300.0
func _physics_process(delta):
var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
velocity = input_dir * speed
move_and_slide()
Animation (AnimatedSprite2D)
@onready var anim = $AnimatedSprite2D
func _process(delta):
if velocity.length() > 0:
anim.play("walk")
else:
anim.play("idle")
Collision Detection (Area2D)
extends Area2D
func _ready():
body_entered.connect(_on_body_entered)
func _on_body_entered(body):
if body.is_in_group("player"):
print("Player entered!")
queue_free() # 자신 제거
Using TileMap
@onready var tilemap = $TileMap
func _ready():
# 타일 좌표 (0, 0)에 타일 ID 1 배치
tilemap.set_cell(0, Vector2i(0, 0), 1)
🌍 3D Game Workflows
FPS Player Controller
extends CharacterBody3D
@export var speed = 5.0
@export var jump_velocity = 4.5
var gravity = ProjectSettings.get_setting("physics/3d/default_gravity")
func _physics_process(delta):
# 중력
if not is_on_floor():
velocity.y -= gravity * delta
# 점프
if Input.is_action_just_pressed("ui_accept") and is_on_floor():
velocity.y = jump_velocity
# 이동
var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
var direction = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()
velocity.x = direction.x * speed
velocity.z = direction.z * speed
move_and_slide()
Camera Rotation (Mouse)
extends Camera3D
@export var sensitivity = 0.003
func _ready():
Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
func _input(event):
if event is InputEventMouseMotion:
rotation.y -= event.relative.x * sensitivity
rotation.x -= event.relative.y * sensitivity
rotation.x = clamp(rotation.x, -PI/2, PI/2)
🛠️ Common Patterns
Scene Transition
# 다음 씬으로 이동
get_tree().change_scene_to_file("res://scenes/level2.tscn")
# 씬 인스턴스 생성
var enemy_scene = preload("res://scenes/enemy.tscn")
var enemy = enemy_scene.instantiate()
add_child(enemy)
Timer
# 타이머 노드 사용
@onready var timer = $Timer
func _ready():
timer.timeout.connect(_on_timer_timeout)
timer.start(2.0) # 2초 후 신호 발생
func _on_timer_timeout():
print("Timer finished!")
Tween Animation
func fade_out():
var tween = create_tween()
tween.tween_property($Sprite2D, "modulate:a", 0.0, 1.0) # 1초간 투명화
UI Update
extends Control
@onready var label = $Label
func update_score(score):
label.text = "Score: %d" % score
🏗️ Build & Export (MiniPC)
Web (HTML5) Build
cd $HOME/
godot4 --headless --path MyGame --export-release "Web" output/index.html
Export Preset Settings (project.godot)
[export]
name="Web"
platform="Web"
runnable=true
export_path="export/web/index.html"
Custom Boot Splash
# East Sea Games 로고 사용
cp $HOME/godot-demo/boot_splash.png MyGame/
📖 References
Commonly Used Nodes
- 2D: Node2D, Sprite2D, CharacterBody2D, RigidBody2D, Area2D, Camera2D, TileMap, AnimatedSprite2D
- 3D: Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, Area3D, Camera3D
- UI: Control, Label, Button, Panel, HBoxContainer, VBoxContainer
- Audio: AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D
- Other: Timer, AnimationPlayer, CollisionShape2D/3D
Useful Links
References Directory
references/gdscript-cheatsheet.md: GDScript Syntax Cheat Sheetreferences/nodes-reference.md: List of Commonly Used Nodesreferences/best-practices.md: Godot Best Practicesreferences/2d-patterns.md: Common 2D Game Patternsreferences/3d-patterns.md: Common 3D Game Patterns
Version: 1.0.0
Author: Miss Kim
Date: 2026-02-05