SDK GameObject script API documentation

Version: alpha

FUNCTIONS
AcquireInstanceIndex() Retrieve an instance index from the index pool for...
AssignInstanceIndex() Assign an index to the instance, only if the insta...
ComponentOnReload() Called when the resource the component is based on...
ComponentTypeGetContext() get the component type global context
ComponentTypeGetTypeIndex() Get the component type index. Used for with e.g. d...
ComponentTypeSetAddToUpdateFn() set the component add-to-update callback
ComponentTypeSetChildIteratorFn() set the component child iterator function
ComponentTypeSetContext() set the component type global context
ComponentTypeSetCreateFn() set the component create callback
ComponentTypeSetDeleteWorldFn() set the world destroy callback
ComponentTypeSetDestroyFn() set the component destroy callback
ComponentTypeSetFinalFn() set the component finalize callback
ComponentTypeSetFixedUpdateFn() set the component update callback
ComponentTypeSetGetFn() set the component get callback
ComponentTypeSetGetPropertyFn() set the component get property callback
ComponentTypeSetHasUserData() set the component type need for a per component instance user data
ComponentTypeSetInitFn() set the component init callback
ComponentTypeSetNewWorldFn() set the new world callback
ComponentTypeSetOnInputFn() set the component on-input callback
ComponentTypeSetOnMessageFn() set the component on-message callback
ComponentTypeSetOnReloadFn() set the component on-reload callback
ComponentTypeSetPostUpdateFn() set the component post update callback
ComponentTypeSetPrio() set the component type prio order
ComponentTypeSetPropertyIteratorFn() set the component property iterator function
ComponentTypeSetReadsTransforms() set the component type transform dependency flag
ComponentTypeSetRenderFn() set the component render callback
ComponentTypeSetSetPropertiesFn() set the component set properties callback
ComponentTypeSetSetPropertyFn() set the component set property callback
ComponentTypeSetUpdateFn() set the component update callback
ConstructInstanceId() Construct a hash of an instance id based on the in...
Delete() Delete gameobject instance
DeleteBones() Recursively delete all instances flagged as bones ...
dmScript::PostDDF() Sends a script message
dmScript::PostScriptUnrefMessage() Sends an unref script message
GetCollection() Retrieve a collection from the specified instance
GetComponentId() Get component id from component index.
GetComponentTypeIndex() Get the component type index
GetIdentifier() Get instance identifier
GetMessageSocket() Retrieve the message socket for the specified coll...
GetPosition() get position
GetRotation() get rotation
GetScale() get scale
GetUniformScale() get uniform scale
GetWorldMatrix() get world matrix
GetWorldPosition() get world position
GetWorldRotation() get world rotation
GetWorldScale() get world scale
GetWorldTransform() get world transform
GetWorldUniformScale() get world uniform scale
INVALID_INSTANCE_POOL_INDEX() Value for an invalid instance index, this must be ...
IsBone() Check whether the instance is flagged as a bone.
New() Create a new gameobject instance
PropertyContainerCopy() Allocates and copies a property container
PropertyContainerCreate() Creates the final property container
PropertyContainerCreateBuilder() Create a property container builder with memory pr...
PropertyContainerDestroy() Deallocates a property container
PropertyContainerMerge() Merges two containers into a newly allocated conta...
PropertyContainerPushBool() Add a property of type bool to the container
PropertyContainerPushFloat() Add a property of type float to the container
PropertyContainerPushHash() Add a property of type dmhash_t to the container
PropertyContainerPushQuat() Add a property of type float4 to the container
PropertyContainerPushURL() Add a property of type dmMessage::URL to the conta...
PropertyContainerPushURLString() Add a property of type (url) string to the contain...
PropertyContainerPushVector3() Add a property of type float3 to the container
PropertyContainerPushVector4() Add a property of type float4 to the container
SetBone() Set whether the instance should be flagged as a bo...
SetBoneTransforms() Set the local transforms recursively of all instan...
SetIdentifier() Set instance identifier. Must be unique within the...
SetPosition() set position
SetRotation() set rotation
SetScale() set uniform scale
SetScale() set scale
Spawn() spawn a new game object
TraverseGetRoot() Gets the top node of the whole game (the main coll...
TraverseIterateChildren() Get a scene node iterator for the nodes' children
TraverseIterateNext() Step a scene node iterator to the next sibling
TraverseIterateProperties() Create a scene node traversal property iterator
TraverseIteratePropertiesNext() Steps the scene node traversal property iterator t...
ENUMS
CreateResult Create result enum
InputResult Input result enum
Playback Playback type enum
PropertyResult property result
PropertyType property types
PropertyValueType Type of property value
Result result enumeration
SceneNodePropertyType scene node property types
UpdateResult Update result enum

Functions

AcquireInstanceIndex()

AcquireInstanceIndex(collection)

Retrieve an instance index from the index pool for the collection.

PARAMETERS

collection dmGameObject::HColleciton Collection from which to retrieve the instance index.

RETURNS

instance uint32_t index from the index pool of collection.

AssignInstanceIndex()

AssignInstanceIndex(index,instance)

Assign an index to the instance, only if the instance is not null.

PARAMETERS

index uint32_t The index to assign.
instance dmGameObject::HInstance The instance that should be assigned the index.

ComponentOnReload()

ComponentOnReload(params)

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

PARAMETERS

params const dmGameObject::ComponentOnReloadParams& the parameters

ComponentTypeGetContext()

ComponentTypeGetContext(type)

get the component type global context

PARAMETERS

type HComponentType the type

RETURNS

context void* component type global context

ComponentTypeGetTypeIndex()

ComponentTypeGetTypeIndex(type)

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()

ComponentTypeSetAddToUpdateFn(type,fn)

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()

ComponentTypeSetChildIteratorFn(type,fn)

set the component child iterator function. Called during inspection

PARAMETERS

type HComponentType the type
fn FIteratorChildren child iterator function

ComponentTypeSetContext()

ComponentTypeSetContext(type,context)

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()

ComponentTypeSetCreateFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentCreate callback

ComponentTypeSetDeleteWorldFn()

ComponentTypeSetDeleteWorldFn(type,fn)

Set the world destroy callback. Called when a collection (i.e. a "world") is destroyed.

PARAMETERS

type HComponentType the type
fn ComponentDeleteWorld callback

ComponentTypeSetDestroyFn()

ComponentTypeSetDestroyFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentDestroy callback

ComponentTypeSetFinalFn()

ComponentTypeSetFinalFn(type,fn)

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()

ComponentTypeSetFixedUpdateFn(type,fn)

Set the component update callback. Called when it's time to update all component instances.

PARAMETERS

type HComponentType the type
fn ComponentsFixedUpdate callback

ComponentTypeSetGetFn()

ComponentTypeSetGetFn(type,fn)

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()

ComponentTypeSetGetPropertyFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentGetProperty callback

ComponentTypeSetHasUserData()

ComponentTypeSetHasUserData(type,has_user_data)

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()

ComponentTypeSetInitFn(type,fn)

Set the component init callback. Called on each gameobject's components, during a gameobject's initialization.

PARAMETERS

type HComponentType the type
fn ComponentInit callback

ComponentTypeSetNewWorldFn()

ComponentTypeSetNewWorldFn(type,fn)

Set the new world callback. Called when a collection (i.e. a "world") is created.

PARAMETERS

type HComponentType the type
fn ComponentNewWorld callback

ComponentTypeSetOnInputFn()

ComponentTypeSetOnInputFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentOnInput callback

ComponentTypeSetOnMessageFn()

ComponentTypeSetOnMessageFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentOnMessage callback

ComponentTypeSetOnReloadFn()

ComponentTypeSetOnReloadFn(type,fn)

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()

ComponentTypeSetPostUpdateFn(type,fn)

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()

ComponentTypeSetPrio(type,prio)

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()

ComponentTypeSetPropertyIteratorFn(type,fn)

set the component property iterator function. Called during inspection

PARAMETERS

type HComponentType the type
fn FIteratorProperties property iterator function

ComponentTypeSetReadsTransforms()

ComponentTypeSetReadsTransforms(type,reads_transforms)

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()

ComponentTypeSetRenderFn(type,fn)

Set the component render callback. Called when it's time to render all component instances.

PARAMETERS

type HComponentType the type
fn ComponentsRender callback

ComponentTypeSetSetPropertiesFn()

ComponentTypeSetSetPropertiesFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentSetProperties callback

ComponentTypeSetSetPropertyFn()

ComponentTypeSetSetPropertyFn(type,fn)

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

PARAMETERS

type HComponentType the type
fn ComponentSetProperty callback

ComponentTypeSetUpdateFn()

ComponentTypeSetUpdateFn(type,fn)

Set the component update callback. Called when it's time to update all component instances.

PARAMETERS

type HComponentType the type
fn ComponentsUpdate callback

ConstructInstanceId()

ConstructInstanceId(index)

Construct a hash of an instance id based on the index provided.

PARAMETERS

index uint32_t The index to base the id off of.

RETURNS

id dmhash_t hash of the instance id constructed.

Delete()

Delete(collection,instance,recursive)

Delete gameobject instance

PARAMETERS

collection dmGameObject::HCollection Gameobject collection
instance dmGameObject::HInstance Gameobject instance
recursive bool If true, delete child hierarchy recursively in child to parent order (leaf first)

DeleteBones()

DeleteBones(parent)

Recursively delete all instances flagged as bones under the given parent instance. The order of deletion is depth-first, so that the children are deleted before the parents.

PARAMETERS

parent HInstance Parent instance of the hierarchy

dmScript::PostDDF()

dmScript::PostDDF(message,sender,receiver,function_ref,unref_function_after_call)

Sends a script message. Wraps the message in a dmGameSystemDDF::ScriptMessage struct.

PARAMETERS

message TDDFType* The ddf message to send
sender dmMessage::Message* The sender
receiver dmMessage::Message* The receiver
function_ref int The function ref. 0 wil cause the "on_message" to be called
unref_function_after_call bool call dmScript::UnrefInInstance on the function_ref after the dmScript::PCall is made

RETURNS

success bool true if successful

dmScript::PostScriptUnrefMessage()

dmScript::PostScriptUnrefMessage(sender,receiver,reference)

Sends a script message to unreference a script object

PARAMETERS

sender dmMessage::Message* The sender
receiver dmMessage::Message* The receiver
reference int The reference to remove

RETURNS

success Result RESULT_OK if successful

GetCollection()

GetCollection(instance)

Retrieve a collection from the specified instance

PARAMETERS

instance dmGameObject::HInstance Game object instance

RETURNS

collection dmGameObject::HInstance The collection the specified instance belongs to

GetComponentId()

GetComponentId(instance,component_index,component_id)

Get component id from component index.

PARAMETERS

instance dmGameObject::HInstance Instance
component_index uint16_t Component index
component_id dmhash_t* Component id as out-argument

RETURNS

result dmGameObject::Result RESULT_OK if the component was found

GetComponentTypeIndex()

GetComponentTypeIndex(collection,type_hash)

Get the component type index

PARAMETERS

collection Collection handle
type_hash dhmash_t The hashed name of the registered component type (e.g. dmHashString("guic"))

RETURNS

type_index uint32_t The component type index. 0xFFFFFFFF if not found

GetIdentifier()

GetIdentifier(instance)

Get instance identifier

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmhash_t Identifier. dmGameObject::UNNAMED_IDENTIFIER if not set.

GetMessageSocket()

GetMessageSocket(collection)

Retrieve the message socket for the specified collection.

PARAMETERS

collection dmGameObject::HCollection Collection handle

RETURNS

socket dmMessage::HSocket The message socket of the specified collection

GetPosition()

GetPosition(instance)

Get gameobject instance position

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Point3 Position

GetRotation()

GetRotation(instance)

Get gameobject instance rotation

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Quat rotation

GetScale()

GetScale(instance)

Get gameobject instance scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Vector3 Non-uniform scale

GetUniformScale()

GetUniformScale(instance)

Get gameobject instance uniform scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

float Uniform scale

GetWorldMatrix()

GetWorldMatrix(instance)

Get game object instance world transform as Matrix4.

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::MAtrix4 World transform matrix.

GetWorldPosition()

GetWorldPosition(instance)

Get gameobject instance world position

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Point3 World position

GetWorldRotation()

GetWorldRotation(instance)

Get gameobject instance world rotation

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Quat World rotation

GetWorldScale()

GetWorldScale(instance)

Get game object instance world transform

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Vector3 World scale

GetWorldTransform()

GetWorldTransform(instance)

Get game object instance world transform

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmTransform::Transform World transform

GetWorldUniformScale()

GetWorldUniformScale(instance)

Get game object instance uniform scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

float World uniform scale

INVALID_INSTANCE_POOL_INDEX()

INVALID_INSTANCE_POOL_INDEX()

Value for an invalid instance index, this must be the same as defined in gamesys_ddf.proto for Create#index.

PARAMETERS

None

IsBone()

IsBone(instance)

Check whether the instance is flagged as a bone.

PARAMETERS

instance HImstance Instance

RETURNS

result bool True if flagged as a bone

New()

New(collection,prototype_name)

Create a new gameobject instance

PARAMETERS

collection dmGameObject::HCollection Gameobject collection
prototype_name |type: const char*] Prototype file name. May be 0.

RETURNS

instance dmGameObject::HInstance New gameobject instance. NULL if any error occured

PropertyContainerCopy()

PropertyContainerCopy(original)

Allocates and copies a property container

PARAMETERS

original HPropertyContainer The original property container

RETURNS

container HPropertyContainer The new property container

PropertyContainerCreate()

PropertyContainerCreate(builder)

Creates the final property container

PARAMETERS

builder HPropertyContainerBuilder The property container builder

RETURNS

container HPropertyContainer The property container

PropertyContainerCreateBuilder()

PropertyContainerCreateBuilder(params)

Create a property container builder with memory preallocated

PARAMETERS

params PropertyContainerBuilderParams The params holding the memory requirements

RETURNS

container HPropertyContainerBuilder The builder

PropertyContainerDestroy()

PropertyContainerDestroy(container)

Deallocates a property container

PARAMETERS

container HPropertyContainer The property container

PropertyContainerMerge()

PropertyContainerMerge(original,overrides)

Merges two containers into a newly allocated container The properties in the overrides container will take presedence.

PARAMETERS

original HPropertyContainer The original property container
overrides HPropertyContainer The container with override properties

RETURNS

container HPropertyContainer The merged property container

PropertyContainerPushBool()

PropertyContainerPushBool(builder,id,value)

Add a property of type bool to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
value bool The value of the property

PropertyContainerPushFloat()

PropertyContainerPushFloat(builder,id,value)

Add a property of type float to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
value float The value of the property

PropertyContainerPushHash()

PropertyContainerPushHash(builder,id,value)

Add a property of type dmhash_t to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
value dmhash_t The value of the property

PropertyContainerPushQuat()

PropertyContainerPushQuat(builder,id,values)

Add a property of type float4 to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
values float* The value of the property (4 floats)

PropertyContainerPushURL()

PropertyContainerPushURL(builder,id,value)

Add a property of type dmMessage::URL to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
value dmMessage::URL The value of the property

PropertyContainerPushURLString()

PropertyContainerPushURLString(builder,id,value)

Add a property of type (url) string to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
value const char* The value of the property

PropertyContainerPushVector3()

PropertyContainerPushVector3(builder,id,values)

Add a property of type float3 to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
values float* The value of the property (3 floats)

PropertyContainerPushVector4()

PropertyContainerPushVector4(builder,id,values)

Add a property of type float4 to the container

PARAMETERS

builder HPropertyContainerBuilder The container builder
id dmhash_t The id of the property
values float* The value of the property (4 floats)

SetBone()

SetBone(instance,bone)

Set whether the instance should be flagged as a bone. Instances flagged as bones can have their transforms updated in a batch through SetBoneTransforms. Used for animated skeletons.

PARAMETERS

instance HImstance Instance
bone bool true if the instance is a bone

SetBoneTransforms()

SetBoneTransforms(instance,component_transform,transforms,transform_count)

Set the local transforms recursively of all instances flagged as bones, starting with component with id. The order of the transforms is depth-first.

PARAMETERS

instance HImstance First Instance of the hierarchy to set
component_transform dmTransform::Transform the transform for component root
transforms Array of transforms to set depth-first for the bone instances
transform_count Size of the transforms array

RETURNS

Number of instances found

SetIdentifier()

SetIdentifier(collection,instance,identifier)

Set instance identifier. Must be unique within the collection.

PARAMETERS

collection dmGameObject::HCollection Collection
instance dmGameObject::HInstance Instance
identifier dmhash_t Identifier

RETURNS

result dmGameObject::Result RESULT_OK on success

SetPosition()

SetPosition(instance,position)

Set gameobject instance position

PARAMETERS

instance dmGameObject::HInstance Gameobject instance
position dmGameObject::Point3 New Position

SetRotation()

SetRotation(instance,position)

Set gameobject instance rotation

PARAMETERS

instance dmGameObject::HInstance Gameobject instance
position New Position

SetScale()

SetScale(instance,scale)

Set gameobject instance uniform scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance
scale New uniform scale

SetScale()

SetScale(instance,scale)

Set gameobject instance non-uniform scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance
scale New uniform scale

Spawn()

Spawn(collection,prototype,prototype_name,id,properties,position,rotation,scale)

Spawns a new gameobject instance. The actual creation is performed after the update is completed.

PARAMETERS

collection HCollection Gameobject collection
prototype HPrototype Prototype
prototype_name const char* Prototype file name (.goc)
id dmhash_t Id of the spawned instance
properties HPropertyContainer Container with override properties
position dmVMath::Vector3 Position of the spawed object
rotation dmVMath::Quat Rotation of the spawned object
scale dmVMath::Vector3 Scale of the spawned object return instance HInstance the spawned instance, 0 at failure

TraverseGetRoot()

TraverseGetRoot(regist,node)

Gets the top node of the whole game (the main collection)

PARAMETERS

regist dmGameObject::HRegister the full gameobject register
node dmGameObject::HRegister the node to inspect

RETURNS

result bool True if successful

EXAMPLES

The following examples show how to iterate over currently loaded scene graph 
void OutputNode(dmGameObject::SceneNode* node) {
    dmGameObject::SceneNodeIterator it = dmGameObject::TraverseIterateChildren(node);
    while(dmGameObject::TraverseIterateNext(&it))
    {
        OutputProperties(&it.m_Node); // see dmGameObject::TraverseIterateProperties()
        OutputNode(&it.m_Node);
    }
}

bool OutputScene(HRegister regist) {
    dmGameObject::SceneNode root;
    if (!dmGameObject::TraverseGetRoot(regist, &root))
        return false;
    OutputNode(&node);
}

TraverseIterateChildren()

TraverseIterateChildren(node)

Get a scene node iterator for the nodes' children

PARAMETERS

node dmGameObject::SceneNode* the parent node

RETURNS

iterator dmGameObject::SceneNodeIterator the iterator

TraverseIterateNext()

TraverseIterateNext(it)

Step a scene node iterator to the next sibling

PARAMETERS

it dmGameObject::SceneNodeIterator* the iterator

RETURNS

result bool true if successful. false if the iterator is finished

TraverseIterateProperties()

TraverseIterateProperties(node)

Create a scene node traversal property iterator

PARAMETERS

node dmGameObject::SceneNode* the node to inspect

RETURNS

iterator dmGameObject::SceneNodePropertyIterator the property iterator

EXAMPLES

The following examples show how to iterate over the properties of a node 
dmGameObject::SceneNodePropertyIterator pit = TraverseIterateProperties(node);
while(dmGameObject::TraverseIteratePropertiesNext(&pit))
{
    const char* name = dmHashReverseSafe64(pit.m_Property.m_NameHash);
    switch(pit.m_Property.m_Type)
    {
    case dmGameObject::SCENE_NODE_PROPERTY_TYPE_NUMBER: ...
    ...
    }
}

TraverseIteratePropertiesNext()

TraverseIteratePropertiesNext(it)

Steps the scene node traversal property iterator to the next property

PARAMETERS

it dmGameObject::SceneNodePropertyIterator* the iterator

RETURNS

finished bool True if the iterator it valid, false if the iterator is finished.