Loading function...
Please make sure JavaScript is enabled. Otherwise you will be unable to see the function documentation.
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.
Calling this function will instantly stop execution of your script and shut it down if it was started automatically.
If the 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.
None.
None.
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 the 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.
None.
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 the main script of a collection is shutdown as a result of calling this function, the entire collection will also be shutdown.
None.
DSL4 The optional Not backwards compatible argument was added.
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.
None.
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.
None.
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.
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)
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.
DSL4 Passing a custom Environment no longer stops a script from creating normal script flow threads.
Run two scripts in the same collection by using StartScript.
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
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.
DSL4 The optional Name argument was added.
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.
None.
None.
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.
None.
Returns the name of Script's collection, or of the current collection.
Returns the environment assigned to Script or the current script.
Returns the name of Script or the current script.
Returns if Script is running, as in not shutdown or shutting down.
Returns if Script's collection or the running collection is a zipped collection.
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.
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.
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.
Create any type of thread, using the same general rules as CreateThread. Some threads can only be created using this function.
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.
None.
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.
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.
Returns if Thread is running, as in not shutdown or shutting down.
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.
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.
None.
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.
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.
None.