kjaylee/godot

Godot Engine Skill

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-design when you need to define the game concept, loops, and system design before implementation.
• Use game-dev-rust-godot when you need full pipeline governance across assets/tests/shipping, not only engine-specific guidance.

Godot 4.x 게임 엔진 개발을 위한 종합 가이드. 프로젝트 생성부터 빌드, GDScript 코딩, Scene/Node 시스템, 2D/3D 게임 제작까지 전 과정을 지원합니다.

🚀 Quick Start

신규 프로젝트 생성 (CLI)

# MiniPC에서 실행 (Godot 4.6 설치됨)
cd $HOME/
godot4 --headless --path . --create-project "MyGame"

# 또는 맥 스튜디오에서 원격 실행
# (nodes.run 또는 ssh 사용)

프로젝트 구조

MyGame/
├── project.godot       # 프로젝트 설정
├── scenes/             # 씬 파일 (.tscn)
│   ├── main.tscn
│   ├── player.tscn
│   └── enemy.tscn
├── scripts/            # GDScript 파일
│   ├── player.gd
│   └── enemy.gd
├── assets/             # 에셋 (텍스처, 사운드 등)
│   ├── sprites/
│   ├── sounds/
│   └── fonts/
└── export_presets.cfg  # 빌드 설정

첫 씬 생성

1. Node2D (2D 게임) 또는 Node3D (3D 게임) 루트 노드 생성
2. 자식 노드 추가 (Sprite2D, CharacterBody2D, Camera2D 등)
3. 스크립트 첨부 (Attach Script)
4. _ready(), _process(delta) 함수 작성

📚 GDScript Basics

핵심 라이프사이클 함수

extends Node2D

# 씬 트리 진입 시 1회 호출
func _ready():
    print("Ready!")

# 매 프레임 호출 (delta = 프레임 시간)
func _process(delta):
    position.x += 100 * delta  # 초당 100픽셀 이동

# 물리 프레임마다 호출 (고정 간격)
func _physics_process(delta):
    move_and_slide()

변수 & 타입

# 타입 추론
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 접근

# 자식 노드 가져오기
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

플레이어 이동 (8방향)

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()

애니메이션 (AnimatedSprite2D)

@onready var anim = $AnimatedSprite2D

func _process(delta):
    if velocity.length() > 0:
        anim.play("walk")
    else:
        anim.play("idle")

충돌 감지 (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()  # 자신 제거

TileMap 사용

@onready var tilemap = $TileMap

func _ready():
    # 타일 좌표 (0, 0)에 타일 ID 1 배치
    tilemap.set_cell(0, Vector2i(0, 0), 1)

🌍 3D Game Workflows

FPS 플레이어 컨트롤러

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()

카메라 회전 (마우스)

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

씬 전환

# 다음 씬으로 이동
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)

타이머

# 타이머 노드 사용
@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) 애니메이션

func fade_out():
    var tween = create_tween()
    tween.tween_property($Sprite2D, "modulate:a", 0.0, 1.0)  # 1초간 투명화

UI 업데이트

extends Control

@onready var label = $Label

func update_score(score):
    label.text = "Score: %d" % score

🏗️ 빌드 & Export (MiniPC)

Web (HTML5) 빌드

cd $HOME/
godot4 --headless --path MyGame --export-release "Web" output/index.html

Export Preset 설정 (project.godot)

[export]
name="Web"
platform="Web"
runnable=true
export_path="export/web/index.html"

커스텀 부트 스플래시

# East Sea Games 로고 사용
cp $HOME/godot-demo/boot_splash.png MyGame/

📖 References

자주 쓰는 노드

• 2D: Node2D, Sprite2D, CharacterBody2D, RigidBody2D, Area2D, Camera2D, TileMap, AnimatedSprite2D
• 3D: Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, Area3D, Camera3D
• UI: Control, Label, Button, Panel, HBoxContainer, VBoxContainer
• 오디오: AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D
• 기타: Timer, AnimationPlayer, CollisionShape2D/3D

유용한 링크

• Godot 공식 문서
• GDQuest 튜토리얼
• First 2D Game 튜토리얼

References 디렉토리

• references/gdscript-cheatsheet.md: GDScript 문법 치트시트
• references/nodes-reference.md: 자주 쓰는 노드 목록
• references/best-practices.md: Godot 베스트 프랙티스
• references/2d-patterns.md: 2D 게임 공통 패턴
• references/3d-patterns.md: 3D 게임 공통 패턴

---

Version: 1.0.0
Author: Miss Kim
Date: 2026-02-05