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...

패키지, 패치, 모드 내보내기

사용 사례

때때로 게임이 배포된 후에 기능을 추가하고 싶은 경우가 있습니다.

이런 예시로는...

다운로드 가능한 콘텐츠(DLC): 자신의 게임에 기능과 콘텐츠를 추가하는 기능.
패치: 배포된 제품에 존재하는 버그를 고치는 기능.
모드: 다른 사람들에게 게임의 콘텐츠를 만드는 기능을 허가함.

이 툴은 개발자가 초기 출시 단계를 넘어 확장하는 것을 도와줍니다.

PCK/ZIP 파일의 개요

Godot는 리소스 팩이라는 기능을 통해 이를 활성화합니다 (.pck 확장자로 된 PCK 파일 또는 ZIP 파일).

장점:

증가하는 업데이트/패치
DLC 제공
모드 지원 제공
모드에 필요한 소스 코드 공개 없음
더 많은 모듈형 프로젝트 구조
사용자는 게임 전체를 교체할 필요가 없음

파일을 사용하는 첫번째는 프로젝트를 내보내고 플레이어에게 전달하는 것입니다. 그 뒤, 나중에 기능이나 콘텐츠를 추가하려 한다면, 단지 PCK 파일을 통해 사용자에게 업데이트를 전달하면 됩니다.

PCK 파일은 보통 다음을 포함하지만, 제한은 없습니다:

스크립트
씬
셰이더
모델
텍스처
소리 효과
음악
게임으로 가져오기 적당한 다른 애셋

PCK 파일은 원래 게임이 런타임에 불러오는 완전히 다른 Godot 프로젝트가 될 수도 있습니다.

PCK와 ZIP 파일을 동시에 추가 팩으로 로드할 수 있습니다. 두 형식을 비교하려면 :ref:`doc_exporting_projects_pck_versus_zip`를 참조하세요.

런타임에 느슨한 파일을 로드하려면(Godot에서 PCK 또는 ZIP으로 압축하지 않음) 대신 다음 예제에서: 사용을 고려하세요. 이는 사용자가 모드를 특정 파일 형식으로 압축할 필요 없이 Godot로 제작되지 않은 사용자 생성 콘텐츠를 로드하는 데 유용합니다.

이 접근 방식의 단점은 PCK/ZIP 파일과 동일한 리소스 관리의 이점을 얻지 못하기 때문에 게임 로직에 대한 투명성이 떨어진다는 것입니다.

Security concerns

It is important to note that loading PCK files for patches, mods, or extra content like expansions, will require you to code a system to automatically load files based on their location, and possibly name. This is a security vulnerability in three scenarios. One, a user downloads a mod with malicious code. Two, a malicious program already exists on an end user's PC and has replaced the PCK file with a malicious copy. Three, you are distributing patch PCK files through a game launcher and the system has become compromised.

Take this into consideration when determining how to use PCK files in a project. For situations where you have a patching system via a launcher, consider using asymmetric cryptography. You could store the public key in the main PCK, and sign patch or expansion PCK files with the private key. See the Crypto class for more information.

Copyright concerns

If you want to use PCK files to distribute extra paid content, such as expansions, keep in mind that Godot provides no out-of-the-box way to prevent someone from copying the PCK file, and putting it on another person's computer. Any kind of DRM system is your responsibility to implement if that's what you want.

PCK 파일 생성하기

In order to pack all resources of a project into a PCK file, open the project and go to Project > Export, select an export preset, and click on Export PCK/ZIP.

다른 방법은 명령줄에서 내보내기가 있습니다. 출력 파일은 PCK나 ZIP 파일 확장자명으로 끝나고, 그 뒤 내보내기 처리는 선택한 플랫폼에 맞는 타입의 파일로 빌드할 것입니다.

Patch PCK files

Generating Patch PCK files

To create a PCK file that only contains resources not present in the original release of a project, you would create a patch PCK file. This could be used for patches, mods, or expansions. For this to work you'll first need to have a PCK file for your project at the point of its initial release.

To generate a patch PCK file, within the export menu, and with your desired preset selected, click on the Patching tab. At the bottom is the Base Packs section. Click on the Add Pack button, then navigate to the PCK file you exported that contains everything in your project for its initial release.

Now, when you go to export a PCK file of your project again, if you have the Export as Patch button selected, only resources that have changed will be exported in the PCK file.

You can also add any patches you export to your base packs for future use. For example, adding patch.pck will ensure that patch2.pck will not include any resources from that first patch.

Delta encoding

Patch PCK files can be made smaller through the use of delta encoding. This makes it so that only the parts of a file that have been changed are updated. This does have a drawback of longer load times for the resources that are updated, and each patch for a resource cumulatively increases its load time.

There are two settings for delta encoding in addition to the filters:

Delta Encoding Compression Level: Controls how much compression is applied to the files. We do not recommend any more than the default of 19. Beyond that more memory is needed for export and import for significantly fewer gains. Any positive values will have the same decompression speed, however export will take longer the higher the number is. Negative values enable fast mode, which means larger files, but the decompression speed is higher.
Delta Encoding Minimum Size Reduction: Controls how much size has to be saved at minimum for compression to be used on an individual file. For example, at a level of 10%, if the file size can only be reduced by 5%, then the file won't use delta encoding.

The default compression level, 19, is the highest recommended level.

For the smallest patch size possible we recommend turning off compression for any resources you want to patch. Even if your base PCK files were compressed that shouldn't cause an issue.

There are several places compression can be disabled for different resources:

Import settings related to compression on individually imported resources, such as translation or 3D model files
Compress Binary Resources in the editor settings
GDScript Export Mode in the Scripts tab of an export preset

참고

After disabling Compress Binary Resources you must delete the contents of your projects .godot/imported/ folder, then closing and open the project again to re-generate it.

It's important to note that when you export a delta encoded patch on top of previous patches, the packs you list under Base Packs in the Patching tab must be the exact same files that are loaded by the game at runtime, in the exact order they are loaded in. Re-exporting previous versions may end up being slightly different, due to non-determinism in Godot's export process, which can cause the patching to fail. This only applies to delta encoded patches, regular ones don't have this issue.

런타임에 PCK 또는 ZIP 파일 열기

PCK 또는 ZIP 파일을 불러오려면, ProjectSettings 싱글톤을 사용합니다. 다음 예제는 게임 실행 파일의 디렉터리에 mod.pck 파일을 실행하는 것입니다. PCK 또는 ZIP 파일의 루트에는 mod_scene.tscn 테스트 씬을 포함하고 있습니다.

func _your_function():
    # This could fail if, for example, mod.pck cannot be found.
    var success = ProjectSettings.load_resource_pack(OS.get_executable_path().get_base_dir().path_join("mod.pck"))

    if success:
        # Now one can use the assets as if they had them in the project from the start.
        var imported_scene = load("res://mod_scene.tscn")

private void YourFunction()
{
    // This could fail if, for example, mod.pck cannot be found.
    var success = ProjectSettings.LoadResourcePack(OS.GetExecutablePath().GetBaseDir().PathJoin("mod.pck"));

    if (success)
    {
        // Now one can use the assets as if they had them in the project from the start.
        var importedScene = (PackedScene)ResourceLoader.Load("res://mod_scene.tscn");
    }
}

경고

이미 동일한 파일 경로/이름을 가진 파일을 가진 프로젝트로 파일을 가져온다면, 가져온 것으로 바꿀 것입니다. 이는 DLC나 모드를 만들 때 주의해야 하는 점입니다 (모드를 특정 모드 하위 폴더로 분리하는 툴로 쉽게 해결됩니다). 하지만, 이것 또한 게임의 패치를 만드는 방식이기도 합니다. 이런 종류의 PCK 파일은 이전에 불러온 PCK 파일의 콘텐츠를 고칠 수 있습니다.

그러나 이는 자신의 게임에 대한 패치를 만드는 방법이기도 합니다. 이러한 종류의 PCK/ZIP 파일은 이전에 로드된 PCK/ZIP의 내용을 수정할 수 있습니다. 따라서 팩이 로드되는 순서가 중요합니다.

원래 파일을 덮어쓰지 못하도록 하려면 ProjectSettings.load_resource_pack()으로 두 번째 인자에 false를 넘겨주면 됩니다.

참고

C# 프로젝트의 경우, 우선 DLL을 빌드해 프로젝트 디렉터리에 저장해야 합니다. 그 다음으로 리소스 팩을 로딩하기 전에 다음과 같이 DLL을 먼저 불러와야 합니다: Assembly.LoadFile("mod.dll")

문제 해결

리소스 팩을 로드하고 있는데 변경 사항이 눈에 띄지 않는다면 팩이 너무 늦게 로드되었기 때문일 수 있습니다. 이는 :ref:`preload() <class_@GDScript_method_preload>`를 사용하여 다른 장면을 미리 로드할 수 있는 메뉴 장면의 경우 특히 그렇습니다. 즉, 메뉴에서 팩을 로드해도 이미 사전 로드된 다른 씬에는 영향을 미치지 않습니다.

이를 방지하려면 가능한 한 빨리 팩을 로드해야 합니다. 이렇게 하려면 새 autoload 스크립트를 만들고 자동 로드 스크립트의 _init()``에서 :ref:`ProjectSettings.load_resource_pack() <class_ProjectSettings_method_load_resource_pack>`을 호출하세요. ``_enter_tree() 또는 ``_ready()``가 아닌 기능입니다.

Modding considerations

If one wishes to support mods for their game, they will need their users to create similarly exported files. Assuming the original game expects a certain structure for the PCK's resources, and/or a certain interface for its scripts, then one of two things has to be done.

The developer must document these expected structures/
interfaces, expect modders to install Godot Engine, and then also expect those modders to conform to the documentation's defined API when building mod content for the game (so that it will work). Users would then use Godot's built in exporting tools to create a PCK file, as detailed above.
The developer uses Godot to build a GUI tool for adding their exact API
content to a project. This Godot tool must either run on a tools-enabled build of the engine or have access to one (distributed alongside or perhaps in the original game's files). The tool can then use the Godot executable to export a PCK file from the command line with OS.execute(). The game itself shouldn't use a tool-build of the engine (for security), so it's best to keep the modding tool and game separate.