명령줄(Command line) 튜토리얼

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

참고

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

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

명령줄 참조

일반 옵션

명령

서술

-h, --help, /?

명령줄 옵션 목록을 표시합니다.

--version

버전 문자열을 표시합니다.

-v, --verbose

Verbose 표준 출력 모드를 사용합니다.

--quiet

조용한 모드. 표준 출력으로 메시지를 출력하지 않습니다. 오류는 계속 표시됩니다.

실행 설정

명령

서술

-e, --editor

씬을 실행하는 대신 에디터를 시작합니다 (tools이 활성화되어 있어야 합니다).

-p, --project-manager

프로젝트가 자동으로 감지되어도, 프로젝트 매니저를 먼저 시작합니다. (tools이 켜져 있어야 합니다).

-q, --quit

첫 반복 이후에 종료합니다.

-l <locale>, --language <locale>

특정 로케일(두_단어 코드의 <locale>)을 사용합니다. 더 자세한 정보는 Locales을 참고하세요.

--path <directory>

프로젝트의 경로 (<directory>에는 'project.godot' 파일이 있어야 합니다).

-u, --upwards

'project.godot' 파일을 찾기 위해 위로 폴더를 스캔합니다.

--main-pack <file>

불러올 팩 (.pck) 파일의 경로.

--render-thread <mode>

렌더 스레드 모드 ('unsafe', 'safe', 'separate'). 더 자세한 정보는 Thread Model를 참고하세요.

--remote-fs <address>

원격 파일 시스템 (<host/IP>[:<port>] 주소).

--audio-driver <driver>

오디오 드라이버. 사용할 수 있는 드라이버 목록을 표시하려면 먼저 --help를 입력하세요.

--video-driver <driver>

비디오 드라이버. 사용할 수 있는 드라이버 목록을 표시하려면 먼저 --help를 입력하세요.

디스플레이 설정

명령

서술

-f, --fullscreen

전체화면 모드를 요청합니다.

-m, --maximized

최대화된 창을 요청합니다.

-w, --windowed

창모드를 요청합니다.

-t, --always-on-top

항상 화면 위에 고정된(always-on-top) 창을 요청합니다.

--resolution <W>x<H>

창 해상도를 요청합니다.

--position <X>,<Y>

창 위치를 요청합니다.

--low-dpi

낮은 DPI 모드를 강제합니다 (macOS와 Windows만 가능).

--no-window

창이 보이지 않도록 합니다. --script와 함께 쓰면 유용합니다.

디버그 설정

참고

디버그 설정은 에디터와 디버그 내보내기 템플릿에서만 사용할 수 있습니다 (debug 또는 release_debug 빌드 대상이 필요합니다. 더 자세한 정보는 Target(대상)을 참고하세요).

명령

서술

-d, --debug

디버그 (로컬 표준 출력 디버거).

-b, --breakpoints

브레이크포인트 목록. 소스::라인 형태로 쉼표로 구분되며, 공백이 없습니다 (공백 대신 %%20을 사용합니다).

--profiling

스크립트 디버거에서 프로파일링을 켭니다.

--remote-debug <address>

원격 디버그 (<host/IP>:<port> 주소).

--debug-collisions

씬을 실행할 때 콜리전 모양을 보여줍니다.

--debug-navigation

씬을 실행할 때 내비게이션 폴리곤을 보여줍니다.

--frame-delay <ms>

높은 CPU 점유율을 시뮬레이션합니다 (각 프레임을 <ms> 밀리초만큼 지연합니다).

--time-scale <scale>

실행 시간 규모를 제한합니다 (1.0이 기본 속도이며, 높은 값일 수록 더 빠릅니다).

--disable-render-loop

렌더 루프를 끕니다. 따라서 스크립트에서 명시적으로 호출할 때만 렌더링을 합니다.

--disable-crash-handler

플랫폼 코드가 지원하는 경우 충돌 핸들러를 끕니다.

--fixed-fps <fps>

FPS(초당 프레임)을 고정된 숫자로 제한합니다. 이 설정은 실시간 동기화를 끕니다.

--print-fps

표준 출력에 FPS(초당 프레임)를 프린트합니다.

독립형 툴

명령

서술

-s <script>, --script <script>

스크립트를 실행합니다.

--check-only

오류만 구문 분석하고 종료합니다 (--script와 함께 사용합니다).

--export <target>

주어진 내보내기 대상을 사용해서 프로젝트를 내보냅니다. 경로가 .pck나 .zip으로 확장자 이름으로 끝나는 경우, 메인 팩만 내보냅니다 (tools(툴)이 활성화되어 있어야 합니다).

--export-debug <target>

--export와 비슷하지만 디버그 템플릿을 사용합니다 (tools(툴)이 활성화되어 있어야 합니다).

--doctool <path>

엔진 API 참조를 주어진 <경로>에 XML 형식으로 덤프합니다. 이미 해당 파일이 있다면 병합합니다. (tools(툴)이 활성화되어 있어야 합니다).

--no-docbase

기본 유형을 덤프하는 것을 허가하지 않습니다 (--doctool과 함께 쓰며, tools(툴)이 활성화되어 있어야 합니다).

--build-solutions

스크립팅 솔루션을 빌드합니다 (예: C# 프로젝트 용. tools(툴)이 활성화되어 있어야 합니다).

--gdnative-generate-json-api

GDNative 바인딩을 위해 Godot API의 JSON 덤프를 만듭니다 (tools(툴)이 활성화되어 있어야 합니다).

--test <test>

단위 테스트를 실행합니다. 테스트 목록을 표시하려면 --help를 먼저 사용하세요. (tools(툴)이 활성화되어 있어야 합니다).

--export-pack <preset> <path>

--export와 비슷하지만 주어진 사전 설정에 대한 게임 팩만 내보냅니다. <path> 확장자는 PCK 형식인지 ZIP 형식인지 여부를 결정합니다. (tools(툴)이 활성화되어 있어야 합니다).

경로

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

프로젝트 경로 설정하기

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 --path path_to_your_project --export my_export_preset_name game.exe

프로젝트 생성하기

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

mkdir newgame
cd newgame
touch project.godot

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

에디터 실행하기

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

godot -e

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

godot -e scene.tscn

씬 지우기

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

rm scene.tscn

게임 실행하기

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

godot

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

godot scene.tscn

디버깅

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

godot -d
godot -d scene.tscn

내보내기(Exporting)

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

godot --export "Linux/X11" /var/builds/project
godot --export 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가 지정되지 않는 한) 현재 작업 디렉토리로 가정합니다.

sayhello.gd의 첫 번째 줄은 일반적으로 shebang이라고 합니다. Godot 바이너리가 PATHgodot로 존재한다면, 최신 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