Module : library-fontfx

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

User Defined Type : FFXCharacter

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.

User Defined Type : FFXText

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.

Function : FFXCreateText(txt,text,fontImageID)

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.

Function : FFXDeleteText(txt)

Delete a font text object and tidy up sprites used.

Function : FFXOffsetSprite(char,xOffset,yOffset,xScale,yScale)

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.

Function : FFXRestart(txt)

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.

Function : FFXSetAnchorPoints(txt,x,y)

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).

Function : FFXSetAnimation(txt,animation)

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.

Function : FFXSetColor(txt,r,g,b,a)

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'.

Function : FFXSetFontSize(txt,width,height)

Change the font size. This is the biggest the font can get, e.g. the biggest character possible will fit in this space

Function : FFXSetPosition(txt,x,y)

Reposition the text, taking note of anchorage points.

Function : FFXSetText(txt,text)

Update the text and resize/position accordingly.

Function : FFXStop(txt)

Stop an animation from running.

Function : FFXSync(txt)

Update the given animation as per the system clock. This should be called as part of the usual Sync() loop (see the examples).