FS2 Open Lua Scripting - Revision history

Lafiel: /* Custom SEXPs */ Whoops, fix custom sexp docs

2026-01-10T00:34:50Z

Custom SEXPs: Whoops, fix custom sexp docs

← Older revision		Revision as of 00:34, 10 January 2026
Line 184:		Line 184:
	This table basically means that we now have a new SEXP called <tt>example-script-sexp</tt> which takes a single string as an argument.		This table basically means that we now have a new SEXP called <tt>example-script-sexp</tt> which takes a single string as an argument.
	To actually run scripting code, we now need to register a function with the SEXP. This is done by assigning <tt>mn.LuaSEXPs[<SEXP name>]</tt> a function that takes the same parameters as specified in the SEXP table. For this example, this would be:		To actually run scripting code, we now need to register a function with the SEXP. This is done by assigning <tt>mn.LuaSEXPs[<SEXP name>]</tt> a function that takes the same parameters as specified in the SEXP table. For this example, this would be:
	mn.LuaSEXPs["example-script-sexp"] = function(message)		mn.LuaSEXPs["example-script-sexp"].Action = function(message)
	--message is a string		--message is a string
	ba.warning(message)		ba.warning(message)

Goober5000: /* +Override: Make FSO ignore things */ clarify syntax

2024-03-11T03:13:18Z

+Override: Make FSO ignore things: clarify syntax

← Older revision		Revision as of 03:13, 11 March 2024
Line 224:		Line 224:
	This section details situations where certain FSO-specific tricks are required or very helpful to complete a certain task.		This section details situations where certain FSO-specific tricks are required or very helpful to complete a certain task.
	====+Override: Make FSO ignore things====		====+Override: Make FSO ignore things====
	As you may have noticed, the hooks in scripting.html specify whether they are ''overridable'' or not. In this context, overridable means that we can tell FSO to pretend that whatever caused the action to activate didn’t actually occur. In the example with the afterburner weapon, an override would cause the weapon to ''not actually collide'' with the ship it hit, just passing through it. To override a hook, after your normal script block, add <tt>+Override:</tt>, and then add another block of code. This block of code should return a boolean. If it returns true, the hook will be overridden. If it returns false, FSO proceeds as normal.		As you may have noticed, the hooks in scripting.html specify whether they are ''overridable'' or not. In this context, overridable means that we can tell FSO to pretend that whatever caused the action to activate didn’t actually occur. In the example with the afterburner weapon, an override would cause the weapon to ''not actually collide'' with the ship it hit, just passing through it. To override a hook, after your normal script block, add <tt>+Override:</tt>, and then add another block of code. This block of code should return a boolean. If it returns true, the hook will be overridden. If it returns false, FSO proceeds as normal. Here is an example from Blighted:
			$On Ship Collision: [ HUD_OnShipCollision() ]
			+Override: [ return ENEMIES_OnCollisionOverride() ]
			Note that these are two different blocks of code: <code>HUD_OnShipCollision()</code> is the normal behavior for this hook, but <code>return ENEMIES_OnCollisionOverride()</code> determines whether the hook actually runs.

			Incidentally, '''+Override:''' does not require the normal script block to have any code in it. The following will randomly disable ship collisions 50% of the time:
			$On Ship Collision: []
			+Override: [ return ba.rand32f() < 0.5 ]

	====Repeating SEXP Arguments====		====Repeating SEXP Arguments====
	The SEXP table can contain the <tt>$Repeat</tt> tag. It implies that all arguments following the tag can be repeated in FRED up to the argument maximum. If that is the case, special care needs to be taken on the Lua side to accommodate the repeating arguments.		The SEXP table can contain the <tt>$Repeat</tt> tag. It implies that all arguments following the tag can be repeated in FRED up to the argument maximum. If that is the case, special care needs to be taken on the Lua side to accommodate the repeating arguments.

Goober5000: /* Avoid runSEXP */

2023-01-25T04:19:43Z

Avoid runSEXP

← Older revision		Revision as of 04:19, 25 January 2023
Line 362:		Line 362:
	This is a short section on how we prefer to style our scripts for FSO. Some of these are performance relevant, while others are more for a better level of organization.		This is a short section on how we prefer to style our scripts for FSO. Some of these are performance relevant, while others are more for a better level of organization.
	===Avoid runSEXP===		===Avoid runSEXP===
	If you can, avoid evaluateSEXP, evaluateNumericSEXP and runSEXP. These are comparably slow, as they require ~~a lot of~~ text processing, and ~~are~~ a more error prone than just doing everything in script. If you find you ~~cannot avoid~~ them ~~for one reason~~ or ~~another~~, consider adding a feature request on the SCP's GitHub page to add the missing functionality to the scripting API.		If you can, avoid evaluateSEXP, evaluateNumericSEXP and runSEXP. These are comparably slow, as they require both text processing and the assembling of a SEXP node tree. They can also be more error prone than just doing everything in a script. Using them occasionally is not necessarily a bad thing (and many existing scripts use them without a problem), but if you find you are using them frequently or in high-performance situations, consider adding a feature request on the SCP's GitHub page to add the missing functionality to the scripting API.

	===Make everything a local===		===Make everything a local===
	If you have a function or a piece of code that regularly accesses the same variable, consider making a <tt>local</tt> copy of it. For things such as access to FSO’s API, this can be a lot faster since calls to the API are generally accompanied by safety checks or even expensive calculations. But even when accessing a subtable of a Lua object or a global variable, it can often be faster to copy it to a local and then use that local		If you have a function or a piece of code that regularly accesses the same variable, consider making a <tt>local</tt> copy of it. For things such as access to FSO’s API, this can be a lot faster since calls to the API are generally accompanied by safety checks or even expensive calculations. But even when accessing a subtable of a Lua object or a global variable, it can often be faster to copy it to a local and then use that local

Goober5000: /* Keep your Script’s Code in a Table */ bit of clarity

2023-01-25T04:12:14Z

Keep your Script’s Code in a Table: bit of clarity

← Older revision		Revision as of 04:12, 25 January 2023
Line 367:		Line 367:
	===Setup functions in On Game Init===		===Setup functions in On Game Init===
	This one is less performance relevant, but it has been somewhat established that scripts try to keep most of their code in function definitions that are run in On Game Init, which are then just called in each hook’s code, instead of having all the code in the hook itself.		This one is less performance relevant, but it has been somewhat established that scripts try to keep most of their code in function definitions that are run in On Game Init, which are then just called in each hook’s code, instead of having all the code in the hook itself.
	===Keep your Script’s Code in a Table===		===Keep your Script’s Code in a Lua Table===
	Try to avoid saving a lot of variables or functions to the global ~~variable space~~. Since the global namespace is shared among all scripts, it is easy to accidentally overwrite another script’s variable or function otherwise. It is recommended that all scripts have exactly one overarching table, and then declare functions and variables for the script as objects of this table.		Try to avoid saving a lot of variables or functions in the global scope. Since the global namespace is shared among all scripts, it is easy to accidentally overwrite another script’s variable or function otherwise. It is recommended that all scripts have exactly one overarching Lua table, and then declare functions and variables for the script as objects of this table.

Lafiel at 18:16, 24 January 2023

2023-01-24T18:16:16Z

← Older revision		Revision as of 18:16, 24 January 2023
Line 314:		Line 314:
	end		end

	For the SEXP-Table side, see [Dynamic_SEXPs#.23Lua_AI here].		For the SEXP-Table side, see [[Dynamic_SEXPs#.23Lua_AI\|here]].

	===Common Pitfalls===		===Common Pitfalls===

Lafiel: Major revamp of the Scripting Tutorial, now a lot more focussed on FSO's API and common pitfalls and use cases

2023-01-20T11:29:21Z

Major revamp of the Scripting Tutorial, now a lot more focussed on FSO's API and common pitfalls and use cases

Show changes

TopAce: it's still NOT "Freespace"

2022-11-28T22:35:32Z

it's still NOT "Freespace"

← Older revision		Revision as of 22:35, 28 November 2022
Line 1:		Line 1:
	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.		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.

	You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.		You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.
Line 6:		Line 6:

	== What You Need ==		== What You Need ==
	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.		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.

	Here we go!		Here we go!
Line 39:		Line 39:

	== Comments ==		== Comments ==
	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)		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)

	For example, this:		For example, this:
Line 153:		Line 153:
	By this point, you may be bored of all this exposition. So here's your typical "Hello, World!" example.		By this point, you may be bored of all this exposition. So here's your typical "Hello, World!" example.

	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:		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:
	#Conditional Hooks		#Conditional Hooks
	$Version: 3.7		$Version: 3.7

Echelon9: Reflect source code hosting via Git

2015-05-03T05:07:13Z

Reflect source code hosting via Git

← Older revision		Revision as of 05:07, 3 May 2015
Line 3:		Line 3:
	You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.		You don't need to read the Appendices, but I recommend at least reading the "Optimizing" section if you're doing much scripting.

	<p>'''IMPORTANT: This page was last updated on 5/27/2007 and assumes you are using the most up-to-date build at that time, [http://www.hard-light.net/forums/index.php/topic,47201.0.html C05202007]. There may be slight syntax differences with significantly newer or older builds. You should also make sure you are using a build ~~from the Unstable/HEAD CVS branch~~.'''</p>		<p>'''IMPORTANT: This page was last updated on 5/27/2007 and assumes you are using the most up-to-date build at that time, [http://www.hard-light.net/forums/index.php/topic,47201.0.html C05202007]. There may be slight syntax differences with significantly newer or older builds. You should also make sure you are using a development build.'''</p>

	== What You Need ==		== What You Need ==

TopAce: If it's scripting, it must be SCP-related. Haven't read the article

2008-09-24T18:09:00Z

If it's scripting, it must be SCP-related. Haven't read the article

← Older revision		Revision as of 18:09, 24 September 2008
Line 370:		Line 370:
	* [http://www.lua.org/pil/ Programming in Lua]		* [http://www.lua.org/pil/ Programming in Lua]
	* [http://www.lua-users.org/ lua-users.org]		* [http://www.lua-users.org/ lua-users.org]

			[[Category:Source Code Project]]

WMCoolmon: Updated page to reflect changes in newer builds

2007-05-27T07:29:44Z

Updated page to reflect changes in newer builds

Show changes