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

Exportando pacotes, patches e mods

Casos de uso

Muitas vezes deseja-se adicionar funcionalidades ao jogo após ele já ter sido distribuído.

Exemplos disso incluem...

Conteúdo para download: a capacidade de adicionar recursos e conteúdo ao jogo.
Patches: a capacidade de corrigir um bug que está presente em um produto enviado.
Mods: conceda a outras pessoas a capacidade de criar conteúdo para o jogo.

Essas ferramentas ajudam os desenvolvedores a estender seu desenvolvimento além do lançamento inicial.

Visão geral dos arquivos PCK/ZIP

O Godot permite isso através de um recurso chamado resource packs (pacotes de recursos, arquivos PCK, com a extensão .pck, ou arquivos ZIP).

Vantagens:

atualizações/patches incrementais
oferecer DLCs
oferecer suporte a mods
nenhuma divulgação de código fonte necessária para mods
estrutura de projeto mais modular
os usuários não precisam substituir o jogo inteiro

A primeira parte do uso deles envolve exportar e distribuir o projeto aos jogadores. Depois, quando se deseja adicionar funcionalidades ou conteúdo posteriormente, basta distribuir as atualizações através de arquivos PCK/ZIP para os usuários.

Os arquivos PCK/ZIP geralmente contêm, mas não se limitam a:

scripts
cenas
shaders
modelos
texturas
efeitos sonoros
música
qualquer outro asset adequado para importação para o jogo

Os arquivos PCK/ZIP podem até mesmo ser um projeto Godot completamente diferente, que o jogo original carrega em tempo de execução.

É possível carregar tanto arquivos PCK quanto ZIP como pacotes adicionais ao mesmo tempo. Veja Formatos de arquivo PCK versus ZIP para uma comparação dos dois formatos.

Ver também

Se você deseja carregar arquivos soltos em tempo de execução (não compactados em um PCK ou ZIP pelo Godot), considere usar Carregamento e salvamento de arquivos durante a execução em vez disso. Isso é útil para carregar conteúdo gerado pelo usuário que não foi feito com o Godot, sem exigir que os usuários compactem seus mods em um formato de arquivo específico.

A desvantagem dessa abordagem é que ela é menos transparente para a lógica do jogo, pois não se beneficiará do mesmo gerenciamento de recursos que os arquivos PCK/ZIP.

Preocupações com segurança

É importante notar que carregar arquivos PCK para patches, mods ou conteúdo extra como expansões exigirá que você programe um sistema para carregar arquivos automaticamente com base em sua localização e, possivelmente, nome. Isso é uma vulnerabilidade de segurança em três cenários. Um, um usuário baixa um mod com código malicioso. Dois, um programa malicioso já existe no PC do usuário final e substituiu o arquivo PCK por uma cópia maliciosa. Três, você está distribuindo arquivos PCK de patch através de um launcher de jogo e o sistema foi comprometido.

Leve isso em consideração ao determinar como usar arquivos PCK em um projeto. Para situações em que você tem um sistema de atualização através de um launcher, considere usar criptografia assimétrica. Você pode armazenar a chave pública no PCK principal e assinar os arquivos PCK de patch ou expansão com a chave privada. Veja a classe Crypto para mais informações.

Preocupações com direitos autorais

Se você deseja usar arquivos PCK para distribuir conteúdo pago extra, como expansões, tenha em mente que o Godot não fornece nenhuma maneira nativa para impedir que alguém copie o arquivo PCK e o coloque no computador de outra pessoa. Qualquer tipo de sistema de DRM é de sua responsabilidade implementar, se for isso o que você deseja.

Gerando arquivos PCK

Para empacotar todos os recursos de um projeto em um arquivo PCK, abra o projeto e vá em Project > Export, selecione uma predefinição de exportação e clique em Export PCK/ZIP.

Another method would be to export from the command line with --export-pack. The output file must end with a .pck or .zip file extension. The export process will build that type of file for the chosen platform.

Arquivos PCK de atualização

Gerando arquivos PCK de atualização

Para criar um arquivo PCK que contenha apenas recursos não presentes no lançamento original de um projeto, você criaria um arquivo PCK de patch. Isso poderia ser usado para patches, mods ou expansões. Para que isso funcione, você primeiro precisará ter um arquivo PCK do seu projeto no ponto de seu lançamento inicial.

Para gerar um arquivo PCK de patch, dentro do menu de exportação e com o preset desejado selecionado, clique na aba Patching. Na parte inferior está a seção Base Packs. Clique no botão Add Pack e navegue até o arquivo PCK que você exportou que contém tudo no seu projeto para o lançamento inicial.

Agora, quando você for exportar um arquivo PCK do seu projeto novamente, se você tiver o botão Export as Patch selecionado, apenas os recursos que mudaram serão exportados no arquivo PCK.

Você também pode adicionar quaisquer patches que exportar aos seus pacotes base para uso futuro. Por exemplo, adicionar patch.pck garantirá que o patch2.pck não inclua nenhum recurso daquele primeiro patch.

Codificação delta

Arquivos PCK de correção (patch) podem ser tornados menores através do uso de codificação delta. Isso faz com que apenas as partes de um arquivo que foram alteradas sejam atualizadas. Isso tem a desvantagem de tempos de carregamento mais longos para os recursos que são atualizados, e cada correção para um recurso aumenta cumulativamente seu tempo de carregamento.

Existem duas configurações para codificação delta além dos filtros:

Delta Encoding Compression Level: Controla quanta compressão é aplicada aos arquivos. Não recomendamos mais do que o padrão de 19. Além disso, mais memória é necessária para exportação e importação para ganhos significativamente menores. Quaisquer valores positivos terão a mesma velocidade de descompressão, no entanto, a exportação demorará mais quanto maior for o número. Valores negativos ativam o modo rápido, o que significa arquivos maiores, mas a velocidade de descompressão é maior.
Delta Encoding Minimum Size Reduction: Controla quanta redução de tamanho deve ser economizada no mínimo para que a compressão seja usada em um arquivo individual. Por exemplo, em um nível de 10%, se o tamanho do arquivo só puder ser reduzido em 5%, então o arquivo não usará codificação delta.

O nível de compressão padrão, 19, é o nível mais alto recomendado.

Para o menor tamanho de patch possível, recomendamos desativar a compressão para quaisquer recursos que você deseja patchear. Mesmo que seus arquivos PCK base tenham sido compactados, isso não deve causar problemas.

Existem vários lugares onde a compressão pode ser desativada para diferentes recursos:

Configurações de importação relacionadas à compressão em recursos importados individualmente, como arquivos de tradução ou de modelos 3D
Compress Binary Resources nas configurações do editor
GDScript Export Mode na aba Scripts de um preset de exportação

Nota

Depois de desativar Compress Binary Resources, você deve deletar o conteúdo da pasta .godot/imported/ do seu projeto, fechar e abrir o projeto novamente para gerá-lo de novo.

É importante notar que quando você exporta um patch codificado em delta em cima de patches anteriores, os pacotes que você lista sob Base Packs na aba Patching devem ser exatamente os mesmos arquivos que são carregados pelo jogo em tempo de execução, na ordem exata em que são carregados. Reexportar versões anteriores pode acabar sendo ligeiramente diferente devido ao não-determinismo no processo de exportação do Godot, o que pode fazer com que o patch falhe. Isso se aplica apenas a patches codificados em delta; os regulares não têm esse problema.

Abrindo arquivos PCK ou ZIP em tempo de execução

Para carregar um arquivo PCK ou ZIP, utiliza-se o singleton ProjectSettings. O exemplo a seguir espera um arquivo mod.pck no diretório do executável do jogo. O arquivo PCK ou ZIP contém uma cena de teste mod_scene.tscn em sua raiz.

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");
    }
}

Aviso

Por padrão, se você importar um arquivo com o mesmo caminho/nome de outro já existente no projeto, o arquivo importado irá substituí-lo. Isso é algo que deve ser observado ao criar DLCs ou mods. Você pode resolver esse problema usando uma ferramenta que isole mods em uma subpasta específica para mods.

No entanto, também é uma forma de criar patches para o próprio jogo. Um arquivo PCK/ZIP deste tipo pode corrigir o conteúdo de um PCK/ZIP carregado anteriormente (portanto, a ordem na qual os pacotes são carregados importa).

Para cancelar este comportamento, passe false como o segundo argumento para ProjectSettings.load_resource_pack().

Nota

Para um projeto em C#, você precisa construir a DLL e colocá-la no diretório do projeto primeiro. Em seguida, antes de carregar o pacote de recursos, você precisa carregar a DLL da seguinte forma: Assembly.LoadFile("mod.dll")

Solução de problemas

Se você estiver carregando um pacote de recursos e não estiver notando nenhuma mudança, pode ser devido ao pacote ser carregado tarde demais. Este é especialmente o caso com cenas de menu que podem pré-carregar outras cenas usando preload(). Isso significa que carregar um pacote no menu não afetará a outra cena que já foi pré-carregada.

Para evitar isso, você precisa carregar o pacote o mais cedo possível. Para fazer isso, crie um novo script de autoload e chame ProjectSettings.load_resource_pack() na função _init() do script de autoload, em vez de _enter_tree() ou _ready().

Considerações sobre modding

Se desejar oferecer suporte a mods em seu jogo, será necessário permitir que os usuários criem arquivos exportados de forma semelhante. Assumindo que o jogo original espera uma determinada estrutura para os recursos do PCK e/ou uma determinada interface para seus scripts, então uma de duas abordagens deve ser adotada.

O desenvolvedor deve documentar essas estruturas esperadas/
interfaces, esperar que os modders instalem o Godot Engine e também que sigam a API definida na documentação ao criar conteúdo para o jogo (para que funcione). Os usuários então utilizariam as ferramentas de exportação integradas do Godot para criar um arquivo PCK, conforme descrito anteriormente.
O desenvolvedor usa o Godot para construir uma ferramenta GUI para adicionar sua API exata
conteúdo para um projeto. Esta ferramenta Godot deve ser executada em uma versão do motor com suporte a ferramentas ou ter acesso a uma (distribuída junto ao jogo ou aos seus arquivos). A ferramenta pode então utilizar o executável do Godot para exportar um arquivo PCK pela linha de comando usando OS.execute(). O jogo em si não deve usar uma versão do motor com ferramentas habilitadas (por questões de segurança), portanto é melhor manter a ferramenta de modding separada do jogo.