Zap

Appearance

Options ​

Options are placed at the beginning of Zap config files and allow you to configure the way Zap generates code.

server_output & client_output ​

These two options allow you to configure where Zap will output generated code. If you're not using the CLI these options can be ignored.

The paths are relative to the configuration file and should point to a lua(u) file.

Default ​

Example ​

remote_scope ​

This option changes the name of the remotes generated by Zap.

Default ​

The generated remotes will be ZAP_RELIABLE and ZAP_UNRELIABLE respectively.

Example ​

The generated remotes will change to be PACKAGE_NAME_RELIABLE and PACKAGE_NAME_UNRELIABLE respectively.

remote_folder ​

This option changes the name folder that Zap's remotes are placed inside of ReplicatedStorage.

Default ​

The generated remotes will be in ReplicatedStorage -> ZAP.

Example ​

The generated remotes be in ReplicatedStorage -> CHARACTER

casing ​

This option changes the casing of the API generated by Zap.

Using the FireAll function as an example:

CasingExample
PascalCaseFireAll
camelCasefireAll
snake_casefire_all

INFO

This option does not change the casing of your event or type names. It only changes the casing of generated API functions.

Default ​

"PascalCase"

Options ​

  • "camelCase"
  • "PascalCase"
  • "snake_case"

Example ​

write_checks ​

This option determines if Zap should check types when writing data to the network. This is useful for development and debugging, but can see some performance hits, and should be disabled in production.

DANGER

Zap only checks types that cannot be statically checked by Luau or TypeScript.

For example, Zap will not check if a string (20) is a string, but it will check that the string is 20 characters long.

Default ​

false

Options ​

  • true
  • false

Example ​

typescript ​

This option determines if Zap should generate TypeScript definition files alongside generated Luau code.

When enabled, Zap will generate a .d.ts file for the server and client with the same paths as the generated Luau server and client.

Default ​

false

Options ​

  • true
  • false

Example ​

manual_event_loop ​

This option determines if Zap automatically sends reliable events and functions each Heartbeat.

When enabled, the SendEvents function exported from the client and server modules that must be called manually.

This is useful when you can easily run SendEvents after all events have been fired each frame.

DANGER

At the time of writing (January 2024), Roblox has an issue where firing remotes at too high of a rate (above 60 hz) can cause the server to have incredibly high network response times.

This causes servers to essentially crash, and all clients to disconnect.

This can be mitigated by firing remotes to the server at a timed rate, so as to not exceed 60 hz.

lua
local Timer = 0

RunService.Heartbeat:Connect(function(DeltaTime)
	Timer += DeltaTime

	-- Only send events 60 times per second
	if Timer >= 1 / 60 then
		Timer = 0
		Zap.SendEvents()
	end
end)

Note that Zap uses RunService.Heartbeat and a 61 hz rate by default.

Default ​

false

Options ​

  • true
  • false

Example ​

typescript_max_tuple_length ​

The maximum non-nested length of tuples Zap can generate, with anything longer generating an array.

Default ​

10

Example ​

yield_type ​

This option changes the way functions yield in zap.

Default ​

"yield"

Options ​

INFO

The "future" option is not avaliable when typescript is enabled.

  • "yield"
  • "future"
  • "promise"

Example ​

async_lib ​

INFO

This option is not required when yield_type is set to yield

WARNING

When using typescript, provide the path to the RuntimeLib.

This option provides the async library to Zap. The option must include a require statement, as it will be fed directly into the Luau code.

When using Futures, you must provide a path to Future by red-blox. As of writing, there are no other future libraries for Roblox.

Zap is also compatible with almost any Promise library. Some common examples are:

*The default in roblox-ts.

Default ​

The path is empty.

Example ​

tooling ​

This option determines if Zap should generate a file to allow it to inteface with other tooling. More information on this feature can be found on the tooling intergration page.

Default ​

false

Example ​

tooling_output ​

This options allows you to configure where Zap will output its generated tooling code. If you're not using the CLI these options can be ignored.

The path is relative to the configuration file and should point to a lua(u) file.

Default ​

Example ​

or

tooling_show_internal_data ​

This option will add an additional element to the start of the arguments array returned by the tooling intergration function. More information on its structure can be found here.

Default ​

false

Example ​

disable_fire_all ​

This option determines if Zap should generate a .FireAll method on the server side. This is useful to turn off to prevent footguns if you're only ever sending events to loaded players.

Default ​

false

Example ​