AK's ManiaScript Tutorial/Reference

[krial057]

NOTICE: THIS DOCUMETATION IS OUTDATED AND NOT COMPLETE. FOR A NEWER AND BETTER ONE, VIEW THE ONE OF konte: http://forum.maniaplanet.com/viewtopic.php?f=279&t=4851
AK's ManiaScript Tutorial
Hey, I wrote a small Tutorial about ManiaScript. I hope you enjoy. (If you find any grammatical or other sorts of errors, please report them (There will be a lot xD)

Where is ManiaScript used?
At the moment, ManiaScripts are mainly used for:
-ManiaLinks
-Track Editor Plugins
-Maniatracker
What is possible with ManiaScript?
Unlike a lot of people thought, ManiaScript is at the moment not able to change car physics or handle car events.
Here is the list with the possibilities for the different categories:
For the ManiaLinks:
• You can edit ManiaLink Elements (change position, show, hide, change Text, …)
• You can handle some Input Events (Mouse click, keyboard events, …)
For the Editor Plugin:
• You can create ManiaLink Elements, which are then layered over the editor. (this results, that also all the possibilities of Manialink functions are available)
• You can do nearly everything that is possible in the Editor too (Placing Blocks, enter a specific mode (testmode, …). However it is not possible to do things that are also not possible in the Editor(like placing Blocks at the same position, remove pillars, …)
For the ManiaTracker:
• You can change the camera position and rotation
• … (Don’t know much information)
The programming language
It appears that ManiaScript is a complete new programming language. Because of this, here are some informations I found out: (Basic programming skills needed)
Structure of a program:
Like in C, the program starts from the main function (However the main function has no return type, not even Void oO, it’s like a constructor in C++ or Java). Program Example:

Code: Select all

#RequireContext CGameCtnEditorPluginScriptHandler
main()
{
	DialogDoMessage("Hello world");
}

If you don’t declare any function, you don’t need the main function. Example:

Code: Select all

#RequireContext CGameCtnEditorPluginScriptHandler
DialogDoMessage("Hello world");

However this will NOTwork:

Code: Select all

#RequireContext CGameCtnEditorPluginScriptHandler
Void sayHello()
{
	DialogDoMessage("Hello world");
}
sayHello();

You may notice that every statement ends with a semicolon character (;).
The language is also case sensitive. This means, that "Dialogdomessage" is not the same as "DialogDoMessage".
The comments are the same as in C: /* comment */ for multiple line comments and // for single line comments.
Variables and Data Types:

Fundamental data types
Here a list of the fundamental data types:
Void
Boolean:
True or False
Integer
…,-5,-4,-3,-2,-1,0,1,2,3,4,5,…
Real
-4.325 0.0 0.1
Notice: You have to set a point, even if you have 1, you have to enter 1.0 or 1. . If you want to convert a integer to a real, you could write for example: 1.*Map.Size.X
Text
“blabla1” "\"Hello\nworld\""
Class <- ?
Vec2
object with 2 real numbers: <5.0,10.3>, <-10.0,10.3>, …
The members can be accessed with vector.X and vector.Y, or like an array vector[0] vector[1]
Vec3
Same as Vec2, just with 3 real numbers.: <5.0,10.3,10.3>, <-10.0,10.3,-5.>, …
The members can be accessed with vector2.X and vector2.Y and vector2.Z , or like an array vector[0] vector[1] vector[2]
Int3
Same as Vec3, just with integers: <5,10,10>, <-10,10,-5>, …
Iso4

Compound Data Types
Arrays
An array is formed like in php: Every element has a key and a value:

Code: Select all

declare Text[Text] Colors = ["Red1"=>"Diamond", "Red2"=>"Heart", "Black1"=>"Spade", " Black2"=>"Club"];
DialogDoMessage(Colors["Red2"]);

You can access element values by specifying the key.: Array[key]=value.
The declaration is like the following:
declare valueType[keyType] ArrayName = [key1=>value1, key2=>value2];
Yet another example:

Code: Select all

declare Text[Integer] Colors = [0=>"Diamond", 1=>"Heart", 2=>"Spade", 3=>"Club"];
DialogDoMessage(Colors[2]);

Variable declarations
Declarations always begin with the “declare” keyword.
You can declare variables in 2 ways. If you don’t want to give the variable a value at declaration, you have to define the data type at declaration. If you give the variable immediately a value, you don’t need to precise the data type.
Example:

Code: Select all

declare Integer varInteger; //Works
declare Integer varInteger=5; //Works
declare varInteger=5; //Works
declare varIntger; //DOES NOT WORK!

Global Variables
You can’t declare global variables outside of the main() function, like in C. If you want to declare a global variable, you have to enter the keywords “for ManialinkPage” after the declaration:

Code: Select all

#RequireContext CGameCtnEditorPluginScriptHandler
Void sayHello()
{
   declare Text a for ManialinkPage;
   DialogDoMessage(a);
}
main()
{
   declare Text a for ManialinkPage;
   a="Hello world";
   sayHello ();
}

Notice: You have to declare the variable in every function where you want to use it.

Constant Variables
You can declare constants with the following syntax:
#Const nameOfTheConstant Value

Example:
#Const Pi 3.1415
...
x=x*Pi;

Operators
Arithmetic operators ( +, -, *, /, % )
+addition
-subtraction
*multiplication
/division
%modulo

Code: Select all

declare a=3+5; //a=8
a=7%5 //a=2

Compound assignment (+=, -=, *=, /=,^=)
Notice: ^= only works, for text. It will append text to another text.
declare a=0;
a+=1; //a=1
a+=3; //a=4
a*=3;//a=12
a%=5;//a=2

Increase and decrease (++, --)
NOT POSSIBLE WITH MANIASCRIPT ATM!

Control Structures
Conditional structure
The If and else conditional
The if and else structure is the same as in C:

Code: Select all

if (x >0)
{
	Sign=”Positive”;
}
else if (x<0)
{
	
	Sign=”Negative”;
}
else
	Sign=”Null”

Notice: If there is only a single statement to be executed, you don’t need to put the braces { }.
Iteration structures (loops)
The while-loop
The while loop is the same as in C:

Code: Select all

while (x < 10)
{
	x+=1;
}

The for-loop
The for-loop has the following stucture:

Code: Select all

for(counter vaiable, from, to)
{
	Statement;
	...
}

Notice: The counter variable gets declared by ManiaScript. So you don’t need to declare the variable:

Code: Select all

//declare Integer i; -> Not needed
for(i, -5, 10)
{
	x+=i;
}

The selective structure: switch
The switch structure is nearly the same as in C. Unlike, than in C, the program goes immediately after a group of statements to the end of the switch. So, you don’t need to enter a break; after every group of statements.

Code: Select all

switch (expression)
{
  case constant1:
     group of statements 1;
  case constant2:
     group of statements 2;
  .
  .
  .
  default:
     default group of statements
}

More coming soon

[krial057]

Maniascript in Manialinks
I won't write a Tutorial about how to use Maniascript in Manialinks, because there is already a very good one:
ManiaLinks Tutorial
Maniascript in ManiaLinks

Use Maniascript for Editor Plugins
(coming soon...)

[krial057]

(reserved)

[kalimerre]

Nice tutorial, stick it ! I wait other parts

[krial057]

Thank you, this motivates me
A small update:
added Arrays, Global Varaibles and Control structures (While, for, switch, if)

I'll probably go next deeper inside the editorplugin scripts. Like how Coordinations are handled, the main functions, ...

[TGYoshi]

Mmmm wasting time on this while Nadeo is writing it as well .
However, useful if you want to get started right now.

[Boss-Bravo]

Nice Tutorial, Thanks

[SurferIX]

Hi!
Very nice tutorial, and it's very useful (it's missing from your links about ManiaLinks, so keep on the good work ).

You forgot one thing, it's not :

Code: Select all

for(counter vaiable, from, to)

But:

Code: Select all

for(counter vaiable, from, to[, step])

The step variable is optional but exists .

[dePaljas]

Thanks a lot. I suppose the nearly in:

You can do nearly everything that is possible in the Editor too

includes placing 'items' (editor's F4, or 'objects' if you will)..

[Florenzius]

Nope, i don't think so