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... |
| 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) |
void AppParamsFinalize(AppParams* app_params)
Finalizes an extension app params struct (deallocates internal memory)
PARAMETERS
AppParams* |
app_params |
the params |
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 |
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 |
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 |
HContextRegistry AppParamsGetContextRegistry(AppParams* params)
Gets the context registry used by the extension app params.
PARAMETERS
AppParams* |
params |
the params |
RETURNS
HContextRegistry |
the context registry |
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 |
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 |
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 |
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));
void ExtensionAppParamsFinalize(ExtensionAppParams* app_params)
Finalizes an extension app params struct (deallocates internal memory)
PARAMETERS
ExtensionAppParams* |
app_params |
the params |
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 |
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 |
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 |
HContextRegistry ExtensionAppParamsGetContextRegistry(ExtensionAppParams* params)
Gets the context registry used by the extension app params.
PARAMETERS
ExtensionAppParams* |
params |
the params |
RETURNS
HContextRegistry |
the context registry |
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 |
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 |
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 |
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));
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 |
void ExtensionParamsFinalize(ExtensionParams* app_params)
Finalizes an extension params struct (deallocates internal memory)
PARAMETERS
ExtensionParams* |
app_params |
the params |
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 |
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 |
HContextRegistry ExtensionParamsGetContextRegistry(ExtensionParams* params)
Gets the context registry used by the extension params.
PARAMETERS
ExtensionParams* |
params |
the params |
RETURNS
HContextRegistry |
the context registry |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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;
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
void ExtensionUnregisteriOSUIApplicationDelegate(void* delegate)
Deregister a previously registered iOS application delegate. This function is only available on iOS.
PARAMETERS
void* |
delegate |
An id |
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 |
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 |
void ParamsFinalize(Params* app_params)
Finalizes an extension params struct (deallocates internal memory)
PARAMETERS
Params* |
app_params |
the params |
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 |
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 |
HContextRegistry ParamsGetContextRegistry(Params* params)
Gets the context registry used by the extension params.
PARAMETERS
Params* |
params |
the params |
RETURNS
HContextRegistry |
the context registry |
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 |
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 |
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 |
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 |
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 |
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;
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
void UnregisteriOSUIApplicationDelegate(void* delegate)
Deregister a previously registered iOS application delegate. This function is only available on iOS.
PARAMETERS
void* |
delegate |
An id |
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 |
TYPE
struct AppParamsThe extension app parameters
MEMBERS
HConfigFile |
m_ConfigFile |
Deprecated |
AppExitCode |
m_ExitStatus |
App exit code |
TYPE
struct ExtensionAppParamsThe extension app parameters
MEMBERS
HConfigFile |
m_ConfigFile |
Deprecated |
ExtensionAppExitCode |
m_ExitStatus |
App exit code |
TYPE
struct ExtensionParamsParameters 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. |
TYPE
struct ParamsParameters 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. |
Result FCallback(Params params)
Callback typedef for functions passed to RegisterCallback().
PARAMETERS
Params |
params |
RETURNS
Result |
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 |
ExtensionResult FExtensionAppFinalize(ExtensionAppParams params)
Callback when the app is being finalized
PARAMETERS
ExtensionAppParams |
params |
RETURNS
ExtensionResult |
EXTENSION_RESULT_OK if all went ok |
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 |
ExtensionResult FExtensionCallback(ExtensionParams params)
Callback typedef for functions passed to RegisterCallback().
PARAMETERS
ExtensionParams |
params |
RETURNS
ExtensionResult |
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 |
ExtensionResult FExtensionFinalize(ExtensionParams params)
Calls for the finalization of an extension
PARAMETERS
ExtensionParams |
params |
RETURNS
ExtensionResult |
EXTENSION_RESULT_OK if all went ok |
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 |
void FExtensionOnEvent(ExtensionParams params, ExtensionEvent event)
Receives an event from the engine
PARAMETERS
ExtensionParams |
params |
|
ExtensionEvent |
event |
The current event |
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 |
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 |
ExtensionResult FExtensionUpdate(ExtensionParams params)
Updates an extension. Called for each game frame.
PARAMETERS
ExtensionParams |
params |
RETURNS
ExtensionResult |
EXTENSION_RESULT_OK if all went ok |
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 |
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 |
void HExtension()
Opaque extension configuration handle. Borrowed during the register and unregister callbacks; do not retain it. Configure callbacks only in register.
PARAMETERS
void HExtension()
Opaque extension configuration handle. Borrowed during the register and unregister callbacks; do not retain it. Configure callbacks only in register.
PARAMETERS
Engine exit code.
APP_EXIT_CODE_NONE |
|
APP_EXIT_CODE_REBOOT |
|
APP_EXIT_CODE_EXIT |
Extra callback type for RegisterCallback function.
CALLBACK_PRE_RENDER |
|
CALLBACK_POST_RENDER |
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 |
Engine exit code.
EXTENSION_APP_EXIT_CODE_NONE |
|
EXTENSION_APP_EXIT_CODE_REBOOT |
|
EXTENSION_APP_EXIT_CODE_EXIT |
Extra callback type for RegisterCallback function.
EXTENSION_CALLBACK_PRE_RENDER |
|
EXTENSION_CALLBACK_POST_RENDER |
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 |
Parameters available through ExtensionParamsGetFloat.
EXTENSION_PARAM_DT |
engine update delta time |
Result enumeration.
EXTENSION_RESULT_OK |
|
EXTENSION_RESULT_INIT_ERROR |
Parameters available through ParamsGetFloat.
PARAM_DT |
engine update delta time |
Result enumeration.
RESULT_OK |
|
RESULT_INIT_ERROR |
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);
Set if the platform is Android
Set if the platform is Html5
Set if the platform is iPhoneOS
Set if the platform is Linux
Set if the platform is OSX
Set if the platform is Windows (on both x86 and x86_64)