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

Portes de plataforma personalizados

Semelhante ao Módulos personalizados em C++, a arquitetura multiplataforma do Godot foi projetada de uma forma que permite criar portas (ports) de plataforma sem modificar nenhum código-fonte existente.

Um exemplo de port de plataforma personalizado distribuído independentemente da engine é o FRT, que tem como alvo computadores de placa única (single-board computers). Note que este port de plataforma atualmente tem como alvo o Godot 3.x; portanto, ele não usa a abstração DisplayServer que é nova no Godot 4.

Algumas razões para criar ports de plataforma personalizados podem ser:

Você quer portar seu jogo para consoles (veja também a página do site da Godot sobre suporte a consoles), mas deseja escrever a camada de plataforma por conta própria. Esse é um processo longo e árduo, pois exige a assinatura de acordos de confidencialidade (NDAs) com os fabricantes de consoles, mas permite que você tenha controle total sobre o processo de portabilidade para consoles.
Você quer portar o Godot para uma plataforma exótica que não é suportada atualmente.

Se você tiver dúvidas sobre a criação de um port de plataforma personalizado, sinta-se à vontade para perguntar no canal #platforms do Godot Contributors Chat.

Nota

O Godot é uma engine moderna com requisitos modernos. Mesmo se você pretender apenas rodar projetos 2D simples na plataforma alvo, ela ainda requer uma quantidade de memória que torna inviável a execução na maioria dos consoles retrô. Para referência, no Godot 4, um projeto vazio sem nada visível requer cerca de 100 MB de RAM para rodar no Linux (50 MB em modo headless).

Se você quiser rodar o Godot em plataformas com fortes restrições de memória, as versões mais antigas do Godot têm requisitos de memória mais baixos. O processo de portabilidade é semelhante, com exceção do DisplayServer não ser separado do singleton OS.

Portas de plataforma oficiais

Os ports de plataforma oficiais podem ser usados como referência ao criar um port de plataforma personalizado:

Embora o código da plataforma geralmente seja autocontido, há exceções a essa regra. Por exemplo, os drivers de áudio compartilhados por várias plataformas e os drivers de renderização estão localizados na pasta drivers/ do código-fonte do Godot.

Criando uma porta de plataforma personalizada

Criar um port de plataforma personalizado é uma grande tarefa que exige conhecimento prévio dos SDKs da plataforma. Dependendo de quais recursos você precisa, a quantidade de trabalho necessária varia:

Recursos obrigatórios de um port de plataforma

No mínimo, um port de plataforma deve ter os métodos do singleton OS implementados para ser compilável e utilizável para operação headless. Uma imagem vetorial logo.svg (32×32) também deve estar presente na pasta da plataforma. Esse logotipo é exibido na caixa de diálogo Exportar para cada predefinição de exportação que tenha como alvo a plataforma em questão.

Veja esta implementação para a plataforma Linux/*BSD como um exemplo. Veja também o cabeçalho do singleton OS para referência.

Nota

Se a sua plataforma alvo for do tipo UNIX, considere herdar da classe OS_Unix para realizar grande parte do trabalho automaticamente.

Se a plataforma não for do tipo UNIX, você pode usar o port para Windows como referência.

arquivo detect.py

Um arquivo detect.py deve ser criado dentro da pasta da plataforma com todos os métodos implementados. Esse arquivo é necessário para que o SCons detecte a plataforma como uma opção válida para compilação. Veja o arquivo detect.py para a plataforma Linux/*BSD como um exemplo.

Todos os métodos devem ser implementados dentro do detect.py da seguinte forma:

is_active(): Pode ser usado para desativar temporariamente a compilação para uma plataforma. Geralmente, isso deve sempre retornar True.
get_name(): Retorna o nome visível ao usuário da plataforma como uma string.
can_build(): Retorna True se o sistema host for capaz de compilar para la plataforma alvo, False caso contrário. Não coloque verificações lentas aqui, pois isso é consultado quando a lista de plataformas é solicitada pelo usuário. Use configure() para verificações extensas de dependência.
get_opts(): Retorna a lista de opções de compilação do SCons que podem ser definidas pelo usuário para esta plataforma.
get_flags(): Retorna a lista de flags do SCons sobrescritas para esta plataforma.
configure(): Realiza a configuração da compilação, como a seleção de opções do compilador dependendo das opções do SCons escolhidas.

Recursos opcionais de um port de plataforma

Na prática, a operação headless não basta se você quiser ver algo na tela e gerenciar dispositivos de entrada. Você também pode querer saída de áudio para a maioria dos jogos.

Alguns links nesta lista apontam para a implementação da plataforma Linux/*BSD como referência.

Um ou mais DisplayServers, com os métodos de gerenciamento de janelas implementados. O DisplayServer também cobre recursos como suporte a mouse, suporte a tela de toque e driver de tablet (para entrada de caneta). Veja o cabeçalho do singleton DisplayServer para referência.
- Para plataformas que não possuem suporte total a gerenciamento de janelas (or se isso não for relevante para o port que você está fazendo), a maioria das funções de gerenciamento de janelas pode ser deixada praticamente sem implementação. Essas funções podem ser feitas para apenas verificar se o ID da janela é MAIN_WINDOW_ID e operações específicas como redimensionamento podem ser vinculadas ao recurso de resolução de tela da plataforma (se relevante). Qualquer tentativa de criar ou manipular outros IDs de janela pode ser rejeitada.
Se a plataforma alvo suportar as APIs gráficas em questão: Contexto de renderização para Vulkan, Direct3D 12 OpenGL 3.3 ou OpenGL ES 3.0.
Gerenciadores de entrada para teclado e controle.
Um ou mais drivers de áudio. O driver de áudio pode estar localizado na pasta platform/ (isso é feito para as plataformas Android e Web) ou na pasta drivers/ se várias plataformas puderem usar esse driver de áudio. Veja o cabeçalho do singleton AudioServer para referência.
Um gerenciador de travamentos (Crash handler), para imprimir o rastreamento (backtrace) de travamentos quando o jogo quebra. Isso permite uma resolução de problemas mais fácil em plataformas onde os logs não são facilmente acessíveis.
Driver de conversão de texto em fala (para acessibilidade).
Um gerenciador de exportação (para exportar a partir do editor, incluindo o Implantação com um clique). Não é obrigatório se você pretende exportar apenas um PCK a partir do editor e, em seguida, executar o binário do modelo de exportação diretamente, renomeando-o para corresponder ao arquivo PCK. Veja o cabeçalho EditorExportPlatform para referência. O arquivo run_icon.svg (16×16) deve estar presente na pasta da plataforma se o Implantação com um clique estiver implementado para a plataforma alvo. Este ícone é exibido no topo do editor quando a implantação com um clique está configurada para a plataforma alvo.

Se a plataforma alvo não suportar a execução de Vulkan, Direct3D 12, OpenGL 3.3 ou OpenGL ES 3.0, você tem duas opções:

Usar uma biblioteca em tempo de execução para traduzir as chamadas de Vulkan ou OpenGL para outra API gráfica. Por exemplo, o MoltenVK é usado no macOS para traduzir Vulkan para Metal em tempo de execução.
Criar um novo renderizador do zero. Essa é uma grande tarefa, especialmente se você quiser dar suporte a renderização tanto em 2D quanto em 3D com recursos avançados.

Distribuindo um port de plataforma personalizado

Perigo

Antes de distribuir um port de plataforma personalizado, certifique-se de que você tem permissão para distribuir todo o código que está sendo vinculado. Os SDKs de console normalmente estão sob acordos de confidencialidade (NDAs) que impedem a redistribuição ao público.

Os ports de plataforma são projetados para serem o mais autocontidos possível. A maior parte do código pode ser mantida dentro de uma única pasta localizada em platform/. Assim como no Módulos personalizados em C++, isso permite simplificar o processo de compilação, tornando possível fazer um git clone de uma pasta de plataforma dentro da pasta platform/ de um clone do repositório do Godot e, em seguida, executar scons platform=<nome>. Nenhum outro passo é necessário para a compilação, a menos que dependências de terceiros específicas da plataforma precisem ser instaladas primeiro.

No entanto, quando um driver de renderização personalizado é necessário, outra pasta deve ser adicionada em drivers/. Nesse caso, o port da plataforma pode ser distribuído como um fork do repositório do Godot ou como uma coleção de várias pastas que podem ser adicionadas sobre um clone do repositório Git do Godot.