Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

명령줄 튜토리얼

일부 개발자들은 명령줄을 광범위하게 사용하는 것을 좋아합니다. Godot는 이들에게 친숙하도록 설계되었고, 여기에는 완전히 명령줄으로만 작업하는 단계가 설명되어 있습니다. 엔진은 외부 라이브러리에 거의 의존하지 않으므로 초기화 시간이 매우 빨라서 이 워크플로에 적합합니다.

참고

Windows와 Linux의 터미널에서 상대 또는 절대 경로로 Godot 바이너리를 실행할 수 있습니다.

macOS에서는 Godot가 .app 번들(파일이 아닌 폴더)에 포함되어 있기 때문에 프로세스가 다릅니다. macOS의 터미널에서 Godot 바이너리를 실행하려면 Godot 애플리케이션 번들이 있는 폴더로 cd한 다음 Godot.app/Contents/MacOS/Godot 뒤에 인수를 넣어 명령줄을 실행해야 합니다. 애플리케이션 번들의 이름을 Godot에서 다른 이름으로 변경했다면 이 명령줄을 적절하게 편집해야 합니다.

명령줄 참조

범례

• 편집기 빌드, 디버그 내보내기 템플릿 및 릴리스 내보내기 템플릿에서 사용할 수 있습니다.

• 편집기 빌드 및 디버그 내보내기 템플릿에서만 사용할 수 있습니다.

• 편집기 빌드에서만 사용할 수 있으며 ``disable_path_overrides=false``로 컴파일된 템플릿을 내보냅니다.

• 에디터 빌드에서만 사용할 수 있습니다.

알 수 없는 명령줄 인수는 아무런 영향을 미치지 않습니다. 주어진 빌드 유형에 존재하지 않는 명령줄 인수를 사용할 때 엔진은 경고를 표시하지 않습니다.

일반 옵션

명령	설명
-h, --help	명령줄 옵션의 목록을 표시합니다.
--version	버전 문자열을 표시합니다.
-v, --verbose	버보스 표준 출력 모드를 사용합니다.
-q, --quiet	조용한 모드. 표준 출력으로 메시지를 출력하지 않습니다. 오류는 계속 표시됩니다.
--no-header	시작 시 엔진 버전 및 렌더링 방법 헤더를 인쇄하지 않습니다.

실행 옵션

명령	설명
--, ++	사용자가 제공한 인수에 대한 구분 기호입니다. 다음 인수는 엔진에서 사용되지 않지만 ``OS.get_cmdline_user_args()``에서 읽을 수 있습니다.
-e, --editor	씬을 실행하는 대신 편집기를 시작하십시오.
-p, --project-manager	프로젝트가 자동으로 감지되어도 프로젝트 매니저를 시작합니다.
--recovery-mode	"도구 스크립트, 편집기 플러그인, GDExtension 애드온 등과 같이 일반적으로 시작 충돌을 일으킬 수 있는 기능을 비활성화하는 복구 모드에서 편집기를 시작합니다.
--debug-server <uri>	에디터 디버그 서버 시작(<protocol>://<host/IP>[:<port>], 예: tcp://127.0.0.1:6007)
--dap-port <포트>	GDScript 디버그 어댑터 프로토콜에 지정된 포트를 사용합니다. 권장 포트 범위 [1024, 49151].
--lsp-port <포트>	GDScript 언어 서버 프로토콜에 지정된 포트를 사용합니다. 권장 포트 범위 [1024, 49151].
--quit	첫 반복 이후에 종료합니다.
--quit-after	지정된 반복 횟수 후에 종료합니다. 비활성화하려면 0으로 설정합니다.
-l, --language <로케일>	특정 로케일을 사용합니다. <로케일>은 language_Script_COUNTRY_VARIANT 형식을 따르는데 여기서 language는 소문자로 된 2 또는 3글자 언어 코드이고 나머지는 선택 사항입니다. 자세한 사항은 로컬 좌표을 참조하세요.
--path <디렉터리>	프로젝트의 경로 (<directory>에는 'project.godot' 파일이 있어야 합니다).
scene <경로>	시작해야 하는 프로젝트에서 씬의 경로 또는 UID입니다.
--main-pack <파일>	불러올 팩 (.pck) 파일의 경로.
--render-thread <모드>	렌더 스레드 모드 ('unsafe', 'safe', 'separate'). 자세한 사항은 스레드 모델을 참조하세요.
--remote-fs <주소>	원격 파일시스템 (<host/IP>[:<port>] 주소).
--remote-fs-password <암호>	원격 파일시스템에 대한 암호.
--audio-driver <드라이버>	오디오 드라이버. 사용 가능한 드라이버의 목록을 표시하려면 먼저 --help를 입력하세요.
--display-driver <드라이버>	비디오 드라이버. 사용 가능한 드라이버의 목록을 표시하려면 먼저 --help를 입력하세요.
--audio-output-latency <ms>	오디오 출력 대기 시간을 밀리초 단위로 재정의합니다(기본값은 15ms). 값이 낮을수록 사운드 재생의 반응성이 높아지지만 CPU 사용량이 증가하고 CPU가 따라잡지 못하는 경우 오디오 균열이 발생할 수 있습니다.
--rendering-method <렌더러>	Renderer name. Valid values are forward_plus, mobile, and gl_compatibility. Requires driver support.
--rendering-driver <드라이버>	비디오 드라이버. 사용 가능한 드라이버의 목록을 표시하려면 먼저 --help를 입력하세요.
--gpu-index <기기_인덱스>	Use a specific GPU (only available on the Forward+/Mobile renderers; run with --verbose to get available device list).
--text-driver <드라이버>	텍스트 드라이버(글꼴, BiDi, 쉐이핑).
--tablet-driver <드라이버>	펜 태블릿 입력 드라이버.
--headless	헤드리스 모드(--display-driver headless --audio-driver Dummy)를 활성화합니다. 서버 및 ``--script``에 유용합니다.
--log-file	프로젝트에서 정의한 기본 위치 대신 지정된 경로에 출력/오류 로그를 씁니다. <file> 경로는 프로젝트 디렉터리에 대해 절대 또는 상대 경로여야 합니다.
--write-movie <파일>	영화를 작성하는 방식(보통 .avi 또는 .png 확장자)으로 엔진을 실행합니다. ``--fixed-fps``는 활성화되면 강제되지만 영화 FPS를 변경하는 데 사용할 수 있습니다. ``--disable-vsync``는 동영상 작성 속도를 높일 수 있지만 상호 작용을 더욱 어렵게 만듭니다. ``--quit-after``는 쓸 프레임 수를 지정하는 데 사용할 수 있습니다.

표시 옵션

명령	설명
-f, --fullscreen	전체화면 모드를 요청합니다.
-m, --maximized	최대화된 창을 요청합니다.
-w, --windowed	창 모드를 요청합니다.
-t, --always-on-top	창을 항상 위에 요청합니다.
--resolution <너비>x<높이>	창 해상도를 요청합니다.
--position <X>,<Y>	창 위치를 요청합니다.
--screen <N>	창 화면을 요청합니다.
--single-window	단일 창을 사용합니다 (별도의 하위 창 없음).
--xr-mode <모드>	XR 모드를 선택합니다 ('default', 'off', 'on').
--wid <창_id>	창에 부모로 지정되도록 요청합니다.
--accessibility <모드>	접근성 모드를 선택합니다 ['auto' (스크린 리더가 실행 중일 때, 디폴트), 'always', 'disabled'].

디버그 옵션

명령	설명
-d, --debug	디버그 (로컬 표준 출력 디버거).
-b, --breakpoints	중단점은 소스::줄의 쉼표로 구분된 쌍으로 나열하며 공백이 없습니다 (대신 %20을 사용합니다).
--ignore-error-breaks	디버거가 연결되어 있으면 오류 중단점을 보내는 것을 방지합니다.
--profiling	스크립트 디버거에서 프로파일링을 활성화합니다.
--gpu-profile	프레임 렌더링 중 가장 많은 시간이 소요된 작업의 GPU 프로필을 보여줍니다.
--gpu-validation	디버깅을 위해 그래픽 API 검증 레이어를 활성화합니다.
--gpu-abort	GPU 오류(일반적으로 검증 계층 오류)로 인해 중단하면 시스템이 정지될 때 문제를 보는 데 도움이 될 수 있습니다.
--generate-spirv-debug-info	SPIR-V 디버그 정보를 생성합니다. 이를 통해 RenderDoc로 소스 수준 셰이더 디버깅을 허용합니다.
--extra-gpu-memory-tracking	추가 메모리 추적을 활성화합니다 (RenderingDevice.get_driver_and_device_memory_report() 및 연결된 메서드에 대한 클래스 참조를 참조하세요). 현재는 Vulkan에만 구현되어 있습니다. 이 기능을 활성화하면 버그가 있는 드라이버나 Vulkan 로도의 버그로 인해 일부 시스템에서 충돌이 발생할 수 있습니다. https://github.com/godotengine/godot/issues/95967을 참조하세요.
--accurate-breadcrumbs	빵가루 사이에 강제 장벽을 생성합니다. GPU 재설정을 일으키는 명령을 좁히는 데 유용합니다. 현재 Vulkan에만 구현되어 있습니다.
--remote-debug <uri>	원격 디버깅 (<프로토콜>://<호스트/IP>[:<포트>], 예: tcp://127.0.0.1:6007).
--single-threaded-scene	씬 트리는 단일 스레드 모드로 실행됩니다. 하위 스레드 그룹은 비활성화되고 메인 스레드에서 실행됩니다.
--debug-collisions	씬을 실행할 때 콜리전 모양을 보여줍니다.
--debug-paths	씬을 실행할 때 경로 줄을 보여줍니다.
--debug-navigation	씬을 실행할 때 내비게이션 폴리곤을 보여줍니다.
--debug-avoidance	씬을 실행할 때 내비게이션 어보이던스 디버그 비주얼을 보여줍니다.
--debug-stringnames	엔진이 종료될 때 모든 StringName 할당을 포준 출력에 출력합니다.
--debug-canvas-item-redraw	캔버스 항목에서 리드로우를 요청할 때마다 사각형을 표시합니다 (저사양 모드 문제를 해결하는 데 유용함).
--max-fps <fps>	초당 렌더링되는 최대 프레임의 수를 설정합니다 (전력 사용량을 제한하는 데 사용 가능). 값이 0이면 프레임 속도가 제한이 없게 됩니다.
--frame-delay <ms>	높은 CPU 점유률을 시뮬레이션합니다 (각 프레임을 <ms>밀리초씩 지연). FPS 제한으로 사용하지 마세요. 대신 --max-fps를 사용하세요.
--time-scale <스케일>	시간 스케일를 강제합니다 (값이 높을수록 더 빠르고, 1.0은 보통 속도).
--disable-vsync	프로젝트 설정에서 활성화된 경우에도 수직 동기화를 강제로 비활성화합니다. 드라이버 수준의 수직 동기화 시행을 오버라이드하지 않습니다.
--disable-render-loop	렌더 루프를 비활성화하여 스크립트에서 명시적으로 호출될 때만 렌더링이 발생하도록 합니다.
--disable-crash-handler	플랫폼 코드에서 지원하는 경우 충돌 핸들러를 비활성화합니다.
--fixed-fps <fps>	초당 프레임 수를 고정된 숫자로 강제합니다. 이 설정은 실시간 동기화가 비활성화됩니다.
--delta-smoothing <enable>	프레임 델타 스무딩을 활성화하거나 비활성화합니다 ('enable', 'disable').
--print-fps	초당 프레임을 표준 출력에 출력합니다.
--editor-pseudolocalization	편집기와 프로젝트 매니저에 대한 의사 현지화를 활성화합니다.

독립형 툴

명령	설명
-s, --script <스크립트>	스크립트를 실행합니다. <script>``는 프로젝트에 상대적인 리소스 경로(``myscript.gd``는 ``res://my_script.gd``로 해석됨) 또는 절대 파일 시스템 경로(예: Windows: ``C:/tmp/my_script.gd)여야 합니다.
--main-loop <메인_루프_이름>	전역 클래스 이름으로 지정된 MainLoop를 실행합니다.
--check-only	오류만 구문 분석하고 종료합니다 (--script와 함께 사용합니다).
--import	편집기를 시작하고 리소스를 가져올 때까지 기다린 다음 종료합니다. --editor 및 ``--quit``를 의미합니다.
--export-release <프리셋> <경로>	주어진 사전 설정 및 출력 경로를 사용하여 릴리스 모드에서 프로젝트를 내보냅니다. 사전 설정 이름은 "export_presets.cfg"에 정의된 이름과 일치해야 합니다. ``<path>``는 프로젝트 디렉터리에 대해 절대적이거나 상대적이어야 하며 바이너리의 파일 이름(예: "builds/game.exe")을 포함해야 합니다. 대상 디렉터리가 존재해야 합니다.
--export-debug <프리셋> <경로>	``--export-release``와 비슷하지만 디버그 템플릿을 사용합니다. ``--import``를 의미합니다.
--export-pack <프리셋> <경로>	--export-release와 비슷하지만, 주어진 프리셋에 대한 게임 팩만 내보냅니다. <경로> 확장자는 PCK 또는 ZIP 형식인지 여부를 결정합니다. --import를 암시합니다.
--export-patch <프리셋> <경로>	변경된 파일만 포함하여 팩을 내보냅니다. 다른 고려 사항은 --export-pack 설명을 참조하세요.
--patches <경로>	``--export-patch``와 함께 사용할 패치 목록입니다. 목록은 쉼표로 구분됩니다.
--install-android-build-template	Android 빌드 템플릿을 설치합니다. --export-release 또는 ``--export-debug``와 함께 사용됩니다.
--convert-3to4 [<최대_파일_kb>] [<최대_줄_크기>]	프로젝트를 Godot 3.x에서 Godot 4.x로 변환하세요.
--validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]	프로젝트를 Godot 3.x에서 Godot 4.x로 변환할 때 어떤 요소의 이름이 바뀌는지 보여줍니다.
--doctool [<경로>]	엔진 API 참조를 지정된 <경로>에 엔진 API 참조를 XML 형식으로 덤프하고, 기존 파일이 발견되면 병합합니다.
--no-docbase	기본 유형 덤프를 허용하지 않습니다(``--doctool``와 함께 사용됨).
--dump-extension-api	엔진 API를 덤프하는 대신 현재 프로젝트에 로드된 모든 GDExtensions(``--doctool``와 함께 사용)에서 API 참조를 생성하세요.
--gdscript-docs <경로>	엔진 API를 덤프하는 대신 <path>``(--doctool``와 함께 사용)에 있는 GDScript 파일의 인라인 문서에서 API 참조를 생성하세요.
--build-solutions	스크립팅 솔루션을 구축합니다(예: C# 프로젝트용). ``--editor``를 암시하며 편집하려면 유효한 프로젝트가 필요합니다.
--dump-gdextension-interface	현재 폴더에 GDExtension 헤더 파일 "gdextension_interface.h"를 생성합니다. 이 파일은 GDExtension을 구현하는 데 필요한 기본 파일입니다.
--dump-gdextension-interface	현재 폴더에 "gdextension_interface.json"이라는 GDExtension 인터페이스의 JSON 덤프를 생성합니다.
--dump-extension-api	현재 폴더에 "extension_api.json"이라는 GDExtension 바인딩용 Godot API의 JSON 덤프를 생성합니다.
--dump-extension-api	이전 옵션과 마찬가지로 Godot API의 JSON 덤프를 생성하지만 문서도 포함합니다.
--validate-extension-api <경로>	이전 버전의 엔진에서 덤프된 확장 API 파일(위 옵션 사용)을 검증하여 API 호환성을 보장합니다. 비호환성 또는 오류가 감지되면 반환 코드는 0이 아닙니다.
--benchmark	런타임을 벤치마크하고 콘솔에 인쇄합니다.
--benchmark-file <경로>	런타임을 벤치마킹하고 JSON 형식으로 지정된 파일에 저장합니다. 경로는 절대 경로여야 합니다.
--test [--help]	단위 테스트 <doc_unit_testing>`을 실행합니다(``tests=yes``로 엔진을 컴파일해야 함). 자세한 내용은 `--test --help``를 사용하세요.

경로

Godot 바이너리의 경로를 PATH 환경 변수에 넣어서 godot를 입력하면 어느 곳에서든지 쉽게 실행하는 것을 권장합니다. Linux에서는 Godot 바이너리를 /usr/local/bin에 배치해서 godot를 입력하면 실행되게 할 수 있습니다.

Windows 또는 macOS에서 이를 쉽게 달성하려면 `Scoop <https://scoop.sh>`__(Windows) 또는 `Homebrew <https://brew.sh>`__(macOS)을 사용하여 Godot를 설치할 수 있습니다. 그러면 자동으로 설치된 Godot의 복사본이 ``PATH``에 사용 가능하게 됩니다:

WindowsmacOS

# Add "Extras" bucket
scoop bucket add extras

# Standard editor:
scoop install godot

# Editor with C# support (will be available as `godot-mono` in `PATH`):
scoop install godot-mono

프로젝트 경로 설정하기

Godot 바이너리의 위치와 현재 작업 디렉터리의 위치에 따라, 다음 명령이 올바르게 작동하려면 프로젝트의 경로를 설정해야 합니다.

다음과 같이 프로젝트의 project.godot 파일 경로를 첫 번째 인수로 주면 됩니다:

godot path_to_your_project/project.godot [other] [commands] [and] [args]

혹은 --path 인자를 사용합니다:

godot --path path_to_your_project [other] [commands] [and] [args]

예를 들어, (아래에서 설명할) 게임을 내보내는 전체 명령은 다음과 같을 것입니다:

godot --headless --path path_to_your_project --export-release my_export_preset_name game.exe

프로젝트의 하위 디렉터리에서 시작할 때 Godot의 --upwards 인수를 사용하면 상위 디렉터리를 재귀적으로 검색하여 project.godot 파일을 자동으로 찾을 수 있습니다.

예를 들어, 하위 디렉터리에 중첩된 씬(아래 설명 참조)를 실행하는 것은 작업 디렉터리가 동일한 경로에 있을 때 다음과 같을 수 있습니다.

godot --upwards nested_scene.tscn

프로젝트 만들기

명령줄에서 프로젝트를 생성하려면 셸을 원하는 위치로 이동하고 project.godot 파일을 만드세요.

mkdir newgame
cd newgame
touch project.godot

프로젝트는 이제 Godot로 열 수 있습니다.

편집기 실행하기

Godot를 -e 플래그로 실행하면 편집기가 실행됩니다. 이 작업은 프로젝트 디렉터리 또는 하위 디렉터리에서 수행해야 합니다, 그렇지 않으면 명령이 무시되고 프로젝트 매니저가 나타납니다.

godot -e

project.godot 파일에 대한 전체 경로를 전달할 때 -e 플래그는 생략될 수 있습니다.

씬을 만들고 저장하면 나중에 해당 씬을 인수로 사용해 동일한 코드를 실행해서 편집할 수 있습니다.

godot -e scene.tscn

씬 지우기

Godot는 여러분의 파일시스템에 친화적이고 추가적인 메타데이터 파일을 만들지 않습니다. 씬 파일을 지우려면 rm을 사용하세요. 지울 씬을 참조하는 게 있다면 열 때 오류가 발생할 것입니다.

rm scene.tscn

게임 실행하기

게임을 실행하려면, 프로젝트 디렉터리나 하위 디렉터리에서 Godot를 실행하면 됩니다.

godot

project.godot 파일을 전달하면 게임을 실행하는 대신 항상 편집기가 실행됩니다.

특정 씬을 테스트해야 하는 경우 씬을 명령줄로 전달하세요.

godot scene.tscn

디버깅

명령줄에서는 오류가 기록되지 않기 때문에 오류를 잡는 것이 어려운 작업이 될 수 있습니다. 이를 위해 명령줄은 d옵션을 통해 디버거를 제공합니다. 게임이나 간단한 씬을 디버깅할 수 있습니다.

godot -d

godot -d scene.tscn

내보내기

명령줄에서 프로젝트를 내보내는 것도 지원됩니다. 특히 연속적인 통합(CI: Continuous Integration) 설정에 유용합니다. Godot의 헤드리스 버전(서버 빌드, 비디오 없음)은 이런 점에서 이상적입니다.

참고

GPU 액세스 권한이 없는 플랫폼(예: 지속적 통합)에서는 --headless 명령줄 인수를 사용해야 합니다**. GPU 액세스가 가능한 플랫폼에서 ``--headless``는 프로젝트를 내보내는 동안 창이 생성되는 것을 방지합니다.

# `godot` must be a Godot editor binary, not an export template.
# Also, export templates must be installed for the editor
# (or a valid custom export template must be defined in the export preset).
godot --headless --export-release "Linux/X11" /var/builds/project
godot --headless --export-release Android /var/builds/project.apk

프리셋 이름은 프로젝트의 export_presets.cfg 파일에 정의된 내보내기 프리셋의 이름과 일치해야 합니다. 프리셋 이름에 공백이나 특수 문자(예: "Windows 바탕화면")가 포함된 경우 따옴표로 묶어야 합니다.

게임의 디버그 버전을 내보내기 위해, --export 대신 --export-debug 스위치를 사용하세요. 매개변수와 사용법은 동일합니다.

PCK 파일만 내보내려면 내보내기 경로, 프리셋 이름, 파일 확장자 앞에 --export 대신 --export-pack 옵션을 사용하세요. 내보내기 경로 확장자는 패키지의 형식(PCK 또는 ZIP)을 결정합니다.

경고

--export, --export-debug 또는 --export-pack의 경로로 상대 경로를 지정할 때 경로는 project.godot 파일이 포함된 디렉터리에 상대적이므로, 현재 작업 디렉터리와 관련이 없습니다.

스크립트 실행하기

명령줄에서 .gd 스크립트를 간단하게 실행할 수 있습니다.특히 일괄 변환 또는 커스텀 불러오기/내보내기를 위한, 큰 프로젝트에서 유용합니다.

스크립트는 SceneTree 또는 MainLoop를 상속받아야 합니다.

다음은 작동 방식에 대한 간단한 sayhello.gd 예제입니다:

#!/usr/bin/env -S godot -s
extends SceneTree

func _init():
    print("Hello!")
    quit()

그리고 어떻게 실행하는 지에 대한 예제입니다:

# Prints "Hello!" to standard output.
godot -s sayhello.gd

project.godot가 경로에 존재하지 않으면, 현재 경로는 (-path가 지정되지 않는 한) 현재 작업 디렉터리로 가정합니다.

스크립트 경로는 프로젝트와 관련된 리소스 경로(여기서는 res://sayhello.gd)로 해석됩니다. 대신 절대 파일 시스템 경로를 사용할 수도 있습니다. 이는 스크립트가 프로젝트 디렉터리 외부에 있는 경우 유용합니다.

위 sayhello.gd의 첫 번째 줄은 일반적으로 shebang이라고 합니다. Godot 바이너리가 PATH에 godot로 존재한다면, 최신 Linux 배포판과 macOS에서 다음과 같이 스크립트를 실행할 수 있습니다:

# Mark script as executable.
chmod +x sayhello.gd
# Prints "Hello!" to standard output.
./sayhello.gd

위의 내용이 현재 버전의 Linux 또는 macOS에서 작동하지 않으면 다음과 같이 Shebang이 있는 위치에서 바로 Godot를 실행하도록 할 수 있습니다:

#!/usr/bin/godot -s