Component

Namespace: dmGameObject Language: C++ Type: Defold C++ File: component.h Source: engine/gameobject/src/dmsdk/gameobject/component.h Include: dmsdk/gameobject/component.h

Api for manipulating game object components (WIP)

API

ComponentAddToUpdate

Type: TYPEDEF Component add to update function. Only components called with this function should be included in the update passes.

Parameters

• params (const dmGameObject::ComponentAddToUpdateParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentAddToUpdateParams

Type: STRUCT Parameters to ComponentAddToUpdate callback.

Members

• m_Collection (HCollection) - Collection handle
• m_Instance (HInstance) - Game object instance
• m_World (void*) - Component world
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer

ComponentCreate

Type: TYPEDEF Component create function. Should allocate all necessary resources for the component. The game object instance is guaranteed to have its id, scene hierarchy and transform data updated when this is called.

Parameters

• params (const dmGameObject::ComponentCreateParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentCreateParams

Type: STRUCT Parameters to ComponentCreate callback.

Members

• m_Instance (HInstance) - Game object instance
• m_Position (dmVMath::Point3) - Local component position
• m_Rotation (dmVMath::Quat) - Local component rotation
• m_Scale (dmVMath::Vector3) - Local component scale
• m_PropertySet (PropertySet) - Set of properties
• m_Resource (void*) - Component resource
• m_World (void*) - Component world, as created in the ComponentNewWorld callback
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer
• m_ComponentIndex (uint16_t) - Index of the component type being created (among all component types)

ComponentDeleteWorld

Type: TYPEDEF Component world destroy function

Parameters

• params (const dmGameObject::ComponentDeleteWorldParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentDeleteWorldParams

Type: STRUCT Parameters to ComponentDeleteWorld callback.

Members

• m_Context - [type void*] Context for the component type
• m_World - [type void*] The pointer to the world to destroy

ComponentDestroy

Type: TYPEDEF Component destroy function. Should deallocate all necessary resources.

Parameters

• params (const dmGameObject::ComponentDestroyParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentDestroyParams

Type: STRUCT Parameters to ComponentDestroy callback.

Members

• m_Collection (HCollection) - Collection handle
• m_Instance (HInstance) - Game object instance
• m_World (void*) - Component world
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer

ComponentFinal

Type: TYPEDEF Component finalize function. Should clean up as it is called when the component is disabled.

Parameters

• params (const dmGameObject::ComponentFinalParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentFinalParams

Type: STRUCT Parameters to ComponentFinal callback.

Members

• m_Collection (HCollection) - Collection handle
• m_Instance (HInstance) - Game object instance
• m_World (void*) - Component world
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer

ComponentGet

Type: TYPEDEF A simple way to get the component instance from the user_data (which was set during creation)

Parameters

• params (const dmGameObject::ComponentGetParams&) - Update parameters

Returns

• component (void*) - The internal component pointer

ComponentGetParams

Type: STRUCT Parameters to ComponentGet callback.

Members

• m_World (HComponentWorld) - Component world
• m_UserData (HComponentInternal) - Component internal representation

ComponentGetProperty

Type: TYPEDEF Callback for retrieving a property value of the component.

Parameters

• params (const dmGameObject::ComponentGetPropertyParams&) - the parameters
• out_value (dmGameObject::PropertyDesc&) - (out) the property

Returns

• result (dmGameObject::PropertyResult) - PROPERTY_RESULT_OK if retrieving the property was ok

ComponentGetPropertyParams

Type: STRUCT Parameters to ComponentGetProperty callback.

Members

• m_Context (void*) - Context for the component type
• m_World (void*) - Component world
• m_Instance (HInstance) - Game object instance
• m_PropertyId (dmhash_t) - Id of the property
• m_UserData (uintptr_t*) - User data storage pointer
• m_Options (HPropertyOptions) - Options for getting the property

ComponentInit

Type: TYPEDEF Component init function. Should set the components initial state as it is called when the component is enabled.

Parameters

• params (const dmGameObject::ComponentInitParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentInitParams

Type: STRUCT Parameters to ComponentInit callback.

Members

• m_Collection (HCollection) - Collection handle
• m_Instance (HInstance) - Game object instance
• m_World (void*) - Component world
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer

ComponentIterProperties

Type: TYPEDEF Callback when iterating over the properties for a component.

Notes

• This function is only available/used in debug builds, when traversing the scene graph in order to export this data for external tools (e.g. external testing libraries like Poco)

Parameters

• pit (dmGameObject::SceneNodePropertyIterator) - the property iterator
• node (dmGameObject::SceneNode*) - the scene node

ComponentNewWorld

Type: TYPEDEF Component world create function

Parameters

• params (const dmGameObject::ComponentNewWorldParams&)

Returns

• result (CreateResult) - CREATE_RESULT_OK on success

ComponentNewWorldParams

Type: STRUCT Parameters to ComponentNewWorld callback.

Members

• m_Context (void*) - Context for the component type
• m_ComponentIndex (uint8_t) - Component type index that can be used later with GetWorld()
• m_MaxInstances (uint32_t) - Max component game object instance count (if applicable)
• m_World (void**) - Out-parameter of the pointer in which to store the created world
• m_MaxComponentInstances (uint32_t) - Max components count of this type in current collection counted at the build stage. If component in factory then value is 0xFFFFFFFF

ComponentOnInput

Type: TYPEDEF Component on-input function. Called when input is sent to this component

Parameters

• params (const dmGameObject::ComponentOnInputParams&) - Input parameters

Returns

• result (InputResult) - How the component handled the input

ComponentOnInputParams

Type: STRUCT Parameters to ComponentOnInput callback.

Members

• m_Instance (HInstance) - Instance handle
• m_InputAction (const InputAction*) - Information about the input that occurred (note that input being released is also treated as input)
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer

ComponentOnMessage

Type: TYPEDEF Component on-message function. Called when message is sent to this component

Parameters

• params (const dmGameObject::ComponentOnMessageParams&) - Update parameters

Returns

• result (UpdateResult) - UPDATE_RESULT_OK on success

ComponentOnMessageParams

Type: STRUCT Parameters to ComponentOnMessage callback.

Members

• m_Instance (HInstance) - Instance handle
• m_World (void*) - World
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer
• m_Message (dmMessage::Message*) - Message

ComponentOnReload

Type: FUNCTION Called when the resource the component is based on has been reloaded.

Parameters

• params (const dmGameObject::ComponentOnReloadParams&) - the parameters

ComponentOnReloadParams

Type: STRUCT Parameters to ComponentOnReload callback.

Members

• m_Instance (HInstance) - Instance handle
• m_Resource (void*) - Resource that was reloaded
• m_World (void*) - Component world
• m_Context (void*) - User context
• m_UserData (uintptr_t*) - User data storage pointer

ComponentSetProperties

Type: TYPEDEF Set a property set for the component.

Parameters

• params (const dmGameObject::ComponentSetPropertiesParams&) - the parameters

Returns

• result (dmGameObject::PropertyResult) - PROPERTY_RESULT_OK if property was set

ComponentSetPropertiesParams

Type: STRUCT Parameters to ComponentSetProperties callback.

Members

• m_Instance (HInstance) - Instance handle
• m_PropertySet (PropertySet) - Property set to use
• m_UserData (uintptr_t*) - User data storage pointer

ComponentSetProperty

Type: TYPEDEF Callback for setting a property value of the component.

Parameters

• params (const dmGameObject::ComponentSetPropertyParams&) - the parameters

Returns

• result (dmGameObject::PropertyResult) - PROPERTY_RESULT_OK if property was set

ComponentSetPropertyParams

Type: STRUCT Parameters to ComponentSetProperty callback.

Members

• m_Context (void*) - Context for the component type
• m_World (void*) - Component world
• m_Instance (HInstance) - Game object instance
• m_PropertyId (dmhash_t) - Id of the property
• m_UserData (uintptr_t*) - User data storage pointer
• m_Value (PropertyVar) - New value of the property
• m_Options (HPropertyOptions) - Options for setting the property

ComponentsPostUpdate

Type: TYPEDEF Component post update function. The component state should never be modified in this function.

Parameters

• params (const dmGameObject::ComponentsPostUpdateParams&) - Update parameters

Returns

• result (UpdateResult) - UPDATE_RESULT_OK on success

ComponentsPostUpdateParams

Type: STRUCT Parameters for ComponentsPostUpdate callback.

Members

• m_Collection (HCollection) - Collection handle
• m_World (void*) - Component world
• m_Context (void*) - User context

ComponentsRender

Type: TYPEDEF Component render function.

Parameters

• params (const dmGameObject::ComponentsRenderParams&) - Update parameters

Returns

• result (UpdateResult) - UPDATE_RESULT_OK on success

ComponentsRenderParams

Type: STRUCT Parameters to ComponentsRender callback.

Members

• m_Collection (HCollection) - Collection handle
• m_World (void*) - Component world
• m_Context (void*) - User context

ComponentsUpdate

Type: TYPEDEF Component update function. Updates all component of this type for all game objects

Parameters

• params (const dmGameObject::ComponentsUpdateParams&) - Update parameters
• params (dmGameObject::ComponentsUpdateResult&) - (out) Update result

Returns

• result (UpdateResult) - UPDATE_RESULT_OK on success

ComponentsUpdateParams

Type: STRUCT Parameters to ComponentsUpdate callback.

Members

• m_Collection (HCollection) - Collection handle
• m_UpdateContext (const UpdateContext*) - Update context
• m_World (void*) - Component world
• m_Context (void*) - User context

ComponentsUpdateResult

Type: STRUCT Parameters to ComponentsUpdate callback.

Members

• m_TransformsUpdated (bool) - True if a component type updated any game object transforms

ComponentTypeCreateCtx

Type: STRUCT Context used when registering a new component type

Members

• m_Config (dmConfigFile::HConfig) - The config file
• m_Factory (dmResource::HFactory) - The resource factory
• m_Register (dmGameObject::HRegister) - The game object registry
• m_Script (dmScript::HContext) - The shared script context
• m_Contexts (dmHashTable64<void*>) - Mappings between names and contextx

ComponentTypeGetContext

Type: FUNCTION get the component type global context

Parameters

• type (HComponentType) - the type

Returns

• context (void*) - component type global context

ComponentTypeGetTypeIndex

Type: FUNCTION Get the component type index. Used for with e.g. dmGameObject::GetWorld()/GetContext()

Parameters

• type (HComponentType) - the type

Returns

• type_index (uint32_t) - The type index.

ComponentTypeSetAddToUpdateFn

Type: FUNCTION Set the component add-to-update callback. Called for each component instal, when the game object is spawned.

Parameters

• type (HComponentType) - the type
• fn (ComponentAddToUpdate) - callback

ComponentTypeSetChildIteratorFn

Type: FUNCTION set the component child iterator function. Called during inspection

Parameters

• type (HComponentType) - the type
• fn (dmGameObject::FIteratorChildren) - child iterator function

ComponentTypeSetContext

Type: FUNCTION Set the component type global context. Usually set when registering the component type.

Parameters

• type (HComponentType) - the type
• context (void*) - component type global context

ComponentTypeSetCreateFn

Type: FUNCTION Set the component create callback. Called when a component instance is created.

Parameters

• type (HComponentType) - the type
• fn (ComponentCreate) - callback

ComponentTypeSetDeleteWorldFn

Type: FUNCTION Set the world destroy callback. Called when a collection (i.e. a “world”) is destroyed.

Parameters

• type (HComponentType) - the type
• fn (ComponentDeleteWorld) - callback

ComponentTypeSetDestroyFn

Type: FUNCTION Set the component destroy callback. Called when a component instance is destroyed.

Parameters

• type (HComponentType) - the type
• fn (ComponentDestroy) - callback

ComponentTypeSetFinalFn

Type: FUNCTION Set the component finalize callback. Called on each gameobject’s components, during a gameobject’s finalization.

Parameters

• type (HComponentType) - the type
• fn (ComponentFinal) - callback

ComponentTypeSetFixedUpdateFn

Type: FUNCTION Set the component update callback. Called when it’s time to update all component instances.

Parameters

• type (HComponentType) - the type
• fn (ComponentsUpdate) - callback

ComponentTypeSetGetFn

Type: FUNCTION Set the component get callback. Called when the scripts want to retrieve the individual component user data given an url.

Parameters

• type (HComponentType) - the type
• fn (ComponentGet) - callback

ComponentTypeSetGetPropertyFn

Type: FUNCTION Set the component get property callback. Called when accessing a property via go.get()

Parameters

• type (HComponentType) - the type
• fn (ComponentGetProperty) - callback

ComponentTypeSetHasUserData

Type: FUNCTION Set the component type need for a per component instance user data. Defaults to true.

Parameters

• type (HComponentType) - the type
• has_user_data (bool) - does each component instance need user data

ComponentTypeSetInitFn

Type: FUNCTION Set the component init callback. Called on each gameobject’s components, during a gameobject’s initialization.

Parameters

• type (HComponentType) - the type
• fn (ComponentInit) - callback

ComponentTypeSetLateUpdateFn

Type: FUNCTION Set the component late update callback. Called after regular update of all component instances but before render and before post update.

Parameters

• type (HComponentType) - the type
• fn (ComponentsUpdate) - callback

ComponentTypeSetNewWorldFn

Type: FUNCTION Set the new world callback. Called when a collection (i.e. a “world”) is created.

Parameters

• type (HComponentType) - the type
• fn (ComponentNewWorld) - callback

ComponentTypeSetOnInputFn

Type: FUNCTION Set the component on-input callback. Called once per frame, before the Update function.

Parameters

• type (HComponentType) - the type
• fn (ComponentOnInput) - callback

ComponentTypeSetOnMessageFn

Type: FUNCTION Set the component on-message callback. Called multiple times per frame, to flush messages.

Parameters

• type (HComponentType) - the type
• fn (ComponentOnMessage) - callback

ComponentTypeSetOnReloadFn

Type: FUNCTION Set the component on-reload callback. Called when the resource of a component instance is reloaded.

Parameters

• type (HComponentType) - the type
• fn (ComponentOnReload) - callback

ComponentTypeSetPostUpdateFn

Type: FUNCTION Set the component post update callback. Called for each collection after the update, before the render.

Parameters

• type (HComponentType) - the type
• fn (ComponentsPostUpdate) - callback

ComponentTypeSetPrio

Type: FUNCTION Set the component type prio order. Defines the update order of the component types.

Parameters

• type (HComponentType) - the type
• prio (uint16_t) - prio order

ComponentTypeSetPropertyIteratorFn

Type: FUNCTION set the component property iterator function. Called during inspection

Parameters

• type (HComponentType) - the type
• fn (dmGameObject::FIteratorProperties) - property iterator function

ComponentTypeSetReadsTransforms

Type: FUNCTION Set the component type transform dependency flag. If this flag is set, it might trigger an dmGameObject::UpdateTransforms() (if there are dirty transforms)

Parameters

• type (HComponentType) - the type
• reads_transforms (bool) - transform dependency flag

ComponentTypeSetRenderFn

Type: FUNCTION Set the component render callback. Called when it’s time to render all component instances.

Parameters

• type (HComponentType) - the type
• fn (ComponentsRender) - callback

ComponentTypeSetSetPropertiesFn

Type: FUNCTION Set the component set properties callback. Called when the component instance is being spwned.

Parameters

• type (HComponentType) - the type
• fn (ComponentSetProperties) - callback

ComponentTypeSetSetPropertyFn

Type: FUNCTION Set the component set property callback. Called when accessing a property via go.set()

Parameters

• type (HComponentType) - the type
• fn (ComponentSetProperty) - callback

ComponentTypeSetUpdateFn

Type: FUNCTION Set the component update callback. Called when it’s time to update all component instances.

Parameters

• type (HComponentType) - the type
• fn (ComponentsUpdate) - callback

DM_DECLARE_COMPONENT_TYPE

Type: MACRO Register a new component type

Parameters

• symbol (symbol) - The unique C++ symbol name
• name (const char*) - name of the component type (i.e. the resource suffix)
• create_fn (dmGameObject::Result (fn)(const ComponentTypeCreateCtx ctx, HComponentType type)) - The type configuration function. May not be 0.
• destroy_fn (dmGameObject::Result (fn)(const ComponentTypeCreateCtx ctx, HComponentType type)) - The type destruction function. May be 0.

HComponentType

Type: TYPEDEF Component type handle. It holds the life time functions for a type.