Module : library-fontfx
Defined in '.\library-fontfx.agc'

This is a library for animating fonts easily. It is not dissimilar to the CreateText() option, except in that if you want things to animate, you do not have to bother with all the tweens and chains, you just tell it what you want to do. Examples are in the main.agc file. All of these use the same font (the standard 'subimages' font) but you can use as many fonts as you like. It is best to start by looking at the 5 demos (change the gosub) to pick another demo, and try to see how they work, especially Demo2 which gives an overview of the built in animation commands.

It is perhaps not too advisable to use this for too much action in a high speed game. The reason for this is primarily that it is written in AGK Basic itself, so in a high speed scenario there could be a lot of other things going on, and processor power is not infinite, especially on some cheaper Android tablets and phones. It may be fine to animate a "Get Ready!" message at the start of a level, but it is probably not a great idea to use it for the score which is being continually updated and animated. It might work better than I think, mind. It should be remembered that once an animation has completed FFSync() calls do almost nothing, so you could animate the score into position and do it, but I wouldn't advise animating the score while the game is playing.

As with many AGK features, it has a 'sync' call which should be called using the main Sync() loop to update everything. This is FFXSync()

Animations are sequences of commands, seperated by colons. Each command can have parameters, currently there are four possible parameters, time (how long one animation takes) repeat (how many times it should repeat, 0 = for ever), tween, which tween, if any should be used in the animation, and mod1 and mod2 which control the animation. Generally mod1 controls the 'aggressiveness' of the animation, so in curve for example (which makes the text follow a sine curve) it adjusts the deflection in the curve. The built in animations are documented in full later. Each part is seperated by a comma (e.g. "curve,repeat=2,time=2,mod1=4" is a single animation command.

You can have as many of these commands sequentially as you want. If you want one to repeat endlessly, just have a final command "loop" (see Demo3)

There is one catch. Some animations (curve is one) repeat infinitely by default. If you want to run it for just (say) five seconds, you need to do "curve,repeat=1,time=4.0", if you leave the repeat out it will default to zero and will repeat the curve forever.

Additional animations can be hard coded, there is an example of this in Demo4, which attempts to replicate (approximately) the level end text from Rainbow Islands (Goal In!). The exact code is explained there, but the basic idea is each character is called in turn, and you decide what to do with it - so in 'curve' for example you can move it up or down dependent on a sine calculation. You can make each character any size you want, make it go anywhere you want, set it to any angle and alpha. There is a helper function FFXOffsetSprite which assists with this.

One detail is that AGK doesn't really do optional extensibility well. The FFXEXTENSION constant works round this problem. If you have no 'user defined animations' it can be set to zero (see main.agc), but if you have user defined ones (the demo has one called "goalin") then this is defined to a function call, this function is then responsible for processing the animation. The FFXEXTENSION must be present either as a 0 or a call, if not the library won't compile.

the FFXCharacter and FFXText structures are documented, but unless you are hand coding animations in AGK Basic, you should have no need of them

The tween functions in this library were derived from libclaw documentation developed by Julien Jorge

Name | library-fontfx
Author | Paul Scott Robson
Email | paulscottrobson@gmail.com
License | MIT
Prefix | FFX
Version | 0.1
Created | 08-Feb-15
Updated | 17-Feb-15
Provides | fontfx

User Defined Type : FFXCharacter
Defined in '.\library-fontfx.agc'
This type represents a single character. It provides all the information for that character to be animated if necessary. This is only used when writing hard coded animations.

Member | Type | Description
--- | --- | ---
spriteID | integer | Sprite ID - still kept when not in use.
x | float | Horizontal position of the sprite
y | float | Vertical position of the sprite
width | float | Default sprite width
height | float | Default sprite height
charIndex | integer | Character number (count from 1)
wordIndex | integer | Word number (count from 1)

User Defined Type : FFXText
Defined in '.\library-fontfx.agc'
This type represents a single animateable string. It does not use AGK2 Strings because their sub characters can't be independently scaled.
The developer should not manipulate this directly but use the methods. provided. It can be accessed for values needed for hard coded animations.

Member | Type | Description
--- | --- | ---
x | float | Horizontal position
y | float | Vertical position
xTopLeft | float | Top left of string x
yTopLeft | float | Top left of string y
charWidth | float | Required char width
charHeight | float | Required char height
maxWidth | float | Largest width of character
maxHeight | float | Largest height of character
anchorPointX | integer | Horizontal Anchor point (-1 left, 0 centre, 1 right)
anchorPointY | integer | Vertical Anchor point (-1 top,0 centre, 1 bottom)
currentString | string | Current string value
characters | FFXCharacter[0] | Array of FFX characters.
isAnimationRunning | integer | Set to non-zero when animation is running.
fullWidth | float | Width of whole string
fullHeight | float | Height of whole string
fontImageId | integer | Image ID of font.
wordCount | integer | Number of words.
charCount | integer | Characters in whole String
animationStartTime | integer | System clock when animation started (milliseconds)
animationRepeatCount | integer | Repeat counter for animation.
animationTime | integer | Time it runs for (overridden or default, milliseconds)
animationPosition | integer | Animation position : 0->1000
animationModifier1 | float | Animation modifiers 1
animationModifier2 | float | Animation modifiers 2
animationCommand | string | Complete animation command.
animationCommandNo | integer | Index of animation number.
animationCommandCount | integer | Animations in current command
animationCurrentCommand | string | Current single animation being executed
animationTween | string | Current tween for animation.

Function : FFXCreateText(txt,text,fontImageID)
Defined in '.\library-fontfx.agc'
Create a new animated text object. This is built using a single font. You cannot change the font used. (just delete it and recreate it with the new font). The font is created filling most of the screen width and centred horizontally and vertically.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
text | String | Text to store in there.
fontImageID | integer | Image ID of font to draw with.
returns | none |

Function : FFXDeleteText(txt)
Defined in '.\library-fontfx.agc'
Delete a font text object and tidy up sprites used.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
returns | none |

Function : FFXOffsetSprite(char,xOffset,yOffset,xScale,yScale)
Defined in '.\library-fontfx.agc'
Offset sprite by a position and scale it, keeping position correct - required because of top/left coordinates. Helper function for character manipulation. DO NOT USE for anything else.

Parameter | Type | Description
--- | --- | ---
char | ref FFXCharacter |
xOffset | float | Horizontal offset position.
yOffset | float | Vertical offset position.
xScale | float | Horizontal scaling (1.0 = unchanged, -ve = flip)
yScale | float | Vertical scaling (1.0 = unchanged, -ve = flip)
returns | none |

Function : FFXRestart(txt)
Defined in '.\library-fontfx.agc'
Restart the current animation on the given text object. This can be done at any time. The FFXSync() command returns 0 if the animation is no longer running.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
returns | none |

Function : FFXSetAnchorPoints(txt,x,y)
Defined in '.\library-fontfx.agc'
Set the anchor point for the text, e.g. the 'target' for SetPosition. If you set it to -1,-1 then SetPosition(x,5,8) will put the top left corner at (5,8).

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
x | integer | horizontal anchor point (-1 left,0 centre, 1 right)
y | integer | vertical anchor point (-1 top,0 centre, 1 bottom)
returns | none |

Function : FFXSetAnimation(txt,animation)
Defined in '.\library-fontfx.agc'
Prepare to run an animation on a text object. This associates the command with the text object setting it up to run. Subsequent calls to FFXSync() do the actual animation.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
animation | string | Animation to run.
returns | none |

Function : FFXSetColor(txt,r,g,b,a)
Defined in '.\library-fontfx.agc'
Set the text ARGB colours - same as SetSpriteColor() functionality in AGK2. All values are 0-255 and are a fractional multiplier of the ARGB values. It is not possible to increase the ARGB of a sprite pixel using this method. Used judiciously, this will allow one font to have several 'looks'.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
r | integer | Colour Red
g | integer | Colour Greem
b | integer | Colour Blue
a | integer | Alpha
returns | none |

Function : FFXSetFontSize(txt,width,height)
Defined in '.\library-fontfx.agc'
Change the font size. This is the biggest the font can get, e.g. the biggest character possible will fit in this space

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
width | float | Width in units (-1 to calculate from A/R)
height | float | Height in units (-1 to calculate from A/R)
returns | none |

Function : FFXSetPosition(txt,x,y)
Defined in '.\library-fontfx.agc'
Reposition the text, taking note of anchorage points.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
x | float | new position horizontal
y | float | new position vertical
returns | none |

Function : FFXSetText(txt,text)
Defined in '.\library-fontfx.agc'
Update the text and resize/position accordingly.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
text | String | Text to store in there.
returns | none |

Function : FFXStop(txt)
Defined in '.\library-fontfx.agc'
Stop an animation from running.

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
returns | none |

Function : FFXSync(txt)
Defined in '.\library-fontfx.agc'
Update the given animation as per the system clock. This should be called as part of the usual Sync() loop (see the examples).

Parameter | Type | Description
--- | --- | ---
txt | ref FFXText | Font Text Object
returns | integer | 0 if the animation is complete, 1 otherwise.

Generated by agkdoc.py on 02/17/15 16:58:04