Blink IDL Compiler

Blink is an IDL (Interface Definition Language) compiler written in Luau, specifically designed for ROBLOX buffer networking. It focuses on generating high-performance, bandwidth-efficient code to reduce player ping and CPU usage compared to generalized networking solutions.

Key benefits include:

• Bandwidth Efficiency: Lower bandwidth usage leads to lower ping.
• Performance: Optimized for lower CPU usage.
• Security: Automatically validates client-sent data before it reaches critical game code and uses compression to make network traffic snooping (e.g., via RemoteSpy) significantly more difficult.

Events are the primary mechanism for communication between the client and server in Blink. They are defined using the event keyword in .blink files.

An event definition requires specifying the following fields:

• From: The side that fires the event (Server or Client).
• Type: The reliability mode (Reliable or Unreliable).
• Call: The listening API pattern exposed to the receiver (SingleSync, ManySync, SingleAsync, ManyAsync, or Polling).
• Data: The type of data sent (can be a single type or a type pack/tuple).

event MyEvent {
    From: Server,
    Type: Reliable,
    Call: SingleAsync,
    Data: f64
}

When defining an event, you must choose a Type and a Call pattern.

Reliability (Type)

• Reliable: Guaranteed arrival in the order sent.
• Unreliable: No guarantee of arrival or order. Maximum size is 1000 bytes.

Listening API (Call)

• SingleSync: Exactly one listener; listener cannot yield.
• ManySync: Multiple listeners; listeners cannot yield.
• SingleAsync: Exactly one listener; listener may yield.
• ManyAsync: Multiple listeners; listeners may yield.
• Polling: Listeners iterate through the event using .Iter().

ERROR

Avoid Sync events unless performance is critical. Yielding or erroring in a sync event can cause undefined or game-breaking behavior.

To send multiple data values through a single event, use a Type Pack (tuple). Define this by listing types separated by commas within parentheses in the Data field.

event MyTypePackEvent {
    From: Server,
    Type: Reliable,
    Call: SingleAsync,
    Data: (u8, u16, u32)
}

Benchmark results are presented in tables comparing blink against other tools like roblox, zap, and bytenet.

Metrics Definitions

• FPS (Frames Per Second): Measures the processing throughput. Higher values indicate better performance.
• Kbps (Kilobits per second): Measures the bandwidth consumption. Lower values indicate better data compression/efficiency.
• P[NUMBER]: Represents the percentile (e.g., P95 is the 95th percentile).
• Loss (%): The percentage of data lost during transmission. Blink aims for 0% loss.

Result Tables

Results are split into two categories for each test case (e.g., Entities or Booleans):

1. Tool (FPS): Performance in terms of frames per second.
2. Tool (Kbps): Performance in terms of bandwidth usage.

Ranges can be used with various types (Numbers, Strings, Arrays, Buffers, Vectors, Maps) to limit the extents of their representable values.

• Full Ranges: Both minimum and maximum values are provided (e.g., 0..100).
• Half Ranges: Only a minimum or maximum is provided (e.g., 0.. for minimum 0 to infinity, or ..100 for negative infinity to maximum 100).
• Exact Ranges: Only a single value is provided (e.g., 0 or 100).

// Full range
0..100

// Half range (min only)
0..

// Half range (max only)
..100

// Exact range
100

Scopes allow you to group similar types and events together for improved per-file organization. You define a scope using the scope keyword followed by a name. Definitions inside a scope (like type or event) are encapsulated within that scope.

Note: Scopes automatically capture any definitions from their parent scopes, making parent types available inside the child scope.

scope ExampleScope {
    type InScopeType = u8
    event InScopeEvent {
        From: Server,
        Type: Reliable,
        Call: SingleSync,
        Data: u8
    }
}

struct Example {
    Reference = ExampleScope.InScopeType
}

Append a ? after an entire type to make it optional. This is critical when working with Roblox Instances that might be nil due to streaming or existence issues.

type Username = string(3..20)?

To generate the Luau files from your .blink description, use the Blink CLI. Open a terminal in the directory containing your file and run the blink command followed by your filename.

This process generates two Luau files based on your ClientOutput and ServerOutput options.

blink FILE_NAME

To quickly deploy a new documentation site using this template, you can clone the repository directly to Vercel. This will set up the environment and deploy the template automatically.

https://vercel.com/new/clone?s=https%3A%2F%2Fgithub.com%2Fshuding%2Fnextra-docs-template&showOptionalTeamCreation=false

To avoid manual recompilation during rapid development, use the --watch flag. When this flag is passed, blink will monitor the target file and all of its imports (including nested imports) for changes and automatically recompile whenever a change is detected.

blink file-name --watch