Loading function...

Please make sure JavaScript is enabled. Otherwise you will be unable to see the function documentation.

This is a header function, meaning it is meant to go on the top of your main script as an alternative to using config.txt.
Similar to setting allow_on_server in config (which is usually the better option), this will allow your script to keep running even when connected to a server.

Arguments

None.

Results

None.

This is a header function, meaning it is meant to go on the top of your main script as an alternative to using config.txt.
Calling this function will instantly stop execution of your script and shut it down if it was started automatically. If a main script of a collection is shutdown as a result of calling this function, the entire collection will also be shutdown. It is worth noting that a script being loaded as a dependency to an automatically started script or collection will not be stopped by this function.

Arguments

None.

Results

None.

Example

Give the player money, but only if the script was started manually.

DontAutoStartScript()
PlayerAddMoney(10000)

This is a header function, meaning it is meant to go on the top of your main script as an alternative to using config.txt.
This function makes sure that Collection is running, and if it is not then it should be started. If it does not exist or it fails to start, then this script will be shutdown, execution will instantly stop, and the console will inform the user that they are missing a needed dependency. If a main script of a collection is shutdown as a result of calling this function, the entire collection will also be shutdown. A difference between setting a dependency in the config and requiring it using this function, is that requiring it in the config ensures it was running *before* starting the dependent collection at all.

Arguments

Results

None.

Example

Require all animations to be loaded for this script to run. Remember loadanim.lua is released as part of DSL, so this won't require extra effort from the user. It will just ensure that it is running if they have opted to not have their scripts automatically start. 

RequireDependency("loadanim.lua")

This is a header function, meaning it is meant to go on the top of your main script as an alternative to using config.txt.
This function makes sure that the current version of DSL is at least Version. If Not backwards compatible is true, then it requires that the current version of DSL is the exact version specified. If the current DSL version does not match what is desired, then this script will be shutdown, execution will instantly stop, and the console will inform the user that they do not have the right version. If a main script of a collection is shutdown as a result of calling this function, the entire collection will also be shutdown.

The version number required here should only be an integer, as any decimal part will be disregarded.

Arguments

Results

None.

Versions

DSL4 The optional Not backwards compatible argument was added.

Example

We can require a certain loader version if we know something will only work in that version.

RequireLoaderVersion(4)

RegisterLocalizedText("QUICK_EXAMPLE", 100)
ReplaceLocalizedText("QUICK_EXAMPLE", "These localized text functions were introduced in DSL4, so it is important we check for that version so anyone running an old DSL version will know they need to upgrade.")

function main()
	while not SystemIsReady() do
		Wait(0)
	end
	Wait(1000)
	TutorialShowMessage("QUICK_EXAMPLE", 5000)
end

This is a header function, meaning it is meant to go on the top of your main script as an alternative to using config.txt.
This function makes sure that system access is enabled (see allow_system_access in DSL's config). If system access is not enabled, then this script will be shutdown, execution will instantly stop, and the console will inform the user that they need system access enabled to continue. If a main script of a collection is shutdown as a result of calling this function, the entire collection will also be shutdown.

Arguments

None.

Results

None.

Load a DSL script into the current script's environment. This differs from StartScript as loading a script means it will load into the current script rather than fully "starting" a new script. This can basically be thought of as the DSL version of ImportScript (though you can still use ImportScript to load scripts from Scripts.img). Name is given as a relative path.

Arguments

Results

None.

Example

A main script can load a secondary script as a way of splitting large amounts of code into separate files for organization.

The loaded script is loaded into the script that called LoadScript, allowing said script to use the functions and variables defined there.

main.lua:

LoadScript("example.lua")

-- Hello world, from another script! will be printed
F_HelloWorld()

-- nil will be printed, because we cannot access the local variables of the other function
print(some_local)

-- but we do share globals with that script, so we can see 7 printed here
print(some_global)

example.lua:

local some_local = 4
some_global = 7
function F_HelloWorld()
	print("Hello world, from another script!")
end

Start a DSL script and add it to the current collection. This differs from LoadScript as starting a script means it gets its own script object, environment, and flow threads. Name is given as a relative path.

You can optionally supply your own Environment instead of letting the default one be generated.

The Script may not be returned if the script is terminated before this function returns.

Arguments

Results

Versions

DSL4 Passing a custom Environment no longer stops a script from creating normal script flow threads.

Example

Run two scripts in the same collection by using StartScript.

main.lua:

StartScript("secondary.lua")

function main()
	while not SystemIsReady() do
		Wait(0)
	end
	while true do
		TextPrintString("hello from main.lua", 0, 1)
		Wait(0)
	end
end

secondary.lua:

function main()
	while not SystemIsReady() do
		Wait(0)
	end
	while true do
		TextPrintString("hello from secondary.lua", 0, 2)
		Wait(0)
	end
end

Creating a virtual script is very similar to creating a script with StartScript, except that a function is given instead of a file. This allows you to get the benefits of having another script object, without the need for a dedicated file. If you do not care about giving it a special Name, you can just give the Function as the first argument.

Arguments

Results

Versions

DSL4 The optional Name argument was added.

Stops the current script collection. Similar to TerminateCurrentScript, this will not instantly take control from your script. The most common use for this function is to mark the script collection as INACTIVE, which does not happen automatically when your scripts die.

Arguments

None.

Results

None.

This function replaces the existing TerminateCurrentScript. If DSL is not running or UseBaseGameScriptFunctions was called with true, the original function is used. Otherwise the current DSL script is shutdown. This does not instantly take control away from your script, meaning your code will continue execution until the current thread yields or control is otherwise returned to DSL.

Arguments

None.

Results

None.

Example

Stop the script when a button is pressed.

function main()
	while not SystemIsReady() do
		Wait(0)
	end
	while true do
		TextPrintString("running", 0, 2)
		Wait(0)
		if IsButtonBeingPressed(3,0) then
			TerminateCurrentScript()
			print("this will be printed because control is not instantly taken away")
			Wait(0)
			print("this will not be printed because waiting gave control back to DSL")
		end
	end
end

Shutdown Script, or the current script if not given.

Arguments

Results

None.

Returns the current Script.

Arguments

None.

Results

Returns the name of Script's collection, or of the current collection.

Arguments

Results

Returns the environment assigned to Script or the current script.

Arguments

Results

Returns the name of Script or the current script.

Arguments

Results

Returns a table that is available to all scripts in the current collection. The table is only actually created the first time this function is called. By default, the table will be accessible from anywhere using dsl.

If Share mode is true, the shared table cannot be accessed through dsl. If no value is given, the share mode will not be changed. Attempting to change the share mode after the table is created will result in an error.

Arguments

Results

Versions

DSL7 A mostly useless argument was removed, and the optional Share mode argument was added.

Example

Communicate with a second script using a shared table.

main.lua:

gShared = GetScriptSharedTable()
StartScript("secondary.lua")

function main()
	while not SystemIsReady() do
		Wait(0)
	end
	while gShared.some_text do
		TextPrintString(gShared.some_text, 0, 1)
		Wait(0)
	end
end

secondary.lua:

gShared = GetScriptSharedTable()
gShared.some_text = "hello world"

function main()
	Wait(9000)
	gShared.some_text = "good bye"
	Wait(1000)
	gShared.some_text = nil
end

Returns a table that is available to all scripts in the current collection. The table is only actually created the first time this function is called. The table will be accessible from anywhere using net.

This function will fail if it is not called by a network script (client scripts from a server or main scripts on a server).

Arguments

Results

Versions

DSL7 A mostly useless argument was removed, and the optional Share mode argument was added.

Returns if Script is running, as in not shutdown or shutting down.

Arguments

Results

Returns if Script's collection or the running collection is a zipped collection.

Arguments

Results

This function replaces the existing CreateThread. If DSL is not running or UseBaseGameScriptFunctions was called with true, the original function is used. Otherwise a GAME thread is created and added to the current script. These threads run directly after the base game's. When creating a DSL script, Function can be a string to refer to a function in the current script's environment. In this case, the name of the thread is also preserved to be shown in console messages or returned with GetThreadName. Any extra Arguments are passed to the thread function when the thread starts.

Arguments

Results

Example

Do something on a delay by quickly creating a thread with an anonymous function.

function main()
	while not SystemIsReady() do
		Wait(0)
	end
	while true do
		local ped = PedGetTargetPed(gPlayer)
		if PedIsValid(ped) and IsButtonBeingPressed(7,0) then
			
			-- player insulted a ped, let's apply emotional damage after a second delay
			CreateThread(function()
				Wait(1000)
				if PedIsValid(ped) then -- make sure they're still valid after waiting
					PedApplyDamage(ped, 1000)
				end
			end)
			
		end
	end
end

Create a SYSTEM thread, using the same general rules as CreateThread. These threads run while the game is paused or out of focus, before most parts of the game are updated each frame.

Arguments

Results

Create a DRAWING thread, using the same general rules as CreateThread. These threads run directly before the game presents its back buffer, meaning anything you draw will be on top of everything the game drew.

Arguments

Results

Create any type of thread, using the same general rules as CreateThread. Some threads can only be created using this function.

Arguments

Results

Shutdown the current thread. Similar to TerminateCurrentScript, control is not instantly taken away. You will have to yield if you want to instantly jump out of thread exectuion.

Arguments

None.

Results

None.

This function replaces the existing TerminateThread. If DSL is not running or UseBaseGameScriptFunctions was called with true, the original function is used. Otherwise it will shutdown Thread or the current thread.

Arguments

Results

None.

Return the name of Thread or of the current thread. It is possible this function will not return anything if the thread was not created with a name.

Arguments

Results

Returns if Thread is running, as in not shutdown or shutting down.

Arguments

Results

Returns the time until Thread or the current thread will be allowed to update again. If a coroutine you created calls Wait, this function can be used with the current thread to get what time was passed.

Arguments

Results

This function replaces the existing Wait. If DSL is not running or UseBaseGameScriptFunctions was called with true, the original function is used. Otherwise the current thread will yield and next time it will be allowed to update is set to Milliseconds from now.

Arguments

Results

None.

Example

Almost every script will need to make use of Wait.

function main()
	
	-- wait until the system is ready before doing anything else
	while not SystemIsReady() do
		Wait(0)
	end
	
	-- main loop that is always running for as long as the script is alive
	while true do
		TextPrintString("you can script things that run every frame here", 0, 2)
		Wait(0)
	end
	
end

If you ever need one of the replaced base script manager functions to run when it normally wouldn't, you can use this function. Usually this will just result in issues, but it is provided for the sake of giving scripters the option to use the original functions.

Arguments

Results

None.

Loads a script from Scripts.img into the current script's environment.
This function emulates the ImportScript normally available to base game scripts. This function is a special case, because the original version is actually hidden by util.lur. The version typically available to base game scripts is actually provided by util.lur that is made specifically for each script. In an effort to mimic this behavior, DSL does not register this function as a global function. Instead, it is put into each script's environment just like util.lur would normally do.

Arguments

Results

None.