View source for Tutorial - Basic Scripting

As scripting seems to be something difficult for most people to even start utilizing i thought it might be a good idea to write a short tutorial about the issue. Basic understanding of Lua or practically any other scripting or coding language is helpful but is not actually required as there is an abundance of well written guides to scripting in the internet. Some of these have been gathered to the links section in the [[Scripting.tbl]] page. Especially the [http://lua-users.org/wiki/TutorialDirectory Tutorial Directory] in [http://lua-users.org/wiki/ Lua-Users wiki] is very usefull in learning to use Lua scripting with FreeSpace Open.

==Very Basics==

First take a good look at the [[Scripting.tbl]] page. From there you can see the hooks you can use for scripting. In addition to these there are few additional in [[Weapons.tbl]], namely '''$Collide Ship:''' and '''$Collide Weapon:''' but these arent supported by the 3.6.9 code branch.
<br><br>
All the hooks require square brackets after them into where the actual script is inserted.
<br><br>
'''Scripting.tbl'''
<pre>$Simulation:

[
...
]</pre>

Commenting rest of the line away is done with double dashes, like so '''''&#x2013; &#x2013;'''''.

==First Example==

Lets start with creating a small script that writes text to the screen. That is the very old '''Hello, World''' example. To achieve that effect we first need to create a scripting.tbl file and then also to create the needed sections. In order to achieve that goal first create a plain text document using (for example) notepad or similar non-formatting text editor.
*Name the empty text file as scripting.tbl
*Move it to '''''data/tables''''' directory
*Add the needed '''#Global Hooks''' and '''#End''' to the table.
<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

#End</pre>

===Draw Text to Screen===

To write text (or rather a text string) to the screen we need to use certain Lua functions. The needed function '''''drawString()''''' is located in the '''Graphics''' library (abbreviated '''gr'''), [http://fs2source.warpcore.org/temp/scripting.html#Graphics Graphic library in Scripting.html]. To use that function we first need to create a '''''$HUD:''''' hook where we can place it. The function also needs some arguments and we ought to give it the required arguments. First we need the string ''''Hello, World'''' followed by the location coordinates (pixels) where the game is instructed to draw the string. Also note that as the function is from the '''Graphics''' library we need to add '''''gr.''''' before the function (that is to write gr.drawString instead of just drawString).
<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

$HUD:

[

--Draws 'Hello, World' to the HUD
gr.drawString('Hello, World', 100, 100)

]

#End</pre>

===Drawing in Different Locations===

In the first example we draw the string so that it started from the position 100, 100. Now lets draw the same string also elsewhere on the screen.
<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

$HUD:

[

gr.drawString('Hello, World', 100, 100)
gr.drawString('Hello, World', 130, 160)
gr.drawString('Hello, World', 160, 220)
gr.drawString('Hello, World', 190, 280)

]

#End</pre>

===Drawing in Different Colors===

Now that we have several text strings drawn to the screen we might want to try to alter their colors. For this we need another function from the '''Graphics''' library, '''''setColor()''''' that accepts four arguments. These are basic RGBA values of which the A (alpha or transparency) is optional.
<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

$HUD:

[

gr.setColor(0, 255, 0)
gr.drawString('Hello, World', 100, 100)
gr.setColor(255, 0, 0)
gr.drawString('Hello, World', 130, 160)
gr.setColor(0, 0, 255)
gr.drawString('Hello, World', 160, 220)
gr.setColor(255, 255, 255, 128)
gr.drawString('Hello, World', 190, 280)

]

#End</pre>
<br><br>
NOTE: Some of the functions (mainly from graphics library) are specific to certain global hooks. That is if you try to use them in a wrong hook the script wont do anything. Game doesnt actually warn about this so you may have to figure this one out on simple trial-and-error method.

==Drawing Particles==

Next we will try drawing particles to the screen. Again we need the scripting.tbl for this
<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

#End</pre>

===Scripted Particles===

To draw (or render) particles to the screen we need to use other Lua functions than what we used in the text example. The required function is '''''createParticle()''''' from '''Testing''' library (abbreviated '''ts.''') and to place it into the '''$Simulation:''' hook. This function requires several arguments but for this example we only need to use few of them. As can be seen from the [http://fs2source.warpcore.org/temp/scripting.html#Testing scripting.html] the function uses vector objects for the first two arguments followed by two numerical ones and several others. 
<br><br>
This means however that before we can actually start using the function we need to get some vector objects. Function to create these objects can be found from '''Math''' (abbreviated '''ma.''') library ('''''newVector()'''''). We also need to assign a type for the particle, for this purpose the 'Debug' is good enough. Other values can be set to be what ever we wish them to be. Its good to remember though that the script is executed every frame.
<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

$Simulation:

[

--1st create a new vector object and assign it as variable
nullvec = ma.newVector(0,0,0)

--2nd draw the particle
ts.createParticle(nullvec,nullvec,1,20,'Debug')

]

#End</pre>

===Attaching Bitmaps to Particles===

Now that we have managed to draw a particle to the screen we might want to start modifying it. Lets begin with changing the 'Debug' particle into something else. Lets select for example '''laserglow03''' for this example. For this we first need to load the graphics into a texture handle, and that can be done with '''''loadTexture''''' function from the '''Graphics''' library. Then we must change the particle script a bit by adding several new (optional) arguments to it. This is done by first changing the earlier 'Debug' into 'Bitmap' followed by ''', -1, false''' and finally by the texture.

<br><br>
'''Scripting.tbl'''
<pre>#Global Hooks

$Simulation:

[

nullvec = ma.newVector(0,0,0)

--load a new graphic
particletexture = gr.loadTexture('laserglow03')

ts.createParticle(nullvec,nullvec,1,20,'Bitmap', -1, false, particletexture)

]

#End</pre>

==Using Statements==


==Drawing Scripted Weapon Effect==