FreeScript
leap
by utility-library · version 2026.10.06 · updated 3 days ago
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 59 KB
- Code check
- Clean
- Licence
- AGPL-3.0
- Released
- Nov 2026
Pre-processor of a "modernized" and extended version of lua that pre-processes in pure executable lua. Mainly intended for FiveM
Leap V3
Think of it as an effective "modernity" leap into the future to make lua a feature-rich language.
Leap is inspired by the functionality and syntax found in JS and is primarily intended for FiveM, this however does not deny the possibility of extension to wider horizons.
To assist with debugging and error reporting, Leap retains the original line numbers from the code.
Leap features a caching system that processes only the files that have been modified, ensuring that the resource is only preprocessed when necessary; if no changes are detected, the resource will simply restart.
You can find the files created by this system under the
After preprocessing, Leap automatically adds the
Since it will modify the
Add Leap to your resource dependencies, after which you can access any of its features.
When the resource starts, Leap will handle the preprocessing of the necessary files automatically.
Example:
You can also manually use the
NEW FiveM Sandbox Workaround
To use Leap with the newly introduced FiveM sandbox, add the following line to your
Leap requires write access to resource folders in order to preprocess resources. Since the sandbox blocks direct filesystem writes, Leap will automatically spawn a new Node.js Worker Thread that bypasses these sandbox restrictions, allowing Leap to write to the resource folder when needed.
If you don't trust this behavior, i highly suggest reading the implementation yourself to verify exactly what the worker does and what permissions are being used.
Escrow
To use Leap under escrow or outside the Leap ecosystem, please deploy only the build folder, excluding the source as its not "standard" lua syntax
Commands
TIP: these commands can also be used in the cfg after the leap startup.
leap restart
leap build
resource structure tree after build:
Leap Libraryleap.deserialize
Converts serialized class back into an instance of a specific class, restoring the object's structure and data
All sub objects will also be deserialized recursively
Classes can expose the
leap.serialize
Converts an object or an array of objects (typically an instance of a class) into a serializable table format.
All sub objects will also be serialized recursively
Example:
Classes can expose the
The
```lua
@skipSerialize({"transient"})
class MyClass {
myVar = vec3(1, 2, 3),
transient = false,
}
local obj = new MyClass()
-- Need to change values to trigger serialization
obj.myVar = vector3(2, 3, 4)
obj.transient = true
local serialized = leap.serialize(obj) -- {"__type":"MyClass","myVar":{"x":2.
…
Leap (Lua extension accessibility pre-processor) is a fast pre-processor of a "modernized" and extended version of lua that pre-processes in pure executable lua.Think of it as an effective "modernity" leap into the future to make lua a feature-rich language.
Leap is inspired by the functionality and syntax found in JS and is primarily intended for FiveM, this however does not deny the possibility of extension to wider horizons.
To assist with debugging and error reporting, Leap retains the original line numbers from the code.
Leap features a caching system that processes only the files that have been modified, ensuring that the resource is only preprocessed when necessary; if no changes are detected, the resource will simply restart.
You can find the files created by this system under the
cache folder in the root folder of your server (near the resources folder)After preprocessing, Leap automatically adds the
build subfolder (if needed) to all file declarations in the fxmanifest.lua under the client, server, shared, and escrow_ignore sections.Since it will modify the
fxmanifest.lua it requires the permission to run the refresh command, you can allow this by adding add_ace resource.leap command.refresh allow in your server.cfg
The vscode syntax highlight extension is available!, to contribute visit leap_syntax_highlight_vscode.
Note To contribute to the grammar and/or preprocessor in general please visit leap_preprocessor.Installation
- Download the latest version or clone the repository with
git clone https://github.com/utility-library/leap.git - After downloading/cloning, inside the folder run
npm install - Add
add_unsafe_worker_permission leapto yourserver.cfg(explained here) - Then you can start leap as any other resource (
start leaporensure leapin yourserver.cfg)
Add Leap to your resource dependencies, after which you can access any of its features.
When the resource starts, Leap will handle the preprocessing of the necessary files automatically.
Example:
your_resource_that_use_leap > fxmanifest.lua:
fx_version "cerulean"
game "gta5"
server_script "server.lua"
dependency "leap" -- This is necessary to have the resource automatically preprocessedYou can also manually use the
leap restart your_resource_that_use_leap command to preprocess the files and restart the resource.NEW FiveM Sandbox Workaround
To use Leap with the newly introduced FiveM sandbox, add the following line to your
server.cfg:
add_unsafe_worker_permission leapLeap requires write access to resource folders in order to preprocess resources. Since the sandbox blocks direct filesystem writes, Leap will automatically spawn a new Node.js Worker Thread that bypasses these sandbox restrictions, allowing Leap to write to the resource folder when needed.
If you don't trust this behavior, i highly suggest reading the implementation yourself to verify exactly what the worker does and what permissions are being used.
Escrow
To use Leap under escrow or outside the Leap ecosystem, please deploy only the build folder, excluding the source as its not "standard" lua syntax
Commands
TIP: these commands can also be used in the cfg after the leap startup.
leap restart
leap restart build and restarts the resource, manual version of the more classic restart leap build
leap build pre-processes the resource by creating a subfolder named build that contains the pre-processed version of the resource (This will ignore the cache)resource structure tree after build:
│ fxmanifest.lua
│
├───build
│ └───server
│ main.lua
│
└───server
main.luaLeap Libraryleap.deserialize
Converts serialized class back into an instance of a specific class, restoring the object's structure and data
All sub objects will also be deserialized recursively
Note: leap.deserialize will NOT call the constructor of the classExample:
RegisterNetEvent("myEvent", function(myObject)
local obj = leap.deserialize(myObject)
print(obj.myVar)
end)Classes can expose the
deserialize method to achieve custom serialization.
class MyClass {
myVar = vec3(1, 2, 3),
deserialize = function(data)
self.myVar = vector3(data.myVar[1], data.myVar[2], data.myVar[3]) -- Restore the vec3 from the array
end
}leap.serialize
Converts an object or an array of objects (typically an instance of a class) into a serializable table format.
All sub objects will also be serialized recursively
Example:
local myObject = MyClass:new()
myObject.myVar = "Hello"
local serialized = leap.serialize(myObject) -- {myVar = "Hello"}
TriggerServerEvent("myEvent", serialized)Classes can expose the
serialize method to achieve custom serialization.
class MyClass {
myVar = vec3(1, 2, 3),
serialize = function()
return {
myVar = {math.round(self.myVar.x, 3), math.round(self.myVar.y, 3), math.round(self.myVar.z, 3)}, -- Save a vec3 to an array with rounded values
}
end
}The
skipSerialize decorator can be used to prevent certain fields from being serialized.```lua
@skipSerialize({"transient"})
class MyClass {
myVar = vec3(1, 2, 3),
transient = false,
}
local obj = new MyClass()
-- Need to change values to trigger serialization
obj.myVar = vector3(2, 3, 4)
obj.transient = true
local serialized = leap.serialize(obj) -- {"__type":"MyClass","myVar":{"x":2.
…