https://wiki.hard-light.org/api.php?action=feedcontributions&feedformat=atom&user=72.194.192.77FreeSpace Wiki - User contributions [en]2026-11-15T12:01:07ZUser contributionsMediaWiki 1.43.9https://wiki.hard-light.org/index.php?title=Scripting_API&diff=4644Scripting API2006-02-13T07:36:41Z<p>72.194.192.77: </p>
<hr />
<div>The FS2_Open scripting API is intended to be as cross-platform and as language non-specific as possible. However, it is generally assumed that the most popular language will be Lua.<br />
<br />
==Part One: Basic API and Scripting Hooks ==<br />
===Things To Know===<br />
;Script_system:This object abstracts a scripting session. It is generally used to allow for easy construction/destruction of whatever is necessary to initialize scripting system objects, and make sure that the right language session data is passed. Its constructor takes one argument, the name of the scripting session (for easy debugging)<br />
;Script_system.CreateLuaSession(libraries):Initializes a Lua session. Until this is called, you will not be able to use Lua at all and fs2_open should ignore code chunks that use it.<br />
;Script_system.ParseChunk(debugname):Parses a 'code chunk'. These are snippets of code encapsulated by symbols such as square brackets or parentheses. It stores a handle to the parsed script in memory (Probably bytecode).<br />
:script_system.RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk<br />
====Example====<br />
This snippet of code (using FS2_Open functions) will parse a file that has scripting after each "$Global:" variable identifier. After all the scripting has been parsed, it will evaluate every hook, once.<br />
//Create script system object<br />
script_system Script_system;<br />
<br />
//Create array that holds a series of scripting hooks<br />
std::vector<script_hook> Script_globalhooks;<br />
<br />
//Initialize Lua<br />
Script_system.CreateLuaState(Lua_libraries);<br />
<br />
//Parse file<br />
read_file_text("scripting.tbl");<br />
reset_parse();<br />
while(optional_string("$Global:"))<br />
{<br />
Script_globalhooks.push_back(st->ParseChunk());<br />
}<br />
<br />
//Execute hooks<br />
for(uint i = 0; i < Script_globalhooks.size(); i++)<br />
{<br />
Script_system.RunBytecode(Script_globalhooks[i]);<br />
}<br />
<br />
==Part Two: The Higher-Level Lua Library==<br />
The Lua library is probably what you'll want to be the most familiar with, as it's where you'll edit to add functions, classes, libraries, and variables.<br />
<br />
<br />
===Limitations===<br />
* Lbraries can only contain functions, and not variables or arrays.<br />
* All "arrays" must be an object with an indexer (see LUA_INDEXER define).<br>I was not able to get this working originally, but I've got another idea on how to try this so if you really feel an array class would be best in a given situation, tell me.<br />
<br />
<br />
===General conventions===<br />
For the internal Lua API:<br />
* All internal lua functions are prefixed with lua_<br />
* All Lua library and object variables are prefixed with l_, so "l_Graphics".<br />
* When failure occurs due to a bad type being passed, or a subsystem not being ready, LUA_RETURN_NIL is usually used.<br />
* When failure lies with the content of data, rather than the circumstances or type, LUA_RETURN_FALSE is generally used where appropriate.<br />
<br />
For Scripting:<br />
* All variable names have the form of "EverySomethingIsCapitalized"<br />
* All function names have the form of "doSomethingFast()"<br />
* All object names have the form of "somethingneat"<br />
* All library names are one capitalized word. For more than one word, the same syntax as variables(?)<br />
* All library shortnames are two noncapitalized letters relating to the name. "Sound" -> "sd"<br />
* So far, I've used three-letter noncapitalized variables for globals. But I may decide to switch to the normal variable convention soon, as it's MUCH clearer about what the variable is.<br />
<br />
<br />
===Things To Know===<br />
;lua_lib:Defines a Lua library.<br />
;lua_obj:Defines a Lua object type (userdata).<br />
;LUA_FUNC:Defines a Lua member function. Used with both lua_lib and lua_obj.<br />
;LUA_VAR:Defines a Lua member variable. Only used with lua_obj.<br />
;LUA_INDEXER:Defines Lua activity when brackets are used. Only used with lua_obj.<br />
<br />
Once you invoke any of the above, it's not necessary to do anything else for it to be present in Lua.<br />
<br />
===lua_lib===<br />
lua_lib l_Base("Base", "ba", "Base Freespace 2 functions");<br />
Defines a Lua library, which can contain member functions (But not any kind of variables).<br />
<br />
Probably the simplest and most obvious to work with. The first field is the library name; the second is the shorthand version. The last is merely the description, which is only used for -ouput_scripting<br />
<br />
<br />
===lua_obj===<br />
lua_obj<object_h> l_Ship("ship", "Ship object", &l_Object);<br />
Defines a lua object, via a C++ template. The <> defines what type of C data the object will hold. In general, it's better to pass a handle to Freespace data (such as the ship_info struct) than to try and copy the entire thing. For 'static' data - such as image handles or species indices - a simple <int> with the index of the item will suffice. For perishable data, you may want to store a unique identifier - say, an object's signature. In the above example, I use a helper struct that holds both a pointer to the object, and the object's signature. That way, all I need to do is check that the object at the pointer has the same signature to make sure that the handle is still valid.<br />
<br />
The next two parameters are fairly obvious - the name of the object (becomes the metatable name), and the description in output_scripting.<br />
<br />
The last parameter warrants some explanation - it is the parent of the object. Multiple levels of derived objects aren't supported, and a derived object must have the same type as its parent object, since all of the parent object's functions will generally only support the parent object's data type, and it's just needlessly complicating.<br />
<br />
<br />
===LUA_FUNC===<br />
LUA_FUNC(newVector, l_Math, "[x, y, z]", "Vector object", "Creates a vector object")<br />
One of the two most used of the Big 5. The same tactics used for a LUA_FUNC are virtually the same for LUA_VAR and LUA_INDEXER.<br />
<br />
There are two components to LUA_FUNC. The first is the arguments (above); the second is the actual body.<br />
<br />
The arguments are, the function name (As it will appear in Lua). This is also used internally for the C compiler, so it is not actually a string. The second argument is the library or object that the function is a part of. So, the above example is the "newVector" function of the "Math" library, and would be accessed by calling "Math.newVector()"<br />
<br />
The third, fourth, and fifth arguments are all purely descriptive, but you should always fill them in if applicable to ensure good documentation. The first is the arguments that the function will take; they may be in any form you please, but I have generally used the "required, required, [optional, optional]" form. As you can see, in the example all arguments are optional.<br />
The second argument is the return value. If the function returns different types, you should note it here.<br />
The last argument is the basic description. Because it can be pretty long, I've sometimes split it up across multiple lines.<br />
<br />
Now, for the body of the define:<br />
{<br />
vec3d v3 = vmd_zero_vector;<br />
lua_get_args(L, "|fff", &v3.xyz.x, &v3.xyz.y, &v3.xyz.z);<br />
return lua_set_args(L, "o", l_Vector.Set(v3));<br />
}<br />
'''Defining function variables'''<br />
<br />
In the first line, we create the C vector object that we're going to return, and initialize it to 0 (since all arguments are optional).<br />
<br />
'''Parsing arguments passed to your function in Lua'''<br />
<br />
In the second line, lua_get_args is used to parse the arguments from Lua. This function is big and messy and takes care of all the warnings and errors that may be caused by invalid types and such. The first argument, L, is just the lua state data that must be passed along; ignore it but don't forget it. The second argument is a list of characters that specify the variable types. These characters represent the following C types:<br />
*b - Boolean<br />
*d - Double<br />
*f - Float<br />
*i - Int<br />
*s - String<br />
*x - Fix<br />
*o - lua_obj (See later)<br />
Finally,<br />
*| - Denotes all variables after this as being optional.<br />
<br />
All arguments after the formatting string should be pointers to the variables you want lua_get_args to set. Be careful; compilers will not catch if you use the a boolean where you have specified a double, for example. Optional variables will only be changed if a value is specified.<br />
'''Note:''' If a wrong type is passed to an optional variable of your function, that variable will be skipped, although variables after it may be changed.<br />
'''Note:''' You do pass pointers to (char *), so you end up passing a char **. Lua will take care of all memory concerns; don't try to deallocate the pointer yourself.<br />
<br />
When using the 'o' parameter, you can get objects in one of two ways:<br />
vec3d v3;<br />
vec3d *v3p;<br />
lua_get_args(L, "oo", l_Vector.GetPtr(&v3p), l_Vector.Get(&v3));<br />
"v3p" would be a pointer to the first object's data, while "v3" would merely hold a copy of the data in the second object. Because it's not necessary to allocate or copy as much memory, getting pointers may be faster; but at the same time, you should be careful not to change the data in the pointer unless you really want to, as it will change the actual object's data. '''''When you define a member function, the object will be passed as the first argument'''''. As a result, this lua_get_args call would be suitable for, say, a function that copies the data passed in the argument to the calling object - "vectora:copyData(vectorb)".<br />
<br />
lua_get_args will return the number of arguments parsed, or 0 if the required variables requirement was not met. So when working with required variables (or an object), you should generally use the form:<br />
if(!lua_get_args(...))<br />
return LUA_RETURN_NIL;<br />
The exception being when you want to actually know the number of arguments, in which case you should handle 0 appropriately. (More on LUA_RETURN_NIL later)<br />
<br />
'''Return values'''<br />
<br />
Return values are set via the lua_set_args function, which works pretty much exactly the same as lua_get_args, except in reverse. The differences:<br />
*Actual variables, rather than pointers, are passed.<br />
*Objects use their .Set() function (and there is no SetPtr() function).<br />
*No | character<br />
<br />
Always use "return lua_set_args", or one of the following:<br />
*LUA_RETURN_NIL - Function returns nothing.<br />
*LUA_RETURN_FALSE - Function returns false.<br />
*LUA_RETURN_TRUE - Function returns true.<br />
<br />
Yes, you can have multiple return values. The syntax in Lua is:<br />
a, b = Library.theFunction() --In Lua<br />
<br />
'''Operators'''<br />
<br />
Definitely an advanced topic, which I will write when someone has need for it. These are slightly crazy as you can reverse objects and I don't fully understand what happens when you try to use an operator on two different objects that have different actions defined for that one operator.<br />
<br />
Look at the vector class for what I've done with operators; if you got the LUA_FUNC section, you should be able to understand it. Note that the lua_isnumber() functions take the almighty L, and the argument index to check (Starting from 1).<br />
<br />
Look up the lua_Operators[] array for the full list of operators, as well as a bit of descriptive text.<br />
<br />
<br />
===LUA_VAR===<br />
LUA_VAR(Name, l_Species, "String", "Species name")<br />
Arguments are variable name, object that this variable will be a member of, the type that this variable is, and a brief description of what the variable is.<br />
<br />
Variables defined by fs2_open are functions. This is generally the easiest and fastest way to go about doing things, since Lua is only a part of the much-larger fs2_open base, which cannot be going through the API to get at variables - not without causing massive code rewrites and slowdowns.<br />
<br />
So, if you want an object to have actual data, you'll have to rely on the internal C dataset to do this. See the vector class for a good example.<br />
<br />
'''Actually doing stuff with LUA_VAR'''<br />
<br />
The two big differences with LUA_VAR are the LUA_SETTING_VAR macro, and how lua_get_args is used. Much like with functions, the first argument of lua_get_args will be the object that the variable is a member of. The second argument is optional, and is the value that the variable may be set to.<br />
<br />
Here's the body for the above example, minus some safeguarding to make it easier to read:<br />
char *s = NULL;<br />
int idx;<br />
if(!lua_get_args(L, "o|s", l_Species.Get(&idx), &s))<br />
return LUA_RETURN_NIL;<br />
<br />
if(LUA_SETTING_VAR && s != NULL) {<br />
strncpy(Species_info[idx].species_name, s, sizeof(Species_info[idx].species_name)-1);<br />
}<br />
<br />
return lua_set_args(L, "s", Species_info[idx].species_name);<br />
<br />
You should consider LUA_SETTING_VAR to be the safest way of determining whether or not a variable is actually being set, because it uses Lua's own internal guidelines to determine this. <br />
<br />
It is good practice to return the value of the variable after changing it, so the scripter can check the value afterwards.<br />
<br />
<br />
===LUA_INDEXER===<br />
LUA_INDEXER(l_ShipTextures, "Texture name or index", "Texture", "Ship textures")<br />
First argument is the object, second is what can be placed in the brackets ([]), third is the type returned, and fourth is a description of what the array is.<br />
<br />
The first argument passed to the indexer will be the parent object; the second, the index (This can be whatever you like - a number, a string, even an image handle, just as long as lua_get_args can handle it). The third, the value that the scripter wants the current index to be set to.<br />
<br />
In all other respects, it is exactly like LUA_VAR; use LUA_SETTING_VAR to determine whether you are in setting mode or not.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Development_Reference&diff=2015Development Reference2006-02-04T02:26:50Z<p>72.194.192.77: Made page a list</p>
<hr />
<div>* [[Scripting API]]<br />
* [[FS2_Open Lua Scripting]]</div>72.194.192.77https://wiki.hard-light.org/index.php?title=FS2_Open_Lua_Scripting&diff=4751FS2 Open Lua Scripting2006-02-03T21:48:44Z<p>72.194.192.77: Added information on +Override</p>
<hr />
<div>This page is intended as a crash-course in Lua scripting as it relates to Freespace 2. It's only meant to get you started with Lua scripting - more advanced concepts such as metatables will not be covered.<br />
<br />
You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.<br />
<br />
== What You Need ==<br />
You will need a basic understanding of how to open and edit computer files, a copy of Freespace 2, and an open mind. Any kind of prior scripting experience will be immensely helpful, but you shouldn't need any to understand this document.<br />
<br />
Here we go!<br />
<br />
<b>Note:</b> Although all the examples should not cause syntax errors anywhere, they may not work in certain places. For example, you have to load a mission before you can get handles to ships in the mission.<br />
<br />
== Scripting hooks ==<br />
A scripting hook is a segment of Lua code, that is run at a specific place in FS2_Open. Some scripting hooks, such as $GameInit, are executed only once. Others, such as state hooks, are executed every frame. Others may be executed only when a specific action occurs (such as a keypress or a ship warping out).<br />
<br />
There are three different types of hooks. All hooks are parsed and loaded into memory when they are read, so there is no speed difference. Also, the optional field "+Override: YES" can be used to make a scripting hook completely override fs2_open's usual behavior. (For example, for the HUD, this would completely disable the default fs2_open HUD and use the scripting version instead)<br />
<br />
For the sake of organization, information on different scripting hooks can be found in the wiki page for the table that they are actually in.<br />
<br />
=== Return hook ===<br />
$Hook: 2 + Mission.getNumShips()<br />
This works like a normal table variable, except that you can use scripting functions as well.<br />
<br />
=== Normal hook ===<br />
$Hook: [<br />
gr.setColor(255, 255, 255)<br />
gr.drawString("Hello, world!")<br />
<br />
return 2 + Mission.getNumShips()<br />
]<br />
A normal hook is denoted by [ and ]. Whatever is within the brackets is passed to the Lua interpreter. This means that you cannot use table-style ;; comments within brackets; you must use Lua's comments.<br />
<br />
However, you can still use it with a .tbl field that takes a value, using the "return" command. In this case, even though the other lines are still run, the $Hook: variable would be set to the same value as in the 'Return hook' example.<br />
<br />
=== File hook ===<br />
<pre>$Hook: [[script.lua]]</pre><br />
A file hook loads the scripting from the file in the data/scripts directory. In all other respects, it is the same as a normal hook.<br />
<br />
== Comments ==<br />
A "comment" (in any programming or scripting language) is a block of a script that is ignored. In Lua there is only one kind of comment, which starts with double-dashes. Any time you put two dashes in a Lua script outside of a string, the rest of the line will be ignored. (This is the same as putting a double-semicolon in a Freespace table)<br />
<br />
For example, this:<br />
--Load a mission for use in the mainhall<br />
Mission.loadMission("sm2-10.fs2") --Use 'King's Gambit' for now.<br />
<br />
Will do exactly the same thing as this:<br />
Mission.loadMission("sm2-10.fs2")<br />
<br />
== Variables ==<br />
A variable is the simplest kind of thing that there is in Lua. All it really does is hold data; no more, no less. They really aren't that scary. Here are some different types of variables<br />
<br />
--Number variable<br />
life = 42<br />
<br />
--String variable<br />
name = "Bob"<br />
<br />
--Boolean variables<br />
smoking = true<br />
healthy = false<br />
<br />
--Userdata (Handle or object) variable<br />
player = mn.getShipByName("Alpha 1")<br />
<br />
--Nil variable<br />
--Erases a previously set variable<br />
life = nil<br />
<br />
--Member variable of userdata. Can be any of the above types.<br />
player.Name = "Ship"<br />
<br />
<b>Note:</b> Although technically objects and handles are all userdata, it's easier to just think of every object and handle as being different types of variables.<br />
<br />
=== Arrays ===<br />
<br />
An array is a special type of variable, that holds multiple variables. The '''''index''''' of all Lua arrays starts at 1.<br />
<br />
--Set the fifth element of array to 1<br />
a[5] = 12<br />
--Set n to the fifth element (tehe)<br />
n = a[5]<br />
--n will be 12<br />
<br />
== Libraries ==<br />
In order to gain access to the FS2_Open engine through scripting, you must use the FS2_Open libraries. Each library represents a different section of the engine. In addition, libraries may be referenced one of two ways: the full name, or a shorthand version of the name made up of two letters. Here, the same setColor '''''function''''' is used twice.<br />
<br />
Graphics.setColor(255, 255, 255)<br />
gr.setColor(255, 255, 255)<br />
<br />
For the sake of easy reading, I've used the longhand version of names in the wiki. However, I recommend you learn the shorthand versions as they're generally faster to work with when scripting.<br />
<br />
To get a full list of library functions, use the "-output_scripting" command line parameter. This should create a file called scripting.html, with a list of the different libraries, functions, and types supported by that build. (Use a web browser to open it)<br />
<br />
<br />
== Functions ==<br />
A function is an instruction to Lua to do something. It may change variables, or it may call (activate) other functions. Functions are the meat of scripting; they get everything done. Essentially, they are much like an individual SEXP.<br />
<br />
As a result, this section is pretty tough, but covers almost all of the specific knowledge you'll need to work within Lua.<br />
<br />
=== Function vocabulary ===<br />
* '''''Return value''''' - Data that a function returns. Any data that a function returns may be stored in a variable.<br />
* '''''Arguments''''' - Data that is given to a function. May be data itself, a variable containing the data, or even the return value of another function.<br />
* '''''Call''''' - To run a function.<br />
<br />
<br />
=== Typical function use ===<br />
<b>Example:</b> This will write "Alpha 1" in the upper-left corner of the screen.<br />
player = Mission.getShipByName("Alpha 1")<br />
Graphics.setColor(255, 255, 255)<br />
Graphics.drawString(player.Name, 5, 5)<br />
<br />
* <b>Line 1:</b> <br>In the first line, the "getShipByName" function of the mission library is run. Because "Alpha 1" is specified as the argument, the return value of the getShipByName function will be the ship handle of the ship named "Alpha 1" in the mission (or nil if Alpha 1 is dead or there was no Alpha 1 to begin with). Because the player variable is set to the function, it will take on the return value of the function. <br><br><b>Result</b><br>After the first line, the player variable is a ship handle to the ship named "Alpha 1" in the current mission.<br />
<br />
<br />
* <b>Line 2</b><br>In the second line, the "setColor" function is used to set the current drawing color to pure white. Unlike getShipByName, it takes at least three arguments, all numbers - the red, green, and blue scale of the current color, from 0 to 255. It's always a good idea to use the setColor function before doing any drawing in scripting, as the engine can and will change the current color between scripting hooks.<br><br><b>Result</b> <br>Current drawing color is set to pure white<br />
<br />
<br />
* <b>Line 3</b><br>In the third line, the drawString function takes three arguments - a string, followed by two numbers. The string specifies the text to write, the numbers specify the x and y position of the upper-left corner of the written text. As you can see, we've directly used a '''''member variable''''' of the player variable to fill the first argument. Because we got the ship handle by its name, the Name variable will be the same as the name that we got it by ("Alpha 1").<br><br><b>Result</b><br>After the third line, "Alpha 1" will appear in the upper-left corner of the string in white text.<br />
<br />
<b>Note:</b> Numbers and certain types of userdata will automatically convert to strings. In all other cases, functions will give an error if you try to use the wrong type of argument.<br />
<br />
<b>Debugging note:</b> If Alpha 1 were dead in the above example, you would get an error about 'trying to index a nil value' because it would not be able to run the getName() function.<br />
<br />
<br />
=== Userdata functions ===<br />
Handles and objects may also have functions.<br />
<br />
<b>Example:</b> This will write the number of subsystem's on Alpha 1's ship in the upper-left corner.<br />
player = Mission.getShipByName("Alpha 1")<br />
Graphics.drawString(player:getNumSubsystems(), 5, 5)<br />
<br />
As before, we get the handle to the Alpha 1 ship with getShipByName.<br />
<br />
<br />
=== Optional arguments ===<br />
<br />
Sometimes you don't have to use an argument. For example, the setColor function has an optional fourth argument - how opaque the color should be. If the argument isn't used, the color is totally opaque. These two lines do the same thing:<br />
<br />
Graphics.setColor(255, 255, 255)<br />
Graphics.setColor(255, 255, 255, 255)<br />
<br />
<br />
== Quick, a full example! ==<br />
By this point, you may be bored of all this exposition. So here's your typical "Hello, World!" example.<br />
<br />
For this amazing trick, we'll make our very own splash screen. Turn off all Freespace 2 mods, and create a file called "scripting.tbl" in your data/tables directory. Open that up in a text editor, and write:<br />
#Global Hooks<br />
$Splash: [<br />
--Set the color to white<br />
Graphics.setColor(255, 255, 255)<br />
--Write "Hello, world!"<br />
Graphics.drawString("Hello, world!", 5, 10)<br />
]<br />
+Override: YES<br />
#End<br />
<br />
Now, when you start up FS2_Open, you should see "Hello, world!" in the upper-left, as it loads.<br />
<br />
== Control structures ==<br />
A control structure is a series of statements that let you change how a script runs, based on some condition - say, a ship is dead, or the life of a certain ship has fallen below a certain amount.<br />
<br />
=== If statements ===<br />
If statements are a way to check if something is some way or not. All if statements have the form:<br />
if (something) then<br />
(execute)<br />
end<br />
<br />
(something) can be true, or false. If it's true, then (execute) will be run. If it's false, then the script will skip down to "end" and go on from there.<br />
<br />
To check that a handle is valid:<br />
ship = Mission.getShipByName("Alpha 2")<br />
if ship then<br />
--This will always happen while Alpha 2 is alive<br />
Graphics.drawString("MACKIE LIVES!", 5, 10)<br />
end<br />
<br />
To check a variable value<br />
x = 42<br />
y = 23<br />
if x < y or x is y then<br />
--We never get here, because x is bigger than y<br />
end<br />
<br />
=== For statements ===<br />
A for statement is generally used to iterate through a list.<br />
<br />
<b>Example:</b><br />
This bit of scripting will run through all of Alpha 2's subsystems if she isn't dead, and display a list of them in the upper-left.<br />
<br />
ship = Mission.getShipByName("Alpha 2")<br />
if ship then<br />
num_subsys = ship:getNumSubsystems()<br />
x = 5<br />
y = 5<br />
for i=1,num_subsys do<br />
--Use the i variable to go through the ship's subsystems,<br />
--and to change the y position of the text.<br />
gr.drawString(ship[i]:getName(), x, y + i*10)<br />
end<br />
end<br />
<br />
=== More information ===<br />
For other keywords you can use with control structures, see the [http://www.lua.org/manual/5.0/manual.html#2.5.2 Lua Documentation]<br />
<br />
For more detailed information on if statements and other types of control structures, see the [http://lua-users.org/wiki/ControlStructureTutorial Lua-users wiki]<br />
<br />
<br />
== Appendices ==<br />
<br />
There's more depth to scripting than what's covered above. To make the rest of the article shorter, I've put the topics still within the scope of this article, but not necessary to know in most cases, down here.<br />
<br />
However, I HIGHLY recommend you read the optimizing scripting section.<br />
<br />
=== Appendix: Optimizing scripting ===<br />
<br />
Because fs2_open is written in C, which is much faster than Lua, it is much better to store variables in C and provide Lua functions to work with them. In addition, to keep Lua scripting from messing with C scripting and to make it as friendly as possible, there are a number of safeguards to catch problems, in most of the Lua functions.<br />
<br />
As a result, whenever you're working with a value provided by a library or object function, you should set it to a Lua variable if you're going to use it more than 1-2 times due to the large overhead resulting from the interface.<br />
<br />
Thus, even though it may [i]look[/i] like "Name" is a member variable of the ship handle, it is actually a function that performs 3-4 validity checks before returning the value, which must also be converted from C to Lua. Setting a variable to the return value of the function means that you can use that variable wherever you want to use the ship name using the native Lua environment.<br />
<br />
=== Appendix: Debugging scripting ===<br />
<br />
Unfortunately, the Lua interpreter provides only limited debugging information about hooks. (Supposedly, it will provide more information about scripting within user functions, but I haven't tested that claim yet)<br />
<br />
Generally, error messages complaining about referencing or indexing a 'nil value' occur because a function could not return a handle, so it returned nil. Some functions also return false to indicate that the handle is correct, but due to some kind of wrong information being passed, it couldn't complete.<br />
<br />
Generally, you should check all handles before using them:<br />
player = getShipByName("Alpha 1")<br />
if player then<br />
<br />
end<br />
<br />
With all uses of the player handle falling in the "if" statement.<br />
<br />
=== Appendix: Function types ===<br />
<br />
Here's all the different kinds of functions you can have:<br />
--A function provided by itself<br />
x = cos(y)<br />
--A function provided by a library<br />
x = Math.cos(y)<br />
--A function provided by a userdata variable.<br />
x = y:cos()<br />
In every case, x would be set to the cosine of y, which is 1.<br />
<br />
<b>Note:</b> You must use a ":" with userdata functions, as in the example. This tells Lua that it needs to give the function the value of the variable that it's being called from.<br />
<br />
=== Appendix: Making your own functions ===<br />
So, let's make the doSomething() function do, well, something.<br />
doSomething = function()<br />
color = "red"<br />
end<br />
As you can see, creating a function is much like creating a variable; you just use function() instead of the value, then write what you want the function to do. To end the function, you just write "end"<br />
<br />
Now, let's use our new doSomething() function.<br />
color = "black"<br />
doSomething()<br />
--After using doSomething(), color is now red<br />
<br />
Functions can also '''''return''''' values.<br />
--Make a new function<br />
doSomethingElse = function()<br />
return 10<br />
end<br />
x = 0<br />
doSomething()<br />
--x is now 27<br />
x = doSomethingElse()<br />
--x is now 10<br />
<br />
=== Appendix: Variable Scope ===<br />
The '''''scope''''' of a variable is the area where it exists. Writing <tt>local</tt> in front of the variable name will tell Lua that the variable should only exist within that function or hook.<br />
<br />
Note that this means that if you use the same variable name in two different hooks without using local, the same variable will be used.<br />
<br />
<b>Note:</b><br />
<br />
You may find it useful to have some way of distinguishing global variables from local ones, to remind yourself that the value does carry over. For example, starting global variable names with "g_".<br />
<br />
<b>Example:</b> The following will draw the text "Media VP" in the upper-left corner of the main hall, even though the variable is set in a different hook than it is used in.<br />
<br />
#Global Hooks<br />
$GameInit: [g_mod = "Media VP"]<br />
#End<br />
<br />
#State Hooks<br />
$State: GS_STATE_MAIN_MENU<br />
$Hook: [Graphics.drawString(g_mod, 0, 0)]<br />
#End<br />
<br />
=== Appendix: Variable Types ===<br />
Variables can hold different types of data. These basic types are:<br />
<br />
==== Boolean ====<br />
A boolean is a simple variable - it can be true, or false.<br />
--It's Monday, and Dilbert is at the office<br />
working = true<br />
--Oops, he just opened Solitaire<br />
working = false<br />
<br />
==== Numbers ====<br />
A number is any variable that holds (As you might've guessed) a number. A number will automatically convert into a string, if needed.<br />
--A variable can be a whole number, like this<br />
x = 5<br />
--Or it can be a decimal value<br />
x = 3.141592654<br />
--Or you can divide two numbers for a fraction<br />
x = 3/4<br />
<br />
==== Strings ====<br />
A string is a variable that holds a series of characters, and a character is any number, letter, or symbol on your keyboard (and then some). Basically, strings are the way that words and sentences are passed around in Lua.<br />
--A cow says moo!<br />
cow = "moo"<br />
--A friend's name<br />
friend = "Bob"<br />
Note that actual string content is contained within double quotation marks, to mark it as a string.<br />
<br />
==== nil ====<br />
nil isn't really a variable type, but it is important. nil means that a variable doesn't hold anything. If you want to get rid of a variable, you just set it to be nil.<br />
<br />
--Today I got a new dog<br />
dog = "Spot"<br />
--But then he ran away<br />
dog = nil<br />
<br />
Any time an error says that a variable is nil, it usually means that it doesn't exist (Double-check your spelling).<br />
<br />
==== Userdata/objects ====<br />
Objects (or "userdata", as they are known in Lua) is a variable that can contain other variables, or functions. Variables or functions within an object are known as "member variables" or "member functions".<br />
<br />
--Assuming we have a my_car object, this will copy it to your_car<br />
your_car = my_car<br />
--Congratulations! But maybe you want to customize it?<br />
--Note how I refer to the member variable, color<br />
your_car.color = "Red"<br />
<br />
==== Handles ====<br />
A handle isn't technically a Lua type, but handles are used a lot in FS2_Open Lua scripting. Essentially, a handle is a variable that refers to a specific object; but doesn't actually contain that object's data. An example is the "shipclass" type; it doesn't actually contain the data in ships.tbl, it just serves to reference the ship class so that you can get and set data.<br />
--Get the "GTF Ulysses" ship type<br />
--For this, I use the function 'getShipclassByName'<br />
ulysses = tb.getShipclassByName("GTF Ulysses")<br />
--Now get rid of the handle<br />
ulysses = nil<br />
--Even though we've gotten rid of the handle, the Ulysses will still exist.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=FS2_Open_Lua_Scripting&diff=1925FS2 Open Lua Scripting2006-02-03T21:43:57Z<p>72.194.192.77: Minor corrections to formatting</p>
<hr />
<div>This page is intended as a crash-course in Lua scripting as it relates to Freespace 2. It's only meant to get you started with Lua scripting - more advanced concepts such as metatables will not be covered.<br />
<br />
You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.<br />
<br />
== What You Need ==<br />
You will need a basic understanding of how to open and edit computer files, a copy of Freespace 2, and an open mind. Any kind of prior scripting experience will be immensely helpful, but you shouldn't need any to understand this document.<br />
<br />
Here we go!<br />
<br />
<b>Note:</b> Although all the examples should not cause syntax errors anywhere, they may not work in certain places. For example, you have to load a mission before you can get handles to ships in the mission.<br />
<br />
== Scripting hooks ==<br />
A scripting hook is a segment of Lua code, that is run at a specific place in FS2_Open. Some scripting hooks, such as $GameInit, are executed only once. Others, such as state hooks, are executed every frame. Others may be executed only when a specific action occurs (such as a keypress or a ship warping out).<br />
<br />
There are three different types of hooks. All hooks are parsed and loaded into memory when they are read, so there is no speed difference.<br />
<br />
For the sake of organization, information on different scripting hooks can be found in the wiki page for the table that they are actually in.<br />
<br />
=== Return hook ===<br />
$Hook: 2 + Mission.getNumShips()<br />
This works like a normal table variable, except that you can use scripting functions as well.<br />
<br />
=== Normal hook ===<br />
$Hook: [<br />
gr.setColor(255, 255, 255)<br />
gr.drawString("Hello, world!")<br />
<br />
return 2 + Mission.getNumShips()<br />
]<br />
A normal hook is denoted by [ and ]. Whatever is within the brackets is passed to the Lua interpreter. This means that you cannot use table-style ;; comments within brackets; you must use Lua's comments.<br />
<br />
However, you can still use it with a .tbl field that takes a value, using the "return" command. In this case, even though the other lines are still run, the $Hook: variable would be set to the same value as in the 'Return hook' example.<br />
<br />
=== File hook ===<br />
<pre>$Hook: [[script.lua]]</pre><br />
A file hook loads the scripting from the file in the data/scripts directory. In all other respects, it is the same as a normal hook.<br />
<br />
== Comments ==<br />
A "comment" (in any programming or scripting language) is a block of a script that is ignored. In Lua there is only one kind of comment, which starts with double-dashes. Any time you put two dashes in a Lua script outside of a string, the rest of the line will be ignored. (This is the same as putting a double-semicolon in a Freespace table)<br />
<br />
For example, this:<br />
--Load a mission for use in the mainhall<br />
Mission.loadMission("sm2-10.fs2") --Use 'King's Gambit' for now.<br />
<br />
Will do exactly the same thing as this:<br />
Mission.loadMission("sm2-10.fs2")<br />
<br />
== Variables ==<br />
A variable is the simplest kind of thing that there is in Lua. All it really does is hold data; no more, no less. They really aren't that scary. Here are some different types of variables<br />
<br />
--Number variable<br />
life = 42<br />
<br />
--String variable<br />
name = "Bob"<br />
<br />
--Boolean variables<br />
smoking = true<br />
healthy = false<br />
<br />
--Userdata (Handle or object) variable<br />
player = mn.getShipByName("Alpha 1")<br />
<br />
--Nil variable<br />
--Erases a previously set variable<br />
life = nil<br />
<br />
--Member variable of userdata. Can be any of the above types.<br />
player.Name = "Ship"<br />
<br />
<b>Note:</b> Although technically objects and handles are all userdata, it's easier to just think of every object and handle as being different types of variables.<br />
<br />
=== Arrays ===<br />
<br />
An array is a special type of variable, that holds multiple variables. The '''''index''''' of all Lua arrays starts at 1.<br />
<br />
--Set the fifth element of array to 1<br />
a[5] = 12<br />
--Set n to the fifth element (tehe)<br />
n = a[5]<br />
--n will be 12<br />
<br />
== Libraries ==<br />
In order to gain access to the FS2_Open engine through scripting, you must use the FS2_Open libraries. Each library represents a different section of the engine. In addition, libraries may be referenced one of two ways: the full name, or a shorthand version of the name made up of two letters. Here, the same setColor '''''function''''' is used twice.<br />
<br />
Graphics.setColor(255, 255, 255)<br />
gr.setColor(255, 255, 255)<br />
<br />
For the sake of easy reading, I've used the longhand version of names in the wiki. However, I recommend you learn the shorthand versions as they're generally faster to work with when scripting.<br />
<br />
To get a full list of library functions, use the "-output_scripting" command line parameter. This should create a file called scripting.html, with a list of the different libraries, functions, and types supported by that build. (Use a web browser to open it)<br />
<br />
<br />
== Functions ==<br />
A function is an instruction to Lua to do something. It may change variables, or it may call (activate) other functions. Functions are the meat of scripting; they get everything done. Essentially, they are much like an individual SEXP.<br />
<br />
As a result, this section is pretty tough, but covers almost all of the specific knowledge you'll need to work within Lua.<br />
<br />
=== Function vocabulary ===<br />
* '''''Return value''''' - Data that a function returns. Any data that a function returns may be stored in a variable.<br />
* '''''Arguments''''' - Data that is given to a function. May be data itself, a variable containing the data, or even the return value of another function.<br />
* '''''Call''''' - To run a function.<br />
<br />
<br />
=== Typical function use ===<br />
<b>Example:</b> This will write "Alpha 1" in the upper-left corner of the screen.<br />
player = Mission.getShipByName("Alpha 1")<br />
Graphics.setColor(255, 255, 255)<br />
Graphics.drawString(player.Name, 5, 5)<br />
<br />
* <b>Line 1:</b> <br>In the first line, the "getShipByName" function of the mission library is run. Because "Alpha 1" is specified as the argument, the return value of the getShipByName function will be the ship handle of the ship named "Alpha 1" in the mission (or nil if Alpha 1 is dead or there was no Alpha 1 to begin with). Because the player variable is set to the function, it will take on the return value of the function. <br><br><b>Result</b><br>After the first line, the player variable is a ship handle to the ship named "Alpha 1" in the current mission.<br />
<br />
<br />
* <b>Line 2</b><br>In the second line, the "setColor" function is used to set the current drawing color to pure white. Unlike getShipByName, it takes at least three arguments, all numbers - the red, green, and blue scale of the current color, from 0 to 255. It's always a good idea to use the setColor function before doing any drawing in scripting, as the engine can and will change the current color between scripting hooks.<br><br><b>Result</b> <br>Current drawing color is set to pure white<br />
<br />
<br />
* <b>Line 3</b><br>In the third line, the drawString function takes three arguments - a string, followed by two numbers. The string specifies the text to write, the numbers specify the x and y position of the upper-left corner of the written text. As you can see, we've directly used a '''''member variable''''' of the player variable to fill the first argument. Because we got the ship handle by its name, the Name variable will be the same as the name that we got it by ("Alpha 1").<br><br><b>Result</b><br>After the third line, "Alpha 1" will appear in the upper-left corner of the string in white text.<br />
<br />
<b>Note:</b> Numbers and certain types of userdata will automatically convert to strings. In all other cases, functions will give an error if you try to use the wrong type of argument.<br />
<br />
<b>Debugging note:</b> If Alpha 1 were dead in the above example, you would get an error about 'trying to index a nil value' because it would not be able to run the getName() function.<br />
<br />
<br />
=== Userdata functions ===<br />
Handles and objects may also have functions.<br />
<br />
<b>Example:</b> This will write the number of subsystem's on Alpha 1's ship in the upper-left corner.<br />
player = Mission.getShipByName("Alpha 1")<br />
Graphics.drawString(player:getNumSubsystems(), 5, 5)<br />
<br />
As before, we get the handle to the Alpha 1 ship with getShipByName.<br />
<br />
<br />
=== Optional arguments ===<br />
<br />
Sometimes you don't have to use an argument. For example, the setColor function has an optional fourth argument - how opaque the color should be. If the argument isn't used, the color is totally opaque. These two lines do the same thing:<br />
<br />
Graphics.setColor(255, 255, 255)<br />
Graphics.setColor(255, 255, 255, 255)<br />
<br />
<br />
== Quick, a full example! ==<br />
By this point, you may be bored of all this exposition. So here's your typical "Hello, World!" example.<br />
<br />
For this amazing trick, we'll make our very own splash screen. Turn off all Freespace 2 mods, and create a file called "scripting.tbl" in your data/tables directory. Open that up in a text editor, and write:<br />
#Global Hooks<br />
$Splash: [<br />
--Set the color to white<br />
Graphics.setColor(255, 255, 255)<br />
--Write "Hello, world!"<br />
Graphics.drawString("Hello, world!", 5, 10)<br />
]<br />
+Override: YES<br />
#End<br />
<br />
Now, when you start up FS2_Open, you should see "Hello, world!" in the upper-left, as it loads.<br />
<br />
== Control structures ==<br />
A control structure is a series of statements that let you change how a script runs, based on some condition - say, a ship is dead, or the life of a certain ship has fallen below a certain amount.<br />
<br />
=== If statements ===<br />
If statements are a way to check if something is some way or not. All if statements have the form:<br />
if (something) then<br />
(execute)<br />
end<br />
<br />
(something) can be true, or false. If it's true, then (execute) will be run. If it's false, then the script will skip down to "end" and go on from there.<br />
<br />
To check that a handle is valid:<br />
ship = Mission.getShipByName("Alpha 2")<br />
if ship then<br />
--This will always happen while Alpha 2 is alive<br />
Graphics.drawString("MACKIE LIVES!", 5, 10)<br />
end<br />
<br />
To check a variable value<br />
x = 42<br />
y = 23<br />
if x < y or x is y then<br />
--We never get here, because x is bigger than y<br />
end<br />
<br />
=== For statements ===<br />
A for statement is generally used to iterate through a list.<br />
<br />
<b>Example:</b><br />
This bit of scripting will run through all of Alpha 2's subsystems if she isn't dead, and display a list of them in the upper-left.<br />
<br />
ship = Mission.getShipByName("Alpha 2")<br />
if ship then<br />
num_subsys = ship:getNumSubsystems()<br />
x = 5<br />
y = 5<br />
for i=1,num_subsys do<br />
--Use the i variable to go through the ship's subsystems,<br />
--and to change the y position of the text.<br />
gr.drawString(ship[i]:getName(), x, y + i*10)<br />
end<br />
end<br />
<br />
=== More information ===<br />
For other keywords you can use with control structures, see the [http://www.lua.org/manual/5.0/manual.html#2.5.2 Lua Documentation]<br />
<br />
For more detailed information on if statements and other types of control structures, see the [http://lua-users.org/wiki/ControlStructureTutorial Lua-users wiki]<br />
<br />
<br />
== Appendices ==<br />
<br />
There's more depth to scripting than what's covered above. To make the rest of the article shorter, I've put the topics still within the scope of this article, but not necessary to know in most cases, down here.<br />
<br />
However, I HIGHLY recommend you read the optimizing scripting section.<br />
<br />
=== Appendix: Optimizing scripting ===<br />
<br />
Because fs2_open is written in C, which is much faster than Lua, it is much better to store variables in C and provide Lua functions to work with them. In addition, to keep Lua scripting from messing with C scripting and to make it as friendly as possible, there are a number of safeguards to catch problems, in most of the Lua functions.<br />
<br />
As a result, whenever you're working with a value provided by a library or object function, you should set it to a Lua variable if you're going to use it more than 1-2 times due to the large overhead resulting from the interface.<br />
<br />
Thus, even though it may [i]look[/i] like "Name" is a member variable of the ship handle, it is actually a function that performs 3-4 validity checks before returning the value, which must also be converted from C to Lua. Setting a variable to the return value of the function means that you can use that variable wherever you want to use the ship name using the native Lua environment.<br />
<br />
=== Appendix: Debugging scripting ===<br />
<br />
Unfortunately, the Lua interpreter provides only limited debugging information about hooks. (Supposedly, it will provide more information about scripting within user functions, but I haven't tested that claim yet)<br />
<br />
Generally, error messages complaining about referencing or indexing a 'nil value' occur because a function could not return a handle, so it returned nil. Some functions also return false to indicate that the handle is correct, but due to some kind of wrong information being passed, it couldn't complete.<br />
<br />
Generally, you should check all handles before using them:<br />
player = getShipByName("Alpha 1")<br />
if player then<br />
<br />
end<br />
<br />
With all uses of the player handle falling in the "if" statement.<br />
<br />
=== Appendix: Function types ===<br />
<br />
Here's all the different kinds of functions you can have:<br />
--A function provided by itself<br />
x = cos(y)<br />
--A function provided by a library<br />
x = Math.cos(y)<br />
--A function provided by a userdata variable.<br />
x = y:cos()<br />
In every case, x would be set to the cosine of y, which is 1.<br />
<br />
<b>Note:</b> You must use a ":" with userdata functions, as in the example. This tells Lua that it needs to give the function the value of the variable that it's being called from.<br />
<br />
=== Appendix: Making your own functions ===<br />
So, let's make the doSomething() function do, well, something.<br />
doSomething = function()<br />
color = "red"<br />
end<br />
As you can see, creating a function is much like creating a variable; you just use function() instead of the value, then write what you want the function to do. To end the function, you just write "end"<br />
<br />
Now, let's use our new doSomething() function.<br />
color = "black"<br />
doSomething()<br />
--After using doSomething(), color is now red<br />
<br />
Functions can also '''''return''''' values.<br />
--Make a new function<br />
doSomethingElse = function()<br />
return 10<br />
end<br />
x = 0<br />
doSomething()<br />
--x is now 27<br />
x = doSomethingElse()<br />
--x is now 10<br />
<br />
=== Appendix: Variable Scope ===<br />
The '''''scope''''' of a variable is the area where it exists. Writing <tt>local</tt> in front of the variable name will tell Lua that the variable should only exist within that function or hook.<br />
<br />
Note that this means that if you use the same variable name in two different hooks without using local, the same variable will be used.<br />
<br />
<b>Note:</b><br />
<br />
You may find it useful to have some way of distinguishing global variables from local ones, to remind yourself that the value does carry over. For example, starting global variable names with "g_".<br />
<br />
<b>Example:</b> The following will draw the text "Media VP" in the upper-left corner of the main hall, even though the variable is set in a different hook than it is used in.<br />
<br />
#Global Hooks<br />
$GameInit: [g_mod = "Media VP"]<br />
#End<br />
<br />
#State Hooks<br />
$State: GS_STATE_MAIN_MENU<br />
$Hook: [Graphics.drawString(g_mod, 0, 0)]<br />
#End<br />
<br />
=== Appendix: Variable Types ===<br />
Variables can hold different types of data. These basic types are:<br />
<br />
==== Boolean ====<br />
A boolean is a simple variable - it can be true, or false.<br />
--It's Monday, and Dilbert is at the office<br />
working = true<br />
--Oops, he just opened Solitaire<br />
working = false<br />
<br />
==== Numbers ====<br />
A number is any variable that holds (As you might've guessed) a number. A number will automatically convert into a string, if needed.<br />
--A variable can be a whole number, like this<br />
x = 5<br />
--Or it can be a decimal value<br />
x = 3.141592654<br />
--Or you can divide two numbers for a fraction<br />
x = 3/4<br />
<br />
==== Strings ====<br />
A string is a variable that holds a series of characters, and a character is any number, letter, or symbol on your keyboard (and then some). Basically, strings are the way that words and sentences are passed around in Lua.<br />
--A cow says moo!<br />
cow = "moo"<br />
--A friend's name<br />
friend = "Bob"<br />
Note that actual string content is contained within double quotation marks, to mark it as a string.<br />
<br />
==== nil ====<br />
nil isn't really a variable type, but it is important. nil means that a variable doesn't hold anything. If you want to get rid of a variable, you just set it to be nil.<br />
<br />
--Today I got a new dog<br />
dog = "Spot"<br />
--But then he ran away<br />
dog = nil<br />
<br />
Any time an error says that a variable is nil, it usually means that it doesn't exist (Double-check your spelling).<br />
<br />
==== Userdata/objects ====<br />
Objects (or "userdata", as they are known in Lua) is a variable that can contain other variables, or functions. Variables or functions within an object are known as "member variables" or "member functions".<br />
<br />
--Assuming we have a my_car object, this will copy it to your_car<br />
your_car = my_car<br />
--Congratulations! But maybe you want to customize it?<br />
--Note how I refer to the member variable, color<br />
your_car.color = "Red"<br />
<br />
==== Handles ====<br />
A handle isn't technically a Lua type, but handles are used a lot in FS2_Open Lua scripting. Essentially, a handle is a variable that refers to a specific object; but doesn't actually contain that object's data. An example is the "shipclass" type; it doesn't actually contain the data in ships.tbl, it just serves to reference the ship class so that you can get and set data.<br />
--Get the "GTF Ulysses" ship type<br />
--For this, I use the function 'getShipclassByName'<br />
ulysses = tb.getShipclassByName("GTF Ulysses")<br />
--Now get rid of the handle<br />
ulysses = nil<br />
--Even though we've gotten rid of the handle, the Ulysses will still exist.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=FS2_Open_Lua_Scripting&diff=1924FS2 Open Lua Scripting2006-02-03T21:41:00Z<p>72.194.192.77: </p>
<hr />
<div>This page is intended as a crash-course in Lua scripting as it relates to Freespace 2. It's only meant to get you started with Lua scripting - more advanced concepts such as metatables will not be covered.<br />
<br />
You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.<br />
<br />
== What You Need ==<br />
You will need a basic understanding of how to open and edit computer files, a copy of Freespace 2, and an open mind. Any kind of prior scripting experience will be immensely helpful, but you shouldn't need any to understand this document.<br />
<br />
Here we go!<br />
<br />
<b>Note:</b> Although all the examples should not cause syntax errors anywhere, they may not work in certain places. For example, you have to load a mission before you can get handles to ships in the mission.<br />
<br />
== Scripting hooks ==<br />
A scripting hook is a segment of Lua code, that is run at a specific place in FS2_Open. Some scripting hooks, such as $GameInit, are executed only once. Others, such as state hooks, are executed every frame. Others may be executed only when a specific action occurs (such as a keypress or a ship warping out).<br />
<br />
There are three different types of hooks. All hooks are parsed and loaded into memory when they are read, so there is no speed difference.<br />
<br />
For the sake of organization, information on different scripting hooks can be found in the wiki page for the table that they are actually in.<br />
<br />
=== Return hook ===<br />
$Hook: 2 + Mission.getNumShips()<br />
This works like a normal table variable, except that you can use scripting functions as well.<br />
<br />
=== Normal hook ===<br />
$Hook: [<br />
gr.setColor(255, 255, 255)<br />
gr.drawString("Hello, world!")<br />
<br />
return 2 + Mission.getNumShips()<br />
]<br />
A normal hook is denoted by [ and ]. Whatever is within the brackets is passed to the Lua interpreter. This means that you cannot use table-style ;; comments within brackets; you must use Lua's comments.<br />
<br />
However, you can still use it with a .tbl field that takes a value, using the "return" command. In this case, even though the other lines are still run, the $Hook: variable would be set to the same value as in the 'Return hook' example.<br />
<br />
=== File hook ===<br />
<pre>$Hook: [[script.lua]]</pre><br />
A file hook loads the scripting from the file in the data/scripts directory. In all other respects, it is the same as a normal hook.<br />
<br />
== Comments ==<br />
A "comment" (in any programming or scripting language) is a block of a script that is ignored. In Lua there is only one kind of comment, which starts with double-dashes. Any time you put two dashes in a Lua script outside of a string, the rest of the line will be ignored. (This is the same as putting a double-semicolon in a Freespace table)<br />
<br />
For example, this:<br />
--Load a mission for use in the mainhall<br />
Mission.loadMission("sm2-10.fs2") --Use 'King's Gambit' for now.<br />
<br />
Will do exactly the same thing as this:<br />
Mission.loadMission("sm2-10.fs2")<br />
<br />
== Variables ==<br />
A variable is the simplest kind of thing that there is in Lua. All it really does is hold data; no more, no less. They really aren't that scary. Here are some different types of variables<br />
<br />
--Number variable<br />
life = 42<br />
<br />
--String variable<br />
name = "Bob"<br />
<br />
--Boolean variables<br />
smoking = true<br />
healthy = false<br />
<br />
--Userdata (Handle or object) variable<br />
player = mn.getShipByName("Alpha 1")<br />
<br />
--Nil variable<br />
--Erases a previously set variable<br />
life = nil<br />
<br />
--Member variable of userdata. Can be any of the above types.<br />
player.Name = "Ship"<br />
<br />
<b>Note:</b> Although technically objects and handles are all userdata, it's easier to just think of every object and handle as being different types of variables.<br />
<br />
=== Arrays ===<br />
<br />
An array is a special type of variable, that holds multiple variables. The '''''index''''' of all Lua arrays starts at 1.<br />
<br />
--Set the fifth element of array to 1<br />
a[5] = 12<br />
--Set n to the fifth element (tehe)<br />
n = a[5]<br />
--n will be 12<br />
<br />
== Libraries ==<br />
In order to gain access to the FS2_Open engine through scripting, you must use the FS2_Open libraries. Each library represents a different section of the engine. In addition, libraries may be referenced one of two ways: the full name, or a shorthand version of the name made up of two letters. Here, the same setColor '''''function''''' is used twice.<br />
<br />
Graphics.setColor(255, 255, 255)<br />
gr.setColor(255, 255, 255)<br />
<br />
For the sake of easy reading, I've used the longhand version of names in the wiki. However, I recommend you learn the shorthand versions as they're generally faster to work with when scripting.<br />
<br />
To get a full list of library functions, use the "-output_scripting" command line parameter. This should create a file called scripting.html, with a list of the different libraries, functions, and types supported by that build. (Use a web browser to open it)<br />
<br />
<br />
== Functions ==<br />
A function is an instruction to Lua to do something. It may change variables, or it may call (activate) other functions. Functions are the meat of scripting; they get everything done. Essentially, they are much like an individual SEXP.<br />
<br />
As a result, this section is pretty tough, but covers almost all of the specific knowledge you'll need to work within Lua.<br />
<br />
=== Function vocabulary ===<br />
* '''''Return value''''' - Data that a function returns. Any data that a function returns may be stored in a variable.<br />
* '''''Arguments''''' - Data that is given to a function. May be data itself, a variable containing the data, or even the return value of another function.<br />
* '''''Call''''' - To run a function.<br />
<br />
<br />
=== Typical function use ===<br />
<b>Example:</b><br />
This will write "Alpha 1" in the upper-left corner of the screen.<br />
player = Mission.getShipByName("Alpha 1")<br />
Graphics.setColor(255, 255, 255)<br />
Graphics.drawString(player.Name, 5, 5)<br />
<br />
* <b>Line 1:</b> <br>In the first line, the "getShipByName" function of the mission library is run. Because "Alpha 1" is specified as the argument, the return value of the getShipByName function will be the ship handle of the ship named "Alpha 1" in the mission (or nil if Alpha 1 is dead or there was no Alpha 1 to begin with). Because the player variable is set to the function, it will take on the return value of the function. <br><br><b>Result</b><br>After the first line, the player variable is a ship handle to the ship named "Alpha 1" in the current mission.<br />
<br />
<br />
* <b>Line 2</b><br>In the second line, the "setColor" function is used to set the current drawing color to pure white. Unlike getShipByName, it takes at least three arguments, all numbers - the red, green, and blue scale of the current color, from 0 to 255. It's always a good idea to use the setColor function before doing any drawing in scripting, as the engine can and will change the current color between scripting hooks.<br><br><b>Result</b> <br>Current drawing color is set to pure white<br />
<br />
<br />
* <b>Line 3</b><br>In the third line, the drawString function takes three arguments - a string, followed by two numbers. The string specifies the text to write, the numbers specify the x and y position of the upper-left corner of the written text. As you can see, we've directly used a '''''member variable''''' of the player variable to fill the first argument. Because we got the ship handle by its name, the Name variable will be the same as the name that we got it by ("Alpha 1").<br><br><b>Result</b><br>After the third line, "Alpha 1" will appear in the upper-left corner of the string in white text.<br />
<br />
<b>Note:</b> Numbers and certain types of userdata will automatically convert to strings. In all other cases, functions will give an error if you try to use the wrong type of argument.<br />
<br />
<b>Debugging note:</b> If Alpha 1 were dead in the above example, you would get an error about 'trying to index a nil value' because it would not be able to run the getName() function.<br />
<br />
<br />
=== Userdata functions ===<br />
Handles and objects may also have functions.<br />
<br />
<b>Example:</b><br />
player = Mission.getShipByName("Alpha 1")<br />
Graphics.drawString(player:getNumSubsystems(), 5, 5)<br />
<br />
As before, we get the handle to the Alpha 1 ship with getShipByName.<br />
<br />
<br />
=== Optional arguments ===<br />
<br />
Sometimes you don't have to use an argument. For example, the setColor function has an optional fourth argument - how opaque the color should be. If the argument isn't used, the color is totally opaque. These two lines do the same thing:<br />
<br />
Graphics.setColor(255, 255, 255)<br />
Graphics.setColor(255, 255, 255, 255)<br />
<br />
<br />
== Quick, a full example! ==<br />
By this point, you may be bored of all this exposition. So here's your typical "Hello, World!" example.<br />
<br />
For this amazing trick, we'll make our very own splash screen. Turn off all Freespace 2 mods, and create a file called "scripting.tbl" in your data/tables directory. Open that up in a text editor, and write:<br />
#Global Hooks<br />
$Splash: [<br />
--Set the color to white<br />
Graphics.setColor(255, 255, 255)<br />
--Write "Hello, world!"<br />
Graphics.drawString("Hello, world!", 5, 10)<br />
]<br />
+Override: YES<br />
#End<br />
<br />
Now, when you start up FS2_Open, you should see "Hello, world!" in the upper-left, as it loads.<br />
<br />
== Control structures ==<br />
A control structure is a series of statements that let you change how a script runs, based on some condition - say, a ship is dead, or the life of a certain ship has fallen below a certain amount.<br />
<br />
=== If statements ===<br />
If statements are a way to check if something is some way or not. All if statements have the form:<br />
if (something) then<br />
(execute)<br />
end<br />
<br />
(something) can be true, or false. If it's true, then (execute) will be run. If it's false, then the script will skip down to "end" and go on from there.<br />
<br />
To check that a handle is valid:<br />
ship = Mission.getShipByName("Alpha 2")<br />
if ship then<br />
--This will always happen while Alpha 2 is alive<br />
Graphics.drawString("MACKIE LIVES!", 5, 10)<br />
end<br />
<br />
To check a variable value<br />
x = 42<br />
y = 23<br />
if x < y or x is y then<br />
--We never get here, because x is bigger than y<br />
end<br />
<br />
=== For statements ===<br />
A for statement is generally used to iterate through a list.<br />
<br />
<b>Example:</b><br />
This bit of scripting will run through all of Alpha 2's subsystems if she isn't dead, and display a list of them in the upper-left.<br />
<br />
ship = Mission.getShipByName("Alpha 2")<br />
if ship then<br />
num_subsys = ship:getNumSubsystems()<br />
x = 5<br />
y = 5<br />
for i=1,num_subsys do<br />
--Use the i variable to go through the ship's subsystems,<br />
--and to change the y position of the text.<br />
gr.drawString(ship[i]:getName(), x, y + i*10)<br />
end<br />
end<br />
<br />
=== More information ===<br />
For other keywords you can use with control structures, see the [http://www.lua.org/manual/5.0/manual.html#2.5.2 Lua Documentation]<br />
<br />
For more detailed information on if statements and other types of control structures, see the [http://lua-users.org/wiki/ControlStructureTutorial Lua-users wiki]<br />
<br />
<br />
== Appendices ==<br />
<br />
There's more depth to scripting than what's covered above. To make the rest of the article shorter, I've put the topics still within the scope of this article, but not necessary to know in most cases, down here.<br />
<br />
However, I HIGHLY recommend you read the optimizing scripting section.<br />
<br />
=== Appendix: Optimizing scripting ===<br />
<br />
Because fs2_open is written in C, which is much faster than Lua, it is much better to store variables in C and provide Lua functions to work with them. In addition, to keep Lua scripting from messing with C scripting and to make it as friendly as possible, there are a number of safeguards to catch problems, in most of the Lua functions.<br />
<br />
As a result, whenever you're working with a value provided by a library or object function, you should set it to a Lua variable if you're going to use it more than 1-2 times due to the large overhead resulting from the interface.<br />
<br />
Thus, even though it may [i]look[/i] like "Name" is a member variable of the ship handle, it is actually a function that performs 3-4 validity checks before returning the value, which must also be converted from C to Lua. Setting a variable to the return value of the function means that you can use that variable wherever you want to use the ship name using the native Lua environment.<br />
<br />
=== Appendix: Debugging scripting ===<br />
<br />
Unfortunately, the Lua interpreter provides only limited debugging information about hooks. (Supposedly, it will provide more information about scripting within user functions, but I haven't tested that claim yet)<br />
<br />
Generally, error messages complaining about referencing or indexing a 'nil value' occur because a function could not return a handle, so it returned nil. Some functions also return false to indicate that the handle is correct, but due to some kind of wrong information being passed, it couldn't complete.<br />
<br />
Generally, you should check all handles before using them:<br />
player = getShipByName("Alpha 1")<br />
if player then<br />
<br />
end<br />
<br />
With all uses of the player handle falling in the "if" statement.<br />
<br />
=== Appendix: Function types ===<br />
<br />
Here's all the different kinds of functions you can have:<br />
--A function provided by itself<br />
x = cos(y)<br />
--A function provided by a library<br />
x = Math.cos(y)<br />
--A function provided by a userdata variable.<br />
x = y:cos()<br />
In every case, x would be set to the cosine of y, which is 1.<br />
<br />
<b>Note</b><br />
You must use a ":" with userdata functions, as in the example. This tells Lua that it needs to give the function the value of the variable that it's being called from.<br />
<br />
=== Appendix: Making your own functions ===<br />
So, let's make the doSomething() function do, well, something.<br />
doSomething = function()<br />
color = "red"<br />
end<br />
As you can see, creating a function is much like creating a variable; you just use function() instead of the value, then write what you want the function to do. To end the function, you just write "end"<br />
<br />
Now, let's use our new doSomething() function.<br />
color = "black"<br />
doSomething()<br />
--After using doSomething(), color is now red<br />
<br />
Functions can also '''''return''''' values.<br />
--Make a new function<br />
doSomethingElse = function()<br />
return 10<br />
end<br />
x = 0<br />
doSomething()<br />
--x is now 27<br />
x = doSomethingElse()<br />
--x is now 10<br />
<br />
=== Appendix: Variable Scope ===<br />
The '''''scope''''' of a variable is the area where it exists. Writing <tt>local</tt> in front of the variable name will tell Lua that the variable should only exist within that function or hook.<br />
<br />
Note that this means that if you use the same variable name in two different hooks without using local, the same variable will be used.<br />
<br />
<b>Note</b><br />
You may find it useful to have some way of distinguishing global variables from local ones, to remind yourself that the value does carry over. For example, starting global variable names with "g_".<br />
<br />
<b>Example</b><br />
The following will draw the text "Media VP" in the upper-left corner of the main hall, even though the variable is set in a different hook than it is used in.<br />
<br />
#Global Hooks<br />
$GameInit: [g_mod = "Media VP"]<br />
#End<br />
<br />
#State Hooks<br />
$State: GS_STATE_MAIN_MENU<br />
$Hook: [Graphics.drawString(g_mod, 0, 0)]<br />
#End<br />
<br />
=== Appendix: Variable Types ===<br />
Variables can hold different types of data. These basic types are:<br />
<br />
==== Boolean ====<br />
A boolean is a simple variable - it can be true, or false.<br />
--It's Monday, and Dilbert is at the office<br />
working = true<br />
--Oops, he just opened Solitaire<br />
working = false<br />
<br />
==== Numbers ====<br />
A number is any variable that holds (As you might've guessed) a number. A number will automatically convert into a string, if needed.<br />
--A variable can be a whole number, like this<br />
x = 5<br />
--Or it can be a decimal value<br />
x = 3.141592654<br />
--Or you can divide two numbers for a fraction<br />
x = 3/4<br />
<br />
==== Strings ====<br />
A string is a variable that holds a series of characters, and a character is any number, letter, or symbol on your keyboard (and then some). Basically, strings are the way that words and sentences are passed around in Lua.<br />
--A cow says moo!<br />
cow = "moo"<br />
--A friend's name<br />
friend = "Bob"<br />
Note that actual string content is contained within double quotation marks, to mark it as a string.<br />
<br />
==== nil ====<br />
nil isn't really a variable type, but it is important. nil means that a variable doesn't hold anything. If you want to get rid of a variable, you just set it to be nil.<br />
<br />
--Today I got a new dog<br />
dog = "Spot"<br />
--But then he ran away<br />
dog = nil<br />
<br />
Any time an error says that a variable is nil, it usually means that it doesn't exist (Double-check your spelling).<br />
<br />
==== Userdata/objects ====<br />
Objects (or "userdata", as they are known in Lua) is a variable that can contain other variables, or functions. Variables or functions within an object are known as "member variables" or "member functions".<br />
<br />
--Assuming we have a my_car object, this will copy it to your_car<br />
your_car = my_car<br />
--Congratulations! But maybe you want to customize it?<br />
--Note how I refer to the member variable, color<br />
your_car.color = "Red"<br />
<br />
==== Handles ====<br />
A handle isn't technically a Lua type, but handles are used a lot in FS2_Open Lua scripting. Essentially, a handle is a variable that refers to a specific object; but doesn't actually contain that object's data. An example is the "shipclass" type; it doesn't actually contain the data in ships.tbl, it just serves to reference the ship class so that you can get and set data.<br />
--Get the "GTF Ulysses" ship type<br />
--For this, I use the function 'getShipclassByName'<br />
ulysses = tb.getShipclassByName("GTF Ulysses")<br />
--Now get rid of the handle<br />
ulysses = nil<br />
--Even though we've gotten rid of the handle, the Ulysses will still exist.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Guide_to_FS_Open_on_Linux&diff=1921Guide to FS Open on Linux2006-01-30T06:21:46Z<p>72.194.192.77: </p>
<hr />
<div>This HOWTO was written by bottomfan to help Freespace fans get the latest bleeding-edge version of fs2_open from CVS.<br />
<br />
'''''WARNING! Compling from CVS will let you play with the most recent features and BUGS! Yes, BUGS, compile errors, strange game behavior and/or angry monkeys attacking you. Murphy's Law is very much in effect!'''''<br />
<br />
== Installing CVS ==<br />
CVS stands for Concurrent Versions System and is a version control system used to record the changes in documents, such as a source files. Developers use CVS so they can easily share their code changes among other developers.<br />
You will need this tool to download( "checkout" in CVS termology ) fs2_open from the CVS server.<br />
<br />
Use your package tool supplied by your distribution to download and install CVS.<br />
<br />
Debian users want to:<br />
apt-get install cvs<br />
Gentoo users want to:<br />
emerge cvs<br />
<br />
== Installing Dev Libs ==<br />
You will also need OpenAL, libvorbis, OpenGL(most likely provided with your videocard driver),<br />
and LUA development packages( You dont need LUA if you dont need LUA scripting enabled, it wont go b0rk the compile if it cant find it). <br />
And ofcourse the GCC compiler and requierd make tools.<br />
<br />
Debian want to:<br />
apt-get install libopenal-dev libvorbis-dev build-essential<br />
Gentoo want to:<br />
emerge openal libvorbis<br />
Before you begin, make sure you are situated in a a directory where you have write permissons.<br />
Your /home/user/ directory is pretty much a sure bet. I recommend that you create a permanent home/user/dev directory from which you run the CVS command, this way CVS will only update the files changed the next time you download the source.<br />
<br />
== Using the source ==<br />
<br />
=== Downloading ===<br />
<br />
Now get the source. Run from a terminal:<br />
cvs -d:pserver:anonymous:anonymous@warpcore.org:/home/fs2source/cvsroot loginand then<br />
cvs -z3 -d:pserver:anonymous@warpcore.org:/home/fs2source/cvsroot co fs2_open<br />
The first cvs command tells the CVS tool to first use a password file for authentication( pserver ), that you<br />
are user "anonymous" with the password "anonymous" who wants to access warpcore.org's CVS repository "/home/fs2source/cvsroot" and login.<br />
The second command tells the CVS server on which we are now connected to that we want to checkout( co ) the fs2_open module.<br />
<br />
Because 99,999% of all computer errors can be traced back to human-to-keyboard mishaps<br />
(linguistically proven by yours truly),<br />
I've written a quick bash script that will get the source for you. <br />
<br />
Save this and name it something appropriate like "get-fs2_open", and make it executable( <tt>chmod +x get-fs2_open</tt> ).<br />
#!/bin/bash<br />
# CVS Checkout Script for fs2_open<br />
CVS_ATTEMPT=0<br />
until [ $CVS_ATTEMPT = 1 ]; do<br />
cvs -d:pserver:anonymous:anonymous@warpcore.org:/home/fs2source/cvsroot login && \<br />
cvs -z3 -d:pserver:anonymous:anonymous@warpcore.org:/home/fs2source/cvsroot co fs2_open && \<br />
let CVS_ATTEMPT=1<br />
done<br />
NOTE: This script will run until it successfully downloaded fs2_open, abort it with CTRL+C. <br />
( Originally designed to hammer SourceForge's CVS server )<br />
Run the script from a terminal( <tt>./get-fs2_open</tt>) and wait for it to download the source files.<br />
<br />
=== Building ===<br />
<br />
In the directory you ran the CVS command from, a new directory will appear, namely fs2_open.<br />
From that fs2_open directory run in a terminal:<br />
./autogen.sh<br />
autogen.sh is a script that will generate the required makefiles. You will see alot of "checking for this" and "checking for that", this is actually the "configure" script ( which can be run with <tt>./configure</tt> if you need to change the options) examening and configuring fs2_open for your system.<br />
<br />
Now run:<br />
make <br />
Sit back and enjoy gcc work its magic.<br />
<br />
=== Using the Binaries ===<br />
<br />
When the compile is done and if all went well, a binary executable will reside in the code directory <br />
fs2_open_r or fs2_open_d if you configured for a debug build.<br />
Move the binary to where you got your mediaVP's and your all set to go.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Source_Code_Project_index&diff=4425Source Code Project index2006-01-30T06:11:10Z<p>72.194.192.77: </p>
<hr />
<div>===Getting Started with the Source Code Project===<br />
<br />
[[FSSCP Introduction]]<br />
<br>[[Installing fs2_open]]<br />
<br>[[FS2 data installation]]<br />
<br>[[Installing mods for fs2_open]]<br />
<br>[[Troubleshooting]]<br />
<br>[[Bug Reporting]]<br />
<br />
===Getting Started with Development===<br />
<br>[[Coding In C]]<br />
<br>[[Linux CVS Howto]]<br />
<br />
[[Category:Source Code Project]]</div>72.194.192.77https://wiki.hard-light.org/index.php?title=FS2_Open_Lua_Scripting&diff=1923FS2 Open Lua Scripting2006-01-16T23:33:34Z<p>72.194.192.77: /* Finally, a full example! */</p>
<hr />
<div>This page is intended as a crash-course in Lua scripting as it relates to Freespace 2. It's only meant to get you started with Lua scripting - more advanced concepts such as metatables will not be covered.<br />
<br />
== What You Need ==<br />
You will need a basic understanding of how to open and edit computer files, a copy of Freespace 2, and an open mind. Any kind of prior scripting experience will be immensely helpful, but you shouldn't need any to understand this document.<br />
<br />
Here we go!<br />
<br />
== Comments ==<br />
A "comment" (in any programming or scripting language) is a block of a script that is ignored. In Lua there is only one kind of comment, which starts with double-dashes. Any time you put two dashes in a Lua script outside of a string, the rest of the line will be ignored. (This is the same as putting a double-semicolon in a Freespace table)<br />
<br />
For example, this:<br />
--This is a comment<br />
mn.loadMission("sm2-10.fs2") --Load a mission<br />
--Greetings!<br />
<br />
Will do exactly the same thing as this:<br />
mn.loadMission("sm2-10.fs2")<br />
<br />
== Variables ==<br />
A variable is the simplest kind of thing that there is in Lua. All it really does is hold data; no more, no less. They really aren't that scary. Here is a variable, as it may be seen in the wild:<br />
<br />
x = 42<br />
--x is 42<br />
y = x<br />
--y, copycat that it is, is now also equal to 42<br />
<br />
=== Types ===<br />
However, variables can hold different types of data. These basic types are:<br />
<br />
==== Boolean ====<br />
A boolean is a simple variable - it can be true, or false.<br />
--It's Monday, and Dilbert is at the office<br />
working = true<br />
--Oops, he just opened Solitaire<br />
working = false<br />
<br />
==== Numbers ====<br />
A number is any variable that holds (As you might've guessed) a number. A number will automatically convert into a string, if needed.<br />
--A variable can be a whole number, like this<br />
x = 5<br />
--Or it can be a decimal value<br />
x = 3.141592654<br />
--Or you can divide two numbers for a fraction<br />
x = 3/4<br />
<br />
==== Strings ====<br />
A string is a variable that holds a series of characters, and a character is any number, letter, or symbol on your keyboard (and then some). Basically, strings are the way that words and sentences are passed around in Lua.<br />
--A cow says moo!<br />
cow = "moo"<br />
--A friend's name<br />
friend = "Bob"<br />
Note that actual string content is contained within double quotation marks, to mark it as a string.<br />
<br />
==== nil ====<br />
nil isn't really a variable type, but it is important. nil means that a variable doesn't hold anything. If you want to get rid of a variable, you just set it to be nil.<br />
<br />
--Today I got a new dog<br />
dog = "Spot"<br />
--But then he ran away<br />
dog = nil<br />
<br />
Any time an error says that a variable is nil, it usually means that it doesn't exist (Double-check your spelling).<br />
<br />
==== Userdata/objects ====<br />
Objects (or "userdata", as they are known in Lua) is a variable that can contain other variables, or functions. Variables or functions within an object are known as "member variables" or "member functions".<br />
<br />
--Assuming we have a my_car object, this will copy it to your_car<br />
your_car = my_car<br />
--Congratulations! But maybe you want to customize it?<br />
--Note how I refer to the member variable, color<br />
your_car.color = "Red"<br />
<br />
==== Handles ====<br />
A handle isn't technically a Lua type, but handles are used a lot in FS2_Open Lua scripting. Essentially, a handle is a variable that refers to a specific object; but doesn't actually contain that object's data. An example is the "shipclass" type; it doesn't actually contain the data in ships.tbl, it just serves to reference the ship class so that you can get and set data.<br />
--Get the "GTF Ulysses" ship type<br />
--For this, I use the function 'getShipclassByName'<br />
ulysses = tb.getShipclassByName("GTF Ulysses")<br />
--Now get rid of the handle<br />
ulysses = nil<br />
--Even though we've gotten rid of the handle, the Ulysses will still exist.<br />
<br />
=== Scope ===<br />
The '''''scope''''' of a variable is the area where it exists. By default, all variables exist everywhere; however, if you define your own function, writing 'local' in front of the variable name will tell Lua that the variable should only exist within that function.<br />
<br />
Note that this means that if you make a variable called 'x' in one hook, and a variable called 'x' in another hook, they will actually be the same value.<br />
<br />
== Functions ==<br />
A function is an instruction to Lua to do something. It may change variables, or it may call (activate) other functions.<br />
<br />
For example:<br />
doSomething()<br />
This single line of code would, presumeably tell Lua to do 'something'. What that something is, depends on what the function is supposed to do. Note the two parentheses after the function name; these tell Lua to run the function. (There are reasons to use function names without the parentheses, but that is one of those 'advanced topics')<br />
<br />
Here's all the different kinds of functions you can have:<br />
--A function provided by itself<br />
x = cos(y)<br />
--A function provided by a library<br />
x = ma.cos(y)<br />
--A function provided by an object<br />
x = y:cos()<br />
In every case, x would be set to the cosine of y, which is 1.<br />
<br />
Functions may also have multiple arguments:<br />
gr.drawString("Hello!", 5, 10)<br />
This tells Freespace 2 to draw the string "Hello!" on-screen, starting at the point 5 pixels down from the top of the screen, and 10 pixels from the left of the screen.<br />
<br />
=== Finally, a full example! ===<br />
By this point, you may be bored of all this exposition. So let's actually use variables and functions to do something in Freespace!<br />
<br />
For this amazing trick, we'll make our very own splash screen. Turn off all Freespace 2 mods, and create a file called "scripting.tbl" in your data/tables directory. Open that up in a text editor, and write:<br />
#Global Hooks<br />
$Splash: [<br />
--Set the color to white<br />
gr.setColor(255, 255, 255)<br />
--Write "Hello, world!"<br />
gr.drawString("Hello, world!", 5, 10)<br />
]<br />
#End<br />
<br />
Now, when you start up FS2_Open, you should see "Hello, world!" in the upper-left, as it loads.<br />
<br />
=== Making your own functions (Optional) ===<br />
So, let's make the doSomething() function do, well, something.<br />
doSomething = function()<br />
color = "red"<br />
end<br />
As you can see, creating a function is much like creating a variable; you just use function() instead of the value, then write what you want the function to do. To end the function, you just write "end"<br />
<br />
Now, let's use our new doSomething() function.<br />
color = "black"<br />
doSomething()<br />
--After using doSomething(), color is now red<br />
<br />
Functions can also '''''return''''' values.<br />
--Make a new function<br />
doSomethingElse = function()<br />
return 10<br />
end<br />
x = 0<br />
doSomething()<br />
--x is now 27<br />
x = doSomethingElse()<br />
--x is now 10<br />
<br />
== Libraries ==<br />
A library provides various functions, which may in turn provide various objects or handles with their own functions. All Freespace 2 libraries are named using two letters. "Graphics" is "gr", "Mouse" is "ms", and so on.<br />
<br />
You can see how functions in a graphics are referenced in the "Hello, world!" example above.<br />
<br />
To get a full list of library functions, use the "-output_scripting" command line parameter. This should create a file called scripting.html, with a list of the different libraries and functions supported by that build.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=FS2_Open_Lua_Scripting&diff=1835FS2 Open Lua Scripting2006-01-16T23:32:57Z<p>72.194.192.77: </p>
<hr />
<div>This page is intended as a crash-course in Lua scripting as it relates to Freespace 2. It's only meant to get you started with Lua scripting - more advanced concepts such as metatables will not be covered.<br />
<br />
== What You Need ==<br />
You will need a basic understanding of how to open and edit computer files, a copy of Freespace 2, and an open mind. Any kind of prior scripting experience will be immensely helpful, but you shouldn't need any to understand this document.<br />
<br />
Here we go!<br />
<br />
== Comments ==<br />
A "comment" (in any programming or scripting language) is a block of a script that is ignored. In Lua there is only one kind of comment, which starts with double-dashes. Any time you put two dashes in a Lua script outside of a string, the rest of the line will be ignored. (This is the same as putting a double-semicolon in a Freespace table)<br />
<br />
For example, this:<br />
--This is a comment<br />
mn.loadMission("sm2-10.fs2") --Load a mission<br />
--Greetings!<br />
<br />
Will do exactly the same thing as this:<br />
mn.loadMission("sm2-10.fs2")<br />
<br />
== Variables ==<br />
A variable is the simplest kind of thing that there is in Lua. All it really does is hold data; no more, no less. They really aren't that scary. Here is a variable, as it may be seen in the wild:<br />
<br />
x = 42<br />
--x is 42<br />
y = x<br />
--y, copycat that it is, is now also equal to 42<br />
<br />
=== Types ===<br />
However, variables can hold different types of data. These basic types are:<br />
<br />
==== Boolean ====<br />
A boolean is a simple variable - it can be true, or false.<br />
--It's Monday, and Dilbert is at the office<br />
working = true<br />
--Oops, he just opened Solitaire<br />
working = false<br />
<br />
==== Numbers ====<br />
A number is any variable that holds (As you might've guessed) a number. A number will automatically convert into a string, if needed.<br />
--A variable can be a whole number, like this<br />
x = 5<br />
--Or it can be a decimal value<br />
x = 3.141592654<br />
--Or you can divide two numbers for a fraction<br />
x = 3/4<br />
<br />
==== Strings ====<br />
A string is a variable that holds a series of characters, and a character is any number, letter, or symbol on your keyboard (and then some). Basically, strings are the way that words and sentences are passed around in Lua.<br />
--A cow says moo!<br />
cow = "moo"<br />
--A friend's name<br />
friend = "Bob"<br />
Note that actual string content is contained within double quotation marks, to mark it as a string.<br />
<br />
==== nil ====<br />
nil isn't really a variable type, but it is important. nil means that a variable doesn't hold anything. If you want to get rid of a variable, you just set it to be nil.<br />
<br />
--Today I got a new dog<br />
dog = "Spot"<br />
--But then he ran away<br />
dog = nil<br />
<br />
Any time an error says that a variable is nil, it usually means that it doesn't exist (Double-check your spelling).<br />
<br />
==== Userdata/objects ====<br />
Objects (or "userdata", as they are known in Lua) is a variable that can contain other variables, or functions. Variables or functions within an object are known as "member variables" or "member functions".<br />
<br />
--Assuming we have a my_car object, this will copy it to your_car<br />
your_car = my_car<br />
--Congratulations! But maybe you want to customize it?<br />
--Note how I refer to the member variable, color<br />
your_car.color = "Red"<br />
<br />
==== Handles ====<br />
A handle isn't technically a Lua type, but handles are used a lot in FS2_Open Lua scripting. Essentially, a handle is a variable that refers to a specific object; but doesn't actually contain that object's data. An example is the "shipclass" type; it doesn't actually contain the data in ships.tbl, it just serves to reference the ship class so that you can get and set data.<br />
--Get the "GTF Ulysses" ship type<br />
--For this, I use the function 'getShipclassByName'<br />
ulysses = tb.getShipclassByName("GTF Ulysses")<br />
--Now get rid of the handle<br />
ulysses = nil<br />
--Even though we've gotten rid of the handle, the Ulysses will still exist.<br />
<br />
=== Scope ===<br />
The '''''scope''''' of a variable is the area where it exists. By default, all variables exist everywhere; however, if you define your own function, writing 'local' in front of the variable name will tell Lua that the variable should only exist within that function.<br />
<br />
Note that this means that if you make a variable called 'x' in one hook, and a variable called 'x' in another hook, they will actually be the same value.<br />
<br />
== Functions ==<br />
A function is an instruction to Lua to do something. It may change variables, or it may call (activate) other functions.<br />
<br />
For example:<br />
doSomething()<br />
This single line of code would, presumeably tell Lua to do 'something'. What that something is, depends on what the function is supposed to do. Note the two parentheses after the function name; these tell Lua to run the function. (There are reasons to use function names without the parentheses, but that is one of those 'advanced topics')<br />
<br />
Here's all the different kinds of functions you can have:<br />
--A function provided by itself<br />
x = cos(y)<br />
--A function provided by a library<br />
x = ma.cos(y)<br />
--A function provided by an object<br />
x = y:cos()<br />
In every case, x would be set to the cosine of y, which is 1.<br />
<br />
Functions may also have multiple arguments:<br />
gr.drawString("Hello!", 5, 10)<br />
This tells Freespace 2 to draw the string "Hello!" on-screen, starting at the point 5 pixels down from the top of the screen, and 10 pixels from the left of the screen.<br />
<br />
=== Finally, a full example! ===<br />
By this point, you may be bored of all this exposition. So let's actually use variables and functions to do something in Freespace!<br />
<br />
For this amazing trick, we'll make our very own splash screen. Turn off all Freespace 2 mods, and create a file called "scripting.tbl" in your data/tables directory. Open that up in a text editor, and write:<br />
#Global Hooks<br />
$Splash: [<br />
--Set the color to white<br />
gr.setColor(255, 255, 255)<br />
--Write "Hello, world!"<br />
gr.drawString("Hello, world!", 5, 10)<br />
]<br />
#End<br />
<br />
Now, when you start up FS2_Open, you should see "Hello, world!" in the upper-left, as it loads.<br />
<br />
=== Making your own functions (Optional) ===<br />
So, let's make the doSomething() function do, well, something.<br />
doSomething = function()<br />
color = "red"<br />
end<br />
As you can see, creating a function is much like creating a variable; you just use function() instead of the value, then write what you want the function to do. To end the function, you just write "end"<br />
<br />
Now, let's use our new doSomething() function.<br />
color = "black"<br />
doSomething()<br />
--After using doSomething(), color is now red<br />
<br />
Functions can also '''''return''''' values.<br />
--Make a new function<br />
doSomethingElse = function()<br />
return 10<br />
end<br />
x = 0<br />
doSomething()<br />
--x is now 27<br />
x = doSomethingElse()<br />
--x is now 10<br />
<br />
== Libraries ==<br />
A library provides various functions, which may in turn provide various objects or handles with their own functions. All Freespace 2 libraries are named using two letters. "Graphics" is "gr", "Mouse" is "ms", and so on.<br />
<br />
You can see how functions in a graphics are referenced in the "Hello, world!" example above.<br />
<br />
To get a full list of library functions, use the "-output_scripting" command line parameter. This should create a file called scripting.html, with a list of the different libraries and functions supported by that build.</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Talk:Feature_Requests&diff=1604Talk:Feature Requests2005-12-27T01:09:19Z<p>72.194.192.77: </p>
<hr />
<div>Excuse me, but should this be not in the SCP forum or the SCP website? Things like these do not beling to wikis. - [[User:TopAce|TopAce]] 19:15, 10 Dec 2005 (GMT)<br />
<br />
The problem is that adding it to the SCP site would require a special PHP script, and a thread on the forums quickly becomes cluttered by irrelevant posts and discussions on the features. It also serves as a reference for feature requests...not the ideal solution, but the simplest one. [[User:72.194.192.77|72.194.192.77]] 01:09, 27 Dec 2005 (GMT)</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Scripting_API&diff=2017Scripting API2005-12-14T20:21:40Z<p>72.194.192.77: </p>
<hr />
<div>The FS2_Open scripting API is intended to be as cross-platform and as language non-specific as possible. However, it is generally assumed that the most popular language will be Lua.<br />
<br />
== Code Description ==<br />
<br />
===Part One: Basic API and Scripting Hooks ===<br />
====Things To Know====<br />
;script_system:This object abstracts a scripting session. It is generally used to allow for easy construction/destruction of whatever is necessary to initialize scripting system objects, and make sure that the right language session data is passed. Its constructor takes one argument, the name of the scripting session (for easy debugging)<br />
;script_system->CreateLuaSession(libraries):Initializes a Lua session. Until this is called, you will not be able to use Lua at all and fs2_open should ignore code chunks that use it.<br />
;script_system->ParseChunk(debugname):Parses a 'code chunk'. These are snippets of code encapsulated by symbols such as square brackets or parentheses. It stores a handle to the parsed script in memory (Probably bytecode).<br />
:script_system->RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk<br />
====Example====<br />
This snippet of code (using FS2_Open functions) will parse a file that has scripting after each "$Global:" variable identifier. After all the scripting has been parsed, it will evaluate every hook, once.<br />
script_system Script_system;<br />
std::vector<script_hook> Script_globalhooks;<br />
<br />
//Initialize Lua<br />
Script_system.CreateLuaState(Lua_libraries);<br />
<br />
//Parse file<br />
read_file_text("scripting.tbl");<br />
reset_parse();<br />
while(optional_string("$Global:"))<br />
{<br />
Script_globalhooks.push_back(st->ParseChunk());<br />
}<br />
<br />
//Execute hooks<br />
for(uint i = 0; i < Script_globalhooks.size(); i++)<br />
{<br />
Script_system.RunBytecode(Script_globalhooks[i]);<br />
}<br />
<br />
===Part Two: The Higher-Level Lua Library===<br />
====Things To Know====<br />
;script_lua_func_list:A function list array, used to store the name, function pointer, and descriptive text for library functions.<br />
;script_lua_obj_func_list:Same as a function list, except for object member functions and operators<br />
;script_lua_obj_list:An object list array, used to store the name, function object list, and descriptive text for objects.<br />
;script_lua_lib_list:A library function/object list, used to store the library name, function list, object list, and descriptive text. It can then be used to create a Lua session by passing it to CreateLuaSession()<br />
;SCRIPT_END_LIST:Ends the above lists<br />
;lua_cvar<>:A template used as an easy way of ensuring that a given object in Lua has the correct name and type everywhere.<br />
;LUA_OPER_*:A series of defines that can be used in place of an object member function name in the list, to cause the callback function to be used when that operator is present. Not very reliable right now.<br />
;script_lua_callback:Return value for a Lua callback function (ie a C function that is called from Lua)<br />
;script_parse_args:Call from within a Lua function callback to convert the passed arguments to C variables. Uses a format string to check for correct arguments and variable type, followed by pointers to the destination variables. The following list shows formatting characters, followed by the Lua value and the C variable type that must be passed for the value to be stored.<br />
:'b' - boolean (bool*)<br />
:'d' - number (double*)<br />
:'f' - number (float*)<br />
:'i' - number (int*)<br />
:'o' - object (uses the lua_cvar variable's Parse() function with *object)<br />
:'p' - object pointer (uses the lua_cvar variables ParsePtr() function with **object, where object is the actual one allocated by Lua)<br />
:'s' - string (char**)<br />
:'|' - specifies that all arguments after this are optional.<br />
;script_return_args:Call from with a Lua function callback to convert the passed arguments to C variables. Uses the same format as script_parse_args, except that objects use Return() instead of Parse(), and 'p' is not supported.<br />
;LUA_RETURN_NOTHING:A define used for when a function doesn't use script_return_args<br />
<br />
====Example====<br />
A (very small) math library, that provides the function 'math.lvec(x,y,z)'. After this example you could then pass Lua_libraries to CreateLuaSession() to access the function.<br />
//Define the local-vector object<br />
static lua_cvar<vec3d> l_lvec("lvec");<br />
<br />
//Define the callback function<br />
script_lua_callback lua_fs2_lvec(lua_State *L)<br />
{<br />
vec3d v3 = vmd_zero_vector;<br />
script_parse_args(L, "|fff", &v3.xyz.x, &v3.xyz.y, &v3.xyz.z);<br />
<br />
//Note that script_return_args with the "o" parameter creates a new object in Luaspace<br />
//which is managed by Lua<br />
return script_return_args(L, "o", l_lvec.Return(&v3));<br />
}<br />
<br />
//For this example, lvec has no member functions<br />
static const script_lua_obj_func_list lua_math_lvec_funcs[] = {<br />
{SCRIPT_END_LIST},<br />
};<br />
<br />
//Add the callback to the library's function list<br />
static const script_lua_func_list lua_math_lib[] = {<br />
{"lvec", lua_fs2_lvec, "Creates a new local vector","number,number,number","lvec"},<br />
{SCRIPT_END_LIST},<br />
};<br />
<br />
//Add the object to the library's object list<br />
static const script_lua_obj_list lua_math_lib_obj[] = {<br />
{l_lvec.GetName(), lua_math_lvec_funcs, "Local vector"},<br />
{SCRIPT_END_LIST},<br />
};<br />
<br />
//Add the library function and object lists to Lua_libraries<br />
const script_lua_lib_list Lua_libraries[] = {<br />
{"math", lua_math_lib, lua_math_lib_obj, "Math library"},<br />
{SCRIPT_END_LIST},<br />
};</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Scripting_API&diff=1302Scripting API2005-12-14T19:38:53Z<p>72.194.192.77: Initial page</p>
<hr />
<div>The FS2_Open scripting API is intended to be as cross-platform and as language non-specific as possible. However, it is generally assumed that the most popular language will be Lua.<br />
<br />
== Code Description ==<br />
<br />
===Part One: Basic API and Scripting Hooks ===<br />
====Things To Know====<br />
;script_system:This object abstracts a scripting session. It is generally used to allow for easy construction/destruction of whatever is necessary to initialize scripting system objects, and make sure that the right language session data is passed. Its constructor takes one argument, the name of the scripting session (for easy debugging)<br />
;script_system->CreateLuaSession(libraries):Initializes a Lua session. Until this is called, you will not be able to use Lua at all and fs2_open should ignore code chunks that use it.<br />
;script_system->ParseChunk(debugname):Parses a 'code chunk'. These are snippets of code encapsulated by symbols such as square brackets or parentheses. It stores a handle to the parsed script in memory (Probably bytecode).<br />
;script_system->RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk<br />
====Example====<br />
This snippet of code (using FS2_Open functions) will parse a file that has scripting after each "$Global:" variable identifier. After all the scripting has been parsed, it will evaluate every hook, once.<br />
script_system Script_system;<br />
std::vector<script_hook> Script_globalhooks;<br />
<br />
//Initialize Lua<br />
Script_system.CreateLuaState(Lua_libraries);<br />
<br />
//Parse file<br />
read_file_text("scripting.tbl");<br />
reset_parse();<br />
while(optional_string("$Global:"))<br />
{<br />
Script_globalhooks.push_back(st->ParseChunk());<br />
}<br />
<br />
//Execute hooks<br />
for(uint i = 0; i < Script_globalhooks.size(); i++)<br />
{<br />
Script_system.RunBytecode(Script_globalhooks[i]);<br />
}</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Development_Reference&diff=1788Development Reference2005-12-14T19:17:09Z<p>72.194.192.77: </p>
<hr />
<div>[[Scripting API]]</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Main_Page&diff=1463Main Page2005-12-14T19:16:50Z<p>72.194.192.77: </p>
<hr />
<div><p style="margin: 0.5em 0 0; text-align: center; <br />
font-size: 125%; line-height: 1.3"><br />
'''Welcome to the Freespace Wiki, the ultimate source for Freespace info on the web.'''<br />
</p><br />
<br />
<br />
<br />
{| border=0 align=right cellpadding=4 cellspacing=0 width=30% style="margin: 0 0 1em 1em; background: #404040; border: 1px <br />
<br />
#CC0500 solid; border-collapse: collapse; font-size: 95%;"<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Retail Freespace''<br />
|-<br />
| [[Portal:Freespace 1|Freespace 1]]<br />
|-<br />
| [[Portal:Freespace 2|Freespace 2]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Freespace Source Code Project''<br />
|-<br />
| [[Getting Started(Main)|Getting Started]]<br />
|-<br />
| [[Multiplayer(Main)|Multiplayer]]<br />
|-<br />
| [[Command-Line_Reference|Command-Line Reference]]<br />
|-<br />
| [[Development_Reference|Development Reference]]<br />
|-<br />
| [[Feature Requests|Feature Requests]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Modding Freespace''<br />
|-<br />
| [[Portal:Modding|General Modding]]<br />
|-<br />
| [[User-made_Campaigns|User-made Campaigns]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Freespace Universe''<br />
|-<br />
| [[Portal:FS Universe|The Universe]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Other''<br />
|-<br />
| [[Freespace Lingo]]<br />
|-<br />
| [[Freespace_Wiki:Community_Portal|Freespace Community]]<br />
|-<br />
| [[Getting Freespace]]<br />
|-<br />
| [[BitTorrent(Main)|BitTorrent]]<br />
|-<br />
! style="color: white; height: 30px; background: #462424; 70%;"|Alternately, explore the '''FreeSpace''' universe through ''[[Special:Categories|categories]].''<br />
|-<br />
|}<br />
<br />
The Freespace Wiki is designed to be a comprehensive source of data for the Freespace series of games, including information about the games themselves, the Freespace universe, and community activities, such as modding and the Source Code Project. It also contains help with some of the more common problems, such as setting up multiplayer and obtaining the freespace games, which can be quite difficult in stores.<br />
<br />
Anyone can edit the Freespace Wiki, and we encourage you to do so, but please read our [[canon|Canon Policy]] for information on what sort of data should be submitted, and how to submit it, before you begin.<br />
<br />
{| border=0 align=left cellpadding=4 cellspacing=0 width=65% style="margin: 0 0 1em 1em; background: #404040; border: 1px <br />
<br />
#CC0500 solid; border-collapse: collapse; font-size: 95%;"<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Featured Article of the Moment''<br />
|-<br />
|{{Featured Article}}<br />
|}</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Modular_Tables&diff=1402Modular Tables2005-12-10T08:29:11Z<p>72.194.192.77: </p>
<hr />
<div>Modular tables are SCP addition to the standard FreeSpace table system. XMTs (or eXtentable Modular Tables) offer capability to add new entries or alter already existing tables without any need of editing the 'parent' table file.<br />
<br />
==Extentable Tables==<br />
*[[armor.tbl]] can be extended with '''xxx-amr.tbm file''' (non-XMT)<br />
*[[hud_gauges.tbl]] can be extended with '''xxx-hdg.tbm file''' (non-XMT)<br />
*[[music.tbl]] can be extended with '''xxx-mus.tbm file''' (non-XMT)<br />
*[[Ships.tbl]] can be extented with '''xxx-shp.tbm file''' (XMT)<br />
*[[Weapons.tbl]] can be extended with '''xxx-wep.tbm file''' (XMT)<br />
*[[Weapon_expl.tbl]] can be extended with '''xxx-wxp.tbm file''' (non-XMT)<br />
<br />
==Important Notes==<br />
*Modular table files should use the 'parent table' files sections.<br />
*Completely new entries and also complete rewrites of entries in parent table file are always possible.<br />
*For '''xxx-shp.tbl''' and '''xxx-wep.tbl'''<br />
**Table entries in modular tables do not have to be complete. Partial entries can be used to alter the data found in parent table files when only some changes to the original are desired to be made.<br />
**Adding '''+nocreate''' right after the entry's name prevents possible creation of partially undefined entry. For example if the parent table file lacked the entry that was included to the as a partial entry to the modular table file then the creation of partially undefined entry is possible which could cause problems with the game.<br />
***Example:<br />
<br />
$Name: @Subach HL-7<br />
+nocreate<br />
<br />
==Sample - Alpha-wep.tbm==<br />
*Changes the speed of the ''Subach HL-7'' and also adds a faint grey trail to it.<br />
<br />
#Primary Weapons<br />
$Name: @Subach HL-7<br />
+nocreate<br />
$Velocity: 650.0 <br />
$Trail:<br />
+Start Width: 0.4<br />
+End Width: 0.0<br />
+Start Alpha: 0.35<br />
+End Alpha: 0.0<br />
+Max Life: 0.2<br />
+Bitmap: Contrail<br />
#End<br />
<br />
<br />
[[Category:Tables]]</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Feature_Requests&diff=1254Feature Requests2005-12-09T08:54:44Z<p>72.194.192.77: </p>
<hr />
<div>This page is primarily to serve as a database for feature requests for the Source Code Project.<br />
<br />
== Side Multipart Turrets ==<br />
Support for fully rotating turrets on the sides of ships.<br />
* '''Supported By:''' Battlestar Galactica, The Babylon Project<br />
<br />
<br />
== Customizable ship types ==<br />
Add a new table (or an addendum to ships.tbl) that would allow modders to turn on and off individual aspects of ship types, as well as define new ones. Type should be settable in the $Flags: variable, just as it is now, and the :V: defaults should be integrated so that they may be overriden by mods.<br />
* '''Supported By:''' ???</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Feature_Requests&diff=1253Feature Requests2005-12-09T08:54:24Z<p>72.194.192.77: </p>
<hr />
<div>This page is primarily to serve as a database for feature requests for the Source Code Project.<br />
<br />
== Side Multipart Turrets ==<br />
Support for fully rotating turrets on the sides of ships.<br />
* '''Supported By:''' Battlestar Galactica, The Babylon Project<br />
<br />
== Customizable ship types ==<br />
Add a new table (or an addendum to ships.tbl) that would allow modders to turn on and off individual aspects of ship types, as well as define new ones. Type should be settable in the $Flags: variable, just as it is now, and the :V: defaults should be integrated so that they may be overriden by mods.<br />
* '''Supported By:''' ???</div>72.194.192.77https://wiki.hard-light.org/index.php?title=Main_Page&diff=1301Main Page2005-12-09T08:46:44Z<p>72.194.192.77: </p>
<hr />
<div><p style="margin: 0.5em 0 0; text-align: center; <br />
font-size: 125%; line-height: 1.3"><br />
'''Welcome to the Freespace Wiki, the ultimate source for Freespace info on the web.'''<br />
</p><br />
<br />
<br />
<br />
{| border=0 align=right cellpadding=4 cellspacing=0 width=30% style="margin: 0 0 1em 1em; background: #404040; border: 1px <br />
<br />
#CC0500 solid; border-collapse: collapse; font-size: 95%;"<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Retail Freespace''<br />
|-<br />
| [[Portal:Freespace 1|Freespace 1]]<br />
|-<br />
| [[Portal:Freespace 2|Freespace 2]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Freespace Source Code Project''<br />
|-<br />
| [[Getting Started(Main)|Getting Started]]<br />
|-<br />
| [[Multiplayer(Main)|Multiplayer]]<br />
|-<br />
| [[Command-Line_Reference|Command-Line Reference]]<br />
|-<br />
| [[Feature Requests|Feature Requests]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Modding Freespace''<br />
|-<br />
| [[Portal:Modding|General Modding]]<br />
|-<br />
| [[User-made_Campaigns|User-made Campaigns]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Freespace Universe''<br />
|-<br />
| [[Portal:FS Universe|The Universe]]<br />
|-<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Other''<br />
|-<br />
| [[Freespace Lingo]]<br />
|-<br />
| [[Freespace_Wiki:Community_Portal|Freespace Community]]<br />
|-<br />
| [[Getting Freespace]]<br />
|-<br />
| [[BitTorrent(Main)|BitTorrent]]<br />
|-<br />
! style="color: white; height: 30px; background: #462424; 70%;"|Alternately, explore the '''FreeSpace''' universe through ''[[Special:Categories|categories]].''<br />
|-<br />
|}<br />
<br />
The Freespace Wiki is designed to be a comprehensive source of data for the Freespace series of games, including information about the games themselves, the Freespace universe, and community activities, such as modding and the Source Code Project. It also contains help with some of the more common problems, such as setting up multiplayer and obtaining the freespace games, which can be quite difficult in stores.<br />
<br />
Anyone can edit the Freespace Wiki, and we encourage you to do so, but please read our [[canon|Canon Policy]] for information on what sort of data should be submitted, and how to submit it, before you begin.<br />
<br />
{| border=0 align=left cellpadding=4 cellspacing=0 width=65% style="margin: 0 0 1em 1em; background: #404040; border: 1px <br />
<br />
#CC0500 solid; border-collapse: collapse; font-size: 95%;"<br />
! style="color: white; height: 30px; background: #613030; 70%;"|''Featured Article of the Moment''<br />
|-<br />
|{{Featured Article}}<br />
|}</div>72.194.192.77