Namespace: dmExtension
Language: C++
Type: Defold C++
File: extension_gen.hpp
Source: engine/extension/src/dmsdk/extension/extension_gen.hpp
Include: dmsdk/extension/extension_gen.hpp
Functions for creating and controlling engine native extension libraries.
Type: ENUM Engine exit code.
Members
EXTENSION_APP_EXIT_CODE_NONEEXTENSION_APP_EXIT_CODE_REBOOTEXTENSION_APP_EXIT_CODE_EXITType: STRUCT The extension app parameters
Members
m_ConfigFile (HConfigFile) - Deprecatedm_ExitStatus (ExtensionAppExitCode) - App exit codeType: FUNCTION Finalizes an extension app params struct (deallocates internal memory)
Parameters
app_params (ExtensionAppParams*) - the paramsType: FUNCTION get the app exit code
Parameters
app_params (dmExtension::AppParams*) - The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitializeReturns
code (ExtensionAppExitCode) - engine exit codeType: FUNCTION Gets a context using a specified name hash
Parameters
params (ExtensionAppParams) - the paramsname_hash (dmhash_t) - the context name hashReturns
context (void*) - The context, if it existsType: FUNCTION Gets a context using a specified name
Parameters
params (ExtensionAppParams) - the paramsname (const char*) - the context nameReturns
context (void*) - The context, if it existsType: FUNCTION Initializes an extension app params struct NOTE: this is an opaque struct, do not use it’s members directly!
Parameters
app_params (ExtensionAppParams*) - the paramsType: FUNCTION Sets a context using a specified name
Parameters
params (ExtensionAppParams) - the paramsname (const char*) - the context namecontext (void*) - the contextReturns
result (int) - 0 if successfulType: ENUM Extra callback type for RegisterCallback function.
Members
EXTENSION_CALLBACK_PRE_RENDEREXTENSION_CALLBACK_POST_RENDERType: MACRO Declare and register new extension to the engine. This macro is used to declare the extension callback functions used by the engine to communicate with the extension.
Examples
Register a new extension:
DM_DECLARE_EXTENSION(MyExt, "MyExt", AppInitializeMyExt, AppFinalizeMyExt, InitializeMyExt, UpdateMyExt, OnEventMyExt, FinalizeMyExt);
Type: MACRO Set if the platform is Android
Type: MACRO Set if the platform is Html5
Type: MACRO Set if the platform is iPhoneOS
Type: MACRO Set if the platform is Linux
Type: MACRO Set if the platform is OSX
Type: MACRO Set if the platform is Windows (on both x86 and x86_64)
Type: STRUCT Extension event
Type: ENUM Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on
Members
EXTENSION_EVENT_ID_ACTIVATEAPPEXTENSION_EVENT_ID_DEACTIVATEAPPEXTENSION_EVENT_ID_ICONIFYAPPEXTENSION_EVENT_ID_DEICONIFYAPPEXTENSION_EVENT_ID_ENGINE_INITIALIZEDEXTENSION_EVENT_ID_ENGINE_DELETEType: ENUM Engine exit code.
Members
EXTENSION_APP_EXIT_CODE_NONEEXTENSION_APP_EXIT_CODE_REBOOTEXTENSION_APP_EXIT_CODE_EXITType: STRUCT The extension app parameters
Members
m_ConfigFile (HConfigFile) - Deprecatedm_ExitStatus (ExtensionAppExitCode) - App exit codeType: FUNCTION Finalizes an extension app params struct (deallocates internal memory)
Parameters
app_params (ExtensionAppParams*) - the paramsType: FUNCTION get the app exit code
Parameters
app_params (dmExtension::AppParams*) - The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitializeReturns
code (ExtensionAppExitCode) - engine exit codeType: FUNCTION Gets a context using a specified name hash
Parameters
params (ExtensionAppParams) - the paramsname_hash (dmhash_t) - the context name hashReturns
context (void*) - The context, if it existsType: FUNCTION Gets a context using a specified name
Parameters
params (ExtensionAppParams) - the paramsname (const char*) - the context nameReturns
context (void*) - The context, if it existsType: FUNCTION Initializes an extension app params struct NOTE: this is an opaque struct, do not use it’s members directly!
Parameters
app_params (ExtensionAppParams*) - the paramsType: FUNCTION Sets a context using a specified name
Parameters
params (ExtensionAppParams) - the paramsname (const char*) - the context namecontext (void*) - the contextReturns
result (int) - 0 if successfulType: ENUM Extra callback type for RegisterCallback function.
Members
EXTENSION_CALLBACK_PRE_RENDEREXTENSION_CALLBACK_POST_RENDERType: FUNCTION Used when registering new extensions
Type: STRUCT Extension event
Type: ENUM Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on
Members
EXTENSION_EVENT_ID_ACTIVATEAPPEXTENSION_EVENT_ID_DEACTIVATEAPPEXTENSION_EVENT_ID_ICONIFYAPPEXTENSION_EVENT_ID_DEICONIFYAPPEXTENSION_EVENT_ID_ENGINE_INITIALIZEDEXTENSION_EVENT_ID_ENGINE_DELETEType: STRUCT The global parameters avalable when registering and unregistering an extension
Members
m_ConfigFile (HConfigFile) - The game project settings (including overrides and plugins)m_ResourceFactory (HResourceFactory) - The game resource factory / repositorym_L (lua_State*) - The Lua state.Type: FUNCTION Finalizes an extension params struct (deallocates internal memory)
Parameters
app_params (ExtensionParams*) - the paramsType: FUNCTION Gets a context using a specified name hash
Parameters
params (ExtensionParams) - the paramsname_hash (dmhash_t) - the context name hashReturns
context (void*) - The context, if it existsType: FUNCTION Gets a context using a specified name
Parameters
params (ExtensionParams) - the paramsname (const char*) - the context nameReturns
context (void*) - The context, if it existsType: FUNCTION Initializes an extension params struct NOTE: this is an opaque struct, do not use it’s members directly!
Parameters
app_params (ExtensionParams*) - the paramsType: FUNCTION Sets a context using a specified name
Parameters
params (ExtensionAppParams) - the paramsname (const char*) - the context namecontext (void*) - the contextReturns
result (int) - 0 if successfulType: FUNCTION Extension declaration helper. Internal function. Use DM_DECLARE_EXTENSION
Parameters
desc (void*) - A persistent buffer of at least 128 bytes.desc_size (const char*) - size of buffer holding desc. in bytesname (const char*) - extension name. human readble. max 16 characters long.app_initialize (FExtensionAppInitialize) - app-init function. May be nullapp_finalize (FExtensionAppFinalize) - app-final function. May be nullinitialize (FExtensionInitialize) - init function. May not be 0finalize (FExtensionFinalize) - finalize function. May not be 0update (FExtensionUpdate) - update function. May be nullon_event (FExtensionOnEvent) - event callback function. May be nullType: FUNCTION 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).
Notes
Parameters
delegate (void*) - An idType: FUNCTION 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.
Notes
Parameters
delegate (void*) - An idExamples
// myextension_ios.mm
@interface MySceneDelegate : NSObject
- (void)scene:(UIScene*)scene willConnectToSession:(UISceneSession*)session options:(UISceneConnectionOptions*)options;
- (void)scene:(UIScene*)scene openURLContexts:(NSSet*)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;
Type: ENUM Result enumeration.
Members
EXTENSION_RESULT_OKEXTENSION_RESULT_INIT_ERRORType: FUNCTION Deregister a previously registered iOS application delegate. This function is only available on iOS.
Parameters
delegate (void*) - An idType: FUNCTION Deregister a previously registered iOS scene observer on the main thread. This function is only available on iOS.
Parameters
delegate (void*) - An idType: TYPEDEF Callback typedef for functions passed to RegisterCallback().
Parameters
params (ExtensionParams)Returns
return (ExtensionResult)Type: TYPEDEF Callback when the app is being finalized
Parameters
params (ExtensionAppParams)Returns
result (ExtensionResult) - EXTENSION_RESULT_OK if all went okType: TYPEDEF Callback when the app is being initialized. Called before FExtensionInitialize
Notes
Parameters
params (ExtensionAppParams)Returns
result (ExtensionResult) - EXTENSION_RESULT_OK if all went okType: TYPEDEF Callback typedef for functions passed to RegisterCallback().
Parameters
params (ExtensionParams)Returns
return (ExtensionResult)Type: TYPEDEF Calls for the finalization of an extension
Notes
FExtensionFinalize before moving on to the next step, the [ref:FExtensionAppFinalize]Parameters
params (ExtensionParams)Returns
result (ExtensionResult) - EXTENSION_RESULT_OK if all went okType: TYPEDEF Callback when the app is being finalized
Parameters
params (ExtensionAppParams)Returns
result (ExtensionResult) - EXTENSION_RESULT_OK if all went okType: TYPEDEF Receives an event from the engine
Parameters
params (ExtensionParams)event (ExtensionEvent) - The current eventType: TYPEDEF Updates an extension. Called for each game frame.
Parameters
params (ExtensionParams)Returns
result (ExtensionResult) - EXTENSION_RESULT_OK if all went okType: STRUCT The global parameters avalable when registering and unregistering an extension
Members
m_ConfigFile (HConfigFile) - The game project settings (including overrides and plugins)m_ResourceFactory (HResourceFactory) - The game resource factory / repositorym_L (lua_State*) - The Lua state.Type: FUNCTION Finalizes an extension params struct (deallocates internal memory)
Parameters
app_params (ExtensionParams*) - the paramsType: FUNCTION Gets a context using a specified name hash
Parameters
params (ExtensionParams) - the paramsname_hash (dmhash_t) - the context name hashReturns
context (void*) - The context, if it existsType: FUNCTION Gets a context using a specified name
Parameters
params (ExtensionParams) - the paramsname (const char*) - the context nameReturns
context (void*) - The context, if it existsType: FUNCTION Initializes an extension params struct NOTE: this is an opaque struct, do not use it’s members directly!
Parameters
app_params (ExtensionParams*) - the paramsType: FUNCTION Sets a context using a specified name
Parameters
params (ExtensionAppParams) - the paramsname (const char*) - the context namecontext (void*) - the contextReturns
result (int) - 0 if successfulType: FUNCTION Generated from ExtensionRegisterCallback
Type: FUNCTION 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).
Notes
Parameters
delegate (void*) - An idType: FUNCTION 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.
Notes
Parameters
delegate (void*) - An idExamples
// myextension_ios.mm
@interface MySceneDelegate : NSObject
- (void)scene:(UIScene*)scene willConnectToSession:(UISceneSession*)session options:(UISceneConnectionOptions*)options;
- (void)scene:(UIScene*)scene openURLContexts:(NSSet*)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;
Type: ENUM Result enumeration.
Members
EXTENSION_RESULT_OKEXTENSION_RESULT_INIT_ERRORType: FUNCTION Deregister a previously registered iOS application delegate. This function is only available on iOS.
Parameters
delegate (void*) - An idType: FUNCTION Deregister a previously registered iOS scene observer on the main thread. This function is only available on iOS.
Parameters
delegate (void*) - An id