API
API
C++
API reference (Extension) — Alpha (1.14.2)

Defold Learn logo


Extension

Functions for creating and controlling engine native extension libraries.

Namespace: dmExtension
Include: #include <dmsdk/extension/extension_gen.hpp>
TYPES
FCallback Extra extension callback typedef
FEventCallback receive a generic engine event
FExtensionAppFinalize Callback when the app is being finalized
FExtensionAppInitialize Callback when the app is being initialized. Called...
FExtensionCallback Extra extension callback typedef
FExtensionEventCallback receive a generic engine event
FExtensionFinalize Calls for the finalization of an extension
FExtensionInitialize Callback after all extensions have been called wit...
FExtensionOnEvent Receives an event from the engine
FExtensionRegister configure an extension
FExtensionUnregister unregister an extension
FExtensionUpdate Updates an extension. Called for each game frame.
FRegister configure an extension
FUnregister unregister an extension
HExtension extension handle
HExtension extension handle
CONSTANTS
ExtensionDescBufferSize Used when registering new extensions
ENUMS
AppExitCode engine exit code
CallbackType extra callback type
EventID event id enumeration
ExtensionAppExitCode engine exit code
ExtensionCallbackType extra callback type
ExtensionEventID event id enumeration
ExtensionParam extension parameter enumeration
ExtensionResult result enumeration
Param extension parameter enumeration
Result result enumeration
STRUCTS
struct AppParams The extension app parameters
struct Event Extension event
struct ExtensionAppParams The extension app parameters
struct ExtensionEvent Extension event
struct ExtensionParams Parameters for an extension's engine lifecycle, up...
struct Params Parameters for an extension's engine lifecycle, up...
FUNCTIONS
void AppParamsFinalize (AppParams* app_params) Finalizes an extension app params struct (dealloca...
AppExitCode AppParamsGetAppExitCode (dmExtension::AppParams* app_params) get the app exit code
void* AppParamsGetContext (AppParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* AppParamsGetContextByName (AppParams params, const char* name) Gets a context using a specified name
HContextRegistry AppParamsGetContextRegistry (AppParams* params) Gets the context registry used by the extension ap...
void* AppParamsGetUserData (const AppParams* params) get the extension's application user data
void AppParamsInitialize (AppParams* app_params) Initializes an extension app params struct NOTE: t...
int AppParamsSetContext (AppParams params, const char* name, void* context) Sets a context using a specified name
void BroadcastEvent (HContextRegistry context_registry, dmhash_t event_id, const void* data, uint32_t data_size) broadcast an extension event
void ExtensionAppParamsFinalize (ExtensionAppParams* app_params) Finalizes an extension app params struct (dealloca...
ExtensionAppExitCode ExtensionAppParamsGetAppExitCode (dmExtension::AppParams* app_params) get the app exit code
void* ExtensionAppParamsGetContext (ExtensionAppParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* ExtensionAppParamsGetContextByName (ExtensionAppParams params, const char* name) Gets a context using a specified name
HContextRegistry ExtensionAppParamsGetContextRegistry (ExtensionAppParams* params) Gets the context registry used by the extension ap...
void* ExtensionAppParamsGetUserData (const ExtensionAppParams* params) get the extension's application user data
void ExtensionAppParamsInitialize (ExtensionAppParams* app_params) Initializes an extension app params struct NOTE: t...
int ExtensionAppParamsSetContext (ExtensionAppParams params, const char* name, void* context) Sets a context using a specified name
void ExtensionBroadcastEvent (HContextRegistry context_registry, dmhash_t event_id, const void* data, uint32_t data_size) broadcast an extension event
void* ExtensionGetUserData (HExtension extension) get an extension's user data
void ExtensionParamsFinalize (ExtensionParams* app_params) Finalizes an extension params struct (deallocates...
void* ExtensionParamsGetContext (ExtensionParams params, dmhash_t name_hash) Gets a context using a specified name hash
void* ExtensionParamsGetContextByName (ExtensionParams params, const char* name) Gets a context using a specified name
HContextRegistry ExtensionParamsGetContextRegistry (ExtensionParams* params) Gets the context registry used by the extension pa...
bool ExtensionParamsGetFloat (const ExtensionParams* params, ExtensionParam param, float* out_value) Gets a float from the extension callback parameter...
void* ExtensionParamsGetUserData (const ExtensionParams* params) get the extension's user data
void ExtensionParamsInitialize (ExtensionParams* app_params) Initializes an extension params struct NOTE: this ...
int ExtensionParamsSetContext (ExtensionParams params, const char* name, void* context) Sets a context using a specified name
void ExtensionRegister (void* desc, const char* desc_size, const char* name, FExtensionAppInitialize app_initialize, FExtensionAppFinalize app_finalize, FExtensionInitialize initialize, FExtensionFinalize finalize, FExtensionUpdate update, FExtensionOnEvent on_event) Extension declaration helper. Internal function. U...
void ExtensionRegisterDesc (void* desc, uint32_t desc_size, const char* name, FExtensionRegister register_fn, FExtensionUnregister unregister_fn) extension declaration helper
void ExtensionRegisteriOSUIApplicationDelegate (void* delegate) Register application delegate
void ExtensionRegisteriOSUISceneDelegate (void* delegate) Register a scene delegate
void ExtensionSetAppFinalizeFn (HExtension extension, FExtensionAppFinalize fn) set the application finalization callback
void ExtensionSetAppInitializeFn (HExtension extension, FExtensionAppInitialize fn) set the application initialization callback
void ExtensionSetEventFn (HExtension extension, FExtensionEventCallback fn) set the generic event callback
void ExtensionSetFinalizeFn (HExtension extension, FExtensionFinalize fn) set the engine finalization callback
void ExtensionSetInitializeFn (HExtension extension, FExtensionInitialize fn) set the engine initialization callback
void ExtensionSetPostRenderFn (HExtension extension, FExtensionCallback fn) set the post-render callback
void ExtensionSetPreRenderFn (HExtension extension, FExtensionCallback fn) set the pre-render callback
void ExtensionSetUpdateFn (HExtension extension, FExtensionUpdate fn) set the engine update callback
void ExtensionSetUserData (HExtension extension, void* user_data) associate user data with an extension
void ExtensionUnregisteriOSUIApplicationDelegate (void* delegate) Unregister an application delegate
void ExtensionUnregisteriOSUISceneDelegate (void* delegate) Unregister a scene delegate
void* GetUserData (HExtension extension) get an extension's user data
void ParamsFinalize (Params* app_params) Finalizes an extension params struct (deallocates...
void* ParamsGetContext (Params params, dmhash_t name_hash) Gets a context using a specified name hash
void* ParamsGetContextByName (Params params, const char* name) Gets a context using a specified name
HContextRegistry ParamsGetContextRegistry (Params* params) Gets the context registry used by the extension pa...
bool ParamsGetFloat (const Params* params, Param param, float* out_value) Gets a float from the extension callback parameter...
void* ParamsGetUserData (const Params* params) get the extension's user data
void ParamsInitialize (Params* app_params) Initializes an extension params struct NOTE: this ...
int ParamsSetContext (Params params, const char* name, void* context) Sets a context using a specified name
void RegisterCallback () Generated from ExtensionRegisterCallback
void RegisteriOSUIApplicationDelegate (void* delegate) Register application delegate
void RegisteriOSUISceneDelegate (void* delegate) Register a scene delegate
void SetAppFinalizeFn (HExtension extension, FExtensionAppFinalize fn) set the application finalization callback
void SetAppInitializeFn (HExtension extension, FExtensionAppInitialize fn) set the application initialization callback
void SetEventFn (HExtension extension, FEventCallback fn) set the generic event callback
void SetFinalizeFn (HExtension extension, FExtensionFinalize fn) set the engine finalization callback
void SetInitializeFn (HExtension extension, FExtensionInitialize fn) set the engine initialization callback
void SetPostRenderFn (HExtension extension, FCallback fn) set the post-render callback
void SetPreRenderFn (HExtension extension, FCallback fn) set the pre-render callback
void SetUpdateFn (HExtension extension, FExtensionUpdate fn) set the engine update callback
void SetUserData (HExtension extension, void* user_data) associate user data with an extension
void UnregisteriOSUIApplicationDelegate (void* delegate) Unregister an application delegate
void UnregisteriOSUISceneDelegate (void* delegate) Unregister a scene delegate
MACROS
DM_DECLARE_EXTENSION () declare an extension
DM_PLATFORM_ANDROID () Set if the platform is Android
DM_PLATFORM_HTML5 () Set if the platform is Html5
DM_PLATFORM_IOS () Set if the platform is iPhoneOS
DM_PLATFORM_LINUX () Set if the platform is Linux
DM_PLATFORM_OSX () Set if the platform is OSX
DM_PLATFORM_WINDOWS () Set if the platform is Windows (on both x86 and x86_64)

Functions

AppParamsFinalize

void AppParamsFinalize(AppParams* app_params)

Finalizes an extension app params struct (deallocates internal memory)

PARAMETERS

AppParams* app_params the params

AppParamsGetAppExitCode

AppExitCode AppParamsGetAppExitCode(dmExtension::AppParams* app_params)

get the app exit code

PARAMETERS

dmExtension::AppParams* app_params The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitialize

RETURNS

AppExitCode engine exit code

AppParamsGetContext

void* AppParamsGetContext(AppParams params, dmhash_t name_hash)

Gets a context using a specified name hash

PARAMETERS

AppParams params the params
dmhash_t name_hash the context name hash

RETURNS

void* The context, if it exists

AppParamsGetContextByName

void* AppParamsGetContextByName(AppParams params, const char* name)

Gets a context using a specified name

PARAMETERS

AppParams params the params
const char* name the context name

RETURNS

void* The context, if it exists

AppParamsGetContextRegistry

HContextRegistry AppParamsGetContextRegistry(AppParams* params)

Gets the context registry used by the extension app params.

PARAMETERS

AppParams* params the params

RETURNS

HContextRegistry the context registry

AppParamsGetUserData

void* AppParamsGetUserData(const AppParams* params)

Returns the pointer associated with this extension by SetUserData. Available during AppInitialize and AppFinalize, including failed initialization cleanup. Returns null if no pointer was set or outside an extension callback. The extension owns the memory; do not retain the borrowed parameters.

PARAMETERS

const AppParams* params valid application callback parameters

RETURNS

void* this extension's user data, or null

AppParamsInitialize

void AppParamsInitialize(AppParams* app_params)

Initializes an extension app params struct NOTE: this is an opaque struct, do not use it's members directly!

PARAMETERS

AppParams* app_params the params

AppParamsSetContext

int AppParamsSetContext(AppParams params, const char* name, void* context)

Sets a context using a specified name

PARAMETERS

AppParams params the params
const char* name the context name
void* context the context

RETURNS

int 0 if successful

BroadcastEvent

void BroadcastEvent(HContextRegistry context_registry, dmhash_t event_id, const void* data, uint32_t data_size)

Synchronously delivers an event to every eligible generic extension handler. The engine accepts arbitrary event hashes and opaque payloads without event or payload registration. Receivers ignore event ids they do not recognize. Use extension-specific names for custom events; names beginning with _dm_event_ are reserved for engine events. This function is not thread-safe. Call only on the engine thread. Callbacks run on the calling thread; no queuing or worker-thread marshalling occurs. Nested dispatch is supported. Delivery order is unspecified; events cannot be consumed. The context registry and payload are borrowed until return. Each broadcast supplies callback parameters using the registry's contexts and each receiver's user data. Event parameters have a delta time of zero. The sender retains ownership. Data is read-only to receivers. Passing null data with data_size zero sends a payload-free event. The engine forwards the payload without interpreting its contents.

PARAMETERS

HContextRegistry context_registry borrowed engine context registry, or null for no contexts
dmhash_t event_id hash of the event name
const void* data borrowed payload, or null for a payload-free event
uint32_t data_size payload size in bytes; zero for a payload-free event

EXAMPLES

HContextRegistry context_registry = ParamsGetContextRegistry(params);
uint32_t value = 42;
BroadcastEvent(context_registry, dmHashString64("my_extension.changed"), &value, sizeof(value));

ExtensionAppParamsFinalize

void ExtensionAppParamsFinalize(ExtensionAppParams* app_params)

Finalizes an extension app params struct (deallocates internal memory)

PARAMETERS

ExtensionAppParams* app_params the params

ExtensionAppParamsGetAppExitCode

ExtensionAppExitCode ExtensionAppParamsGetAppExitCode(dmExtension::AppParams* app_params)

get the app exit code

PARAMETERS

dmExtension::AppParams* app_params The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitialize

RETURNS

ExtensionAppExitCode engine exit code

ExtensionAppParamsGetContext

void* ExtensionAppParamsGetContext(ExtensionAppParams params, dmhash_t name_hash)

Gets a context using a specified name hash

PARAMETERS

ExtensionAppParams params the params
dmhash_t name_hash the context name hash

RETURNS

void* The context, if it exists

ExtensionAppParamsGetContextByName

void* ExtensionAppParamsGetContextByName(ExtensionAppParams params, const char* name)

Gets a context using a specified name

PARAMETERS

ExtensionAppParams params the params
const char* name the context name

RETURNS

void* The context, if it exists

ExtensionAppParamsGetContextRegistry

HContextRegistry ExtensionAppParamsGetContextRegistry(ExtensionAppParams* params)

Gets the context registry used by the extension app params.

PARAMETERS

ExtensionAppParams* params the params

RETURNS

HContextRegistry the context registry

ExtensionAppParamsGetUserData

void* ExtensionAppParamsGetUserData(const ExtensionAppParams* params)

Returns the pointer associated with this extension by ExtensionSetUserData. Available during AppInitialize and AppFinalize, including failed initialization cleanup. Returns null if no pointer was set or outside an extension callback. The extension owns the memory; do not retain the borrowed parameters.

PARAMETERS

const ExtensionAppParams* params valid application callback parameters

RETURNS

void* this extension's user data, or null

ExtensionAppParamsInitialize

void ExtensionAppParamsInitialize(ExtensionAppParams* app_params)

Initializes an extension app params struct NOTE: this is an opaque struct, do not use it's members directly!

PARAMETERS

ExtensionAppParams* app_params the params

ExtensionAppParamsSetContext

int ExtensionAppParamsSetContext(ExtensionAppParams params, const char* name, void* context)

Sets a context using a specified name

PARAMETERS

ExtensionAppParams params the params
const char* name the context name
void* context the context

RETURNS

int 0 if successful

ExtensionBroadcastEvent

void ExtensionBroadcastEvent(HContextRegistry context_registry, dmhash_t event_id, const void* data, uint32_t data_size)

Synchronously delivers an event to every eligible generic extension handler. The engine accepts arbitrary event hashes and opaque payloads without event or payload registration. Receivers ignore event ids they do not recognize. Use extension-specific names for custom events; names beginning with _dm_event_ are reserved for engine events. This function is not thread-safe. Call only on the engine thread. Callbacks run on the calling thread; no queuing or worker-thread marshalling occurs. Nested dispatch is supported. Delivery order is unspecified; events cannot be consumed. The context registry and payload are borrowed until return. Each broadcast supplies callback parameters using the registry's contexts and each receiver's user data. Event parameters have a delta time of zero. The sender retains ownership. Data is read-only to receivers. Passing null data with data_size zero sends a payload-free event. The engine forwards the payload without interpreting its contents.

PARAMETERS

HContextRegistry context_registry borrowed engine context registry, or null for no contexts
dmhash_t event_id hash of the event name
const void* data borrowed payload, or null for a payload-free event
uint32_t data_size payload size in bytes; zero for a payload-free event

EXAMPLES

HContextRegistry context_registry = ExtensionParamsGetContextRegistry(params);
uint32_t value = 42;
ExtensionBroadcastEvent(context_registry, dmHashString64("my_extension.changed"), &value, sizeof(value));

ExtensionGetUserData

void* ExtensionGetUserData(HExtension extension)

Use during register or unregister to retrieve the pointer associated with this extension by ExtensionSetUserData. The extension owns the memory.

PARAMETERS

HExtension extension borrowed extension configuration handle

RETURNS

void* this extension's user data, or null

ExtensionParamsFinalize

void ExtensionParamsFinalize(ExtensionParams* app_params)

Finalizes an extension params struct (deallocates internal memory)

PARAMETERS

ExtensionParams* app_params the params

ExtensionParamsGetContext

void* ExtensionParamsGetContext(ExtensionParams params, dmhash_t name_hash)

Gets a context using a specified name hash

PARAMETERS

ExtensionParams params the params
dmhash_t name_hash the context name hash

RETURNS

void* The context, if it exists

ExtensionParamsGetContextByName

void* ExtensionParamsGetContextByName(ExtensionParams params, const char* name)

Gets a context using a specified name

PARAMETERS

ExtensionParams params the params
const char* name the context name

RETURNS

void* The context, if it exists

ExtensionParamsGetContextRegistry

HContextRegistry ExtensionParamsGetContextRegistry(ExtensionParams* params)

Gets the context registry used by the extension params.

PARAMETERS

ExtensionParams* params the params

RETURNS

HContextRegistry the context registry

ExtensionParamsGetFloat

bool ExtensionParamsGetFloat(const ExtensionParams* params, ExtensionParam param, float* out_value)

Gets a float from the extension callback parameters. Supported parameters:

Parameter Description
EXTENSION_PARAM_DT Current engine update delta in seconds, before collection-proxy time scaling. Zero outside the extension update callback.

PARAMETERS

const ExtensionParams* params valid parameters for the current callback
ExtensionParam param parameter to read, for example EXTENSION_PARAM_DT
float* out_value output value; left unchanged if the parameter is unsupported

RETURNS

bool true if the parameter is supported, otherwise false

ExtensionParamsGetUserData

void* ExtensionParamsGetUserData(const ExtensionParams* params)

Returns the pointer associated with this extension by ExtensionSetUserData during Initialize, Update, Finalize, pre/post-render and event callbacks. Nested callback delivery restores the outer callback's pointer on return. Returns null if no pointer was set or outside an extension callback. The extension owns the memory; do not retain the borrowed parameters.

PARAMETERS

const ExtensionParams* params valid callback parameters

RETURNS

void* this extension's user data, or null

ExtensionParamsInitialize

void ExtensionParamsInitialize(ExtensionParams* app_params)

Initializes an extension params struct NOTE: this is an opaque struct, do not use it's members directly!

PARAMETERS

ExtensionParams* app_params the params

ExtensionParamsSetContext

int ExtensionParamsSetContext(ExtensionParams params, const char* name, void* context)

Sets a context using a specified name

PARAMETERS

ExtensionParams params the params
const char* name the context name
void* context the context

RETURNS

int 0 if successful

ExtensionRegister

void ExtensionRegister(void* desc, const char* desc_size, const char* name, FExtensionAppInitialize app_initialize, FExtensionAppFinalize app_finalize, FExtensionInitialize initialize, FExtensionFinalize finalize, FExtensionUpdate update, FExtensionOnEvent on_event)

Extension declaration helper. Internal function. Use DM_DECLARE_EXTENSION

PARAMETERS

void* desc A persistent buffer of at least 128 bytes.
const char* desc_size size of buffer holding desc. in bytes
const char* name extension name. Copied for the process lifetime, retaining at most 15 bytes plus NUL.
FExtensionAppInitialize app_initialize app-init function. May be null
FExtensionAppFinalize app_finalize app-final function. May be null
FExtensionInitialize initialize init function. May not be 0
FExtensionFinalize finalize finalize function. May not be 0
FExtensionUpdate update update function. May be null
FExtensionOnEvent on_event event callback function. May be null

ExtensionRegisterDesc

void ExtensionRegisterDesc(void* desc, uint32_t desc_size, const char* name, FExtensionRegister register_fn, FExtensionUnregister unregister_fn)

Internal function used by the three-argument DM_DECLARE_EXTENSION macro. The descriptor storage and name must remain valid for the process lifetime.

PARAMETERS

void* desc aligned descriptor buffer
uint32_t desc_size descriptor buffer size in bytes
const char* name extension name
FExtensionRegister register_fn configuration callback
FExtensionUnregister unregister_fn cleanup callback, or null

ExtensionRegisteriOSUIApplicationDelegate

void ExtensionRegisteriOSUIApplicationDelegate(void* delegate)

Register an iOS application delegate for process-level callbacks such as launch and remote notification registration. Multiple delegates are supported (Max 32). Use application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: for launch. The older applicationDidFinishLaunching: callback is not synthesized. Defold uses the UIScene lifecycle. Application activity, URL and user activity callbacks are not forwarded from scenes; use ExtensionRegisteriOSUISceneDelegate. The game window is created after application launch. Use scene connection to access it, and scene connection options for cold-launch URLs and user activities. application:supportedInterfaceOrientationsForWindow: can override the game's orientation settings, including on iOS 27 and later. The last nonzero mask containing only valid UIInterfaceOrientationMask bits in delegate dispatch order is used. Invalid masks are ignored. The application, scene, and root view controller share this policy, including during full-screen presentations. The game's default mask comes from the DefoldSupportedInterfaceOrientations Info.plist array, with DefoldSupportedInterfaceOrientations~ipad taking precedence on iPad. If neither contains usable orientations, Defold falls back to UISupportedInterfaceOrientations~ipad on iPad, then UISupportedInterfaceOrientations. Arrays contain UIKit orientation names such as UIInterfaceOrientationPortrait. The default policy excludes upside-down portrait on iPhone. If no array is usable, all device-supported orientations are allowed. The built-in manifest keeps the UIKit arrays broad and uses the Defold array for the game's orientation settings. UIKit may ignore orientation restrictions, including on iPhone Duo's inner display. Games must still handle window size changes. Register before scene connection to affect the initial orientation. To update the policy after scene connection, call setNeedsUpdateOfSupportedInterfaceOrientations on the root view controller (iOS 16+) or attemptRotationToDeviceOrientation (iOS 15).

PARAMETERS

void* delegate An id.

ExtensionRegisteriOSUISceneDelegate

void ExtensionRegisteriOSUISceneDelegate(void* delegate)

Register an iOS scene observer. Multiple delegates are supported (Max 32). Defold owns the single game window and its scene configuration. Registered observers receive scene connection/disconnection, activation/deactivation, foreground/background, openURLContexts, continueUserActivity, willContinueUserActivityWithType, didFailToContinueUserActivityWithType:error: and didUpdateUserActivity callbacks. Other optional delegate methods are not forwarded. No legacy UIApplicationDelegate callbacks are synthesized. Register before UIApplicationMain (for example in a static constructor) to receive the initial scene connection. Extension app-initialize is too late. Cold-launch URLs, user activities and notification responses are available in UISceneConnectionOptions. Scene connection may precede Lua initialization; extensions must retain any data they need to deliver to Lua later.

PARAMETERS

void* delegate An id.

EXAMPLES

// myextension_ios.mm
@interface MySceneDelegate : NSObject <UISceneDelegate>
- (void)scene:(UIScene*)scene willConnectToSession:(UISceneSession*)session options:(UISceneConnectionOptions*)options;
- (void)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)contexts;
@end

struct MySceneDelegateRegistration
{
    MySceneDelegate* m_Delegate;
    MySceneDelegateRegistration()
    {
        m_Delegate = [[MySceneDelegate alloc] init];
        dmExtension::RegisteriOSUISceneDelegate(m_Delegate);
    }
    ~MySceneDelegateRegistration()
    {
        dmExtension::UnregisteriOSUISceneDelegate(m_Delegate);
        [m_Delegate release];
    }
};
MySceneDelegateRegistration g_MySceneDelegateRegistration;

ExtensionSetAppFinalizeFn

void ExtensionSetAppFinalizeFn(HExtension extension, FExtensionAppFinalize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionAppFinalize fn callback, or null

ExtensionSetAppInitializeFn

void ExtensionSetAppInitializeFn(HExtension extension, FExtensionAppInitialize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionAppInitialize fn callback, or null

ExtensionSetEventFn

void ExtensionSetEventFn(HExtension extension, FExtensionEventCallback fn)

Call only from the register callback. One handler receives all generic events; use the callback's event_id to select events. No event-name argument or per-event registration is needed. Passing null clears it. Registration resets on engine reboot; no event is replayed to a late receiver.

PARAMETERS

HExtension extension extension configuration handle
FExtensionEventCallback fn callback, or null

ExtensionSetFinalizeFn

void ExtensionSetFinalizeFn(HExtension extension, FExtensionFinalize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionFinalize fn callback, or null

ExtensionSetInitializeFn

void ExtensionSetInitializeFn(HExtension extension, FExtensionInitialize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionInitialize fn callback, or null

ExtensionSetPostRenderFn

void ExtensionSetPostRenderFn(HExtension extension, FExtensionCallback fn)

Call only from the register callback. Passing null clears the callback. Delivery requires successful AppInitialize, or no AppInitialize callback, and stops before AppFinalize. It does not require an Initialize callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionCallback fn callback, or null

ExtensionSetPreRenderFn

void ExtensionSetPreRenderFn(HExtension extension, FExtensionCallback fn)

Call only from the register callback. Passing null clears the callback. Delivery requires successful AppInitialize, or no AppInitialize callback, and stops before AppFinalize. It does not require an Initialize callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionCallback fn callback, or null

ExtensionSetUpdateFn

void ExtensionSetUpdateFn(HExtension extension, FExtensionUpdate fn)

Call only from the register callback. Passing null clears the callback. Updates begin after successful engine initialization and stop before Finalize, even when no Initialize or Finalize callback is configured.

PARAMETERS

HExtension extension extension configuration handle
FExtensionUpdate fn callback, or null

ExtensionSetUserData

void ExtensionSetUserData(HExtension extension, void* user_data)

Call only from the register callback. The engine borrows this pointer; it does not allocate, copy or free the memory. Passing null clears it. Retrieve it from callback parameters with ExtensionParamsGetUserData or ExtensionAppParamsGetUserData, and from the unregister callback with ExtensionGetUserData. Keep it valid through all callbacks, then release it in unregister. If registration fails, release it before returning because unregister is not called. The pointer resets to null before each registration and after unregister, including engine reboot.

PARAMETERS

HExtension extension borrowed extension configuration handle
void* user_data extension-owned pointer, or null

ExtensionUnregisteriOSUIApplicationDelegate

void ExtensionUnregisteriOSUIApplicationDelegate(void* delegate)

Deregister a previously registered iOS application delegate. This function is only available on iOS.

PARAMETERS

void* delegate An id.

ExtensionUnregisteriOSUISceneDelegate

void ExtensionUnregisteriOSUISceneDelegate(void* delegate)

Deregister a previously registered iOS scene observer on the main thread. This function is only available on iOS.

PARAMETERS

void* delegate An id.

GetUserData

void* GetUserData(HExtension extension)

Use during register or unregister to retrieve the pointer associated with this extension by SetUserData. The extension owns the memory.

PARAMETERS

HExtension extension borrowed extension configuration handle

RETURNS

void* this extension's user data, or null

ParamsFinalize

void ParamsFinalize(Params* app_params)

Finalizes an extension params struct (deallocates internal memory)

PARAMETERS

Params* app_params the params

ParamsGetContext

void* ParamsGetContext(Params params, dmhash_t name_hash)

Gets a context using a specified name hash

PARAMETERS

Params params the params
dmhash_t name_hash the context name hash

RETURNS

void* The context, if it exists

ParamsGetContextByName

void* ParamsGetContextByName(Params params, const char* name)

Gets a context using a specified name

PARAMETERS

Params params the params
const char* name the context name

RETURNS

void* The context, if it exists

ParamsGetContextRegistry

HContextRegistry ParamsGetContextRegistry(Params* params)

Gets the context registry used by the extension params.

PARAMETERS

Params* params the params

RETURNS

HContextRegistry the context registry

ParamsGetFloat

bool ParamsGetFloat(const Params* params, Param param, float* out_value)

Gets a float from the extension callback parameters. Supported parameters:

Parameter Description
PARAM_DT Current engine update delta in seconds, before collection-proxy time scaling. Zero outside the extension update callback.

PARAMETERS

const Params* params valid parameters for the current callback
Param param parameter to read, for example PARAM_DT
float* out_value output value; left unchanged if the parameter is unsupported

RETURNS

bool true if the parameter is supported, otherwise false

ParamsGetUserData

void* ParamsGetUserData(const Params* params)

Returns the pointer associated with this extension by SetUserData during Initialize, Update, Finalize, pre/post-render and event callbacks. Nested callback delivery restores the outer callback's pointer on return. Returns null if no pointer was set or outside an extension callback. The extension owns the memory; do not retain the borrowed parameters.

PARAMETERS

const Params* params valid callback parameters

RETURNS

void* this extension's user data, or null

ParamsInitialize

void ParamsInitialize(Params* app_params)

Initializes an extension params struct NOTE: this is an opaque struct, do not use it's members directly!

PARAMETERS

Params* app_params the params

ParamsSetContext

int ParamsSetContext(Params params, const char* name, void* context)

Sets a context using a specified name

PARAMETERS

Params params the params
const char* name the context name
void* context the context

RETURNS

int 0 if successful

RegisterCallback

void RegisterCallback()

Generated from ExtensionRegisterCallback

PARAMETERS


RegisteriOSUIApplicationDelegate

void RegisteriOSUIApplicationDelegate(void* delegate)

Register an iOS application delegate for process-level callbacks such as launch and remote notification registration. Multiple delegates are supported (Max 32). Use application:willFinishLaunchingWithOptions: and application:didFinishLaunchingWithOptions: for launch. The older applicationDidFinishLaunching: callback is not synthesized. Defold uses the UIScene lifecycle. Application activity, URL and user activity callbacks are not forwarded from scenes; use RegisteriOSUISceneDelegate. The game window is created after application launch. Use scene connection to access it, and scene connection options for cold-launch URLs and user activities. application:supportedInterfaceOrientationsForWindow: can override the game's orientation settings, including on iOS 27 and later. The last nonzero mask containing only valid UIInterfaceOrientationMask bits in delegate dispatch order is used. Invalid masks are ignored. The application, scene, and root view controller share this policy, including during full-screen presentations. The game's default mask comes from the DefoldSupportedInterfaceOrientations Info.plist array, with DefoldSupportedInterfaceOrientations~ipad taking precedence on iPad. If neither contains usable orientations, Defold falls back to UISupportedInterfaceOrientations~ipad on iPad, then UISupportedInterfaceOrientations. Arrays contain UIKit orientation names such as UIInterfaceOrientationPortrait. The default policy excludes upside-down portrait on iPhone. If no array is usable, all device-supported orientations are allowed. The built-in manifest keeps the UIKit arrays broad and uses the Defold array for the game's orientation settings. UIKit may ignore orientation restrictions, including on iPhone Duo's inner display. Games must still handle window size changes. Register before scene connection to affect the initial orientation. To update the policy after scene connection, call setNeedsUpdateOfSupportedInterfaceOrientations on the root view controller (iOS 16+) or attemptRotationToDeviceOrientation (iOS 15).

PARAMETERS

void* delegate An id.

RegisteriOSUISceneDelegate

void RegisteriOSUISceneDelegate(void* delegate)

Register an iOS scene observer. Multiple delegates are supported (Max 32). Defold owns the single game window and its scene configuration. Registered observers receive scene connection/disconnection, activation/deactivation, foreground/background, openURLContexts, continueUserActivity, willContinueUserActivityWithType, didFailToContinueUserActivityWithType:error: and didUpdateUserActivity callbacks. Other optional delegate methods are not forwarded. No legacy UIApplicationDelegate callbacks are synthesized. Register before UIApplicationMain (for example in a static constructor) to receive the initial scene connection. Extension app-initialize is too late. Cold-launch URLs, user activities and notification responses are available in UISceneConnectionOptions. Scene connection may precede Lua initialization; extensions must retain any data they need to deliver to Lua later.

PARAMETERS

void* delegate An id.

EXAMPLES

// myextension_ios.mm
@interface MySceneDelegate : NSObject <UISceneDelegate>
- (void)scene:(UIScene*)scene willConnectToSession:(UISceneSession*)session options:(UISceneConnectionOptions*)options;
- (void)scene:(UIScene*)scene openURLContexts:(NSSet<UIOpenURLContext*>*)contexts;
@end

struct MySceneDelegateRegistration
{
    MySceneDelegate* m_Delegate;
    MySceneDelegateRegistration()
    {
        m_Delegate = [[MySceneDelegate alloc] init];
        dmExtension::RegisteriOSUISceneDelegate(m_Delegate);
    }
    ~MySceneDelegateRegistration()
    {
        dmExtension::UnregisteriOSUISceneDelegate(m_Delegate);
        [m_Delegate release];
    }
};
MySceneDelegateRegistration g_MySceneDelegateRegistration;

SetAppFinalizeFn

void SetAppFinalizeFn(HExtension extension, FExtensionAppFinalize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionAppFinalize fn callback, or null

SetAppInitializeFn

void SetAppInitializeFn(HExtension extension, FExtensionAppInitialize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionAppInitialize fn callback, or null

SetEventFn

void SetEventFn(HExtension extension, FEventCallback fn)

Call only from the register callback. One handler receives all generic events; use the callback's event_id to select events. No event-name argument or per-event registration is needed. Passing null clears it. Registration resets on engine reboot; no event is replayed to a late receiver.

PARAMETERS

HExtension extension extension configuration handle
FEventCallback fn callback, or null

SetFinalizeFn

void SetFinalizeFn(HExtension extension, FExtensionFinalize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionFinalize fn callback, or null

SetInitializeFn

void SetInitializeFn(HExtension extension, FExtensionInitialize fn)

Call only from the register callback. Passing null clears the callback.

PARAMETERS

HExtension extension extension configuration handle
FExtensionInitialize fn callback, or null

SetPostRenderFn

void SetPostRenderFn(HExtension extension, FCallback fn)

Call only from the register callback. Passing null clears the callback. Delivery requires successful AppInitialize, or no AppInitialize callback, and stops before AppFinalize. It does not require an Initialize callback.

PARAMETERS

HExtension extension extension configuration handle
FCallback fn callback, or null

SetPreRenderFn

void SetPreRenderFn(HExtension extension, FCallback fn)

Call only from the register callback. Passing null clears the callback. Delivery requires successful AppInitialize, or no AppInitialize callback, and stops before AppFinalize. It does not require an Initialize callback.

PARAMETERS

HExtension extension extension configuration handle
FCallback fn callback, or null

SetUpdateFn

void SetUpdateFn(HExtension extension, FExtensionUpdate fn)

Call only from the register callback. Passing null clears the callback. Updates begin after successful engine initialization and stop before Finalize, even when no Initialize or Finalize callback is configured.

PARAMETERS

HExtension extension extension configuration handle
FExtensionUpdate fn callback, or null

SetUserData

void SetUserData(HExtension extension, void* user_data)

Call only from the register callback. The engine borrows this pointer; it does not allocate, copy or free the memory. Passing null clears it. Retrieve it from callback parameters with ParamsGetUserData or AppParamsGetUserData, and from the unregister callback with GetUserData. Keep it valid through all callbacks, then release it in unregister. If registration fails, release it before returning because unregister is not called. The pointer resets to null before each registration and after unregister, including engine reboot.

PARAMETERS

HExtension extension borrowed extension configuration handle
void* user_data extension-owned pointer, or null

UnregisteriOSUIApplicationDelegate

void UnregisteriOSUIApplicationDelegate(void* delegate)

Deregister a previously registered iOS application delegate. This function is only available on iOS.

PARAMETERS

void* delegate An id.

UnregisteriOSUISceneDelegate

void UnregisteriOSUISceneDelegate(void* delegate)

Deregister a previously registered iOS scene observer on the main thread. This function is only available on iOS.

PARAMETERS

void* delegate An id.

Structs

AppParams

TYPE

struct AppParams

The extension app parameters

MEMBERS

HConfigFile m_ConfigFile Deprecated
AppExitCode m_ExitStatus App exit code


Event

TYPE

struct Event

Extension event

MEMBERS

EventID m_Event


ExtensionAppParams

TYPE

struct ExtensionAppParams

The extension app parameters

MEMBERS

HConfigFile m_ConfigFile Deprecated
ExtensionAppExitCode m_ExitStatus App exit code


ExtensionEvent

TYPE

struct ExtensionEvent

Extension event

MEMBERS

ExtensionEventID m_Event


ExtensionParams

TYPE

struct ExtensionParams

Parameters for an extension's engine lifecycle, update, render and event callbacks.

MEMBERS

HConfigFile m_ConfigFile The game project settings (including overrides and plugins)
HResourceFactory m_ResourceFactory The game resource factory / repository
lua_State* m_L The Lua state.


Params

TYPE

struct Params

Parameters for an extension's engine lifecycle, update, render and event callbacks.

MEMBERS

HConfigFile m_ConfigFile The game project settings (including overrides and plugins)
HResourceFactory m_ResourceFactory The game resource factory / repository
lua_State* m_L The Lua state.


Constants

ExtensionDescBufferSize

Used when registering new extensions


Types

FCallback

Result FCallback(Params params)

Callback typedef for functions passed to RegisterCallback().

PARAMETERS

Params params

RETURNS

Result


FEventCallback

void FEventCallback(Params* params, dmhash_t event_id, const void* data, uint32_t data_size)

Synchronous delivery on the engine thread, after successful AppInitialize (or when it is omitted) until that extension's AppFinalize begins. Engine Initialize is not required: window events and cleanup after a failed initialization may have partial contexts. Engine-owned registry entries are cleared as their contexts are destroyed; Lua and resource-factory parameters can be null during application finalization. Event dispatch is not thread-safe. Publish events only on the engine thread. Callbacks run synchronously on the calling thread; dispatch does not marshal calls from worker threads. Nested dispatch on the same engine thread is supported. One catch-all callback receives every generic event. Parameters and data are borrowed for this call only. Inspect event_id to choose which events to handle; no per-event registration is required. Payload-free events pass null data and data_size zero. Receivers interpret data according to the event's documented payload type and size. Delivery order between extensions is unspecified. All events are broadcasts; every eligible handler is called and events cannot be consumed. Extensions can publish custom events through BroadcastEvent. Ignore ids you do not recognize. Built-in engine event definitions are available in <dmsdk/engine/engine_event.h>.

PARAMETERS

Params* params callback parameters; available contexts depend on lifecycle phase
dmhash_t event_id event name hash
const void* data immutable borrowed payload, or null
uint32_t data_size payload size in bytes; zero for payload-free events


FExtensionAppFinalize

ExtensionResult FExtensionAppFinalize(ExtensionAppParams params)

Callback when the app is being finalized

PARAMETERS

ExtensionAppParams params

RETURNS

ExtensionResult EXTENSION_RESULT_OK if all went ok


FExtensionAppInitialize

ExtensionResult FExtensionAppInitialize(ExtensionAppParams params)

Callback when the app is being initialized. Called before FExtensionInitialize

PARAMETERS

ExtensionAppParams params

RETURNS

ExtensionResult EXTENSION_RESULT_OK if all went ok


FExtensionCallback

ExtensionResult FExtensionCallback(ExtensionParams params)

Callback typedef for functions passed to RegisterCallback().

PARAMETERS

ExtensionParams params

RETURNS

ExtensionResult


FExtensionEventCallback

void FExtensionEventCallback(ExtensionParams* params, dmhash_t event_id, const void* data, uint32_t data_size)

Synchronous delivery on the engine thread, after successful AppInitialize (or when it is omitted) until that extension's AppFinalize begins. Engine Initialize is not required: window events and cleanup after a failed initialization may have partial contexts. Engine-owned registry entries are cleared as their contexts are destroyed; Lua and resource-factory parameters can be null during application finalization. Event dispatch is not thread-safe. Publish events only on the engine thread. Callbacks run synchronously on the calling thread; dispatch does not marshal calls from worker threads. Nested dispatch on the same engine thread is supported. One catch-all callback receives every generic event. Parameters and data are borrowed for this call only. Inspect event_id to choose which events to handle; no per-event registration is required. Payload-free events pass null data and data_size zero. Receivers interpret data according to the event's documented payload type and size. Delivery order between extensions is unspecified. All events are broadcasts; every eligible handler is called and events cannot be consumed. Extensions can publish custom events through ExtensionBroadcastEvent. Ignore ids you do not recognize. Built-in engine event definitions are available in <dmsdk/engine/engine_event.h>.

PARAMETERS

ExtensionParams* params callback parameters; available contexts depend on lifecycle phase
dmhash_t event_id event name hash
const void* data immutable borrowed payload, or null
uint32_t data_size payload size in bytes; zero for payload-free events


FExtensionFinalize

ExtensionResult FExtensionFinalize(ExtensionParams params)

Calls for the finalization of an extension

PARAMETERS

ExtensionParams params

RETURNS

ExtensionResult EXTENSION_RESULT_OK if all went ok


FExtensionInitialize

ExtensionResult FExtensionInitialize(ExtensionParams params)

Callback after all extensions have been called with FExtensionAppInitialize

PARAMETERS

ExtensionParams params

RETURNS

ExtensionResult EXTENSION_RESULT_OK if all went ok


FExtensionOnEvent

void FExtensionOnEvent(ExtensionParams params, ExtensionEvent event)

Receives an event from the engine

PARAMETERS

ExtensionParams params
ExtensionEvent event The current event


FExtensionRegister

ExtensionResult FExtensionRegister(HExtension extension)

Called before any AppInitialize on each engine creation. Set the extension's lifecycle callbacks through the ExtensionSet*Fn functions. Callbacks not set are optional. An update-only extension does not need an Initialize callback. If registration fails, release any partially created state before returning; unregister is called only after successful registration.

PARAMETERS

HExtension extension borrowed extension configuration handle

RETURNS

ExtensionResult EXTENSION_RESULT_OK on success


FExtensionUnregister

ExtensionResult FExtensionUnregister(HExtension extension)

Called after all AppFinalize callbacks for each successfully registered extension, including when a later initialization callback failed. The handle remains valid for this call. Release registration-owned state here.

PARAMETERS

HExtension extension borrowed extension configuration handle

RETURNS

ExtensionResult EXTENSION_RESULT_OK on success


FExtensionUpdate

ExtensionResult FExtensionUpdate(ExtensionParams params)

Updates an extension. Called for each game frame.

PARAMETERS

ExtensionParams params

RETURNS

ExtensionResult EXTENSION_RESULT_OK if all went ok


FRegister

Result FRegister(HExtension extension)

Called before any AppInitialize on each engine creation. Set the extension's lifecycle callbacks through the Set*Fn functions. Callbacks not set are optional. An update-only extension does not need an Initialize callback. If registration fails, release any partially created state before returning; unregister is called only after successful registration.

PARAMETERS

HExtension extension borrowed extension configuration handle

RETURNS

Result RESULT_OK on success


FUnregister

Result FUnregister(HExtension extension)

Called after all AppFinalize callbacks for each successfully registered extension, including when a later initialization callback failed. The handle remains valid for this call. Release registration-owned state here.

PARAMETERS

HExtension extension borrowed extension configuration handle

RETURNS

Result RESULT_OK on success


HExtension

void HExtension()

Opaque extension configuration handle. Borrowed during the register and unregister callbacks; do not retain it. Configure callbacks only in register.

PARAMETERS



HExtension

void HExtension()

Opaque extension configuration handle. Borrowed during the register and unregister callbacks; do not retain it. Configure callbacks only in register.

PARAMETERS



Enums

AppExitCode

Engine exit code.

APP_EXIT_CODE_NONE
APP_EXIT_CODE_REBOOT
APP_EXIT_CODE_EXIT

CallbackType

Extra callback type for RegisterCallback function.

CALLBACK_PRE_RENDER
CALLBACK_POST_RENDER

EventID

Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on

EVENT_ID_ACTIVATEAPP
EVENT_ID_DEACTIVATEAPP
EVENT_ID_ICONIFYAPP
EVENT_ID_DEICONIFYAPP
EVENT_ID_ENGINE_INITIALIZED
EVENT_ID_ENGINE_DELETE

ExtensionAppExitCode

Engine exit code.

EXTENSION_APP_EXIT_CODE_NONE
EXTENSION_APP_EXIT_CODE_REBOOT
EXTENSION_APP_EXIT_CODE_EXIT

ExtensionCallbackType

Extra callback type for RegisterCallback function.

EXTENSION_CALLBACK_PRE_RENDER
EXTENSION_CALLBACK_POST_RENDER

ExtensionEventID

Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on

EXTENSION_EVENT_ID_ACTIVATEAPP
EXTENSION_EVENT_ID_DEACTIVATEAPP
EXTENSION_EVENT_ID_ICONIFYAPP
EXTENSION_EVENT_ID_DEICONIFYAPP
EXTENSION_EVENT_ID_ENGINE_INITIALIZED
EXTENSION_EVENT_ID_ENGINE_DELETE

ExtensionParam

Parameters available through ExtensionParamsGetFloat.

EXTENSION_PARAM_DT engine update delta time

ExtensionResult

Result enumeration.

EXTENSION_RESULT_OK
EXTENSION_RESULT_INIT_ERROR

Param

Parameters available through ParamsGetFloat.

PARAM_DT engine update delta time

Result

Result enumeration.

RESULT_OK
RESULT_INIT_ERROR

Macros

DM_DECLARE_EXTENSION

Declare an extension using its identifier and register/unregister callbacks. The identifier is also its exported registration symbol and name. Register configures lifecycle callbacks on the opaque extension handle, before AppInitialize. Unregister runs after AppFinalize. Both repeat on engine reboot. The legacy eight-argument form remains supported and emits a compiler deprecation warning: DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final). It keeps its callbacks and ABI. Do not add new callbacks to that form; use setters through the three-argument form.

EXAMPLES

static ExtensionResult RegisterMyExtension(HExtension extension)
{
    ExtensionSetUpdateFn(extension, UpdateMyExtension);
    return EXTENSION_RESULT_OK;
}
DM_DECLARE_EXTENSION(MyExtension, RegisterMyExtension, 0);

DM_PLATFORM_ANDROID

Set if the platform is Android


DM_PLATFORM_HTML5

Set if the platform is Html5


DM_PLATFORM_IOS

Set if the platform is iPhoneOS


DM_PLATFORM_LINUX

Set if the platform is Linux


DM_PLATFORM_OSX

Set if the platform is OSX


DM_PLATFORM_WINDOWS

Set if the platform is Windows (on both x86 and x86_64)