### Install Zap CLI using aftman

Source: https://zap.redblox.dev/intro/getting-started.html

Installs the Zap CLI tool using the aftman package manager. This is a straightforward command-line operation.

```bash
aftman add red-blox/zap
```

--------------------------------

### Generate Code with Zap CLI

Source: https://zap.redblox.dev/intro/getting-started.html

Generates server and client output files from a Zap configuration file. The generated files are specified by 'opt' settings in the Zap IDL.

```bash
zap path/to/config.zap
```

--------------------------------

### Zap API Usage for Events (Luau)

Source: https://zap.redblox.dev/intro/getting-started.html

Demonstrates how to use the Luau API generated by Zap to fire and listen to events. Requires the generated output files to be required.

```luau
-- Server
local Zap = require(path.to.server.output)
Zap.MyEvent.FireAll(123, "hello world")
-- Client
local Zap = require(path.to.client.output)
Zap.MyEvent.On(function(Foo, Bar)
print(Foo, Bar)
end)
```

--------------------------------

### Manual Event Loop Example (Lua)

Source: https://zap.redblox.dev/config/options.html

An example demonstrating how to manually send events using Zap.SendEvents() within a Heartbeat connection, limiting the send rate to 60 times per second to avoid potential network performance issues.

```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)
```

--------------------------------

### Define Zap Events with Parameters

Source: https://zap.redblox.dev/config/events.html

Examples of defining events in a Zap configuration file. Shows both named parameters with types and simplified unnamed parameter structures.

```Zap
event MyEvent = {
  from: Server,
  type: Reliable,
  call: ManyAsync,
  data: (Foo: boolean, Bar: u32, Baz: string.utf8)
}
```

```Zap
event OneUnnamedParameter = {
  from: Server,
  type: Reliable,
  call: ManyAsync,
  data: boolean
}

event TwoUnnamedParameters = {
  from: Server,
  type: Reliable,
  call: ManyAsync,
  data: (boolean, u32)
}
```

--------------------------------

### Axis-Aligned CFrame Examples

Source: https://zap.redblox.dev/config/types.html

Demonstrates the 24 possible axis-aligned rotations for use with the AlignedCFrame type in Zap.

```Luau
local CFrameSpecialCases = {
	CFrame.Angles(0, 0, 0),
	CFrame.Angles(0, math.rad(180), math.rad(90)),
	CFrame.Angles(0, math.rad(-90), 0),
	CFrame.Angles(math.rad(90), math.rad(-90), 0),
	CFrame.Angles(0, math.rad(90), math.rad(180)),
}
```

--------------------------------

### Generate TypeScript String Literal Enum (Zap)

Source: https://zap.redblox.dev/config/options.html

This example demonstrates generating TypeScript types as string literals, which is the default behavior for enums in Zap. This ensures that Luau enums are represented as string unions in TypeScript, avoiding potential issues with number-based enum compilation.

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

--------------------------------

### Generate TypeScript Const Enum (Zap)

Source: https://zap.redblox.dev/config/options.html

This example shows how to generate TypeScript `const enum` types using Zap's configuration. When compiled, these enums will emit numbers by default in Luau. This configuration is suitable when number representation is acceptable or desired.

```typescript
const enum RoundStatus {
	Starting,
	Playing,
	Intermission
}
```

--------------------------------

### Generate TypeScript String Const Enum (Zap)

Source: https://zap.redblox.dev/config/options.html

This example illustrates generating TypeScript `const enum` types where enum members are explicitly assigned string values. This approach preserves string representation in both TypeScript and Luau, preventing the default number emission behavior of `ConstEnum`.

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

--------------------------------

### Define Maps and Sets

Source: https://zap.redblox.dev/config/types.html

Illustrates the syntax for creating key-value maps and sets in the Zap configuration.

```zap
map { [string]: u8 }
set { string }
```

--------------------------------

### Configure Server and Client Output Paths (Lua)

Source: https://zap.redblox.dev/config/options.html

Sets the output paths for generated server and client code. These paths are relative to the configuration file and should point to a lua(u) file. Ignored if not using the CLI.

```lua
opt server_output = "./network/server.lua"
opt client_output = "path/to/client/output.lua"
```

```lua
opt server_output = "./network/client.luau"
opt client_output = "src/client/zap.luau"
```

--------------------------------

### Fire Events from Client and Server

Source: https://zap.redblox.dev/usage/generated-api.html

Shows how to trigger events from the client and various methods for the server to send data to players, including Fire, FireAll, FireExcept, FireList, and FireSet.

```lua
-- Client firing
Zap.AnotherEvent.Fire(true, 32)

-- Server firing examples
Zap.MyEvent.Fire(Player, { foo = "baz", bar = 1 })
Zap.MyEvent.FireAll({ foo = "baz", bar = 1 })
Zap.MyEvent.FireExcept(Player, { foo = "baz", bar = 1 })
Zap.MyEvent.FireList({ Player1, Player2 }, { foo = "baz", bar = 1 })
Zap.MyEvent.FireSet({ [Player1] = true, [Player2] = true }, { foo = "baz", bar = 1 })
```

--------------------------------

### Invoke and Handle Functions

Source: https://zap.redblox.dev/usage/generated-api.html

Illustrates how the client invokes a remote function using Call and how the server implements the logic using SetCallback.

```lua
-- Client invocation
local score = Zap.GetScore.Call("round_ipsum-lorem", "LowScore")
print(score)

-- Server callback implementation
local function handleRequest(Player: Player, roundId: string, category: "HighScore" | "LowScore" | "AverageScore"): number
    return 0
end

Zap.GetScore.SetCallback(handleRequest)
```

--------------------------------

### Define String Types and Constraints

Source: https://zap.redblox.dev/config/types.html

Shows how to declare UTF-8 and binary strings, including applying length constraints to the string types.

```zap
string.utf8
string.binary
string.utf8(3..20)
string.binary(3..20)
```

--------------------------------

### Configure Async Library Path (Zap)

Source: https://zap.redblox.dev/config/options.html

The `async_lib` option specifies the path to the asynchronous library used by Zap. This is particularly important when `yield_type` is set to 'promise' and when using TypeScript, where the path to the RuntimeLib must be provided. It requires a `require` statement.

```zapconfig
opt yield_type = "promise"
opt async_lib = "require(game:GetService('ReplicatedStorage').Promise)"
```

--------------------------------

### Configure Tooling Output Path (Zap)

Source: https://zap.redblox.dev/config/options.html

The `tooling_output` option defines the destination path for Zap's generated tooling code. This path is relative to the configuration file and should point to a `.lua` or `.luau` file. It's used in conjunction with the `tooling` option.

```zapconfig
opt tooling = true
opt tooling_output = "src/ReplicatedStorage/RemoteName.profiler.luau"
```

```zapconfig
opt typescript = true
opt tooling = true
opt tooling_output = "src/include/RemoteName.profiler.lua"
```

--------------------------------

### Enable Tooling Integration (Zap)

Source: https://zap.redblox.dev/config/options.html

Setting the `tooling` option to `true` enables Zap to generate files for interfacing with other tools. This feature enhances integration capabilities and requires further configuration via `tooling_output`.

```zapconfig
opt tooling = true
```

--------------------------------

### Listen to Events with Zap

Source: https://zap.redblox.dev/usage/generated-api.html

Demonstrates how to register listeners for events. Use SetCallback for single-listener events and On for events supporting multiple listeners, which returns a disconnect function.

```lua
-- Single listener example
Zap.AnotherEvent.SetCallback(function(Player, Foo, Bar)
    -- Do something with the player and data
end)

-- Multiple listener example
local Disconnect = Zap.MyEvent.On(function(Options)
    -- Do something with the data
end)

-- Disconnect the listener after 10 seconds
task.delay(10, Disconnect)
```

--------------------------------

### Deserializing Remote Event Data in Lua

Source: https://zap.redblox.dev/usage/tooling.html

Demonstrates how to connect to reliable and unreliable remote events and pass the received arguments into a Zap-generated deserializer. This implementation ensures that data is correctly processed for external tooling consumption.

```Lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local zap_deserialiser = require(path.to.deserialiser)
local reliable = ReplicatedStorage:WaitForChild("ZAP_RELIABLE")
local unreliable = ReplicatedStorage:WaitForChild("ZAP_UNRELIABLE")

reliable.OnClientEvent:Connect(function(...)
	local data = zap_deserialiser(reliable, ...)
	print(data)
end)

unreliable.OnClientEvent:Connect(function(...)
	local data = zap_deserialiser(unreliable, ...)
	print(data)
end)
```

--------------------------------

### Configure Luau Types Output Path (Lua)

Source: https://zap.redblox.dev/config/options.html

Specifies the output path for Luau type definitions. The path is relative to the configuration file and must point to a lua(u) file. Requires Zap version 0.6.18 or higher.

```lua
opt types_output = "network/types.luau"
```

--------------------------------

### Define Number Constraints with Zap

Source: https://zap.redblox.dev/config/types.html

Demonstrates how to apply range constraints to numeric types like u8 to limit their valid input range.

```zap
u8(..100)
```

--------------------------------

### Configure API Casing (Lua)

Source: https://zap.redblox.dev/config/options.html

Sets the casing style for generated API functions. This option affects generated functions like 'FireAll' but not event or type names. Options include 'PascalCase', 'camelCase', and 'snake_case'.

```lua
opt casing = "PascalCase"
```

```lua
opt casing = "camelCase"
```

```lua
opt casing = "snake_case"
```

--------------------------------

### Configure TypeScript Definition Generation (Lua)

Source: https://zap.redblox.dev/config/options.html

Determines whether Zap generates TypeScript definition files (.d.ts) alongside Luau code. When enabled, .d.ts files are created for both server and client with paths matching the generated Luau files.

```lua
opt typescript = true
```

```lua
opt typescript = false
```

--------------------------------

### Enable Internal Data in Tooling (Zap)

Source: https://zap.redblox.dev/config/options.html

The `tooling_show_internal_data` option, when set to `true`, adds an extra element to the beginning of the arguments array returned by the tooling integration function. This provides more detailed information for debugging and analysis.

```zapconfig
opt tooling = true
opt tooling_show_internal_data = true
```

--------------------------------

### Handle Roblox Instances

Source: https://zap.redblox.dev/config/types.html

Zap supports passing Roblox Instances. You can specify base classes using dot notation to restrict accepted types.

```Zap
type Part = Instance.BasePart
```

--------------------------------

### Include Microprofiler Labels (Lua)

Source: https://zap.redblox.dev/config/options.html

Enables the inclusion of microprofiler labels in the generated code for diagnosing performance issues. This option is available for Zap versions 0.6.18 and higher.

```lua
opt include_profile_labels = true
```

```lua
opt include_profile_labels = false
```

--------------------------------

### Define Optional Type in Zap

Source: https://zap.redblox.dev/config/types.html

Demonstrates how to make a type optional by appending a '?' to the type name. This allows the variable to hold either the specified type or nil. No external dependencies are required.

```zap
type Character = Instance.Player?

```

--------------------------------

### Configure Function Yielding Behavior (Zap)

Source: https://zap.redblox.dev/config/options.html

The `yield_type` option in Zap configures how functions yield. Options include 'yield' (default), 'future', and 'promise'. Note that the 'future' option is unavailable when TypeScript is enabled.

```zapconfig
opt yield_type = "promise"
```

--------------------------------

### Configure Remote Folder Name (Lua)

Source: https://zap.redblox.dev/config/options.html

Determines the name of the folder within ReplicatedStorage where Zap's remotes are placed. The default folder name is 'ZAP'.

```lua
opt remote_folder = "ZAP"
```

```lua
opt remote_scope = "CHARACTER"
```

--------------------------------

### Define Arrays with Length Constraints

Source: https://zap.redblox.dev/config/types.html

Defines an array of unsigned 8-bit integers and demonstrates how to constrain the array length using range syntax.

```zap
u8[]
u8[10..20]
```

--------------------------------

### Define Asynchronous Function with Arguments and Return Types in Zap

Source: https://zap.redblox.dev/config/functions.html

Defines an asynchronous function named 'Test' in Zap. It accepts an unsigned 8-bit integer ('u8') and a UTF-8 string as arguments, and returns an enum with 'Success' and 'Fail' states. This demonstrates basic function definition with typed arguments and return values.

```Zap
funct Test = {
call: Async,
args: (Foo: u8, Bar: string.utf8),
rets: enum { Success, Fail }
}
```

--------------------------------

### Configure Write Checks (Lua)

Source: https://zap.redblox.dev/config/options.html

Enables or disables type checking when writing data to the network. Useful for development and debugging, but may impact performance and should be disabled in production. Zap checks types that Luau or TypeScript cannot statically verify.

```lua
opt write_checks = true
```

```lua
opt write_checks = false
```

--------------------------------

### Define OR/Union Type in Zap

Source: https://zap.redblox.dev/config/types.html

Illustrates the creation of union types in Zap using the '|' operator. This allows a variable to hold values of different specified types, with runtime checking determining the actual type. Limitations include not being able to have both u8 and u16 in the same union.

```zap
type Union = (
string
| u32
| enum { "hello", "world" }
| enum "tag" { one { b: i8 }, two { c: buffer } }
| unknown
| Instance.Player
| Instance
)

```

--------------------------------

### Defining Decompressed Data Types

Source: https://zap.redblox.dev/usage/tooling.html

Defines the structure of the data returned by the deserializer, supporting both Lua and TypeScript environments. Includes optional internal data structures when tooling_show_internal_data is enabled.

```Lua
type DecompressedData = { { Name: string, Arguments: { any } } }
type InternalData = { EventId: number, CallId: number? }
```

```TypeScript
type DecompressedData = { Name: string, Arguments: unknown[] }[]
interface InternalData { EventId: number, CallId?: number }
```

--------------------------------

### Disable Server-Side FireAll (Zap)

Source: https://zap.redblox.dev/config/options.html

The `disable_fire_all` option, when set to `true`, prevents Zap from generating a `.FireAll` method on the server side. This is a safety measure to avoid accidental broadcasting of events to all players, particularly useful when events should only be sent to loaded players.

```zapconfig
opt disable_fire_all = true
```

--------------------------------

### Define Structs in Zap

Source: https://zap.redblox.dev/config/types.html

Structs are collections of statically named fields used to represent structured data objects.

```Zap
type Item = struct {
	name: string,
	price: u16,
}
```

--------------------------------

### Configure Remote Scope Name (Lua)

Source: https://zap.redblox.dev/config/options.html

Changes the base name for generated remotes. The default scope is 'ZAP', resulting in 'ZAP_RELIABLE' and 'ZAP_UNRELIABLE'.

```lua
opt remote_scope = "ZAP"
```

```lua
opt remote_scope = "PACKAGE_NAME"
```

--------------------------------

### Define Zap Function with Multiple Return Values

Source: https://zap.redblox.dev/config/functions.html

Defines a Zap function named 'MultipleRets' that takes a boolean argument. It returns multiple values: an enum with 'Success' and 'Fail' states, and a UTF-8 string. This demonstrates how to specify multiple return types for a function.

```Zap
funct MultipleRets = {
call: Async,
args: boolean,
rets: (enum { Success, Fail }, string.utf8)
}
```

--------------------------------

### Configure TypeScript Enum Generation (Zap)

Source: https://zap.redblox.dev/config/options.html

The `typescript_enum` option controls how enums are generated in TypeScript output. It can be set to 'StringLiteral' (default), 'ConstEnum', or 'StringConstEnum' to influence the generated TypeScript types and their underlying Luau representation. Using 'ConstEnum' can change Luau enums to accept numbers instead of strings.

```zapconfig
opt typescript_enum = "ConstEnum"
```

--------------------------------

### Define Zap Function with Multiple Unnamed Arguments

Source: https://zap.redblox.dev/config/functions.html

Defines a Zap function that accepts two unnamed arguments: an unsigned 8-bit integer ('u8') and a UTF-8 string. The function returns an enum with 'Success' and 'Fail' states. This illustrates defining functions with multiple arguments without explicit parameter names.

```Zap
funct TwoUnnamedParameters = {
call: Async,
args: (u8, string.utf8),
rets: enum { Success, Fail }
}
```

--------------------------------

### Define Unit Enums

Source: https://zap.redblox.dev/config/types.html

Defines a unit enum in Zap and shows the corresponding generated Luau type definition.

```zap
type RoundStatus = enum { Starting, Playing, Intermission }
```

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

--------------------------------

### Manual Event Loop Sending (Lua)

Source: https://zap.redblox.dev/config/options.html

Controls whether Zap automatically sends reliable events and functions on Heartbeat. When enabled, the 'SendEvents' function must be called manually, typically after all events are fired each frame. This can help mitigate network issues caused by high remote firing rates.

```lua
opt manual_event_loop = true
```

```lua
opt manual_event_loop = false
```

--------------------------------

### Configure Default Call Field (Lua)

Source: https://zap.redblox.dev/config/options.html

Sets the default 'call' field for events. This option is available in Zap version 0.6.18 and later. If not explicitly defined, each event requires a 'call' field.

```lua
opt call_default = "ManySync"
```

```lua
opt call_default = "Polling"
```

--------------------------------

### Define Vectors in Zap

Source: https://zap.redblox.dev/config/types.html

Zap supports vector types with configurable numeric components. The Z component is optional.

```Zap
type Position = vector(f32, f32, f32)
type Size = vector(u8, f32)
type DefaultVector = vector
```

--------------------------------

### Define Tagged Enums in Zap

Source: https://zap.redblox.dev/config/types.html

Tagged enums allow for variants with attached data, similar to Rust enums. This snippet demonstrates the Zap syntax and the resulting Luau type mapping.

```Zap
type Tagged = enum "Type" {
	Number {
		Value: f64,
	},
	String {
		Value: string,
	},
	Boolean {
		Value: boolean,
	},
}
```

```Luau
type t = { type: "number", value: number }
	| { type: "string", value: string }
	| { type: "boolean", value: boolean }
```

--------------------------------

### Define Zap Function with Single Unnamed Argument

Source: https://zap.redblox.dev/config/functions.html

Defines a Zap function that accepts a single, unnamed unsigned 8-bit integer ('u8') as an argument. The return type is an enum with 'Success' and 'Fail' states. This showcases how to define functions when only one argument is needed and naming is optional.

```Zap
funct OneUnnamedParameter = {
call: Async,
args: u8,
rets: enum { Success, Fail }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.