The Multi-Platform Language for Calculators Tutorial

= 0 = Table of contents
1: Introduction
2: Hardware and Compatibility
3: Programming Standards
4: Beginning MLC
5: Drawing
6: Math
7: Variables
8: A Simple Program
9: Sprites In Detail
10: A Sample Program
11: Conclusion

= 1 = [Introduction]
By now you should have already read the MLC Readme and the individual documentation for your model of calculator,
so that will not be covered here. This tutorial will take you through the steps of making a simple MLC game and will 
introduce to you some of the more advanced concepts behind MLC (though, at the moment with MLC being so new, 
many tricks and techniques will undoubtedly be discovered over time that we never imagined).

= 2 = [Hardware and Compatibility]
Before you even begin programming there is something that you need to know and use when programming MLC. Since 
MLC is by definition a multi-platform language (think Java) your games will be run on calculators much different from your
own, for instance, if you have a Casio AFX then your screen size is 128x64, but if you have a ti-83 your screen size is 
96x64. Surely you see a problem here... The solution is for the programmer to purposefully not use the area of the screen 
not visible on other calcs for anything essential for gameplay, I suggest using if for displaying scores, stats, etc. anything that
is not required to play (and these things should also appear somewhere else, like a pause menu or when you die).

Also, on some calcs there are restrictions on the amount of memory MLC can use, etc... so in order to keep your game 
compatible stay within these guidelines:
1: 9.2 KB MAX file size
2: Less than 55 variables (of any type)
3: Less than 60 functions

In almost all cases this simply wont be a problem. but keep it in mind.

You may be thinking "Why should I make my games compatible at the cost of screen space?", well the answer is so that 
others with calcs with bigger screens than yours will do the same for you, and of course so that as many people as possible 
will be able to play your game.  I know of course than in some cases this just wont be possible, and that's ok, just try your 
best and it will be fine.

= 3 = [Programming Standards]
Programming standards are rules that all programmers follow for a language in order to get the most out of that language, 
the rules are not enforced so that they can be broken as needed, but to break them without good reason is considered to 
be a bad practice. Here are the programming standards for MLC, you should adhere to them as much as possible.

1: Preserve Compatibility
2: Use the MAIN function to call the functions that run you program, and not as a major part of your program.
3: Make functions as re-usable as possible and as self contained as possible

= 4 = [Beginning MLC]
If you know a bit of C going into MLC then you should have very little problems, but if MLC is your first language or if 
your switching from BASIC then you should pay close attention.

- MLC structure -

there are 3 special commands/areas in any MLC program to witch different rules apply than anything else in MLC, here they are:

MLC:

"MLC:" must be placed at the top of all MLC programs, this is done so that the MLC interpreter can quickly tell if the 
program is an MLC program and should be listed in the program list.

#DATA
...
#DEND

The Data section is a special area that is looked at before the game starts, it will contain all your Bitmaps and possibly some 
other data your program might need. this can be placed anywhere in your code.

#FNCT MAIN

the MAIN function is the place where your game will start, no matter where it is in the program, your game cannot be run 
without a MAIN function.

= 5 = [Drawing]
If you've ever used BASIC you know what a huge pain it is to draw a complex screen, with each line showing up one at a 
time... well that is no longer a problem with MLC :)

MLC uses double buffering, witch essentially means that it uses two screens, one is the screen which is displayed visibly on 
your calc, and the other is a where all of MLC's drawing commands takes place. when your done drawing you can force the
invisible screen to be copied to the visible one, making everything appear at once.

Example:

MLC:
#FNCT MAIN
#CLRS
#RECT .0 .0 .10 .10 .3 .1
#RECT .10 .10 .20 .20 .3 .1
#RECT .20 .20 .30 .30 .3 .1
#RECT .30 .30 .40 .40 .3 .1
#RECT .40 .40 .50 .50 .3 .1
#RECT .50 .50 .60 .60 .3 .1
#DRAW
#PAUS
#FEND

in the above example none of the rectangles are shown until the #DRAW command is executed, nor is the screen cleared by 
#CLRS (#CLRS actually clears the invisible screen, not the visible one)

in addition to the double buffering remember that MLC uses 4 levels of color, which is shown in #RECT's 5th and 6th 
argument.  .0 = white and .3 is black and .4 is invert (and in the case of RECT .5 is No Fill/Transparent)

Drawing is a very important part of MLC and you should familiarize yourself with it and all its commands before proceeding.

= 6 = [Math]
Math operations in MLC are considerably different than in BASIC, for one thing there is no order of operations.  Also, all 
numbers in MLC are integers, so 1.98 in MLC is just 1 (or actually .1 in MLC syntax).

Example:
in MLC:
.1+.2*.3=.9
with an order of operations it would be:
.1+.2*.3=.7

keep that in mind when your doing any mathematical operations.

Math in MLC is stripped down to its bare essentials, since MLC is a gaming language there shouldn't be a great need for 
advanced mathematical operations, and if there are you may need to find a workaround.  Also note (if you haven't already) 
that all numbers in MLC must be preceded by a . (period).

= 7 = [Variables]
Ok, to start off with im going to assume that you know what a variable is, if you don't then you should probably play around 
with BASIC for a while before starting on MLC.

There  are 6 types of variables in MLC, and the all have their own quirks and features:

1: Integers
2: Strings
3: Bitmaps
4: Sprites
5: Arrays
6: Pointers (not yet supported)

All variables have their own single character type prefix, as listed below:

1: Integers - These variables contain numbers on witch you can perform mathematical operations.
Prefix: %
Example:
%INT=.1

2: Strings - These contain an array of characters, you can use strings for various operations.
Prefix: $
Example:
$STR="TEST"

3: Bitmaps - These aren't exactly true variables, they are merely names for bitmaps defined in the data section, you cannot 
change them.
Prefix: [
Example:
#BITM [BMP 8
0000000000000000
0000000000000000
FFFFFFFFFFFFFFFF

4: Sprites - the most diverse variable type, sprites actually contain a bitmap and several ints.
Prefix: ^
Example:
#SPRT ^SPR [BMP
^SPR.X=.10
^SPR.Y=.10
^SPR.DX=.0
^SPR.DY=.0
^SPR.VX=.0
^SPR.VY=.0

5: Arrays - Arrays can currently only contain ints but in the future I hope to expand them to at least strings and pointers.
Prefix: @
Example:
#ARRY @LIST .5
@LIST(.0)=.1
@LIST(.1)=.2
@LIST(.2)=.3
@LIST(.3)=.4
@LIST(.4)=.5

= 8 = [A Simple Program]
Ok, now that you know the basics we're going to go through the steps of making a MLC program, this program will be 
called "STARS" and will give you a good idea of what MLC can do.

Comments are shown with //, they are not to be included in the actual program.

//Begin your program with the required syntax
MLC:
#FNCT MAIN			//the program will start here
%STAR=.100				//we want to have 100 stars on the screen
%SCRN=.94				//im using this variable so that I can change the width of the screen easily
#FRUN STARS			//calls the function STARS
#FRUN LOOP			//calls the function LOOP
#FEND				//ends the Main function, in keeping with MLC standards we've put as little as possible in here.

#FNCT LOOP			//the start of function LOOP
#SHFT .0 .1 .-1			//shift the screen down one pixel, looping all pixels that go off the screen to the opposite side.
#DRAW				//show the changes to the screen
#FGOB				//go to the beginning of the function
#FEND				//end of function LOOP, in this case it is never reached

#FNCT STARS			//the start of function STARS
#RNDM .0 %SCRN %X		//finds a random X position anywhere on the screen.
#RNDM .0 .64 %Y			//finds a random Y position anywhere on the screen.
#PIXL %X %Y .3			//places a black pixel at X,Y
%STAR=%STAR-.1			//subtracts 1 from STAR
#IIFF %STAR!.0			//checks to see if STAR is not equal to 0
#FGOB				//if STAR is not 0 then the function repeats
#FEND				//ends the function and the control returns to MAIN

pretty simple huh?

= 9 = [Sprites In Detail]
Sprites a LOT different from other variable, and not just because they are actually several grouped vars.  For instance, sprites could be 
told to move on their own, and they have limited floating point 
operations,  here's a point by point detail of what a sprites properties do:

BMP: The Bitmap the sprite is using
X : the X coordinate of the Sprite on the screen
Y : the Y coordinate of the Sprite on the screen
DX : used to simulate floating point operations, DX represents a value between 100 and -100, you can increment or decrement it as 
much as you want and every time it goes beyond its bounds X will be incremented or decremented.
DY : used to simulate floating point operations, DY represents a value between 100 and -100, you can increment or decrement it as 
much as you want and every time it goes beyond its bounds Y will be incremented or decremented.
VX : is the velocity of the sprite horizontally, every time #DISP (name of sprite) is executed the sprite will be moved that much 
horizontally (using X and DX) before being displayed.
VY : is the velocity of the sprite vertically, every time #DISP (name of sprite) is executed the sprite will be moved that much vertically 
(using Y and DY) before being displayed.

so for instance, a bullet could be given a VY value of -100 and it would move 1 pixel upwards each time it was shown.

the BMP property could potentially be used to animate a sprite, if you switch out its BMP every once and a while you can change the 
look of the sprite without having to make a new one, etc...

DX and DY are intended to let you move a sprite slowly across the screen, not 1 pixel at a time, but up to 1/100th of a pixel at a time, 
allowing for acceleration and smoother transitioning.

if you want, you can easily ignore all the sprite properties accept .X and .Y with no ill effect.

= 10 = [A Sample Program]
By now I hope you have a better understanding of how MLC works, this program is an expanded version of the above STARS program, 
using bitmaps and user input:

//Begin your program with the required syntax
MLC:
#FNCT MAIN			//the program will start here
%STAR=.50				//we want to have 50 stars on the screen
%SCRN=.94				//im using this variable so that I can change the width of the screen easily
#FRUN STARS			//calls the function STARS
#FRUN LOOP			//calls the function LOOP
#FEND				//ends the Main function, in keeping with MLC standards we've put as little as possible in here.

#FNCT LOOP			//the start of function LOOP
#SHFT .0 .1 .-1			//shift the screen down one pixel, looping all pixels that go off the screen to the opposite side.
#DRAW				//show the changes to the screen
#GKEY .24 %KLF			//detect if the left arrow key is pressed
#GKEY .26 %KRG			//detect if the right arrow key is pressed
#IIFF %KLF=.1			//if left is pressed...
#SHFT .-1 .0 .-1			//scroll the screen 1 pixel left
#IIFF %KRG=.1			//if right is pressed...
#SHFT .1 .0 .-1			//scroll the screen 1 pixel right
#FGOB				//go to the beginning of the function
#FEND				//end of function LOOP, in this case it is never reached

#FNCT STARS			//the start of function STARS
#RNDM .0 %SCRN %X		//finds a random X position anywhere on the screen.
#RNDM .0 .64 %Y			//finds a random Y position anywhere on the screen.
#DBMP [DOT %X %Y		//places the bitmap DOT at X,Y
%STAR=%STAR-.1			//subtracts 1 from STAR
#IIFF %STAR!.0			//checks to see if STAR is not equal to 0
#FGOB				//if STAR is not 0 then the function repeats
#FEND				//ends the function and the control returns to MAIN

#DATA				//the data section contains all the bitmaps your program will use
#BITM [DOT 8			//creates the bitmap DOT with a size of 8x8
40E0400000000000			//bitmap data
40A0400000000000			//bitmap data
BF1FBFFFFFFFFFFF		//bitmap data
#DEND				//end of the data section

= 11 = [Conclusion]
The above is certainly not all MLC can do, not even close in fact, but if you read the readme and the other documentation you 
should be fine, after all, experimentation is the best way to learn.  I'll probably be adding more to this as time goes on and some 
of the problems people are having come to my attention. if you have a problem, feel free to ask me, my e-mail is 
crimsoncasio@casiocalc.org and I can also be reached through posts on any number of forums.  if your question is a good one 
I might even work it into the tutorial ;)

I hope you enjoy working with MLC ;)

CrimsonCasio, Epic Programming Studios.

