Extension

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.

API

AppExitCode

Type: ENUM Engine exit code.

Members

• EXTENSION_APP_EXIT_CODE_NONE
• EXTENSION_APP_EXIT_CODE_REBOOT
• EXTENSION_APP_EXIT_CODE_EXIT

AppParams

Type: STRUCT The extension app parameters

Members

• m_ConfigFile (HConfigFile) - Deprecated
• m_ExitStatus (ExtensionAppExitCode) - App exit code

AppParamsFinalize

Type: FUNCTION Finalizes an extension app params struct (deallocates internal memory)

Parameters

• app_params (ExtensionAppParams*) - the params

AppParamsGetAppExitCode

Type: FUNCTION get the app exit code

Parameters

• app_params (dmExtension::AppParams*) - The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitialize

Returns

• code (ExtensionAppExitCode) - engine exit code

AppParamsGetContext

Type: FUNCTION Gets a context using a specified name hash

Parameters

• params (ExtensionAppParams) - the params
• name_hash (dmhash_t) - the context name hash

Returns

• context (void*) - The context, if it exists

AppParamsGetContextByName

Type: FUNCTION Gets a context using a specified name

Parameters

• params (ExtensionAppParams) - the params
• name (const char*) - the context name

Returns

• context (void*) - The context, if it exists

AppParamsInitialize

Type: 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 params

AppParamsSetContext

Type: FUNCTION Sets a context using a specified name

Parameters

• params (ExtensionAppParams) - the params
• name (const char*) - the context name
• context (void*) - the context

Returns

• result (int) - 0 if successful

CallbackType

Type: ENUM Extra callback type for RegisterCallback function.

Members

• EXTENSION_CALLBACK_PRE_RENDER
• EXTENSION_CALLBACK_POST_RENDER

DM_DECLARE_EXTENSION

Type: 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);

DM_PLATFORM_ANDROID

Type: MACRO Set if the platform is Android

DM_PLATFORM_HTML5

Type: MACRO Set if the platform is Html5

DM_PLATFORM_IOS

Type: MACRO Set if the platform is iPhoneOS

DM_PLATFORM_LINUX

Type: MACRO Set if the platform is Linux

DM_PLATFORM_OSX

Type: MACRO Set if the platform is OSX

DM_PLATFORM_WINDOWS

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

Event

Type: STRUCT Extension event

EventID

Type: ENUM Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on

Members

• 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

ExtensionAppExitCode

Type: ENUM Engine exit code.

Members

• EXTENSION_APP_EXIT_CODE_NONE
• EXTENSION_APP_EXIT_CODE_REBOOT
• EXTENSION_APP_EXIT_CODE_EXIT

ExtensionAppParams

Type: STRUCT The extension app parameters

Members

• m_ConfigFile (HConfigFile) - Deprecated
• m_ExitStatus (ExtensionAppExitCode) - App exit code

ExtensionAppParamsFinalize

Type: FUNCTION Finalizes an extension app params struct (deallocates internal memory)

Parameters

• app_params (ExtensionAppParams*) - the params

ExtensionAppParamsGetAppExitCode

Type: FUNCTION get the app exit code

Parameters

• app_params (dmExtension::AppParams*) - The app params sent to the extension dmExtension::AppInitialize / dmExtension::AppInitialize

Returns

• code (ExtensionAppExitCode) - engine exit code

ExtensionAppParamsGetContext

Type: FUNCTION Gets a context using a specified name hash

Parameters

• params (ExtensionAppParams) - the params
• name_hash (dmhash_t) - the context name hash

Returns

• context (void*) - The context, if it exists

ExtensionAppParamsGetContextByName

Type: FUNCTION Gets a context using a specified name

Parameters

• params (ExtensionAppParams) - the params
• name (const char*) - the context name

Returns

• context (void*) - The context, if it exists

ExtensionAppParamsInitialize

Type: 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 params

ExtensionAppParamsSetContext

Type: FUNCTION Sets a context using a specified name

Parameters

• params (ExtensionAppParams) - the params
• name (const char*) - the context name
• context (void*) - the context

Returns

• result (int) - 0 if successful

ExtensionCallbackType

Type: ENUM Extra callback type for RegisterCallback function.

Members

• EXTENSION_CALLBACK_PRE_RENDER
• EXTENSION_CALLBACK_POST_RENDER

ExtensionDescBufferSize

Type: FUNCTION Used when registering new extensions

ExtensionEvent

Type: STRUCT Extension event

ExtensionEventID

Type: ENUM Event id enumeration. EVENT_ID_ICONIFYAPP and EVENT_ID_DEICONIFYAPP only available on

Members

• 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

ExtensionParams

Type: 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 / repository
• m_L (lua_State*) - The Lua state.

ExtensionParamsFinalize

Type: FUNCTION Finalizes an extension params struct (deallocates internal memory)

Parameters

• app_params (ExtensionParams*) - the params

ExtensionParamsGetContext

Type: FUNCTION Gets a context using a specified name hash

Parameters

• params (ExtensionParams) - the params
• name_hash (dmhash_t) - the context name hash

Returns

• context (void*) - The context, if it exists

ExtensionParamsGetContextByName

Type: FUNCTION Gets a context using a specified name

Parameters

• params (ExtensionParams) - the params
• name (const char*) - the context name

Returns

• context (void*) - The context, if it exists

ExtensionParamsInitialize

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

Parameters

• app_params (ExtensionParams*) - the params

ExtensionParamsSetContext

Type: FUNCTION Sets a context using a specified name

Parameters

• params (ExtensionAppParams) - the params
• name (const char*) - the context name
• context (void*) - the context

Returns

• result (int) - 0 if successful

ExtensionRegister

Type: 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 bytes
• name (const char*) - extension name. human readble. max 16 characters long.
• app_initialize (FExtensionAppInitialize) - app-init function. May be null
• app_finalize (FExtensionAppFinalize) - app-final function. May be null
• initialize (FExtensionInitialize) - init function. May not be 0
• finalize (FExtensionFinalize) - finalize function. May not be 0
• update (FExtensionUpdate) - update function. May be null
• on_event (FExtensionOnEvent) - event callback function. May be null

ExtensionRegisteriOSUIApplicationDelegate

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.

Notes

• Register before UIApplicationMain to receive launch callbacks. Registration does not retain the delegate; keep it alive until it is unregistered. This function is only available on iOS. [icon:ios]

Parameters

• delegate (void*) - An id.

ExtensionRegisteriOSUISceneDelegate

Type: 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

• Register and unregister on the main thread. Registration does not retain the delegate; keep it alive until unregistering. Each event retains a snapshot of its observers, so unregistering during delivery affects subsequent events. Duplicate registrations are ignored. Late registration does not replay events. This function is only available on iOS. [icon:ios]

Parameters

• delegate (void*) - An id.

Examples

// 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;

ExtensionResult

Type: ENUM Result enumeration.

Members

• EXTENSION_RESULT_OK
• EXTENSION_RESULT_INIT_ERROR

ExtensionUnregisteriOSUIApplicationDelegate

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

Parameters

• delegate (void*) - An id.

ExtensionUnregisteriOSUISceneDelegate

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

Parameters

• delegate (void*) - An id.

FCallback

Type: TYPEDEF Callback typedef for functions passed to RegisterCallback().

Parameters

• params (ExtensionParams)

Returns

• return (ExtensionResult)

FExtensionAppFinalize

Type: TYPEDEF Callback when the app is being finalized

Parameters

• params (ExtensionAppParams)

Returns

• result (ExtensionResult) - EXTENSION_RESULT_OK if all went ok

FExtensionAppInitialize

Type: TYPEDEF Callback when the app is being initialized. Called before FExtensionInitialize

Notes

• There is no guarantuee of initialization order. If an extension requires another extension to be initialized, that should be handled in [ref:FExtensionInitialize].

Parameters

• params (ExtensionAppParams)

Returns

• result (ExtensionResult) - EXTENSION_RESULT_OK if all went ok

FExtensionCallback

Type: TYPEDEF Callback typedef for functions passed to RegisterCallback().

Parameters

• params (ExtensionParams)

Returns

• return (ExtensionResult)

FExtensionFinalize

Type: TYPEDEF Calls for the finalization of an extension

Notes

• All extensions will be called with FExtensionFinalize before moving on to the next step, the [ref:FExtensionAppFinalize]

Parameters

• params (ExtensionParams)

Returns

• result (ExtensionResult) - EXTENSION_RESULT_OK if all went ok

FExtensionInitialize

Type: TYPEDEF Callback when the app is being finalized

Parameters

• params (ExtensionAppParams)

Returns

• result (ExtensionResult) - EXTENSION_RESULT_OK if all went ok

FExtensionOnEvent

Type: TYPEDEF Receives an event from the engine

Parameters

• params (ExtensionParams)
• event (ExtensionEvent) - The current event

FExtensionUpdate

Type: TYPEDEF Updates an extension. Called for each game frame.

Parameters

• params (ExtensionParams)

Returns

• result (ExtensionResult) - EXTENSION_RESULT_OK if all went ok

Params

Type: 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 / repository
• m_L (lua_State*) - The Lua state.

ParamsFinalize

Type: FUNCTION Finalizes an extension params struct (deallocates internal memory)

Parameters

• app_params (ExtensionParams*) - the params

ParamsGetContext

Type: FUNCTION Gets a context using a specified name hash

Parameters

• params (ExtensionParams) - the params
• name_hash (dmhash_t) - the context name hash

Returns

• context (void*) - The context, if it exists

ParamsGetContextByName

Type: FUNCTION Gets a context using a specified name

Parameters

• params (ExtensionParams) - the params
• name (const char*) - the context name

Returns

• context (void*) - The context, if it exists

ParamsInitialize

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

Parameters

• app_params (ExtensionParams*) - the params

ParamsSetContext

Type: FUNCTION Sets a context using a specified name

Parameters

• params (ExtensionAppParams) - the params
• name (const char*) - the context name
• context (void*) - the context

Returns

• result (int) - 0 if successful

RegisterCallback

Type: FUNCTION Generated from ExtensionRegisterCallback

RegisteriOSUIApplicationDelegate

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.

Notes

• Register before UIApplicationMain to receive launch callbacks. Registration does not retain the delegate; keep it alive until it is unregistered. This function is only available on iOS. [icon:ios]

Parameters

• delegate (void*) - An id.

RegisteriOSUISceneDelegate

Type: 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

• Register and unregister on the main thread. Registration does not retain the delegate; keep it alive until unregistering. Each event retains a snapshot of its observers, so unregistering during delivery affects subsequent events. Duplicate registrations are ignored. Late registration does not replay events. This function is only available on iOS. [icon:ios]

Parameters

• delegate (void*) - An id.

Examples

// 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;

Result

Type: ENUM Result enumeration.

Members

• EXTENSION_RESULT_OK
• EXTENSION_RESULT_INIT_ERROR

UnregisteriOSUIApplicationDelegate

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

Parameters

• delegate (void*) - An id.

UnregisteriOSUISceneDelegate

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

Parameters

• delegate (void*) - An id.