Introduction To Moan

This tutorial introduces you to Moan, TNT Basic's powerful MOvement and ANimation system.

Moan allows you to set sprites and viewports moving or animating with one simple command. Once started you can forget about them and they'll keep going on their own! No more need to track their positions or their destinations, just fire and forget!

Outline

Moan actually consists of two sets of commands: the high level set and the low level set.

The high level set consists of quick and easy to use commands that allow you to set animations or movements off for each sprite in turn.

The low level set allows you to install miniture programs into sprites or viewports to control their movement and animation. These programs run in parallel to your main program and are programmed in the Moan runtime compiler language.

Making Something Move

Here's a simple program to move sprite 1 50 pixels to the right at a speed of 1 pixel a frame, try it out:

sprite 1,100,100,1 ' put the sprite on the screen
move sprite 1,50,0,1 ' set it moving
while not mouse button ' run until the mouse is pressed
draw frame
wend

You can also use the Move Viewport command to set viewports scrolling in a similar manner.
You can test if a movement is finished for a sprite or viewport using the Sprite Moving and Viewport Moving functions.

Making Something Animate

You can use similarly simple programs to animate sprites too.

The following program animates sprite 1, showing image 0 for 5 frames, image 1 for 5 frames then image 2 for 10 frames, in a loop. The -1 is the number of times to loop the animation, -1 means forever, any other number will repeat the animation that number of times.

sprite 1,100,100,1 ' put the sprite on the screen
animate sprite 1,-1, 0,5 to 1,5 to 2,10 ' set anim going
while not mouse button ' run until the mouse is pressed
draw frame
wend

The Moan Language

It was mentioned briefly before that Moan has two sets of commands. The second set, introduced here, is for manipulating and programming Moan Channels.

A Moan channel is a way of connecting movement and animation commands to several sprites, or viewports, at the same time. For example, by attaching all your sprites to the same channel, and then issuing a moan move command to the channel, you can move all sprites at once.

The fun doesn't stop there however, you can write mini-programs that run inside the channels in parallel to your main TNT Basic program. These programs can perform complex behaviours that once initiated from your main program can be forgetten about until they are finished.

Programming In Moan

Moan programs are written in strings and are installed into channels at runtime. They are manipulated in exactly the same way as normal strings, and so can be joined or modified or generated by your program on the fly.

The first thing to note about moan programming is that it is different to programming TNT Basic. There are very few moan commands, this is to make it very simple to compile the programs quickly at runtime. All moan commands are composed of a single UPPER CASE letter, here is an example moan program:

str myMoanProgram = "M 50,0,1"

Can you guess what it does? It's actually a Moan 'M'ove command. This program will move all items attached to the channel by 50 pixels horizontally, 0 pixels vertically and at a speed of 1 pixel a frame. It's equivalent to the high level moan command:

move sprite 1,50,0,1

Except that command will only move sprite 1, whereas the moan program, if put into a moan channel, would move everything attached to the channel.

It was mentioned that moan programs only consist of single upper case letters; what about the lower case ones? All lower case letters are completely ignored by the moan compiler, this means you can insert them throughout the moan program as comments, to remind you what's going on:

str myMoanProgram2 = "Move everything 50,0,1"

or even:

str myMoanProgram3 = "Marigolds 50,0,1"

Remember, you can only do this with lower case letters, upper case letters are interpreted as commands! When reading a moan program, just ignore all the lowercase letters and you'll see what the moan compiler sees.

Errors in Moan Programs

What happens if you make an error in your moan program? As moan strings are not compiled until your program installs them into a channel, any errors in the program will not be brought to your attention until after your program is running.
This means any moan program errors will cause runtime errors rather than compile errors, runtime errors are not displayed in Hieroglyph, but are reported in TNT Basic's console window.

The most common error with a moan program is when you accidentally capitalise a word when you shouldn't. The capitalising causes the moan compiler to think it's a command. Moan will try its best to report errors to you, but sometimes it underlines the word after an error by mistake. In general, it will point you to roughtly where the error is though.

Using a Channel to Make Something Move

Now that you understand the basics of moan programs, lets install one into a moan channel and get it to move some sprites around. First define your moan program:

str myMoanProgram = "Move 50,0,1"

Now install it into a moan channel (choose any channel id, zero is used here):

set channel program 0,myMoanProgram

Now put a sprite on screen and attach it to the channel:

sprite 1,100,100,1
add sprite to channel 1,0

That's it, now everytime Draw Frame is called sprite 1 will have moved a bit further, try it with:

while not mouse button
draw frame

wend

Try adding more sprites to the channel and see what happens!

Linking Several Moan Commands

You can link moan commands together in sequence, each one will be executed when the previous command finishes. Moan commands are seperated by either a space or a semi-colon ';'.

For example:

str myProg="Move right 100,0,2; Move left -100,0,2"

or

str myProg2="M 100,0,2 M -100,0,2"

Both programs have the same affect as the lower case letters and ; are ignored.

Making Something Animate

Animation is just as easy in moan, just use the 'A'nim command. Its syntax is:

A numloops, (frame,delay), (frame,delay), ....

Where numloops is the number of times to run the entire anim sequence for, -1 meaning forever. It is the same as the high level Animate Sprite command introduced earlier.

Example:

str myprog="A -1,(1,2),(2,2),(3,2)"

That program shows image 1 for 2 frames, image 2 for 2 frames, image 3 for 2 frames and then repeats. Try it with the sprite movement example earlier.

Multi-Channel Moaning

Moan commands run in sequence, if you have an animate command followed by a move command, the move command will not start until the animation is finished. If the animation is set to loop forever then the movement will never start. How do you get around this?

To get moan commands to run in parallel, you must install them onto separate moan channels. You could set one channel up to control sprite animation, and the other to control movement.

When a sprite or viewport is on two different channels, the results of the movement/animation from each channel are combined before the sprite is drawn. If one channel moves everything upwards, and another channel moves everything right, then a sprite that is on both of these channels would move up and right.

Adding Wind To Your Programs

A good use of multi-channel moaning is to have one channel set aside for moving all sprites at once. Try this out on your existing game, you don't need to be using any other moan channels.

set channel program 1,"Move 10000,0,1"
add sprite to channel 0,1
add sprite to channel 1,1
add sprite to channel 2,1
' ... add all your game's sprites ...

Now, you will find that when you play your game, all the sprites drift slowly off the side of the screen! By modifying the program you can produce a simple wind affect in any direction.

NB: A better way of adding wind is to set up a loop using labels, this is covered in the Advanced Moan Tutorial.

Conclusion

This tutorial introduced Moan, TNT Basic's powerful MOvement and ANimation system.

Moan has two levels that you can work at. The first consists of high level commands that can be used to move or animate individual sprites or viewports easily.

The second set is centred around the use of programmable moan channels, which can be used to move/animate several viewports or sprites at once.

You should now continue your moaning with the Advanced Moan Tutorial.


Table of contents