SDK GameObject script API documentation

Version: stable

FUNCTION
INVALID_INSTANCE_POOL_INDEX() Value for an invalid instance index, this must be ...
GetMessageSocket() Retrieve the message socket for the specified coll...
GetCollection() Retrieve a collection from the specified instance
New() Create a new gameobject instance
Delete() Delete gameobject instance
ConstructInstanceId() Construct a hash of an instance id based on the in...
AcquireInstanceIndex() Retrieve an instance index from the index pool for...
AssignInstanceIndex() Assign an index to the instance, only if the insta...
GetIdentifier() Get instance identifier
SetIdentifier() Set instance identifier. Must be unique within the...
GetComponentId() Get component id from component index.
SetPosition() set position
GetPosition() get position
SetRotation() set rotation
GetRotation() get rotation
SetScale() set uniform scale
SetScale() set scale
GetUniformScale() get uniform scale
GetScale() get scale
GetWorldPosition() get world position
GetWorldRotation() get world rotation
GetWorldScale() get world scale
GetWorldUniformScale() get world uniform scale
GetWorldMatrix() get world matrix
GetWorldTransform() get world transform
SetBone() Set whether the instance should be flagged as a bo...
IsBone() Check whether the instance is flagged as a bone.
SetBoneTransforms() Set the local transforms recursively of all instan...
DeleteBones() Recursively delete all instances flagged as bones ...
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...
ComponentIterProperties() Callback when iterating over the properties for a ...
ComponentTypeGetTypeIndex() Get the component type index. Used for with e.g. d...
ComponentTypeSetNewWorldFn() set the new world callback
ComponentTypeSetDeleteWorldFn() set the world destroy callback
ComponentTypeSetCreateFn() set the component create callback
ComponentTypeSetDestroyFn() set the component destroy callback
ComponentTypeSetInitFn() set the component init callback
ComponentTypeSetFinalFn() set the component finalize callback
ComponentTypeSetAddToUpdateFn() set the component add-to-update callback
ComponentTypeSetGetFn() set the component get callback
ComponentTypeSetRenderFn() set the component render callback
ComponentTypeSetUpdateFn() set the component update callback
ComponentTypeSetFixedUpdateFn() set the component update callback
ComponentTypeSetPostUpdateFn() set the component post update callback
ComponentTypeSetOnMessageFn() set the component on-message callback
ComponentTypeSetOnInputFn() set the component on-input callback
ComponentTypeSetOnReloadFn() set the component on-reload callback
ComponentTypeSetSetPropertiesFn() set the component set properties callback
ComponentTypeSetGetPropertyFn() set the component get property callback
ComponentTypeSetSetPropertyFn() set the component set property callback
ComponentTypeSetContext() set the component type global context
ComponentTypeGetContext() get the component type global context
ComponentTypeSetReadsTransforms() set the component type transform dependency flag
ComponentTypeSetPrio() set the component type prio order
ComponentTypeSetHasUserData() set the component type need for a per component instance user data
ComponentTypeSetChildIteratorFn() set the component child iterator function
ComponentTypeSetPropertyIteratorFn() set the component property iterator function
GetComponentFromLua() Get component user data from a url
dmScript::PostDDF() Sends a script message
ENUMS
Result result enumeration
PropertyType property types
PropertyResult property result
Playback Playback type enum
CreateResult Create result enum
UpdateResult Update result enum
PropertyValueType Type of property value
InputResult Input result enum
SceneNodePropertyType scene node property types

Functions

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

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

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

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

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)

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.

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.

GetIdentifier()

GetIdentifier(instance)

Get instance identifier

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmhash_t Identifier. dmGameObject::UNNAMED_IDENTIFIER if not set.

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

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 [type: dmhash_t* Component id as out-argument

RETURNS

result dmGameObject::Result RESULT_OK if the comopnent was found

SetPosition()

SetPosition(instance,position)

Set gameobject instance position

PARAMETERS

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

GetPosition()

GetPosition(instance)

Get gameobject instance position

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Point3 Position

SetRotation()

SetRotation(instance,position)

Set gameobject instance rotation

PARAMETERS

instance dmGameObject::HInstance Gameobject instance
position New Position

GetRotation()

GetRotation(instance)

Get gameobject instance rotation

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Quat rotation

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

GetUniformScale()

GetUniformScale(instance)

Get gameobject instance uniform scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

float Uniform scale

GetScale()

GetScale(instance)

Get gameobject instance scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmGameObject::Vector3 Non-uniform scale

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

GetWorldUniformScale()

GetWorldUniformScale(instance)

Get game object instance uniform scale

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

float World 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.

GetWorldTransform()

GetWorldTransform(instance)

Get game object instance world transform

PARAMETERS

instance dmGameObject::HInstance Gameobject instance

RETURNS

dmTransform::Transform World transform

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

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

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

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

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.

ComponentIterProperties()

ComponentIterProperties(pit,node)

Callback when iterating over the properties for a component.

PARAMETERS

pit dmGameObject::SceneNodePropertyIterator the property iterator
node dmGameObject::SceneNode* the scene node

ComponentTypeGetTypeIndex()

ComponentTypeGetTypeIndex(type)

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

PARAMETERS

type ComponentType* the type

RETURNS

type_index uint32_t The type index.

ComponentTypeSetNewWorldFn()

ComponentTypeSetNewWorldFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentNewWorld callback

ComponentTypeSetDeleteWorldFn()

ComponentTypeSetDeleteWorldFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentDeleteWorld callback

ComponentTypeSetCreateFn()

ComponentTypeSetCreateFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentCreate callback

ComponentTypeSetDestroyFn()

ComponentTypeSetDestroyFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentDestroy callback

ComponentTypeSetInitFn()

ComponentTypeSetInitFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentInit callback

ComponentTypeSetFinalFn()

ComponentTypeSetFinalFn(type,fn)

Set the component finalize callback. Called on each gameobject's components, during a gameobject's finalization.

PARAMETERS

type ComponentType* the type
fn ComponentFinal callback

ComponentTypeSetAddToUpdateFn()

ComponentTypeSetAddToUpdateFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentAddToUpdate 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 ComponentType* the type
fn ComponentGet callback

ComponentTypeSetRenderFn()

ComponentTypeSetRenderFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentsRender callback

ComponentTypeSetUpdateFn()

ComponentTypeSetUpdateFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentsUpdate callback

ComponentTypeSetFixedUpdateFn()

ComponentTypeSetFixedUpdateFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentsFixedUpdate callback

ComponentTypeSetPostUpdateFn()

ComponentTypeSetPostUpdateFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentsPostUpdate callback

ComponentTypeSetOnMessageFn()

ComponentTypeSetOnMessageFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentOnMessage callback

ComponentTypeSetOnInputFn()

ComponentTypeSetOnInputFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentOnInput callback

ComponentTypeSetOnReloadFn()

ComponentTypeSetOnReloadFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentOnReload callback

ComponentTypeSetSetPropertiesFn()

ComponentTypeSetSetPropertiesFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentSetProperties callback

ComponentTypeSetGetPropertyFn()

ComponentTypeSetGetPropertyFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentGetProperty callback

ComponentTypeSetSetPropertyFn()

ComponentTypeSetSetPropertyFn(type,fn)

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

PARAMETERS

type ComponentType* the type
fn ComponentSetProperty callback

ComponentTypeSetContext()

ComponentTypeSetContext(type,context)

Set the component type global context. Usually set when registering the component type.

PARAMETERS

type ComponentType* the type
context void* component type global context

ComponentTypeGetContext()

ComponentTypeGetContext(type)

get the component type global context

PARAMETERS

type ComponentType* the type

RETURNS

context void* component type global context

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 ComponentType* the type
reads_transforms bool transform dependency flag

ComponentTypeSetPrio()

ComponentTypeSetPrio(type,prio)

Set the component type prio order. Defines the update order of the component types.

PARAMETERS

type ComponentType* the type
prio uint16_t prio order

ComponentTypeSetHasUserData()

ComponentTypeSetHasUserData(type,has_user_data)

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

PARAMETERS

type ComponentType* the type
has_user_data bool does each component instance need user data

ComponentTypeSetChildIteratorFn()

ComponentTypeSetChildIteratorFn(type,fn)

set the component child iterator function. Called during inspection

PARAMETERS

type ComponentType* the type
fn FIteratorChildren child iterator function

ComponentTypeSetPropertyIteratorFn()

ComponentTypeSetPropertyIteratorFn(type,fn)

set the component property iterator function. Called during inspection

PARAMETERS

type ComponentType* the type
fn FIteratorProperties property iterator function

GetComponentFromLua()

GetComponentFromLua(L,index,component_type,world,component,url)

Get component user data from a url. The object referenced by the url must be in the same collection as the caller.

PARAMETERS

L lua_State* Lua state
index lua_State* index to argument (a url)
component_type const char* the call will fail if the found component does not have the specified extension
world void** The world associated owning the component. May be 0
component void** The component data associated with the url. May be 0
url dmMessage::URL* The resolved url. May be 0

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