Z E P H N I
- ALL ABOUT LUA

EXPLAINING LUA

Lua is a language used for scripting, you can find information for the language
on the Lua website here http://www.lua.org/
This article is going to explain how we can use Lua with MMF, but why would we want
to?

Multimedia Fusion is a fantastic tool for programmers and non programmers alike, from
making a simple "bat and ball" game to complicated programmes or games that can
be very usefull or fun to play! If you can think of it (within reason) you can make
it!
Also, there is a million and one different ways of codeing somthing, we all have
our different ways of codeing, because we find it easiest to understand that way.

Lua can help us immensely when making our games, i wouldnt suggest it necessarily
for a "bat and ball" game, but you'll see how it can be extreamly usefull with
more complicated games or programmes. One of the main reasons you might want to
use Lua is for how well you can write a script for your game, and write out your
script that has functions that get called in MMF, so they can be called whenever you
need them, without haveing to code each individual "event" that happens in your
game over and over.
If you wanted a character to speak in your game, have a face to show the character,
then walk over to the right of the screen, and then bring you a weapon, and give
it to you, and then walk out the door.. And then the screen fades out, you hear
a noise, then it fades in and you are somewhere else... It would be quite frustraiting
to code story parts like that in your game, with lua, you could just create a
function for each event, and then use it again whenever you please in the future!
Also Lua can handle IF statements and much more programming elements to make
your codeing as easy as possible.
I will put a quick little example file you can download to try and get an idea
of how it works if you still don't get it at the end of my blabbering!


WRITING YOUR MAIN FUNCTIONS IN LUA

Firstly make sure you have the Lua extension, i think it comes with MMF2, but
if not try to download it from a MMF2 extension site, im sure you have done
that hundreds of times! I am useing the Lua extension, not the Lua+ one.
Alough it should be the same, i don't actualy know i havent used it.

Now in the same folder as your game or appdir$+"\folder\..." make a text file
and name it "data.lua" before the lua file extension name you can call it what
you want, but i'm just calling it data to keep it simple.

In here you will need to write every function you want to use in your game,
and when i say "write the function" all you have to do is choose the name
of the function and use a little statement that returns that function to MMF.
And then with in a function you can also call other functions you have written.

ok so before you get to confused lets just get on with making our tutorial game.

Now in that file before you start writeing your functions we just need to type
out a couple of things, i'll explain it as i go along. Type:

script = coroutine.create(runscript)

Just like a normal language you can create variables, so we created a variable
named script (you can call it what you want but script makes sence) and "script"
holds a value that is assigned on the right hand side of the = operator.
When we create our individual scripts for our game they are going to be all in
their own individual .lua files, so we need to run it as a coroutine with
our main data.lua file. So i think you can understand the coroutine.create() part!
Don't worry if you still don't understand, all will become clear i promise!

Ok now we are going to type a little more in our data.lua file, go down a line or two
and type:

function pause()
coroutine.yeild(script);
end

function resume()
coroutine.resume(script);
end

Now we have created two functions, by their name i think you can see what they do, but
lets go through it.
we start with "function", this is just telling Lua we want to define a function.
Then seperated with a space we write the name of our function, this can be anything, but its
obviously best to give it a name that makes sence.
Then we follow with a "()" left and right bracket, this is where we would usualy put our
parameters, but this function doesnt take any functions, it does its job, and then ends.
Now we have an internal lua function, that is "coroutine.yeild()", and in the parameter feild
we write the name of the variable (coroutine) that we created. This simply pauses or "yeilds"
our coroutine script.
The ";" at the end of the line isn't needed, but if you are in the habbit with languages like
C# then it's no problem puting it at the end of a line.
Then simply enough "end", ends the deffinition of the function.

Now i don't think i need to explain the "resume" function, you should understand it now,
all we have done is created a different function with a different name, and given it a internal
function to resume a coroutine script.

So now we have done that we can write our functions in the data.lua, im just going to show you
quickly how to return the function to MMF. We will make a function that quits our game, Type:

function quit()
DoCall("quit");
end

This "Docall" part takes parameters, and returns them to MMF, the first one is a string and is
the word that MMF will recognise when a Lua function is called, we will learn more about that soon.
If we wanted it to take more parameters, say if we wanted to move a player to a different
X and Y position, we could write a function like this:

function playerNewXY(newX,newY)
DoCall("playerNewXY",newX,newY)
end

Infact, write that out.. but remember to seperate your functions by a line or two so its easy
to read them all.

Ok so now our data.lua file should look something like this:

\\data.lua\\\\\\\\\\\\\\\\\\\\\\\\\

script = coroutine.create(runscript)

function resume()
coroutine.resume(script)
end

function pause()
coroutine.yield(script)
end


function quit()
DoCall("quit");
end

function playerNewXY(newX,newY)
DoCall("playerNewXY",newX,newY);
end

///////////////////////////////////


MMF ANSWERS TO YOUR FUNCTIONS!

Now we actualy get to make our functions do something! This is very simple.
First we have to run our data script, go in to your game and make a new condition:

+ run this event once
- LUA object: run script "function runscript()end"
- LUA object: run file appdir$+"data.lua"
- Lua object: call function "resume" with "" parameters and return 0

So we have first run a script so we can link up our "runscript" coroutine.
We deffine the function runscript, and end it straight away. BY THE WAY! If we
where going to write everything in one file, and just call our functions within MMF then
this wouldnt be needed, nor would we need to create the functions or the variables to do with
coroutines in our data.lua file, but if you just play along you will see why this is the best
way.
We then run the file we created called data.lua, this is where we have all our functions
deffined.

Now, that file is open we can call functions either from MMF or another file, first we will
do it in MMF. Make a new condition:

+ upon pressing "Escape"
- Lua object: call function "quit" with "" parameters and return 0

This now finds the function we created in the data.lua file and does whatever it says, all
we have it do is return itself back to MMF, so now we need to tell MMF what to do when it
recieves that specific function name, new condition:

+ Lua object: On function "quit"
- End the application

This is obvious. when MMF sees a function is called named "quit", we end the game.
Run it to see if it works!

=O HAVING TROUBLE??
If it doesn't quit, then check that your event ordering is correct, you have to make sure that
you run the script "function runscript()end" before running the data.lua file.
The only other mistake would be a typo, or that you havent got your data.lua file in the correct
location.

WORKED?! Great! now you are ready to start writing scripts, lets take a look at how to do that
now.


WRITING YOUR LUA SCRIPTS

Ok, so this is mainly where we have the fun, we will start with something simple, we will just
write a script that quits the game, i know we done that already by calling a function,
but it will get you used to writeing scripts yourself, so just follow along like a good lil'
boy/girl/whatever.
So make a new lua file, i suggest makeing a new folder after your MMF game location because
you might want to write a few.
Call it "example.lua" and in it type:

function runscript()

quit();

end

And save the file where we said. Now back to MMF, we need a condition that triggers this script.
Maybe if it was an RPG game, you would go up to a person and try to talk with them, you would
then trigger the script that you want to, and it might contain a function like "msg" where
they talk to you, or "giveItem" and so on.
But for now just make a condition:

+ Run this event once
- Lua object: run file appdir$+"scripts\example.lua"
- Lua object: run file appdir$+"data.lua"
- Lua object: call function "resume" with "" parameters and return 0

This runs our example.lua file, and then runs it as a coroutine with the data.lua file that
actualy calls the function to MMF if it can find it. And then resumes the script.
This should make sence to you by now, if not, go back a bit and try to understand, or of
course leave a message and i'll do my best to help.
Your script file wont run if you put a function in there that you havent created yet in
the data.lua file, i just learnt that so it could save you some hassle!

When it runs the example.lua file it runs from top to bottom, but all we have typed is quit()
so there is nothing else for it to do, now lets just try to create a couple more functions
and learn a little bit more about returning values and strings to MMF.

RETURNING VALUES AND STRINGS

Ok, now lets get a bit deeper into why lua can be usefull!
In your example.lua file, start from scratch and type:

function runscript()

say("Hello how are you");
pause();
playerNewXY(50,50);
say("Lua told me to move the player, so i did!");
pause();
say("I'm going to quit now...");
pause();
quit();

end

This is just a list of functions that we are going to execute in MMF, remember you can
also deffine variables in lua aswell, but i will talk about that later.
So you may have noticed we used a function we havent made in our data.lua file yet, so lets
go to that and add the function:

function say(text)
DoCall("say",text)
end

Hopefully you understand about makeing functions now, if not you may want to go back over parts
of the tutorial.

Back to MMF!
Make a text object for your level, and a active object aswell, place them on the screen so you
can see them and make the text object a bit bigger so it can take longer sentances!
Go to the event editor and make a condition:

+ LUA object: On function "say"
- Set string to LuaStrParam( "Lua object", 0)

This gets the returned string from our function "say", where the 0 represents the first parameter,
as our function only takes one parameter we just choose the first one which is 0 because it is
0 based.

The next line in our example.lua file calls a pause() function, so the script doesnt just run
to the end without us seeing what it has done.
So make a condition:

+ On any key pressed
- Lua object: call function "resume" with "parameters" and return 0

Now, when you press any key, it will continue reading from the script until it ends, or another
pause function is called.
Finally we need to handle the function playerNewXY so we can move our player to its new X,Y
coordinates. Lets make a new condition:

+ Lua object: On function "playerNewXY"
- set player x position to LuaValParam( "Lua object", 0)
- set player y position to LuaValParam( "Lua object", 1)

This is similar to our string function, except we are returning the value rather than a string,
also we have to values returned (the X and the Y values) so we retrieve the first one by setting
the parrameter index to 0, and the second by setting it to 1.

After this one more key press is needed and then it calls our quit function, and the application
ends!

Run your game and see what happens! You can now change what is to happen in your example.lua
file, try makeing some of your own functions and get used to useing lua!

There is more to explain, but i think this is enough for now, if people want to learn more
i would be happy to write more indepth in to useing lua, because there is still alot more you
could do with it.

You can download my example file here: http://www.box.net/shared/u4pirt062n

I hope this has helped you! let me know if you need any more help, or if you would like me to write a part 2 article on lua so you can learn more!?