Skip to content

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