This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
Se você precisa de interação personalizada com software ou hardware externo em baixo nível, onde Lua não é suficiente, o SDK do Defold permite escrever extensões para a engine em C, C++, C#, Objective-C, Java ou JavaScript, dependendo da plataforma-alvo. Casos de uso típicos para extensões nativas são:
O suporte a C# é experimental e destina-se a extensões nativas, não a componentes de script do Defold. Ele usa .NET 9 NativeAOT para produzir uma biblioteca estática; adicione arquivos-fonte .cs à pasta src de uma extensão e o serviço de build gerará o arquivo de projeto. O suporte a plataformas acompanha os recursos atuais do NativeAOT e do serviço de build. Consulte o exemplo oficial de linguagens para extensões nativas para ver o fluxo de trabalho atual e a configuração testada.
O Defold oferece um ponto de entrada sem configuração para extensões nativas com uma solução de build baseada em nuvem. Qualquer extensão nativa desenvolvida e adicionada a um projeto de jogo, diretamente ou por meio de um projeto de biblioteca, passa a fazer parte do conteúdo comum do projeto. Não é necessário compilar versões especiais da engine e distribuí-las aos membros da equipe; isso é feito automaticamente: qualquer membro da equipe que compilar e executar o projeto receberá um executável da engine específico do projeto, com todas as extensões nativas incorporadas.

O Defold fornece o servidor de build em nuvem gratuitamente, sem restrições de uso. O servidor é hospedado na Europa, e a URL para a qual o código nativo é enviado é configurada na janela de Preferências do Editor ou pela opção de linha de comando --build-server do bob. Se quiser configurar seu próprio servidor, siga estas instruções.
Para criar uma nova extensão, crie uma pasta na raiz do projeto. Essa pasta conterá todas as configurações, código-fonte, bibliotecas e recursos associados à extensão. O builder de extensão reconhece a estrutura de pastas e coleta todos os arquivos-fonte e bibliotecas.
myextension/
│
├── ext.manifest
│
├── src/
│
├── include/
│
├── lib/
│ └──[platforms]
│
├── manifests/
│ └──[platforms]
│
└── res/
└──[platforms]
platform, ou architecture-platform, dependendo de quais arquiteturas suas bibliotecas aceitam.
As plataformas suportadas são ios, android, osx, win32, linux, web.
Os pares arc-platform suportados são arm64-ios, arm64_sim-ios, armv7-android, arm64-android, x86_64-android, arm64-osx, x86_64-osx, x86_64-win32, arm64-linux, x86_64-linux, wasm-web e wasm_pthread-web.
platform, ou architecture-platform, assim como as subpastas de lib. Uma subpasta common também é permitida, contendo arquivos de recurso comuns a todas as plataformas.A pasta opcional manifests de uma extensão contém arquivos adicionais usados no processo de build e empacotamento. Os arquivos devem ser colocados em subpastas nomeadas por platform:
android - Esta pasta aceita um arquivo stub de manifesto a ser mesclado na aplicação principal (conforme descrito aqui).
build.gradle com dependências a serem resolvidas pelo Gradle..keep) para as classes necessárias em tempo de execução.ios - Esta pasta aceita um arquivo stub de manifesto a ser mesclado na aplicação principal (conforme descrito aqui).
Podfile com dependências a serem resolvidas pelo Cocoapods.SwiftPackages.json com dependências a serem resolvidas pelo Swift Package Manager.osx - Esta pasta aceita um arquivo stub de manifesto a ser mesclado na aplicação principal (conforme descrito aqui).
Podfile com dependências a serem resolvidas pelo CocoaPods.SwiftPackages.json com dependências a serem resolvidas pelo Swift Package Manager.web - Esta pasta aceita um arquivo stub de manifesto a ser mesclado na aplicação principal (conforme descrito aqui).Adicione um arquivo .keep ao diretório manifests/android da extensão, ao lado de build.gradle. Por exemplo, /myextension/manifests/android/myextension.keep pode preservar as classes Java da extensão com:
-keep,allowoptimization class com.example.myextension.** { *; }
Substitua com.example.myextension pelo pacote que contém as classes Java da sua extensão. Essa regra preserva as classes e seus membros, permitindo que o R8 otimize seu código. Adicione regras para outras classes acessadas pela Java Native Interface (JNI) ou por reflexão, pois o R8 pode não detectar esses usos automaticamente.
Se a extensão depender de anotações em tempo de execução, inclua também:
-keepattributes *Annotation*
Essas regras são combinadas com o arquivo de preservação selecionado para o projeto quando o R8 está ativado.
Com um servidor Extender compatível, o R8 também reduz os recursos Android. Se a extensão procura recursos dinamicamente por nome, adicione regras XML de preservação de recursos em res/android/res/raw na pasta da extensão.
Uma extensão pode incluir dados no arquivo de jogo declarando recursos personalizados em um arquivo ext.properties ao lado de ext.manifest:
[project]
custom_resources.default = /myextension/data
Por exemplo, coloque um arquivo JSON em /myextension/data/settings.json. O caminho é relativo à raiz do projeto, incluindo a pasta da extensão. Ao compartilhar a extensão como biblioteca, inclua myextension em Include Dirs da biblioteca para que os projetos que a utilizam recebam a extensão e seus dados.
Esses caminhos são combinados com project.custom_resources do game.project e as contribuições de outras extensões. Definir recursos personalizados no projeto não substitui as contribuições das extensões. Tanto os builds do editor quanto os arquivos gerados pelo Bob incluem os arquivos, que podem ser carregados em tempo de execução:
local data, err = sys.load_resource("/myextension/data/settings.json")
if data then
local settings = json.decode(data)
pprint(settings)
else
print(err)
end
Consulte acesso a arquivos para saber como recursos personalizados diferem de recursos de pacote.
Extensões são tratadas como qualquer outro asset no seu projeto e podem ser compartilhadas da mesma forma. Se uma pasta de extensão nativa for adicionada como pasta de biblioteca, ela poderá ser compartilhada e usada por outras pessoas como uma dependência de projeto. Consulte o manual de projeto de biblioteca para mais informações.
Vamos criar uma extensão bem simples. Primeiro, criamos uma nova pasta raiz myextension e adicionamos um arquivo ext.manifest contendo o nome da extensão “MyExtension”. Observe que o nome é um símbolo C++ e deve corresponder ao primeiro argumento de DM_DECLARE_EXTENSION (veja abaixo).

# C++ symbol in your extension
name: "MyExtension"
A extensão consiste em um único arquivo C++, myextension.cpp, criado na pasta “src”.

O arquivo-fonte da extensão contém o seguinte código:
// myextension.cpp
// Extension lib defines
#define LIB_NAME "MyExtension"
#define MODULE_NAME "myextension"
// include the Defold SDK
#include <dmsdk/sdk.h>
static int Reverse(lua_State* L)
{
// The number of expected items to be on the Lua stack
// once this struct goes out of scope
DM_LUA_STACK_CHECK(L, 1);
// Check and get parameter string from stack
char* str = (char*)luaL_checkstring(L, 1);
// Reverse the string
int len = strlen(str);
for(int i = 0; i < len / 2; i++) {
const char a = str[i];
const char b = str[len - i - 1];
str[i] = b;
str[len - i - 1] = a;
}
// Put the reverse string on the stack
lua_pushstring(L, str);
// Return 1 item
return 1;
}
// Functions exposed to Lua
static const luaL_reg Module_methods[] =
{
{"reverse", Reverse},
{0, 0}
};
static void LuaInit(lua_State* L)
{
int top = lua_gettop(L);
// Register lua names
luaL_register(L, MODULE_NAME, Module_methods);
lua_pop(L, 1);
assert(top == lua_gettop(L));
}
dmExtension::Result AppInitializeMyExtension(dmExtension::AppParams* params)
{
return dmExtension::RESULT_OK;
}
dmExtension::Result InitializeMyExtension(dmExtension::Params* params)
{
// Init Lua
LuaInit(params->m_L);
printf("Registered %s Extension\n", MODULE_NAME);
return dmExtension::RESULT_OK;
}
dmExtension::Result AppFinalizeMyExtension(dmExtension::AppParams* params)
{
return dmExtension::RESULT_OK;
}
dmExtension::Result FinalizeMyExtension(dmExtension::Params* params)
{
return dmExtension::RESULT_OK;
}
// Defold SDK uses a macro for setting up extension entry points:
//
// DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)
// MyExtension is the C++ symbol that holds all relevant extension data.
// It must match the name field in the `ext.manifest`
DM_DECLARE_EXTENSION(MyExtension, LIB_NAME, AppInitializeMyExtension, AppFinalizeMyExtension, InitializeMyExtension, 0, 0, FinalizeMyExtension)
Observe a macro DM_DECLARE_EXTENSION, usada para declarar os vários pontos de entrada no código da extensão. O primeiro argumento symbol deve corresponder ao nome especificado em ext.manifest. Para este exemplo simples, não há necessidade de pontos de entrada update ou on_event, então 0 é fornecido nessas posições da macro.
Agora basta compilar o projeto (Projeto ▸ Compilar). Isso enviará a extensão ao builder de extensões, que produzirá uma engine personalizada com a nova extensão incluída. Se o builder encontrar algum erro, uma caixa de diálogo com os erros de build será exibida.
Para testar a extensão, crie um objeto de jogo e adicione um componente de script com algum código de teste:
local s = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
local reverse_s = myextension.reverse(s)
print(reverse_s) --> ZYXWVUTSRQPONMLKJIHGFEDCBAzyxwvutsrqponmlkjihgfedcba
E pronto! Criamos uma extensão nativa totalmente funcional.
Como vimos acima, a macro DM_DECLARE_EXTENSION é usada para declarar os vários pontos de entrada no código da extensão:
DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)
Os pontos de entrada permitem executar código em vários momentos do ciclo de vida de uma extensão:
app_init da extensãoinit da extensão - Todas as APIs do Defold foram inicializadas. Este é o ponto recomendado no ciclo de vida da extensão em que os bindings Lua para o código da extensão são criados.init() dos arquivos de script é chamada.update da extensãoupdate() dos arquivos de script é chamada.on_event da extensãofinal() dos arquivos de script é chamada.final da extensãoapp_final da extensãoOs seguintes identificadores são definidos pelo builder em cada plataforma respectiva:
DM_PLATFORM_WINDOWSDM_PLATFORM_OSXDM_PLATFORM_IOSDM_PLATFORM_ANDROIDDM_PLATFORM_LINUXDM_PLATFORM_HTML5Os logs do servidor de build ficam disponíveis quando o projeto usa extensões nativas. O log do servidor de build (log.txt) é baixado junto com a engine personalizada quando o projeto é compilado e armazenado dentro do arquivo .internal/%platform%/build.zip, além de ser descompactado na pasta de build do seu projeto.
O portal de assets do Defold também contém várias extensões nativas.