Defold Native Extension Structure

A native extension is a folder containing ext.manifest and native code for extending the Defold engine.

Required structure

my_extension/
├── ext.manifest           # Extension manifest (YAML)
├── src/                   # Source code (C/C++/ObjC/JS)
│   ├── extension.cpp      # Main extension entry point
│   └── ...
├── include/               # Public headers (optional)
├── lib/                   # Platform libraries (optional)
│   ├── x86_64-win32/
│   ├── x86_64-linux/
│   ├── arm64-ios/
│   └── ...
├── api/                   # Script API definitions (optional)
│   └── my_extension.script_api
└── res/                   # Platform resources (optional)
    └── android/

ext.manifest format

name: "MyExtension"
platforms:
  x86_64-win32:
    context:
      defines: ["MY_DEFINE"]
      libs: ["user32"]
  arm64-ios:
    context:
      frameworks: ["UIKit"]

Extension entry point (C++)

#define EXTENSION_NAME MyExtension
#define LIB_NAME "MyExtension"
#define MODULE_NAME "myextension"

#include <dmsdk/sdk.h>

static int MyFunction(lua_State* L)
{
    // Implementation
    return 0;
}

static const luaL_reg Module_methods[] =
{
    {"my_function", MyFunction},
    {0, 0}
};

static void LuaInit(lua_State* L)
{
    int top = lua_gettop(L);
    luaL_register(L, MODULE_NAME, Module_methods);
    lua_pop(L, 1);
    assert(top == lua_gettop(L));
}

static dmExtension::Result AppInitializeMyExtension(dmExtension::AppParams* params)
{
    return dmExtension::RESULT_OK;
}

static dmExtension::Result InitializeMyExtension(dmExtension::Params* params)
{
    LuaInit(params->m_L);
    return dmExtension::RESULT_OK;
}

static dmExtension::Result FinalizeMyExtension(dmExtension::Params* params)
{
    return dmExtension::RESULT_OK;
}

DM_DECLARE_EXTENSION(EXTENSION_NAME, LIB_NAME, AppInitializeMyExtension, 0, InitializeMyExtension, 0, 0, FinalizeMyExtension)

HTML5/JavaScript extension

For web platform, use .js files in src/:

var MyExtension = {
    MyFunction: function() {
        // Implementation
    }
};
mergeInto(LibraryManager.library, MyExtension);

Platform library paths (lib/)

• x86_64-win32/ - Windows 64-bit
• x86-win32/ - Windows 32-bit
• x86_64-linux/ - Linux 64-bit
• arm64-osx/ - macOS ARM
• x86_64-osx/ - macOS Intel
• arm64-ios/ - iOS ARM64
• armv7-android/, arm64-android/ - Android
• js-web/, wasm-web/ - HTML5

Prefer dmSDK over Lua API calls

Always use direct C++ dmSDK functions instead of calling Lua API wrappers (e.g. lua_getglobal(L, "go") + lua_call). The dmSDK provides efficient C++ equivalents for most Lua game object operations.

Key dmSDK patterns

Getting game object instances from Lua:

// Get the calling script's game object instance
dmGameObject::HInstance caller = dmScript::CheckGOInstance(L);

// Get the collection from any instance
dmGameObject::HCollection collection = dmGameObject::GetCollection(caller);

// Resolve a hash identifier (from Lua stack) to an instance
dmhash_t id = dmScript::CheckHash(L, index);
dmGameObject::HInstance target = dmGameObject::GetInstanceFromIdentifier(collection, id);

Manipulating game objects directly in C++:

// Position (uses dmVMath::Point3)
dmVMath::Point3 pos = dmGameObject::GetPosition(instance);
dmGameObject::SetPosition(instance, dmVMath::Point3(x, y, z));

// Rotation (uses dmVMath::Quat)
dmVMath::Quat rot = dmGameObject::GetRotation(instance);
dmGameObject::SetRotation(instance, rot);

// Scale
float scale = dmGameObject::GetUniformScale(instance);
dmGameObject::SetScale(instance, scale);
dmGameObject::SetScale(instance, dmVMath::Vector3(sx, sy, sz));

Math types — create once, reuse in loops:

dmVMath::Point3 pos(0.0f, 0.0f, 0.0f);
for (int i = 0; i < count; ++i)
{
    pos.setX(computed_x);
    pos.setY(computed_y);
    dmGameObject::SetPosition(instance, pos);
}

Extracting Lua types via dmScript:

dmVMath::Vector3* v = dmScript::CheckVector3(L, index);
dmVMath::Vector4* v4 = dmScript::CheckVector4(L, index);
dmVMath::Quat* q = dmScript::CheckQuat(L, index);
dmVMath::Matrix4* m = dmScript::CheckMatrix4(L, index);
dmhash_t hash = dmScript::CheckHash(L, index);
dmhash_t hash = dmScript::CheckHashOrString(L, index);

Async Lua callbacks via dmScript

When a native extension needs to asynchronously invoke a user-provided Lua callback (e.g. after a platform event, timer, or async operation), use dmScript::LuaCallbackInfo. Reference: https://github.com/indiesoftby/defold-page-visibility/tree/main/page_visibility/src

Storing a callback from Lua:

static dmScript::LuaCallbackInfo* g_Callback = 0;

static int SetCallback(lua_State* L)
{
    DM_LUA_STACK_CHECK(L, 0);

    // Destroy previous callback to avoid leaks
    if (g_Callback)
    {
        dmScript::DestroyCallback(g_Callback);
        g_Callback = 0;
    }

    if (lua_isfunction(L, 1))
    {
        g_Callback = dmScript::CreateCallback(L, 1);
    }

    return 0;
}

Invoking the callback later (from any native event):

static void OnAsyncEvent(int result_code)
{
    if (!g_Callback || !dmScript::IsCallbackValid(g_Callback))
        return;

    lua_State* L = dmScript::GetCallbackLuaContext(g_Callback);
    DM_LUA_STACK_CHECK(L, 0);

    if (!dmScript::SetupCallback(g_Callback))
    {
        dmScript::DestroyCallback(g_Callback);
        g_Callback = 0;
        return;
    }

    // Push arguments after self (self is already on stack from SetupCallback)
    lua_pushnumber(L, result_code);

    dmScript::PCall(L, 2, 0); // 2 = self + 1 user argument

    dmScript::TeardownCallback(g_Callback);
}

Cleanup in Finalize (prevent leaks on extension unload):

static dmExtension::Result FinalizeMyExtension(dmExtension::Params* params)
{
    if (g_Callback)
    {
        dmScript::DestroyCallback(g_Callback);
        g_Callback = 0;
    }
    return dmExtension::RESULT_OK;
}

Lifecycle: CreateCallback → SetupCallback → PCall → TeardownCallback → DestroyCallback (when done).

For one-shot callbacks, call DestroyCallback right after TeardownCallback. For persistent listeners, keep the callback and only destroy on replacement or finalize.

When Lua API calls are acceptable

Only fall back to lua_getglobal/lua_call patterns when:

• The functionality has no dmSDK C++ equivalent (e.g. go.animate, msg.post to arbitrary URLs)
• You need to call a user-defined Lua callback without the dmScript::LuaCallbackInfo pattern (rare)

Defold engine source as reference

The Defold engine source at https://github.com/defold/defold/tree/dev/engine contains extensive dmSDK usage examples. When implementing native extensions, actively study the engine source to find correct API usage patterns, especially:

• engine/gameobject/ — game object manipulation (dmGameObject::*)
• engine/gamesys/ — component systems (sprite, collision, factory, etc.)
• engine/script/ — script bridge utilities (dmScript::*)
• engine/dlib/ — math, hashing, logging, buffers (dmVMath::*, dmLog*, dmBuffer::*)
• engine/render/ — render pipeline (dmRender::*)

Additionally, the Spine extension at https://github.com/defold/extension-spine/tree/main/defold-spine is an excellent real-world reference for dmSDK usage — it demonstrates component registration, game object manipulation, rendering, resource management, and script bindings.

Use the Librarian tool or defold-api-fetch skill to fetch specific API docs. Browse engine source and extension-spine on GitHub for real-world usage when the API docs are insufficient.

Code formatting

When working with native extensions, ensure .clang-format exists in project root for consistent C/C++ formatting. If missing, fetch from Defold repository:

https://raw.githubusercontent.com/defold/defold/refs/heads/dev/.clang-format

Important: This .clang-format is from the official Defold repository and ensures code style consistency with the engine.

API reference

For C++ SDK documentation, use defold-api-fetch skill with C++ Native Extension APIs section (dmExtension, dmScript, dmBuffer, etc.).