options.md

<script setup lang="ts"> const outputDefaults = `opt server_output = "./network/server.lua" opt client_output = "path/to/client/output.lua"` const outputExample = `opt server_output = "./network/client.luau" opt client_output = "src/client/zap.luau"` const typesOutputExample = `opt types_output = "network/types.luau"` const asyncLibExample = `opt yield_type = "promise" opt async_lib = "require(game:GetService('ReplicatedStorage').Promise)"` const toolingOutputExample = `opt tooling = true opt tooling_output = "src/ReplicatedStorage/RemoteName.profiler.luau"` const toolingOutputExample2 = `opt typescript = true opt tooling = true opt tooling_output = "src/include/RemoteName.profiler.lua"` const toolingShowInternalDataExample = `opt tooling = true opt tooling_show_internal_data = true` </script>

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

types_output [0.6.18+]

Configures where Luau types will be output.

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

Example

call_default [0.6.18+]

The default call field that will be used for events. See call for possible options.

Example

Default

Requires an explicit call field defined on every event.

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:

Casing	Example
PascalCase	FireAll
camelCase	fireAll
snake_case	fire_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

true

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.

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

include_profile_labels

When enabled, microprofiler lables are added to the generated file to diagnose performance issues.

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

typescript_enum [0.6.24+]

This option allows the TypeScript output to generate const enum types instead of string literals.

Default

StringLiteral

Example

Options

In the example:

"StringLiteral" will generate the following TypeScript type:

type RoundStatus = "Starting" | "Playing" | "Intermission"

"ConstEnum" will generate the following TypeScript type:

const enum RoundStatus {
	Starting,
	Playing,
	Intermission
}

::: tip WARNING Because const enum emits numbers by default when compiled, setting typescript_enum to the ConstEnum option will change the Luau output to accept numbers instead of strings for an enum.

If you do not want this behavior use "StringConstEnum" or the default of "StringLiteral". :::

"StringConstEnum" will generate the following TypeScript type:

const enum RoundStatus {
	Starting = "Starting",
	Playing = "Playing",
	Intermission = "Intermission"
}

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 :::

::: tip 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:

• Promise by evaera*
• Promise by Quenty
• Promise by red-blox

^{*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