Scripting API - Revision history

Lafiel at 11:33, 20 January 2023

2023-01-20T11:33:04Z

← Older revision		Revision as of 11:33, 20 January 2023
Line 1:		Line 1:
	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.		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.

			NOTE: This page is about how the Scripting API works internally. If you are here to learn how to ''use'' it, see [[FS2_Open_Lua_Scripting\|FS2 Open Lua Scripting]]

	=New System (HEAD)=		=New System (HEAD)=

Snail: In case you were wondering, Freespace => FreeSpace

2009-02-11T22:24:12Z

In case you were wondering, Freespace => FreeSpace

← Older revision		Revision as of 22:24, 11 February 2009
Line 68:		Line 68:

	# Go to the place in the code you want the action to be triggered.		# Go to the place in the code you want the action to be triggered.
	# Call IsConditionOverride(action #define) to determine if the modder wants to override the retail ~~Freespace~~ 2 action. By convention, conditional hooks also override any other types of hooks, and IsConditionOverride should come '''before''' everything else.		# Call IsConditionOverride(action #define) to determine if the modder wants to override the retail FreeSpace 2 action. By convention, conditional hooks also override any other types of hooks, and IsConditionOverride should come '''before''' everything else.
	## If this action involves an object (Like rendering a ship), pass the pointer to the object using the second argument to IsConditionOverride(). This will be used to check any conditions specified.		## If this action involves an object (Like rendering a ship), pass the pointer to the object using the second argument to IsConditionOverride(). This will be used to check any conditions specified.
	# Call Script_system.RunCondition(action #define) to actually run the method. By convention, this should be called after the retail ~~Freespace~~ 2 action or other types of hooks, so the modder can change anything he doesn't like.		# Call Script_system.RunCondition(action #define) to actually run the method. By convention, this should be called after the retail FreeSpace 2 action or other types of hooks, so the modder can change anything he doesn't like.
	## If you want the modder to be able to return a value, define a type using the format character (2nd argument) and a destination buffer with the data variable (3rd argument). If you want to pass an object, but don't want to involve a return value, set these fields to '\0' and NULL, respectively.		## If you want the modder to be able to return a value, define a type using the format character (2nd argument) and a destination buffer with the data variable (3rd argument). If you want to pass an object, but don't want to involve a return value, set these fields to '\0' and NULL, respectively.
	## If this action involves an object (Like rendering a ship), don't forget to pass the pointer to the objp argument (4th argument).		## If this action involves an object (Like rendering a ship), don't forget to pass the pointer to the objp argument (4th argument).
Line 164:		Line 164:

	===lua_lib===		===lua_lib===
	lua_lib l_Base("Base", "ba", "Base ~~Freespace~~ 2 functions");		lua_lib l_Base("Base", "ba", "Base FreeSpace 2 functions");
	Defines a Lua library, which can contain member functions (But not any kind of variables).		Defines a Lua library, which can contain member functions (But not any kind of variables).

Line 172:		Line 172:
	===lua_obj===		===lua_obj===
	lua_obj<object_h> l_Ship("ship", "Ship object", &l_Object);		lua_obj<object_h> l_Ship("ship", "Ship object", &l_Object);
	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.		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.

	The next two parameters are fairly obvious - the name of the object (becomes the metatable name), and the description in output_scripting.		The next two parameters are fairly obvious - the name of the object (becomes the metatable name), and the description in output_scripting.

TopAce at 18:58, 24 September 2008

2008-09-24T18:58:48Z

← Older revision		Revision as of 18:58, 24 September 2008
Line 289:		Line 289:

	In all other respects, it is exactly like LUA_VAR; use LUA_SETTING_VAR to determine whether you are in setting mode or not.		In all other respects, it is exactly like LUA_VAR; use LUA_SETTING_VAR to determine whether you are in setting mode or not.

			[[Category:Source Code Project]]

WMCoolmon: Partial update with info from Ade

2007-03-19T02:03:44Z

Partial update with info from Ade

@@ Line 1: / Line 1: @@
 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.
 ==Part One: Basic API and Scripting Hooks ==
 ===Things To Know===

72.194.192.77 at 07:36, 13 February 2006

2006-02-13T07:36:41Z

Show changes

72.194.192.77 at 20:21, 14 December 2005

2005-12-14T20:21:40Z

@@ Line 8: / Line 8: @@
 ;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.
 ;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).
-;script_system->RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk
+:script_system->RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk
 ====Example====
 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.
@@ Line 30: / Line 30: @@
   	Script_system.RunBytecode(Script_globalhooks[i]);
+  }

72.194.192.77: Initial page

2005-12-14T19:38:53Z

Initial page

New page

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.

== Code Description ==

===Part One: Basic API and Scripting Hooks ===
====Things To Know====
;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)
;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.
;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).
;script_system->RunBytecode(handle):Actually executes a code chunk that has been parsed with ParseChunk
====Example====
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.
script_system Script_system;
std::vector<script_hook> Script_globalhooks;

//Initialize Lua
Script_system.CreateLuaState(Lua_libraries);

//Parse file
read_file_text("scripting.tbl");
reset_parse();
while(optional_string("$Global:"))
{
Script_globalhooks.push_back(st->ParseChunk());
}

//Execute hooks
for(uint i = 0; i < Script_globalhooks.size(); i++)
{
Script_system.RunBytecode(Script_globalhooks[i]);
}