Entities

From Leadwerks Developer Wiki

Jump to: navigation, search

Contents

Description

An entity is the base class for all "things" in 3D space. A light is an entity. So is a mesh. An entity has a position, rotation, and scale. It can be parented to other entities, or be the parent of a child entity.

Because all entity classes like meshes, lights, etc., are extended from the base entity class, the same positioning and rotation commands below can be used on all 3D objects in the engine.

Tutorials

Classes

The class hierarchy for entities is as follows. Commands work on the specified class and all subclasses. For example, entity commands will work on all entities. Body commands will work on bodies, as well as models, controllers, and vehicles. Conversely, terrain commands will not work on another entity class, like lights.

Members

The following are the documented members of the Entity class. Generally, members should be treated as read-only. For example, setting the entity position by changing the position vector values will fail to perform necessary updates the SetPosition() command would call, and the results may be unpredictable.

  • Entity
    • World world
    • Vec3 position
    • Vec3 rotation
    • Vec3 scale
    • Mat4 mat
    • AABB localaabb
    • AABB aabb
    • Entity parent
    • List kids
    • Int collisiontype
    • Object userdata

Commands

Creation & Destruction

The rest of the (non general) creation commands is found in the entity classes (e.g. CreateCube in Meshes).

CopyEntity

  • C: TEntity CopyEntity(TEntity entity, int recursive=1)
  • C++: TEntity Entity::Copy( void ) const
  • BlitzMax: CopyEntity:TEntity( entity:TEntity )
  • Lua: entity:Copy( recursive )
  • Pascal: function CopyEntity ( entity:THandle; recursive:Integer=1 ): THandle;
Copies an existing entity.
[Examples]

CopyEntityKeys

  • C: void CopyEntityKeys(TEntity src, TEntity dst)
  • C++: TEntity Entity::CopyKeys( void ) const
  • BlitzMax: CopyEntityKeys( src:TEntity, dst:TEntity )
  • Lua: CopyEntityKeys( src, dst )
  • Pascal: function CopyEntityKeys ( src:THandle; dst:THandle ): void;
Copies all keys from one entity to another entity.
[Examples]

FreeEntity

  • C: void FreeEntity( TEntity entity )
  • C++: void Entity::Free( void ) Note: Also called from destructor
  • BlitzMax: FreeEntity( entity:TEntity )
  • Lua: entity:Free()
  • Pascal: procedure FreeEntity ( entity:THandle );
Frees an entity from memory.
[Examples]

Entity Movement

Set

PositionEntity
  • C: void PositionEntity( TEntity entity, TVec3 &position, int global )
  • C++:
    • void Entity::SetPosition( const TVec3& pos = Vector3(0), const EntityTypes& type = LOCAL ) Where type is either LOCAL or GLOBAL
    • void Entity::SetPosition( flt x = 0, flt y = 0, flt z = 0 , const EntityTypes& type = LOCAL )
    • void Entity::SetPosition( const Entity& ent, const EntityTypes& type = LOCAL ) Position same as the other Entity
    • void Entity::SetPosition( float v = 0 , const EntityTypes& type = LOCAL )
  • BlitzMax:
    • PositionEntity( entity:TEntity, position:Byte Ptr [, global=0 ] )
    • Entity.SetPosition( position:Byte Ptr [, global:Int=0] )
    • Entity.SetPositionf( x:Float, y:Float, z:Float [, global:Int=0] )
  • Lua:
    • Entity:SetPosition( position, glob )
    • Entity:SetPositionf( x, y, z, glob )
  • Pascal: procedure PositionEntity ( entity:THandle; const position:TVec3; global:Integer=0 );
Sets the entity position. Setting the global parameter to 1 will set the entity position in global space.
The position parameter is a pointer to three floats. It can be a vec3 object or a float array.
[Examples]
RotateEntity
  • C: void RotateEntity( TEntity entity, TVec3 &rotation, int global )
  • C++:
    • void Entity::SetRotation( const TVec3& rot, const EntityTypes& type = LOCAL ) Where type is either LOCAL or GLOBAL
    • void Entity::SetRotation( flt x, flt y, flt z , const EntityTypes& type = LOCAL )
    • void Entity::SetRotation( const Entity& ent , const EntityTypes& type = LOCAL ) Same rotation as the other Entity
    • void Entity::SetRotation( float v, const EntityTypes& type = LOCAL )
  • BlitzMax: RotateEntity( entity:TEntity, rotation:TVec3 [, global=0 ] )
  • Lua:
    • Entity:SetRotation( position, glob )
    • Entity:SetRotationf( x, y, z, glob )
  • Pascal: procedure RotateEntity ( entity:THandle; const rotation:TVec3; global:Integer=0 );
Sets the entity rotation. Setting the global parameter to 1 will set the entity rotation in global space.
[Examples]
ScaleEntity
  • C: void ScaleEntity( TEntity entity, TVec3 &scale )
  • C++:
    • void Entity::SetScale( const TVec3& scale )
    • void Entity::SetScale( flt x, flt y, flt z )
    • void Entity::SetScale( const Entity& ent ) Scale same as the other Entity
    • void Entity::SetScale( float v )
  • BlitzMax: ScaleEntity( entity:TEntity, scale:TVec3 )
  • Lua:
    • Entity:SetScale( position, glob )
    • Entity:SetScalef( x, y, z, glob )
  • Pascal: procedure ScaleEntity ( entity:THandle; const scale:TVec3 );
Sets the entity's scale.
[Examples]
TurnEntity
  • C: void TurnEntity( TEntity entity, TVec3 &rotation, int global=0 )
  • C++:
    • virtual void Entity::Turn( const Vector3& rotation, const EntityTypes& type = LOCAL ) Where type is either LOCAL or GLOBAL
    • virtual void Entity::Turn( flt x, flt y, flt z , const EntityTypes& type = LOCAL );
  • BlitzMax: TurnEntity( entity:TEntity, rotation:TVec3, global:Int=0 )
  • Lua:
    • entity:Turn( euler:TVec3, global )
    • entity:Turnf( pitch, yaw, roll, global )
  • Pascal: procedure TurnEntity ( entity:THandle; const rotation:TVec3; global:Integer=0 );
Turns an entity by the given rotation amount in degrees.
[Examples]
MoveEntity
  • C: void MoveEntity(TEntity entity, TVec3 &direction=Vec3(1), int global=0)
  • C++:
    • virtual void Entity::Move( const Vector3& movement )
    • virtual void Entity::Move( flt x, flt y, flt z )
  • BlitzMax: MoveEntity( entity:TEntity, movement:TVec3 )
  • Lua:
    • Entity:Move( movement, glob )
    • Entity:Movef( x, y, z, glob )
  • Pascal: procedure MoveEntity ( entity:THandle; const movement:TVec3 );
Moves the entity along its own coordinate system (if global == 0).
[Examples]
TranslateEntity
  • C: void TranslateEntity( TEntity entity, TVec3 &translation, int global )
  • C++:
    • virtual void Entity::Translate( const TVec3& position, const EntityTypes& type = LOCAL ) Where type is either LOCAL or GLOBAL
    • virtual void Entity::Translate( flt x, flt y, flt z, const EntityTypes& type = LOCAL )
  • BlitzMax: TranslateEntity( entity:TEntity, translation:TVec3 [, global=0 ] )
  • Lua:
    • entity:Translate( t:TVec3, global )
    • entity:Translatef( x, y, z, global )
  • Pascal: procedure TranslateEntity ( entity:THandle; const translation:TVec3; global:Integer=0 );
Moves the entity along its parent coordinate system. Setting the global parameter to 1 will translate the entity in global space.
[Examples]
AlignToVector
  • C: void AlignToVector( TEntity entity, TVec3 &vector, int axis, flt rate, flt roll )
  • C++: virtual void Entity::AlignToVector( const TVec3& v, const Axis& axis = LEO::Z, flt rate = 1.0f, flt roll = 0.0f ) Where axis one of X, Y or Z
  • BlitzMax: AlignToVector( entity:TEntity, vector:TVec3 [, axis=3, rate#=1.0, roll#=0.0 ] )
  • Lua:
    • entity:AlignToVector( t:TVec3, axis, rate, roll )
    • entity:AlignToVectorf( x, y, z, axis, rate, roll )
  • Pascal: procedure AlignToVector ( entity:THandle; const vector:TVec3; axis:Integer=3; rate:Single=1; roll:Single=0 );
Aligns an entity to a vector. The axis parameter indicates which axis to align. Use 1 for x, 2 for y, and 3 for the z axis. A rate value of less than 1.0 will gradually change orientation over several frames. The roll value controls the entity's rotation around the vector.
[Examples]
PointEntity
  • C: void PointEntity( TEntity entity1, TEntity entity2, int axis=3, flt rate=1, flt roll=0 )
  • C++: virtual void Entity::Point( const TEntity ent, const Axis& axis = LEO::Z, flt rate = 1.0f, flt roll = 0.0f ) Where axis is one of X, Y, Z
  • BlitzMax: PointEntity( entity1:TEntity, entity2:TEntity [, axis=3, rate#=1.0, roll#=0.0 ] )
  • Lua: entity:Point( entity, axis, rate , roll )
  • Pascal: procedure PointEntity ( entity1:THandle; entity2:THandle; axis:Integer=3; rate:Single=1; roll:Single=0 );
Points an entity at another entity, along any axis. The axis parameter indicates which axis to align. Use 1 for x, 2 for y, and 3 for the z axis. A rate value of less than 1.0 will gradually change orientation over several frames. The roll value controls the entity's rotation around the vector.
[Examples]
SetEntityMatrix
  • C: void SetEntityMatrix( TEntity entity, TVec16 &matrix )
  • C++: void Entity::SetEntityMatrix( const TVec16& matrix )
  • BlitzMax: SetEntityMatrix( entity:TEntity, mat:TMat4 )
  • Lua: entity:SetMatrix( mat )
  • Pascal: procedure SetEntityMatrix ( entity:THandle; const matrix:TVec16 );
Sets an entity's 4x4 matrix. New local position, rotation, and scale values will be calculated. The entity matrix contains the entity orientation in global space. It is not relative to the parent.
[Examples]

Get

EntityPosition
  • C: TVec3 EntityPosition( TEntity entity, int global=0 )
  • C++: TVec3 Entity::GetPosition( const EntityTypes& type = LOCAL ) Where type is either LOCAL or GLOBAL
  • BlitzMax: EntityPosition:TVec3( entity:TEntity, global:Int=0 )
  • Lua: entity:GetPosition( global )
  • Pascal: procedure EntityPosition ( entity:THandle; var position:TVec3; global:Integer=0 );
Retrieves the entity position. Setting the global parameter to 1 will get the entity position in global space.
[Examples]
EntityRotation
  • C: TVec3 EntityRotation( TEntity entity, int global=0 )
  • C++: TVec3 Entity::GetRotation( const EntityTypes& type = LOCAL ) Where type is either LOCAL or GLOBAL
  • BlitzMax: EntityRotation:TVec3( entity:TEntity, global:Int=0 )
  • Lua: entity:GetRotation( global )
  • Pascal: procedure EntityRotation ( entity:THandle; var angle:TVec3; global:Integer=0 );
Retrieves the entity rotation. Setting the global parameter to 1 will get the entity rotation in global space.
[Examples]
EntityScale
  • C: TVec3 EntityScale(TEntity entity)
  • C++: TVec3 Entity::GetScale( void ) const
  • BlitzMax: EntityScale:TVec3( entity:TEntity )
  • Lua: entity:GetScale( global )
  • Pascal: procedure EntityScale ( entity:THandle; var scale:TVec3 );
Retrieves the entity scale.
[Examples]
EntityQuat
  • C: TVec4 EntityQuat(TEntity entity)
  • C++: TVec4 Entity::GetQuat( void ) const
  • BlitzMax: EntityQuat:TQuat( entity:TEntity )
  • Pascal: procedure EntityQuat ( entity:THandle; var quaternion:TVec4 );
Retrieves the entity quaternion.
[Examples]
GetEntityMatrix
  • C: TVec16 GetEntityMatrix(TEntity entity)
  • C++: TVec16 Entity::GetMatrix( void ) const
  • BlitzMax: GetEntityMatrix:TMat4( entity:TEntity )
  • Pascal: procedure GetEntityMatrix ( entity:THandle; var matrix:TVec16 );
Retrieves an entity's 4x4 matrix. The entity matrix contains the entity orientation in global space. It is not relative to the parent.
[Examples]
GetEntityAABB
  • C: TVec6 GetEntityAABB(TEntity entity)
  • C++: TVec6 Entity::GetAABB( void ) const
  • BlitzMax: GetEntityAABB:TAABB( entity:TEntity, aabb:TAABB )
  • Pascal: procedure GetEntityAABB ( entity:THandle; var AABB:TVec6 );
Retrieves the entity AABB (Axis-Aligned Bounding Box). This is 2 points that store the minimum and maximum extents of the entity's 3D volume, in global space.
[Examples]
EntityDistance
  • C: flt EntityDistance( TEntity entity1, TEntity entity2 )
  • C++: flt Entity::GetDistance( const TEntity ent ) const
  • BlitzMax: EntityDistance#( entity1:TEntity, entity2:TEntity )
  • Lua: EntityDistance( entity1, entity2 )
  • Pascal: function EntityDistance ( entity1:THandle; entity2:THandle ): Single;
Returns the distance between entities 1 and 2.
[Examples]

Animation

Animate

  • C: void Animate( TEntity entity, flt frame, flt blend=1, int sequence=0, int recursive=1 )
  • C++: virtual void Entity::Animate( flt frame, flt blend, int sequence=0, const Recursion& recursion = NONRECURSIVE ) Where recursion is either NONRECURSIVE or RECURSIVE
  • BlitzMax: Animate( entity:TEntity, frame:Float [, blend:Float=1.0, sequence:Int=0, recursive=1 ] )
  • Lua: entity:Animate( frame, blend, sequence, recursive )
  • Pascal: procedure Animate ( entity:THandle; frame:Single=0; blend:Single=1; recursive:Integer=1 );
Animates an animated entity. The animation is interpolated between the nearest two keyframes, indicated by the frame parameter. The blend parameter can be used to control the strength of the animation effect. A blend value of 0.5 will interpolate halfway between the current orientation and the animation frame, while a blend value of 1.0 will use the animation frame with no blending. This can be used to mix different animations. Any entity in the hierarchy can be animated independently, so the legs of a character can use one animation while the upper body uses another.
This will only have an effect when used directly on a mesh or on an entity that has a mesh child entity (e.g. a Model). The mesh must have a material specifying a "mesh_..._skin.vert" and "mesh_shadow_skin.vert" shader (see Materials for more info).
[Examples]

LoadAnimation

  • C: int LoadAnimation( TEntity entity, str path )
  • BlitzMax: LoadAnimation:Int(entity:TEntity,path:String)
  • Lua: LoadAnimation:Int(entity:TEntity,path:String)
Returns the index of the loaded animation sequence.
[Examples]

CountAnimations

  • C: int CountAnimations( TEntity entity )
  • BlitzMax: CountAnimations:Int( entity:TEntity )
  • Lua: entity:CountAnimations()
Returns the number of animation sequences an entity has.
[Examples]

AnimationLength

  • C: int AnimationLength( TEntity entity, int sequence=0 )
Returns the length of the specified animation sequence.
[Examples]

ClearAnimation

  • C: void ClearAnimation( TEntity entity )
  • BlitzMax: ClearAnimation( entity:TEntity )
  • Lua: entity:ClearAnimation()
Clears all entity animation sequences.
[Examples]

Entity State/Appearance

Set

EntityType
  • C: void EntityType( TEntity entity, int collisionType=1, int recursive=0 )
  • BlitzMax: EntityType( entity:TEntity, collisionType [, recursive=0 ] )
  • Lua: entity:SetCollisionType(collisionType,recursive)
  • Pascal: procedure EntityType ( entity:THandle; collisionType:Integer=1; recursive:Integer=0 );
Sets the entity collision type. If the recursive parameter is set to 1, all children in the entity's hierarchy will be set as well.
[Examples]
EntityColor
  • C: void EntityColor( TEntity entity, TVec4 &color, int recursive=0 )
  • C++: void Entity::SetColor( const TVec4& color, int recursive=0 )
  • BlitzMax: EntityColor( entity:TEntity, color:TVec4, recursive:Int=0 )
  • Lua:
    • entity:SetColor( color:TVec4, recursive )
    • entity:SetColorf( r, g, b, recursive )
  • Pascal: procedure EntityColor ( entity:THandle; const color:TVec4; recursive:Integer=0 );
Sets the entity color. This affects meshes, emitters, lights, and coronas onyl.
Entity specific effects:
  • A light's intensity is controllable with it's color by multiplying the components: EntityColor(light,Vec4(2)); makes the light twice as bright as EntityColor(light,Vec4(1));
For the other entity types, setting component values higher than 1.0 has no effect.
[Examples]
EntityViewRange
  • C: void EntityViewRange( TEntity entity, int range=VIEWRANGE_NEAR, int recursive=0 )
  • C++: void Entity::SetViewRange( int range=VIEWRANGE_NEAR, const Recursion& recursion = NonRecursive ) Where recursion is Recursive or NonRecursive
  • BlitzMax: EntityViewRange( entity:TEntity, range:Int=0 [, recursive=0 ] )
  • Lua: entity:SetViewRange( range, recursive )
  • Pascal: procedure EntityViewRange ( entity:THandle; range:Integer=0; recursive:Integer=0 );
Sets the entity view range. The entity view range is a number for the view range category from 0 to 3:
  • VIEWRANGE_NEAR = 0     // 50 units
  • VIEWRANGE_MEDIUM = 1 // 125 units
  • VIEWRANGE_FAR = 2       // 250 units
  • VIEWRANGE_INFINITE = 3 // infinite units
The entity will not be drawn if it is further from the camera than the view range. Some entities like coronas use a near fade distance to gradually fade from view. For all the other entity types, the near range setting is ignored. If the recursive parameter is set to 1, all children in the entity's hierarchy will be set as well.
[Examples]
EntityShadowRange
  • C: void EntityShadowRange( TEntity entity, flt range=100, int recursive=0 )
  • C++: void Entity::SetShadowRange( flt range, const Recursion& recursive = NonRecursive ) Where recursove is Recursive or NonRecursive
  • BlitzMax: EntityShadowRange( entity:TEntity, range# [, recursive=0 ] )
  • Lua: entity:SetShadowRange( range, recursive )
  • Pascal: procedure EntityShadowRange ( entity:THandle; range:Single=100; recursive:Integer=0 );
Sets the entity shadow distance. If the entity is further away from the camera than the specified range, it will not cast a shadow. The default entity shadow distance is 100.
[Examples]
EntityShadowMode
  • C: void EntityShadowMode( TEntity entity, int mode, int recursive=0 )
  • C++: void Entity::SetShadowMode( int mode, const Recursion& recursive = NonRecursive )
  • Lua: entity:SetShadowMode( mode, recursive )
  • Pascal: procedure EntityShadowMode ( entity:THandle; mode:Integer=1; recursive:Integer=0 );
Sets the entity shadow mode. mode can be any (bitwise-)OR (|) combination of the following
  • SHADOW_DISABLED (= 0 = No shadows)
  • SHADOW_DYNAMIC (1)
  • SHADOW_STATIC (2)
  • SHADOW_BUFFERED (4)
  • SHADOW_COLOR (8)
The default shadow mode for all lights is SHADOW_DYNAMIC|SHADOW_STATIC (3).
For point and spot lights, use SHADOW_DISABLED, SHADOW_DYNAMIC, SHADOW_STATIC, SHADOW_DYNAMIC|SHADOW_STATIC or SHADOW_DYNAMIC|SHADOW_STATIC|SHADOW_BUFFERED (7).
For global illumination lightmaps, use SHADOW_COLOR.

The default shadow mode for terrains is SHADOW_DISABLED. The default shadow mode for all other entities is SHADOW_DYNAMIC.
For meshes, models and terrains, you can use either SHADOW_DISABLED, SHADOW_DYNAMIC, or SHADOW_STATIC.
See also: Indoor Lighting Optimization
[Examples]
PaintEntity
  • C: void PaintEntity( TEntity entity, TEntity material, int recursive=0 )
  • C++: virtual void Entity::Paint( const Material& mat, const Recursion& recursion = NonRecursive )
  • BlitzMax: PaintEntity( entity:TEntity, material:TMaterial [, recursive=0 ] )
  • Lua: entity:Paint( material, recursive )
  • Pascal: procedure PaintEntity ( entity:THandle; material:THandle; recursive:Integer=0 );
Sets the entity material. The material parameter may be Null. If the recursive parameter is set to 1, all children in the entity's hierarchy will be painted as well.
If this is used on a spot light, the material's texture0 will be used as a projected image (can be used for e.g. spotlight patterns).
[Examples]
HideEntity
  • C: void HideEntity( TEntity entity )
  • C++: virtual void Entity::Hide( void )
  • BlitzMax: HideEntity( entity:TEntity )
  • Lua: entity:Hide()
  • Pascal: procedure HideEntity ( entity:THandle );
Hide an entity.
[Examples]
ShowEntity
  • C: void ShowEntity( TEntity entity )
  • C++: virtual void Entity::Show( void )
  • BlitzMax: ShowEntity( entity:TEntity )
  • Lua: entity:Show()
  • Pascal: procedure ShowEntity ( entity:THandle );
Show an entity.
[Examples]
EntityOcclusionMode
  • C: void EntityOcclusionMode( TEntity entity, int mode, int resursive=0 )
  • C++: void Entity::SetOcclusionMode( int mode )
  • BlitzMax: EntityOcclusionMode( entity:TEntity, mode:Int )
  • Lua: entity:SetOcclusionMode( mode, recursive )
  • Pascal: procedure EntityOcclusionMode ( entity:THandle; mode:Integer; recursive:Integer=0 );
If mode is 1 the entity will use hardware occlusion queries to determine when it is culled, if it is supported on the user's hardware. Use this for high-poly meshes or other slow-to-render objects. By default, pointlights, spotlights, and animated meshes have occlusion culling enabled. Because occlusion queries are calculated with the depth buffer, occlusion culling will not work with wireframe rendering.
[Examples]

Get

EntityCulled
  • C: int EntityCulled( TEntity entity, TEntity camera )
  • C++: bool Entity::IsCulled( const Camera& cam ) const
  • BlitzMax: EntityCulled%( entity:TEntity, camera:TCamera )
  • Lua: entity:Culled( camera )
  • Pascal: function EntityCulled ( entity:THandle; camera:THandle ): Integer;
Returns 0 if the entity is visible from the specified camera, else 1 is returned.
[Examples]
GetEntityType
  • C: int GetEntityType( TEntity entity )
  • C++: int Entity::GetType( void ) const
  • BlitzMax: entity.collisiontype
  • Lua: entity.collisiontype
  • Pascal: function GetEntityType ( entity:THandle ): Integer;
Returns the type number of the specified entity.
[Examples]
GetEntityMaterial
  • C: TMaterial GetEntityMaterial( TEntity entity )
  • C++: Material Entity::GetMaterial( void )
  • BlitzMax:
    • GetEntityMaterial:TMaterial( entity:TEntity )
    • entity.material
  • Lua: entity.material
Returns the entity's material. This value may be Null.
[Examples]
EntityHidden
  • C: int EntityHidden( TEntity entity )
  • C++: bool Entity::IsHidden( void ) const
  • BlitzMax: EntityHidden:Int( entity:TEntity )
  • Lua: entity:Hidden()
  • Pascal: function EntityHidden ( entity:THandle ): Integer;
Returns 1 if the entity is hidden, else 0 is returned. Hiding is recursive, so if the entity's parent (or grandparent, great-grandparent, etc.) is hidden, the child will be considered hidden as well.
[Examples]
EntityExists
  • C: int EntityExists( TEntity entity )
Returns 1 if the specified entity exists otherwise 0.
[Examples]

Entity Hierarchy

EntityParent

  • C: int EntityParent( TEntity entity, TEntity parent, int global=1 )
  • C++: void Entity::SetParent( Entity parent, const EntityTypes& type = Global ) Where type is Local or Global
  • BlitzMax:
    • EntityParent:Int( entity:TEntity, parent:TEntity, global:Int = 1 )
    • entity:SetParent(parent:TEntity,global:Int=1)
  • Lua: entity:SetParent( parent, global )
  • Pascal: procedure EntityParent ( entity:THandle; parent:THandle=0; global:Integer=1 );
Joins an entity as child entity to a parent entity. The child moves, rotate and scales with the parent.
[Examples]

EntityOrder

  • C: void EntityOrder( TEntity entity, int order=0, int recursive=0 )
  • C++: void Entity::SetOrder( Entity parent, int order=0, int recursive=0 )
  • BlitzMax: EntityOrder( entity:TEntity, order:Int, recursive:Int=0 )
  • Lua: entity:SetOrder( order, recursive )
  • Pascal: procedure EntityOrder ( entity:THandle; order:Integer=0; recursive:Integer=0 );
Sets the entity order of road nodes. Higher order roads appear on top of lower order roads. The default value for order is 0.
[Examples]

CountChildren

  • C: int CountChildren( TEntity entity )
  • C++: int Entity::GetCountChildren( void ) const
  • BlitzMax: CountChildren:Int( entity:TEntity )
  • Lua: entity:CountChildren()
  • Pascal: function CountChildren ( entity:THandle ): Integer;
Returns the number of children of the specified entity.
[Examples]

GetChild

  • C: TEntity GetChild( TEntity entity, int n=1 )
  • C++: Entity Entity::GetChild( int index ) const
  • BlitzMax: GetChild:TEntity( entity:TEntity, n:int )
  • Lua: entity:GetChild( index )
  • Pascal: function GetChild ( entity:THandle; n:Integer=1 ): THandle;
Returns the nth child of the given entity. Children are numbered 1 to CountChildren(). Attempting to access a child out of this range will result in a memory exception.
[Examples]

FindChild

  • C: TEntity FindChild( TEntity entity, str name )
  • C++: Entity Entity::FindChild( const_str name )
  • BlitzMax: FindChild:TEntity( entity:TEntity, name:String )
  • Lua: entity:FindChild( name )
  • Pascal: function FindChild ( entity:THandle; name:PAnsiChar ): THandle;
Finds a child entity of the specified Entity by it's "name" key. This also finds sub-children.
[Examples]

GetParent

  • C: TEntity GetParent(TEntity entity)
  • C++: TEntity Entity::GetParent( void ) const
  • BlitzMax: entity.parent
  • Lua: entity.parent
  • Pascal: function GetParent ( entity:THandle ): THandle;
Returns the parent of the specified entity.
[Examples]

Entity Coordinate Transformation

TFormPoint

  • C: TVec3 TFormPoint(TVec3 &point, TEntity src, TEntity dst)
  • BlitzMax: TFormPoint:TVec3( point:TVec3, src:TEntity, dst:TEntity )
  • Lua: TFormPoint( point, src, dst )
  • Pascal: procedure TFormPoint ( var point:TVec3; src:THandle; dst:THandle );
Transforms a point from the coordinate system of the src entity to the coordinate system of dst entity. Either entities may be Null for global space.
[Examples]

TFormVector

  • C: TVec3 TFormVector(TVec3 &vector, TEntity src, TEntity dst)
  • BlitzMax: TFormVector:TVec3( vector:TVec3, src:TEntity, dst:TEntity )
  • Lua: TFormVector( vector, src, dst )
  • Pascal: procedure TFormVector ( var vector:TVec3; src:THandle; dst:THandle );
Transforms a vector from the coordinate system of the src entity to the coordinate system of dst entity. Either entities may be Null for global space.
[Examples]

TFormNormal

  • C: TVec3 TFormNormal(TVec3 &normal, TEntity src, TEntity dst)
  • BlitzMax: TFormNormal:TVec3( normal:TVec3, src:TEntity, dst:TEntity )
  • Lua: TFormNormal( normal, src, dst )
  • Pascal: procedure TFormNormal ( var normal:TVec3; src:THandle; dst:THandle );
Transforms a normal from the coordinate system of the src entity to the coordinate system of dst entity. Either entities may be Null for global space.
[Examples]

TFormQuat

  • C: TVec4 TFormQuat(TVec4 &quaternion, TEntity src, TEntity dst)
  • BlitzMax: TFormQuat:TQuat( quat:TQuat, src:TEntity, dst:TEntity )
  • Lua: TFormQuat( quat, src, dst )
  • Pascal: procedure TFormQuat ( var quat:TVec4; src:THandle; dst:THandle );
Transforms a quaternion from the coordinate system of the src entity to the coordinate system of dst entity. Either entities may be Null for global space.
[Examples]

TFormPlane

  • C: TVec4 TFormPlane(TVec3 &plane, TEntity src, TEntity dst)
  • BlitzMax: TFormPlane:TVec4( plane:TVec3, src:TEntity, dst:TEntity )
  • Lua: TFormPlane( plane, src, dst )
  • Pascal: procedure TFormPlane( var plane:TVec3; src:THandle; dst:THandle );
Transforms a plane from the coordinate system of the src entity to the coordinate system of dst entity. Either entities may be Null for global space.
[Examples]

Entity Logic

ForEachEntityDo

{{CommandDesc | commandname = ForEachEntityDo | protoc = void ForEachEntityDo(byte* function, byte* extra=NULL, int classes=ENTITY_ALL) | protocpp = void ForEachEntityDo( void* pFunction, void* pExtra, int classes ) | protocs = | protobm = | protopas = procedure ForEachEntityDo ( callback:Pointer ); | desc = Scans all entities in the current world, and calls a user defined function for each entity found. The user defined function must be defined as follows:
int _stdcall myfunc( TEntity entity, byte* extra )

The function must return 1 to continue the loop, and 0 to stop the loop.


In Lua the entities field of the world object is a list of entities which can be stepped through using a For EachIn loop:
For entity in iterate(CurrentWorld().entities) do
	--do stuff
End


In BlitzMax the entities field of the world object is a list of entities which can be stepped through using a For EachIn loop:
For entity:TEntity=EachIn CurrentWorld().entities
	'do stuff
Next

ForEachEntityInAABBDo

  • C: void ForEachEntityInAABBDo(TVec6 &aabb, byte* callback, byte* extra=NULL, int entityclass=ENTITY_ALL)
Scans all entities in the current world that are inside the specified region, and calls a user defined function for each entity found. The user defined function must be defined as: void _stdcall myfunc( TEntity entity, byte* extra)
[Examples]

SetEntityCallback

  • C: void SetEntityCallback( TEntity entity, byte* callback, int callbackID )
  • BlitzMax: SetEntityCallback( entity:TEntity, callback:Byte Ptr, callbackID:Int )
Set an entity's callbacks. The following callback IDs may be used:
See here how these functions have to be structed.
[Examples]

SendEntityMessage

  • C: void SendEntityMessage( TEntity entity, str message, int delay=0, byte* extra=0 )
  • BlitzMax: SendEntityMessage( entity:TEntity, message:String, delay:Int=0, extra:Object=Null )
  • Lua: entity:SendMessage( message, delay, extra )
Sends a message to an entity. If the entity has a callback specified for the message receive event, the callback function will be called. The optional delay value defines a time in milliseconds that will elapse before the message is sent.
[Examples]

GetEntityKey

  • C: str GetEntityKey( TEntity entity, str keyname, str defaultvalue="" )
  • C++: str Entity::GetKey( const_str keyname, const_str defaultvalue = "" )
  • BlitzMax: TEntity::GetEntityKey(keyname$ [, defaultvalue$="" ] )
  • Lua: entity:GetKey( name, defaultvalue )
  • Pascal: function GetEntityKey ( entity:THandle; key:PAnsiChar; defaultvalue:PAnsiChar ): PAnsiChar;
Returns the key value for the specified key name. If the key name is not set, the default value will be returned. Some keys are set automatically by the engine (some under specific conditions). See the command's example page for more info on this.
[Examples]

SetEntityKey

  • C: void SetEntityKey( TEntity entity, str keyname, str keyvalue )
  • C++: void Entity::SetKey( const_str keyname, const_str keyvalue )
  • BlitzMax: TEntity::SetKey(keyname$, keyvalue$ )
  • Lua: entity:SetKey( name, value )
  • Pascal: procedure SetEntityKey ( entity:THandle; key:PAnsiChar; value:PAnsiChar );
Sets the specified key name to the key value. Key names and values are user-defined properties.
[Examples]

SetEntityTarget

  • C: void SetEntityTarget( TEntity entity, TEntity target, int index=0 )
  • BlitzMax: SetEntityTarget( entity:TEntity, target:TEntity [, index:Int=0 ] )
  • Lua: entity:SetTarget( target, index )
Sets an entity target. This is a safe way to make entities reference one another. If the target entity is freed, the reference to it will be deleted.
[Examples]

GetEntityTarget

  • C: TEntity GetEntityTarget( TEntity entity, int index=0 )
  • BlitzMax: GetEntityTarget:TEntity( entity:TEntity [, index:Int=0 ])
  • Lua: entity:GetTarget( index )
Retrieves an entity target. This is a safe way to make entities reference one another. This function may return Null.
[Examples]

SetEntityUserData

  • C: void SetEntityUserData(TEntity entity, byte* data=NULL)
  • Lua: entity.userdata
Use this to point to some memory structure holding object specific data which can be retrieved later. You can e.g. free the allocated memory in the ENTITYCALLBACK_FREE.
[Examples]

GetEntityUserData

  • C: byte* GetEntityUserData(TEntity entity)
  • Lua: entity.userdata
Returns the pointer which was assigned to the entity using SetEntityUserData.
[Examples]

Callback Functions

All callbacks use _stdcall, for compatibility with .NET. BlitzMax uses CDECL (default).

FreeEntityCallback

  • C: void _stdcall FreeEntityCallback( TEntity entity )
  • BlitzMax: FreeEntityCallback( entity:TEntity )
This will be called when the entity is freed. Note that the function can have any name. See the examples page for more info.
[Examples]

UpdateMatrixCallback

  • C: void _stdcall UpdateMatrixCallback( TEntity entity )
  • BlitzMax: UpdateMatrixCallback( entity:TEntity )
This will be called whenever the entity moves or rotates. Note that the function can have any name. See the examples page for more info.
[Examples]

UpdateEntityCallback

  • C: void _stdcall UpdateEntityCallback( TEntity entity )
  • BlitzMax: UpdateEntityCallback( entity:TEntity )
This will be called once when the UpdateWorld() command is called. Note that the function can have any name. See the examples page for more info.
[Examples]

UpdatePhysicsCallback

  • C: void _stdcall UpdatePhysicsCallback( TEntity entity )
  • BlitzMax: UpdatePhysicsCallback( entity:TEntity )
This will be called 60 times per second, regardless of framerate. This should be used for physics updates because the physics simulation will be interpolated and smoothed each frame. The physics callback is performed during the UpdateWorld() routine, but it might not be called each frame, or it might be called multiple times in one frame. Note that the function can have any name.
[Examples]

EntityCollisionCallback

  • C: void _stdcall EntityCollisionCallback( TEntity entity0, TEntity entity1, byte* position, byte* normal, byte* force, flt speed )
  • BlitzMax: EntityCollisionCallback(entity0:TEntity,entity1:TEntity,position:Byte Ptr,normal:Byte Ptr,force:Byte Ptr,speed:Float)
This will be called when entity0 collides with another entity. The first entity is always the one which the callback was specified for. Note that the function can have any name. See the examples page for more info.
[Examples]

MessageReceiveCallback

  • C: void _stdcall MessageReceiveCallback( TEntity entity, str message, byte* extra )
  • BlitzMax: MessageReceiveCallback( entity:TEntity, message:String, extra:Object )
This will be called when an entity receives a message. Note that the function can have any name. See the examples page for more info.
[Examples]
Retrieved from "http://www.leadwerks.com/wiki/index.php?title=Entities"