API for manipulating game objects
Namespace: | dmGameObject |
Include: | #include <dmsdk/gameobject/gameobject.h> |
TYPES | |
---|---|
HCollection | Gameobject collection handle |
HComponent | Opaque handle to component instance |
HComponentInternal | Opaque handle to internal representation of a comp... |
HComponentWorld | Opaque handle to a component world |
HInstance | Gameobject instance handle |
HProperties | Gameobject properties handle |
HPropertyContainer | Handle to a list of properties (gameobject_props.h... |
HPrototype | Gameobject prototype handle |
HRegister | Collection register. |
HScript | Script handle |
HScriptInstance | Script instance handle |
InstanceIdMap | Used for mapping instance ids from a collection de... |
InstancePropertyContainers | Contains property containers for game objects to b... |
CONSTANTS | |
---|---|
INVALID_INSTANCE_POOL_INDEX | Value for an invalid instance index, this must be ... |
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 |
STRUCTS | |
---|---|
struct InputAction | Container of input related information. |
struct PropertyDesc | Description of a property |
struct PropertyOptions | Property Options |
struct PropertyVar | property variant |
struct SceneNode | scene graph traversal node |
struct SceneNodeIterator | scene graph traversal iterator |
struct SceneNodeProperty | scene traversal node property |
struct SceneNodePropertyIterator | scene traversal node property |
struct UpdateContext | Update context |
uint32_t AcquireInstanceIndex(dmGameObject::HColleciton collection)
Retrieve an instance index from the index pool for the collection.
PARAMETERS
dmGameObject::HColleciton |
collection |
Collection from which to retrieve the instance index. |
RETURNS
uint32_t |
index from the index pool of collection. |
void AddDynamicResourceHash(HCollection collection, dmhash_t path_hash)
Adds a reference to a dynamically created resource into the collection. If the resource is not released before the collection is being destroyed, the collection will automatically free the resource.
PARAMETERS
HCollection |
collection |
Collection handle |
dmhash_t |
path_hash |
resource path hash |
void AssignInstanceIndex(uint32_t index, dmGameObject::HInstance instance)
Assign an index to the instance, only if the instance is not null.
PARAMETERS
uint32_t |
index |
The index to assign. |
dmGameObject::HInstance |
instance |
The instance that should be assigned the index. |
dmhash_t CreateInstanceId()
Creates a new unique instance ID and returns its hash.
PARAMETERS
RETURNS
dmhash_t |
hash of the new unique instance id |
void Delete(dmGameObject::HCollection collection, dmGameObject::HInstance instance, bool recursive)
Delete gameobject instance
PARAMETERS
dmGameObject::HCollection |
collection |
Gameobject collection |
dmGameObject::HInstance |
instance |
Gameobject instance |
bool |
recursive |
If true, delete child hierarchy recursively in child to parent order (leaf first) |
void DeleteBones(HInstance 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
HInstance |
parent |
Parent instance of the hierarchy |
dmhash_t GetAbsoluteIdentifier(dmGameObject::HInstance instance, const char* identifier)
Get absolute identifier relative to instance. The returned identifier is the representation of the qualified name, i.e. the path from root-collection to the sub-collection which the instance belongs to. Example: if the instance is part of a sub-collection in the root-collection named "sub" and id == "a" the returned identifier represents the path "sub.a"
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance to get absolute identifier to |
const char* |
identifier |
Identifier relative to instance |
RETURNS
dmhash_t |
Absolute identifier. |
dmGameObject::HInstance GetCollection(dmGameObject::HInstance instance)
Retrieve a collection from the specified instance
PARAMETERS
dmGameObject::HInstance |
instance |
Game object instance |
RETURNS
dmGameObject::HInstance |
The collection the specified instance belongs to |
dmGameObject::HCollection GetCollectionByHash(dmGameObject::HRegister regist, dmhash_t socket_name)
Retrieve a collection by socket name hash Note: in native extensions, the register can be retrieved during init using dmEngine::GetGameObjectRegister(dmExtension::AppParams *params)
PARAMETERS
dmGameObject::HRegister |
regist |
Register |
dmhash_t |
socket_name |
The socket name |
RETURNS
dmGameObject::HCollection |
The collection if successful. 0 otherwise. |
dmGameObject::Result GetComponent(dmGameObject::HInstance instance, dmhash_t component_id, uint32_t* component_type, HComponent* component, HComponentWorld* world)
Get the component, component type and its world
PARAMETERS
dmGameObject::HInstance |
instance |
Instance |
dmhash_t |
component_id |
Component id |
uint32_t* |
component_type |
(out) Component type. Used for validation. |
HComponent* |
component |
(out) The component. |
HComponentWorld* |
world |
(out) The component world. May be 0. |
RETURNS
dmGameObject::Result |
RESULT_OK if the component was found |
dmGameObject::Result GetComponentId(dmGameObject::HInstance instance, uint16_t component_index, dmhash_t* component_id)
Get component id from component index.
PARAMETERS
dmGameObject::HInstance |
instance |
Instance |
uint16_t |
component_index |
Component index |
dmhash_t* |
component_id |
Component id as out-argument |
RETURNS
dmGameObject::Result |
RESULT_OK if the component was found |
uint32_t GetComponentTypeIndex(HCollection collection, dmhash_t type_hash)
Get the component type index
PARAMETERS
HCollection |
collection |
Collection handle |
dmhash_t |
type_hash |
The hashed name of the registered component type (e.g. dmHashString("guic")) |
RETURNS
uint32_t |
The component type index. 0xFFFFFFFF if not found |
void* GetContext(HCollection collection, uint32_t component_type_index)
Retrieve the context for a component type
PARAMETERS
HCollection |
collection |
Collection handle |
uint32_t |
component_type_index |
index of the component type |
RETURNS
void* |
The pointer to the context, 0x0 if not found |
dmhash_t GetIdentifier(dmGameObject::HInstance instance)
Get instance identifier
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmhash_t |
Identifier. dmGameObject::UNNAMED_IDENTIFIER if not set. |
dmGameObject::HInstance GetInstanceFromIdentifier(dmGameObject::HCollection collection, dmhash_t identifier)
Get instance from identifier
PARAMETERS
dmGameObject::HCollection |
collection |
Collection |
dmhash_t |
identifier |
Identifier |
RETURNS
dmGameObject::HInstance |
Instance. NULL if instance isn't found. |
dmMessage::HSocket GetMessageSocket(dmGameObject::HCollection collection)
Retrieve the message socket for the specified collection.
PARAMETERS
dmGameObject::HCollection |
collection |
Collection handle |
RETURNS
dmMessage::HSocket |
The message socket of the specified collection |
dmGameObject::Point3 GetPosition(dmGameObject::HInstance instance)
Get gameobject instance position
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::Point3 |
Position |
dmGameObject::Quat GetRotation(dmGameObject::HInstance instance)
Get gameobject instance rotation
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::Quat |
rotation |
dmGameObject::Vector3 GetScale(dmGameObject::HInstance instance)
Get gameobject instance scale
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::Vector3 |
Non-uniform scale |
float GetUniformScale(dmGameObject::HInstance instance)
Get gameobject instance uniform scale
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
float |
Uniform scale |
void* GetWorld(HCollection collection, uint32_t component_type_index)
Retrieve the world in the collection connected to the supplied component
PARAMETERS
HCollection |
collection |
Collection handle |
uint32_t |
component_type_index |
index of the component type |
RETURNS
void* |
The pointer to the world, 0x0 if not found |
dmGameObject::MAtrix4 GetWorldMatrix(dmGameObject::HInstance instance)
Get game object instance world transform as Matrix4.
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::MAtrix4 |
World transform matrix. |
dmGameObject::Point3 GetWorldPosition(dmGameObject::HInstance instance)
Get gameobject instance world position
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::Point3 |
World position |
dmGameObject::Quat GetWorldRotation(dmGameObject::HInstance instance)
Get gameobject instance world rotation
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::Quat |
World rotation |
dmGameObject::Vector3 GetWorldScale(dmGameObject::HInstance instance)
Get game object instance world transform
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmGameObject::Vector3 |
World scale |
dmTransform::Transform GetWorldTransform(dmGameObject::HInstance instance)
Get game object instance world transform
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
dmTransform::Transform |
World transform |
float GetWorldUniformScale(dmGameObject::HInstance instance)
Get game object instance uniform scale
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
RETURNS
float |
World uniform scale |
bool IsBone(HInstance instance)
Check whether the instance is flagged as a bone.
PARAMETERS
HInstance |
instance |
Instance |
RETURNS
bool |
True if flagged as a bone |
dmGameObject::HInstance New(dmGameObject::HCollection collection, const char* prototype_name)
Create a new gameobject instance
PARAMETERS
dmGameObject::HCollection |
collection |
Gameobject collection |
const char* |
prototype_name |
Prototype file name. May be 0. |
RETURNS
dmGameObject::HInstance |
New gameobject instance. NULL if any error occured |
void SetBone(HInstance instance, bool 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
HInstance |
instance |
Instance |
bool |
bone |
true if the instance is a bone |
SetBoneTransforms(HInstance instance, dmTransform::Transform component_transform, dmTransform::Transform* transforms, uint32_t 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
HInstance |
instance |
First Instance of the hierarchy to set |
dmTransform::Transform |
component_transform |
the transform for component root |
dmTransform::Transform* |
transforms |
Array of transforms to set depth-first for the bone instances |
uint32_t |
transform_count |
Size of the transforms array |
RETURNS
|
of instances found |
dmGameObject::Result SetIdentifier(dmGameObject::HCollection collection, dmGameObject::HInstance instance, dmhash_t identifier)
Set instance identifier. Must be unique within the collection.
PARAMETERS
dmGameObject::HCollection |
collection |
Collection |
dmGameObject::HInstance |
instance |
Instance |
dmhash_t |
identifier |
Identifier |
RETURNS
dmGameObject::Result |
RESULT_OK on success |
void SetPosition(dmGameObject::HInstance instance, dmVMath::Point3 position)
Set gameobject instance position
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
dmVMath::Point3 |
position |
New Position |
void SetRotation(dmGameObject::HInstance instance, dmVmath::Quat rotation)
Set gameobject instance rotation
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
dmVmath::Quat |
rotation |
New rotation |
void SetScale(dmGameObject::HInstance instance, float scale)
Set gameobject instance uniform scale
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
float |
scale |
New uniform scale |
void SetScale(dmGameObject::HInstance instance, dmVmath::Vector3 scale)
Set gameobject instance non-uniform scale
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
dmVmath::Vector3 |
scale |
New non-uniform scale |
void SetScaleXY(dmGameObject::HInstance instance, scale_x, scale_y)
Set gameobject instance x and y scale
PARAMETERS
dmGameObject::HInstance |
instance |
Gameobject instance |
|
scale_x |
New x scale |
|
scale_y |
New y scale |
void Spawn(HCollection collection, HPrototype prototype, const char* prototype_name, dmhash_t id, HPropertyContainer properties, dmVMath::Vector3 position, dmVMath::Quat rotation, dmVMath::Vector3 scale)
Spawns a new gameobject instance. The actual creation is performed after the update is completed.
PARAMETERS
HCollection |
collection |
Gameobject collection |
HPrototype |
prototype |
Prototype |
const char* |
prototype_name |
Prototype file name (.goc) |
dmhash_t |
id |
Id of the spawned instance |
HPropertyContainer |
properties |
Container with override properties |
dmVMath::Vector3 |
position |
Position of the spawed object |
dmVMath::Quat |
rotation |
Rotation of the spawned object |
dmVMath::Vector3 |
scale |
Scale of the spawned object return instance HInstance the spawned instance, 0 at failure |
bool TraverseGetRoot(dmGameObject::HRegister regist, dmGameObject::HRegister node)
Gets the top node of the whole game (the main collection)
PARAMETERS
dmGameObject::HRegister |
regist |
the full gameobject register |
dmGameObject::HRegister |
node |
the node to inspect |
RETURNS
bool |
True if successful |
EXAMPLES
The following examples show how to iterate over currently loaded scene graphvoid 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);
}
dmGameObject::SceneNodeIterator TraverseIterateChildren(dmGameObject::SceneNode* node)
Get a scene node iterator for the nodes' children
PARAMETERS
dmGameObject::SceneNode* |
node |
the parent node |
RETURNS
dmGameObject::SceneNodeIterator |
the iterator |
bool TraverseIterateNext(dmGameObject::SceneNodeIterator* it)
Step a scene node iterator to the next sibling
PARAMETERS
dmGameObject::SceneNodeIterator* |
it |
the iterator |
RETURNS
bool |
true if successful. false if the iterator is finished |
dmGameObject::SceneNodePropertyIterator TraverseIterateProperties(dmGameObject::SceneNode* node)
Create a scene node traversal property iterator
PARAMETERS
dmGameObject::SceneNode* |
node |
the node to inspect |
RETURNS
dmGameObject::SceneNodePropertyIterator |
the property iterator |
EXAMPLES
The following examples show how to iterate over the properties of a nodedmGameObject::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: ...
...
}
}
bool TraverseIteratePropertiesNext(dmGameObject::SceneNodePropertyIterator* it)
Steps the scene node traversal property iterator to the next property
PARAMETERS
dmGameObject::SceneNodePropertyIterator* |
it |
the iterator |
RETURNS
bool |
True if the iterator it valid, false if the iterator is finished. |
TYPE
struct InputAction
Container of input related information.
TYPE
struct PropertyDesc
Description of a property. If the property is externally mutable, m_ValuePtr points to the value and its length is m_ElementCount. m_Variant always reflects the value.
MEMBERS
dmhash_t |
m_ElementIds |
For composite properties (float arrays), these ids name each element |
PropertyVar |
m_Variant |
Variant holding the value |
float* |
m_ValuePtr |
Pointer to the value, only set for mutable values. The actual data type is described by the variant. |
uint16_t |
m_ReadOnly |
Determines whether we are permitted to write to this property. |
uint16_t |
m_ValueType |
Indicates type of the property (of type PropertyValueType). |
uint16_t |
m_ArrayLength |
Number of array entries, if the property is an array and zero otherwise. Max supported length is 2^14 (16384 elements) |
TYPE
struct PropertyOptions
Parameters variant that holds key or index for a propertys data structure.
MEMBERS
int32_t |
m_Index |
The index of the property to set, only applicable if property is array. |
dmhash_t |
m_Key |
The key of the property to set, only applicable if property is hashtable. |
uint8_t |
m_HasKey |
A flag if structure contain m_Key value (it can't contain both) |
TYPE
struct PropertyVar
Property variant that holds the data for a variable
MEMBERS
dmGameObject::PropertyType |
m_Type |
property type |
double |
m_Number |
A floating point value (union) |
dmhash_t |
m_Hash |
A hash value (union) |
const uin8_t* |
m_Url |
An URL value (union) |
float |
m_V4 |
A vector4 value (union) |
bool |
m_Bool |
A boolean value (union) |
TYPE
struct SceneNode
Opaque struct that holds info about the current node
TYPE
struct SceneNodeIterator
Opaque struct that holds info about the current position when traversing the scene
TYPE
struct SceneNodeProperty
Struct that holds info about the current position when traversing the scene
MEMBERS
dmhash_t |
m_NameHash |
name |
dmGameObject::SceneNodePropertyType |
m_Type |
type |
union |
m_Value |
value `m_Number` : [type:double] floating point number `m_Hash` : [type:dmhash_t] The hashed value. `m_URL` : [type:char[1024]] The text representation of the url (if reverse hashes are enabled) `m_V4` : [type:float[4]] Used for Vector3, Vector4 and Quat `m_Bool` : [type:bool] A boolean value `m_Text` : [type:const char*] Text from a text property |
TYPE
struct SceneNodePropertyIterator
Holds the property
MEMBERS
dmGameObject::SceneNodeProperty |
m_Property |
property |
TYPE
struct UpdateContext
Update context
MEMBERS
float |
m_TimeScale |
the scaling factor what was applied on the dt (i.e. the collection update time scale) |
float |
m_DT |
the delta time elapsed since last frame (seconds) |
uint32_t |
m_FixedUpdateFrequency |
Number of of calls per second to the FixedUpdate of each component |
Value for an invalid instance index, this must be the same as defined in gamesys_ddf.proto for Create#index.
Gameobject collection handle
Opaque handle to component instance
Opaque handle to internal representation of a component instance
Opaque handle to a component world
Gameobject instance handle
Gameobject properties handle
Handle to a list of properties (gameobject_props.h)
Gameobject prototype handle
Collection register.
Script handle
Script instance handle
Used for mapping instance ids from a collection definition to newly spawned instances
Contains property containers for game objects to be spawned
Create result enum.
dmGameObject::CREATE_RESULT_OK |
|
dmGameObject::CREATE_RESULT_UNKNOWN_ERROR |
Input result enum
INPUT_RESULT_IGNORED |
= 0 |
INPUT_RESULT_CONSUMED |
= 1 |
INPUT_RESULT_UNKNOWN_ERROR |
= -1000 |
Playback type enum
Property result.
dmGameObject::PROPERTY_RESULT_OK |
|
dmGameObject::PROPERTY_RESULT_NOT_FOUND |
|
dmGameObject::PROPERTY_RESULT_INVALID_FORMAT |
|
dmGameObject::PROPERTY_RESULT_UNSUPPORTED_TYPE |
|
dmGameObject::PROPERTY_RESULT_TYPE_MISMATCH |
|
dmGameObject::PROPERTY_RESULT_COMP_NOT_FOUND |
|
dmGameObject::PROPERTY_RESULT_INVALID_INSTANCE |
|
dmGameObject::PROPERTY_RESULT_BUFFER_OVERFLOW |
|
dmGameObject::PROPERTY_RESULT_UNSUPPORTED_VALUE |
|
dmGameObject::PROPERTY_RESULT_UNSUPPORTED_OPERATION |
|
dmGameObject::PROPERTY_RESULT_RESOURCE_NOT_FOUND |
|
dmGameObject::PROPERTY_RESULT_INVALID_INDEX |
|
dmGameObject::PROPERTY_RESULT_INVALID_KEY |
|
dmGameObject::PROPERTY_RESULT_READ_ONLY |
Property types.
dmGameObject::PROPERTY_TYPE_NUMBER |
|
dmGameObject::PROPERTY_TYPE_HASH |
|
dmGameObject::PROPERTY_TYPE_URL |
|
dmGameObject::PROPERTY_TYPE_VECTOR3 |
|
dmGameObject::PROPERTY_TYPE_VECTOR4 |
|
dmGameObject::PROPERTY_TYPE_QUAT |
|
dmGameObject::PROPERTY_TYPE_BOOLEAN |
|
dmGameObject::PROPERTY_TYPE_COUNT |
Type of property value
dmGameObject::PROP_VALUE_ARRAY |
|
dmGameObject::PROP_VALUE_HASHTABLE |
Result enumeration.
dmGameObject::RESULT_OK |
|
dmGameObject::RESULT_OUT_OF_RESOURCES |
|
dmGameObject::RESULT_ALREADY_REGISTERED |
|
dmGameObject::RESULT_IDENTIFIER_IN_USE |
|
dmGameObject::RESULT_IDENTIFIER_ALREADY_SET |
|
dmGameObject::RESULT_COMPONENT_NOT_FOUND |
|
dmGameObject::RESULT_MAXIMUM_HIEARCHICAL_DEPTH |
|
dmGameObject::RESULT_INVALID_OPERATION |
|
dmGameObject::RESULT_RESOURCE_TYPE_NOT_FOUND |
|
dmGameObject::RESULT_BUFFER_OVERFLOW |
|
dmGameObject::RESULT_IDENTIFIER_INVALID |
|
dmGameObject::RESULT_RESOURCE_ERROR |
|
dmGameObject::RESULT_CHILD_NOT_FOUND |
|
dmGameObject::RESULT_INVALID_PROPERTIES |
|
dmGameObject::RESULT_UNABLE_TO_CREATE_COMPONENTS |
|
dmGameObject::RESULT_UNABLE_TO_INIT_INSTANCE |
|
dmGameObject::RESULT_UNKNOWN_ERROR |
scene node property types
dmGameObject::SCENE_NODE_PROPERTY_TYPE_NUMBER |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_HASH |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_URL |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_VECTOR3 |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_VECTOR4 |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_QUAT |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_BOOLEAN |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_TEXT |
|
dmGameObject::SCENE_NODE_PROPERTY_TYPE_COUNT |
Update result enum.
dmGameObject::UPDATE_RESULT_OK |
|
dmGameObject::UPDATE_RESULT_UNKNOWN_ERROR |