rigz.entity: Functions Types Modinfo Source  

Timeline Entity System for blitzmax

This module provides a base entity class for use in any applications that need to have objects in world that need to be controlled and drawn onto the screen. tlEntity provides the means to control these objects in a structured hierarchy with parent and child entities. Entities are drawn using sprites from the single surface module; singlesurface.mod.

Functions Summary

CreateEntity Create a new entity.
SetUpdateFrequency Set the current Update Frequency.

Types Summary

tlEntity Entity type for basic object information.

Functions

Function CreateEntity:tlEntity()
DescriptionCreate a new entity.

Function SetUpdateFrequency(v:Float)
DescriptionSet the current Update Frequency.
Informationthe default update frequency is 30 times per second.

Types

Type tlEntity
DescriptionEntity type for basic object information.
Information

This is the main type for storing entity information such as coordinates, colour and other information. This type is designed to be a base type that you can use to extend and create other types, for example tPlayer or tBullet.

Entities can be parented to other entities and maintain and update a list of children. These children can be relative to their parents therefore minimising the work needed to calculate where entities should be drawn to the screen. If a parent rotates, then it's children will rotate with it and likewise, if the parent moves then its children will move with it as well. Children don't have to be relative however, set realative to false using setrelative to make the children move independantly, however they will still be updated by their parent

If you have an entity with children, and those children in turn have children, in order to update all of those entities only one call to the parent update method is required to see all of the children updated too. This also applies to rendering the entities on screen - by calling render on the parent entity all children entities will also be rendered. See the code below for an example

Entities draw to the screen using tAnimImage, a type that allows for single surface drawing from the singlesurface.mod. To set the image use setavatar and loadsprite() to set the tAnimImage. You can adjust the appearence of the entity such as colour and scale using commands such as setentitycolor, setentityalpha, setentityscale and setangle

When entities are rendered they can be tweened so that their animation and movement on the screen is smoothed out using fixed rate timing. To do this you need to make a call to capture each time the entity is updated which stores the entities last position and other details. Capture is not included in the udpate method because it makes things too inflexible. There are situations where you might want to specify when exactly you want to capture the entity. This means that when you extend tlentity it's a good idea to overide the update method with your own and include a call to capture within it. Then you can make a call to super.update so that the base update method is still tun. Again, see the example to see how it can work.

Example
SuperStrict

Framework brl.max2d
Import rigz.entity
Import rigz.tweener
Import brl.pngloader

SetGraphicsDriver GLMax2DDriver()

Graphics 800, 600

'set up a type that extends tlEntity
Type tAstralBody Extends tlEntity
	
	'create an update method that uses capture to store the old entity values for tweening
	Method update()
		capture()
		
		'call the main update method
		Super.update()
	End Method

End Type

'setup some locals for our solar system
Local Sun:tAstralBody = New tAstralBody
Local Earth:tAstralBody = New tAstralBody
Local Moon:tAstralBody = New tAstralBody
Local Moonlet:tAstralBody = New tAstralBody

sun.setsprite(LoadSprite("sun.png",,, , True))
earth.setsprite(LoadSprite("earth.png",,, , True))
moon.setsprite(LoadSprite("moon.png",,, , True))
moonlet.setsprite(LoadSprite("moon.png",,, , True))
sun.SetHandleX(-100)
sun.SetHandleY(-100)
sun.SetentityScale(.75, .75)
sun.SetAutoCenter(False)
sun.SetZ(0.5)
'add the earth to the sun as a child
sun.addchild(earth)
'set the suns postion
sun.SetPosition(400, 300)
'call capture so there's no tweening at the start
sun.capture()
'add the moon to the earth as a child
earth.addchild(moon)

'as the earth is parented to the sun, its position will be relative to the sun.
'set x will set the earths position 250 pixels to the sun's right
earth.setx(250)
'scale the earth sprite down by half
earth.SetentityScale(0.5, 0.5)
earth.capture()
earth.SetHandleX(-100)
earth.SetHandleY(100)
earth.name = "earth"
earth.SetAutoCenter(False)


'set the moon 75 pixels to the right of the earth
moon.setx(75)
'scale it down to a quarter of its size
moon.SetentityScale(0.25, 0.25)
moon.capture()

moonlet.SetX(25)
moonlet.SetEntityScale(0.1, 0.1)
moonlet.Capture
moonlet.SetSpeed(25)
moonlet.name = "Moonlet"
moon.AddChild(moonlet)

sun.SetRadiusCalculate(True)

'set up a tweener using the tweener module
Local tweener:tTweener = New tTweener.Create(30)
SetUpdateFrequency(30)

'main loop
While Not KeyDown(KEY_ESCAPE)
	Cls
	
	'update the tweener to get the current tween value
	tweener.Update
	
	'logic update loop
	For Local c:Int = 0 To tweener.getFrameTicks()
		'update the sun, which will update its children. For this reason there
		'is no need to update the earth or the moon as the sun will did it for us
		tweener.UpdateExecutionTime()
		sun.update()
		'rotate the sun and the earth
		sun.rotate(1)
		earth.rotate(-5)
		moon.Rotate(2.5)
		If KeyDown(KEY_SPACE) moonlet.SetSpeed(0)
	Next
	
	'draw them all to the screen
	sun.render(1)
	'sun.DrawBoundingBox()
	sun.DrawEntityBoundary()
	earth.DrawentityBoundary()
	moon.DrawEntityBoundary()
	moonlet.DrawEntityBoundary()
	
	Flip 0
	
Wend
Methods Summary
AddChild Add a new child entity to the entity.
AssignRootParent Assign the root parent of the entity.
CalculateBoundingBox Set the AABB Include value for this tlEntity object.
Capture Capture world coordinates, entity angle and scale for tweening.
CaptureAll Capture all including all children.
ClearChildren Clear all child entities from this list of children.
Decay Increases the age value by a given amount.
Destroy Destroy the entity.
DrawBoundingBox draw the bounding box for debugging.
DrawEntityBoundary Draw the whole boundary of the entity including children.
DrawImageBoundary Draw the image boundary of the entity.
GetAge Get the age value in this tlEntity object.
GetAngle Get the current angle of rotation.
GetAnimating Returns true if the entity is animating.
GetBlendMode Get the current blendmode.
GetBlue Get the blue value in this tlEntity object.
GetChildren Get the children that this entity has.
GetCurrentFrame Get the currentframe of the entity sprite animation.
GetEntityAlpha Get the alpha value in this tlEntity object.
GetEntityDirection Get the direction value in this tlEntity object.
GetEntityRadius Get the Entity Radius value in this tlEntity object.
GetEntityScale Gets the x and y scale of the entity.
GetFrameRate Get the framerate value in this tlEntity object.
GetGreen Get the green value in this tlEntity object.
GetHandleX Get the current entity handle x.
GetHandleY Get the current entity image handle y.
GetImageRadius Get the Image Radius value in this tlEntity object.
GetLifeTime Get the lifetime value in this tlEntity object.
GetName Get the name of the entity.
GetOKToRender Get the oktorender value in this tlEntity object.
GetParent Get the current parent of the entity.
GetRadiusCalculate Get the Radius Calculate value in this tlEntity object.
GetRed Get the red value in this tlEntity object.
GetRelative Get whether this entity is relative to it's parent.
GetSpeed Get the current speed of the entity.
GetSprite Get the current sprite (tAnimImage) that the entity uses when it draws to the screen.
GetWX Get the wx value in this tlEntity object.
GetWY Get the wy value in this tlEntity object.
GetX Get the current x coordinate of the entity.
GetY Get the current y coordinate of the entity.
HasBoundingBox Returns true if the axis aligned bounding box is being calculated for this entity.
KillChildren Recursively kills all child entities and any children within those too and so on.
MiniUpdate A mini update called when the entity is created.
Move Move the entity by the amount x and y that you pass to it.
RemoveChild Remove a child entity from this entity's list of children.
Render Render the entity.
Rotate Rotate the entity by the number of degrees you pass to it.
SetAge Set the age value for this tlEntity object.
SetAngle Set the current angle of rotation of the entity.
SetAnimateOnce Set to true to make the entity animate just once.
SetAnimating Set to true to make the entity animate.
SetAutoCenter Set to true to position the handle of the entity at the center.
SetBlendMode Set the current blendmode of the entity ie., ALPHABLEND/LIGHTBLEND.
SetBlue Set the blue value for this tlEntity object.
SetCurrentFrame Set the currentframe of the entity sprite animation.
SetEntityAlpha Set the alpha value for this tlEntity object.
SetEntityColor Set the colour for the tlEntity object.
SetEntityDirection Set the direction value for this tlEntity object.
SetEntityScale Sets the scale of the entity.
SetFrameRate Set the framerate value for this tlEntity object.
SetGreen Set the green value for this tlEntity object.
SetHandleX Set the entities x handle.
SetHandleY Set the entities y handle.
SetLifeTime Set the lifetime value for this tlEntity object.
SetName Set the name of the entity.
SetOKToRender Set the oktorender value for this tlEntity object.
SetParent Set the parent of the entity.
SetPosition The the x and y position of the entity.
SetRadiusCalculate Set the Radius Calculate value for this tlEntity object.
SetRed Set the red value for this tlEntity object.
SetRelative Sets whether this entity remains relative to it's parent.
SetSpeed Set the current speed of the entity.
SetSprite Set the sprite (tAnimImage) that the entity uses when it draws to the screen.
SetUpdateSpeed Set the UpdateSpeed value for this tlEntity object.
SetWX Set the current world x coordinate of the entity.
SetWY Set the current world y coordinate of the entity.
SetX Set the current x coordinate of the entity.
SetY Set the current y coordinate of the entity.
SetZ Set the current zoom level of the entity.
Update Update the entity.
UpdateBoundingBox Update the entities bounding box.
UpdateChildren Update all children of this entity.
UpdateEntityRadius Update the entity's radius of influence.
UpdateParentBoundingBox Update the entity's parent bounding box.
UpdateParentEntityRadius Update the entity's parent radius of influence.
UpdateRootParentEntityRadius Update the entity's parent radius of influence.
Zoom Change the level of zoom for the particle.
Functions Summary
TweenValues Interpolate between 2 values.
Method AddChild(e:tlEntity)
DescriptionAdd a new child entity to the entity.
InformationThis will also automatically set the childs parent.
Method AssignRootParent(e:tlEntity)
DescriptionAssign the root parent of the entity.
InformationThis assigns the root parent of the entity which will be the highest level in the entity hierarchy. This method is generally only used internally, when an entity is added as a child to another entity.
Method CalculateBoundingBox(Value:Int = True)
DescriptionSet the AABB Include value for this tlEntity object.
Method Capture()
DescriptionCapture world coordinates, entity angle and scale for tweening.
InformationTweening is used in applications that use fixed rate timing. This is where the logic routines of an application are updated a fixed amount of times each frame, but the drawing routines are updated as many times as possible. Each time the entity is updated during a logic update you can capture its coordinates, then, depending on how much time has passed since the last logic update, the entity can be interpolated between the old coordinates and the new ones creating a nice smooth movement no matter the PC you're running it on. To simplify things you can use the tweener.mod to implement fixed rate timing. See the tweener.mod for more info.
Method CaptureAll()
DescriptionCapture all including all children.
Method ClearChildren()
DescriptionClear all child entities from this list of children.
InformationThis completely destroys them so the garbage collector can free the memory.
Method Decay(MilliSeconds:Float)
DescriptionIncreases the age value by a given amount.
Method Destroy()
DescriptionDestroy the entity.
InformationThis will destroy the entity and all it's children, ensuring all references are removed. Best to call this when you're finished with the entity to avoid memory leaks.
Method DrawBoundingBox()
Descriptiondraw the bounding box for debugging.
Method DrawEntityBoundary()
DescriptionDraw the whole boundary of the entity including children.
Method DrawImageBoundary()
DescriptionDraw the image boundary of the entity.
Method GetAge:Float()
DescriptionGet the age value in this tlEntity object.
InformationSee SetAge and Decay.
Method GetAngle:Float()
DescriptionGet the current angle of rotation.
Method GetAnimating:Int()
DescriptionReturns true if the entity is animating.
Method GetBlendMode:Int()
DescriptionGet the current blendmode.
Method GetBlue:Int()
DescriptionGet the blue value in this tlEntity object.
Method GetChildren:TList()
DescriptionGet the children that this entity has.
InformationThis will return a list of children that the entity currently has.
Method GetCurrentFrame:Float()
DescriptionGet the currentframe of the entity sprite animation.
Method GetEntityAlpha:Float()
DescriptionGet the alpha value in this tlEntity object.
Method GetEntityDirection:Float()
DescriptionGet the direction value in this tlEntity object.
InformationGet the current direction the entity is travelling in.
Method GetEntityRadius:Float()
DescriptionGet the Entity Radius value in this tlEntity object.
InformationThe entity radius is similar to the Image_Radius except that it also takes into account all the children of the entity as well. Radius_Calculate needs to be set to true for this value to be kept updated.
Method GetEntityScale(sx:Float Var, sy:Float Var)
DescriptionGets the x and y scale of the entity.
Method GetFrameRate:Float()
DescriptionGet the framerate value in this tlEntity object.
Informationsee SetFrameRate for more info.
Method GetGreen:Int()
DescriptionGet the green value in this tlEntity object.
Method GetHandleX:Int()
DescriptionGet the current entity handle x.
Method GetHandleY:Int()
DescriptionGet the current entity image handle y.
Method GetImageRadius:Float()
DescriptionGet the Image Radius value in this tlEntity object.
InformationThe image radius is the area that the entity could possible be drawn to. This takes into account scale and more importantly, the handle of the image. Radius_Calculate needs to be set to true for this value to be kept updated.
Method GetLifeTime:Int()
DescriptionGet the lifetime value in this tlEntity object.
InformationSee SetLifeTime.
Method GetName:String()
DescriptionGet the name of the entity.
Method GetOKToRender:Int()
DescriptionGet the oktorender value in this tlEntity object.
Informationsee SetOKToRender.
Method GetParent:tlEntity()
DescriptionGet the current parent of the entity.
InformationEntities can have parents and children. Entities are drawn relative to their parents if the relative flag is true. Using this command and addchild you can create a hierarchy of entities.
Method GetRadiusCalculate:Int()
DescriptionGet the Radius Calculate value in this tlEntity object.
Informationsee SetRadiusCalculate for more info.
Method GetRed:Int()
DescriptionGet the red value in this tlEntity object.
Method GetRelative:Int()
DescriptionGet whether this entity is relative to it's parent.
Method GetSpeed:Float()
DescriptionGet the current speed of the entity.
Method GetSprite:TAnimImage()
DescriptionGet the current sprite (tAnimImage) that the entity uses when it draws to the screen.
Method GetWX:Float()
DescriptionGet the wx value in this tlEntity object.
InformationWX represents the current x world coordinate of the entity. This may differ to x, which will contain the x coordinate relative to the parent entity.
Method GetWY:Float()
DescriptionGet the wy value in this tlEntity object.
InformationWY represents the current Y world coordinate of the entity. This may differ to y, which will contain the Y coordinate relative to the parent entity.
Method GetX:Float()
DescriptionGet the current x coordinate of the entity.
InformationThis will be relative to the parent if relative is set to true.
Method GetY:Float()
DescriptionGet the current y coordinate of the entity.
InformationThis will be relative to the parent if relative is set to true.
Method HasBoundingBox:Int()
DescriptionReturns true if the axis aligned bounding box is being calculated for this entity.
Method KillChildren()
DescriptionRecursively kills all child entities and any children within those too and so on.
InformationThis sets all the children's dead field to true so that you can tidy them later on however you need. If you just want to get rid of them completely use clearchildren.
Method MiniUpdate()
DescriptionA mini update called when the entity is created.
InformationThis is sometimes necessary to get the correct world coordinates for when new entities are spawned so that tweening is updated too. Otherwise you might experience the entity shooting across the screen as it tweens between locations.
Method Move(xamount:Float, yamount:Float)
DescriptionMove the entity by the amount x and y that you pass to it.
Method RemoveChild(e:tlEntity)
DescriptionRemove a child entity from this entity's list of children.
Method Render(tween:Float)
DescriptionRender the entity.
InformationThis will Draw the entity onto the screen using the tween value you pass to it to interpolate between old and new positions when using fixed rate timing.
Method Rotate(degrees:Float)
DescriptionRotate the entity by the number of degrees you pass to it.
Method SetAge(Value:Float)
DescriptionSet the age value for this tlEntity object.
InformationSetting the age of of the entity allows you to keep track of how old the entity so that something can happen after a given amount of time. See Decay to increase the age by a given amount.
Method SetAngle(v:Float)
DescriptionSet the current angle of rotation of the entity.
Method SetAnimateOnce(v:Int)
DescriptionSet to true to make the entity animate just once.
InformationOnce the entity as reached the end of the animation cycle it will stop animating.
Method SetAnimating(Value:Int)
DescriptionSet to true to make the entity animate.
Method SetAutoCenter(v:Int)
DescriptionSet to true to position the handle of the entity at the center.
Method SetBlendMode(v:Int)
DescriptionSet the current blendmode of the entity ie., ALPHABLEND/LIGHTBLEND.
Method SetBlue(Value:Int)
DescriptionSet the blue value for this tlEntity object.
Method SetCurrentFrame(Value:Float)
DescriptionSet the currentframe of the entity sprite animation.
Method SetEntityAlpha(Value:Float)
DescriptionSet the alpha value for this tlEntity object.
Method SetEntityColor(_red:Int, _green:Int, _blue:Int)
DescriptionSet the colour for the tlEntity object.
Method SetEntityDirection(Value:Float)
DescriptionSet the direction value for this tlEntity object.
InformationSet the current direction the entity is travelling in.
Method SetEntityScale(sx:Float, sy:Float)
DescriptionSets the scale of the entity.
InformationThis will set both the x and y scale of the entity based on the values you pass it.
Method SetFrameRate(Value:Float)
DescriptionSet the framerate value for this tlEntity object.
Informationthe frame rate dicates how fast the entity animates if it has more then 1 frame of animation. The framerate is measured in frames per second.
Method SetGreen(Value:Int)
DescriptionSet the green value for this tlEntity object.
Method SetHandleX(v:Int)
DescriptionSet the entities x handle.
InformationThis will not apply if autocenter is set to true.
Method SetHandleY(v:Int)
DescriptionSet the entities y handle.
InformationThis will not apply if autocenter is set to true.
Method SetLifeTime(Value:Int)
DescriptionSet the lifetime value for this tlEntity object.
InformationLifeTime represents the length of time that the entity should "Live" for. This allows entities to decay and expire in a given time. LifeTime is measured in milliseconds. See SetAge and Decay for adjusting the age of the entity.
Method SetName(v:String)
DescriptionSet the name of the entity.
Method SetOKToRender(Value:Int)
DescriptionSet the oktorender value for this tlEntity object.
InformationSomethimes you might not always want entities to be rendered. When the render method is called, it will always render the children aswell, but if some of those children are effects which are rendered by a particle manager, then you don't want them rendered twice, so you can set this to false to avoid them being rendered.
Method SetParent(e:tlEntity)
DescriptionSet the parent of the entity.
InformationEntities can have parents and children. Entities are drawn relative to their parents if the relative flag is set to true. Using this command and addchild you can create a hierarchy of entities. There's no need to call addchild as well as setparent because both commands will automatically set both accordingly.
Method SetPosition(_x:Float, _y:Float)
DescriptionThe the x and y position of the entity.
InformationThis will be relative to the parent if relative is set to true.
Method SetRadiusCalculate(Value:Int)
DescriptionSet the Radius Calculate value for this tlEntity object.
InformationRadius is the radius of the entity where it could possible be drawn to. This includes all of it's children as well. This will also propagate to all children, so it's best to set this to true before adding children to the entity, that way, the children will acquire the same value as the parent. By default this is false.
Method SetRed(Value:Int)
DescriptionSet the red value for this tlEntity object.
Method SetRelative(v:Int)
DescriptionSets whether this entity remains relative to it's parent.
InformationEntities that are relative to their parent entity will position, rotate and scale with their parent.
Method SetSpeed(v:Float)
DescriptionSet the current speed of the entity.
Method SetSprite(sprite:TAnimImage)
DescriptionSet the sprite (tAnimImage) that the entity uses when it draws to the screen.
InformationtAnimImage is defined in singlesurface.mod, and is a type that draws animated images using a single surface for extra speed.
Method SetUpdateSpeed(Value:Int)
DescriptionSet the UpdateSpeed value for this tlEntity object.
InformationSet to true or false, default is true. Setting to false will make the update method ignore any speed calculations. This is useful in situations where you want to extend tlEntity and calculate speed in your own way.
Method SetWX(v:Float)
DescriptionSet the current world x coordinate of the entity.
Method SetWY(v:Float)
DescriptionSet the current world y coordinate of the entity.
Method SetX(v:Float)
DescriptionSet the current x coordinate of the entity.
InformationThis will be relative to the parent if relative is set to true.
Method SetY(v:Float)
DescriptionSet the current y coordinate of the entity.
InformationThis will be relative to the parent if relative is set to true.
Method SetZ(v:Float)
DescriptionSet the current zoom level of the entity.
Method Update()
DescriptionUpdate the entity.
InformationUpdates its coordinates based on the current speed (cs), applies any gravity, updates the current frame of the image and also updates the world coordinates. World coordinates (wx and wy) represent the location of the entity where it will be drawn on screen. This is calculated based on where the entity is in relation to it's parent entities. Update also updates the entity's children so only a single call to the parent entity is required to see all the children updated.
Method UpdateBoundingBox()
DescriptionUpdate the entities bounding box.
InformationThis will update the entities bounding box, and if the entity has no children it will update its parent bounding box if it has one.
Method UpdateChildren()
DescriptionUpdate all children of this entity.
Method UpdateEntityRadius()
DescriptionUpdate the entity's radius of influence.
InformationThe radius of influence is the area around the entity that could possibly be drawn to. This is used in the timelinefx editor where it's used to autofit the effect to the animation frame.
Method UpdateParentBoundingBox()
DescriptionUpdate the entity's parent bounding box.
Method UpdateParentEntityRadius()
DescriptionUpdate the entity's parent radius of influence.
Method UpdateRootParentEntityRadius()
DescriptionUpdate the entity's parent radius of influence.
Method Zoom(v:Float)
DescriptionChange the level of zoom for the particle.
Function TweenValues:Float(oldValue:Float, value:Float, tween:Float)
DescriptionInterpolate between 2 values.
InformationThis is the function used to achieve render tweening by taking the old and new values and interpolating between the 2.

Module Information

AuthorPeter J. Rigby
CopyrightPeter J. Rigby 2009
PurposeA base entity class
Versionv1.07
History v1.078th November 2009 - Tidied up the behaviour of entities that have a z value other then 1
History v1.077th November 2009 - New field: RootParent. This is the absolute root parent of the entity. Set when you add the entity as a child. see AssignRootParent
History v1.071st November 2009 - You can now SetRadiusCalculate Which starts calculating the entity's area of influence. See SetRadiusCalculate
History v1.0620th September 2009 - Initial implementation of Z on entities (changes the overal scale of an entity and its children)
History v1.047th September 2009 - Added a few more Getters and Setters
History v1.047th September 2009 - Fixed a bug with animated entities causing a crash
History v1.038th August 2009 - Added new variables for storing the bounding boxes of the entity
History v1.038th August 2009 - Render method now only renders if avatar is not null and OKToRender is true
History v1.038th August 2009 - Added OKToRender field so you can control wheter entities are actually rendered
History v1.038th August 2009 - Add a few more getters and settings for various variables
History v1.037th August 2009 - Added UpdateSpeed flag to tlEntity so you can override the updating of the entity speed and movement
History v1.0227th July 2009 - Changed field cs to speed for more readability and added GetSpeed method
History v1.0114th July 2009 - Moved tp_LOOKUP_FREQUENCY and tp_LOOKUP_FREQUENCY_OVERTIME over to timelinefx.mod
History v1.0114th July 2009 - Render method now renders all children as well
History v1.0114th July 2009 - Tidied up the documentation and fleshed it out a bit
History v1.0114th July 2009 - Fixed bug in tlEntity example - import brl.pngloader was omitted
History v1.0113th July 2009 - Fixed a bug in tAnimImage where it wouldn't load images properly
History v1.0028th March 2009 - First Release