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 프로젝트 내에서 파일 경로가 어떻게 작동하는지 설명합니다. res:// 및 user:// 표기법을 사용하여 프로젝트의 경로에 액세스하는 방법과 Godot가 귀하와 귀하의 사용자 시스템에서 프로젝트 및 편집기 파일을 저장하는 위치를 배우게 됩니다.

경로 구분 기호

여러 플랫폼을 더 쉽게 지원하기 위해 Godot는 UNIX 스타일 경로 구분 기호**(슬래시 ``/``)를 사용합니다. 이는 **Windows를 포함한 모든 플랫폼에서 작동합니다.

Godot에서는 ``C:ProjectsGame``와 같은 경로를 작성하는 대신 ``C:/Projects/Game``를 작성해야 합니다.

Windows 스타일 경로 구분 기호(역슬래시 \)도 일부 경로 관련 방법에서 지원되지만 \``는 일반적으로 특별한 의미가 있는 문자에 대한 이스케이프로 사용되므로 이중으로 사용해야 합니다(\``).

이렇게 하면 다른 Windows 응용 프로그램에서 반환된 경로로 작업할 수 있습니다. 모든 것이 의도한 대로 작동하도록 하려면 코드에 슬래시만 사용하는 것이 좋습니다.

팁

String 클래스는 파일 경로를 나타내는 문자열로 작업할 수 있는 12가지 이상의 메서드를 제공합니다.

함수에 이 코드를 추가하세요:

Godot는 파일이 비어 있더라도 project.godot 텍스트 파일이 포함된 모든 폴더에 프로젝트가 존재한다고 간주합니다. 이 파일이 포함된 폴더는 프로젝트의 루트 폴더입니다.

리소스를 나타내는 res://``로 시작하는 경로를 작성하여 관련된 모든 파일에 액세스할 수 있습니다. 예를 들어, ``res://character.png 경로를 사용하여 코드에서 프로젝트의 루트 폴더에 있는 이미지 파일 ``character.png``에 액세스할 수 있습니다.

씬 노드 접근하기

플레이어의 저장 또는 설정과 같은 영구 데이터 파일을 저장하려면 경로 접두사로 res:// 대신 ``user://``를 사용하는 것이 좋습니다. 이는 게임이 실행 중일 때 프로젝트의 파일 시스템이 읽기 전용일 가능성이 높기 때문입니다.

user:// 접두사는 사용자 장치의 다른 디렉터리를 가리킵니다. ``res://``와 달리 ``user://``가 가리키는 디렉토리는 자동으로 생성되며 내보낸 프로젝트에서도 쓰기 가능이 *보장*됩니다.

user:// 폴더의 위치는 프로젝트 설정에 구성된 내용에 따라 다릅니다.

기본적으로 user:// 폴더는 app_userdata/[project_name] 폴더의 Godot의 editor 데이터 경로 내에 생성됩니다. 프로토타입과 테스트 프로젝트가 Godot의 데이터 폴더 내에 독립적으로 유지되도록 하는 기본값입니다.
application/config/use_custom_user_dir <class_ProjectSettings_property_application/config/use_custom_user_dir>`이 프로젝트 설정에서 활성화된 경우, ``user://` 폴더는 Godot의 편집기 데이터 경로 옆, 즉 응용 프로그램 데이터의 표준 위치에 생성됩니다.
- 기본적으로 폴더 이름은 프로젝트 이름에서 유추되지만 application/config/custom_user_dir_name <class_ProjectSettings_property_application/config/custom_user_dir_name>`을 사용하여 추가로 사용자 정의할 수 있습니다. 이 경로에는 경로 구분 기호가 포함될 수 있으므로 이를 사용할 수 있습니다. ``Studio Name/Game Name` 구조를 사용하여 특정 스튜디오의 프로젝트를 그룹화합니다.

데스크탑 플랫폼에서 ``user://``의 실제 디렉토리 경로는 다음과 같습니다.

유형	위치
디폴트	Windows: `%APPDATA%\Godot\app_userdata\[프로젝트_이름]` macOS: `~/Library/Application Support/Godot/app_userdata/[프로젝트_이름]` Linux: `~/.local/share/godot/app_userdata/[프로젝트_이름]`
커스텀 디렉터리	Windows: `%APPDATA%\[프로젝트_이름]` macOS: `~/Library/Application Support/[프로젝트_이름]` Linux: `~/.local/share/[프로젝트_이름]`
커스텀 디렉터리와 이름	Windows: `%APPDATA%\[커스텀_사용자_디렉터리_이름]` macOS: `~/Library/Application Support/[커스텀_사용자_디렉터리_이름]` Linux: `~/.local/share/[커스텀_사용자_디렉터리_이름]`

``[project_name]``는 프로젝트 설정에 정의된 애플리케이션 이름을 기반으로 하지만 :ref:`feature tagged <doc_feature_tags>`를 사용하여 플랫폼별로 이를 재정의할 수 있습니다.

모바일 플랫폼에서 이 경로는 프로젝트에 고유하며 보안상의 이유로 다른 애플리케이션에서는 액세스할 수 없습니다.

HTML5 내보내기에서 ``user://``는 IndexedDB를 통해 장치에 저장된 가상 파일 시스템을 참조합니다. (메인 파일 시스템과의 상호 작용은 JavaScriptBridge 싱글톤를 통해 계속 수행될 수 있습니다.)

디버깅

내보내기에 관한 서술은 GDScript 내보낸 속성로 옮겨졌습니다.

경로를 절대 경로 또는 "로컬" 경로로 변환

:ref:`ProjectSettings.globalize_path() <class_ProjectSettings_method_globalize_path>`를 사용하여 ``res://path/to/file.txt``와 같은 "로컬" 경로를 절대 OS 경로로 변환할 수 있습니다. 예를 들어 :ref:`ProjectSettings.globalize_path() <class_ProjectSettings_method_globalize_path>`는 기본 OS 경로만 허용하므로 :ref:`OS.shell_open() <class_OS_method_shell_open>`을 사용하여 OS 파일 관리자에서 "로컬" 경로를 여는 데 사용할 수 있습니다.

절대 OS 경로를 res:// 또는 user://``로 시작하는 "로컬" 경로로 변환하려면 :ref:`ProjectSettings.localize_path() <class_ProjectSettings_method_localize_path>`를 사용합니다. 이는 프로젝트 루트 또는 ``user:// 폴더의 파일이나 폴더를 가리키는 절대 경로에만 작동합니다.

편집기 데이터 경로

에디터는 플랫폼에 따라 에디터 데이터, 에디터 설정, 캐시에 대해 서로 다른 경로를 사용합니다. 기본적으로 이러한 경로는 다음과 같습니다.

유형	위치
편집기 데이터	윈도우: `%APPDATA%\Godot\` 맥OS: `~/Library/Application Support/Godot/` Windows: `%APPDATA%\Godot\script_templates\`
편집기 설정	윈도우: `%APPDATA%\Godot\` 맥OS: `~/Library/Application Support/Godot/` 리눅스: `~/.config/godot/`
캐시	윈도우: `%TEMP%\Godot\` 맥OS: `~/Library/Caches/Godot/` 리눅스: `~/.cache/godot/`

**편집기 데이터**에는 내보내기 템플릿과 프로젝트별 데이터가 포함되어 있습니다.
**편집기 설정**에는 기본 편집기 설정 구성 파일과 다양한 기타 사용자별 사용자 지정 항목(편집기 레이아웃, 기능 프로필, 스크립트 템플릿 등)이 포함되어 있습니다.
**캐시**에는 편집기에서 생성되었거나 임시로 저장된 데이터가 포함되어 있습니다. Godot가 닫혀 있으면 안전하게 제거할 수 있습니다.

Godot는 Linux/*BSD에서 XDG 기본 디렉터리 사양 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__을 준수합니다. ``XDG_DATA_HOME`, XDG_CONFIG_HOME 및 XDG_CACHE_HOME 환경 변수를 재정의하여 편집기 및 프로젝트 데이터 경로를 변경할 수 있습니다.

참고

`Flatpak으로 포장된 Godot <https://flathub.org/apps/details/org.godotengine.Godot>`__를 사용하는 경우 편집기 데이터 경로는 ``~/.var/app/org.godotengine.Godot/``의 하위 폴더에 위치합니다.

자체 포함 모드

편집기 바이너리와 동일한 디렉토리(또는 macOS 편집기 .app 번들의 경우 MacOS/Contents/)에 ._sc_ 또는 ``_sc_``라는 파일을 생성하면 Godot는 *자체 포함 모드*를 활성화합니다. 이 모드는 Godot가 모든 편집기 데이터, 설정, 캐시를 편집기 바이너리와 동일한 디렉토리에 있는 ``editor_data/``라는 디렉토리에 쓰도록 합니다. 이를 사용하여 편집기의 휴대용 설치를 만들 수 있습니다.

`Godot <https://store.steampowered.com/app/404790/>`__의 Steam 릴리스는 기본적으로 자체 포함 모드를 사용합니다.

참고

내보낸 프로젝트에서는 아직 자체 포함 모드가 지원되지 않습니다. 실행 가능 경로를 기준으로 파일을 읽고 쓰려면 :ref:`OS.get_executable_path() <class_OS_method_get_executable_path>`를 사용합니다. 실행 파일 경로에 파일을 쓰는 것은 실행 파일이 쓰기 가능한 위치(예: Program Files 또는 일반 사용자에게 읽기 전용인 다른 디렉터리가 아님)에 있는 경우에만 작동합니다.