NetRay - High-Performance Roblox Networking Library

[TheYusufGamer (Asta)]

NetRay

High-Performance Roblox Networking Library

NetRay aims to simplify and streamline client-server communication in Roblox using RemoteEvents and RemoteFunctions, providing a structured, efficient, and easier-to-manage approach compared to manual remote instance handling.

Why NetRay?

Managing dozens of individual RemoteEvent and RemoteFunction instances can quickly become messy and error-prone. NetRay offers:

Optimized Performance
Automatic event batching, efficient binary serialization, and intelligent compression reduce network load and improve responsiveness.

Enhanced Reliability
Built-in Circuit Breakers prevent cascading failures, while robust error handling and timeouts make your networking more resilient.

Type Safety & Validation
Define data structures for your events and requests. NetRay automatically validates payloads, catching errors early in development.

Flexible Middleware
Intercept, modify, or block network traffic using a powerful middleware system. Implement logging, rate limiting, or custom validation with ease.

Modern Developer Experience
Clean API using Promises for asynchronous requests, clear event handling patterns, and priority queues simplify complex networking code.

Built-in Monitoring
Debug signals provide visibility into internal events, errors, and potentially network traffic, aiding optimization and troubleshooting.

Features

• Define client->server and server->client communication easily.
• Abstraction over RemoteEvent and RemoteFunction.
• Middleware support
• Automatic Server and Client Rate Limiting
• Dynamic Sender - Automatically selects the best method of sending your data
• And Many More!

Getting Started

Installation

1. Download: Grab the latest .rbxmx model file from the Releases page or Roblox
2. Import: Insert the downloaded model into Roblox Studio, placing it in ReplicatedStorage.

Quick Start Example

--[[ Server Script (e.g., in ServerScriptService) ]]

-- Server: Register and handle an event
local myEvent = NetRay:RegisterEvent("SimpleGreeting", {
  typeDefinition = { message = "string" }
})

myEvent:OnEvent(function(player, data)
  print(player.Name, "sent:", data.message)

  -- Reply back to just that player
  myEvent:FireClient(player, { message = "Server received: ".. data.message })
end)

print("NetRay Server event handler ready.")

--[[ Local Script (e.g., in StarterPlayerScripts) ]]

-- Client: Get event reference and interact
local myEvent = NetRay:GetEvent("SimpleGreeting")

-- Listen for server's reply
myEvent:OnEvent(function(data)
  print("Server replied:", data.message)
end)

-- Fire event to server after a delay
task.delay(3, function()
  local playerName = game:GetService("Players").LocalPlayer.Name
  print("Client sending greeting...")
  myEvent:FireServer({ message = "Hello from ".. playerName })
end)

Documentation
For detailed information, API reference, and advanced usage guides, please visit our documentation website:

NetRay Documentation

Contributing
Contributions are welcome! Please feel free to submit Pull Requests or open Issues for bugs, feature requests, or questions.

License
NetRay is licensed under the MIT License. See the LICENSE file for details.

Special Thanks to

@AlexanderLindholt for Signal +

[HACANTERO]

how does this compare to other networking libraries like red or bytenet?

[TheYusufGamer (Asta)]

It’s on par and better then both

Netray can compress your data and then serialises into a buffer before sending it, it only does this if it benefits from the compression otherwise it automatically chooses the best type for your data so you don’t need to specify e.g CFramexxx(whatever CFrame precision you wanna use) and send the data.

Netray also supports Binary, JSON and tables to be written and read from buffers.
This includes complex tables, deeply nested, flat etc so you can send a table full of different data types and it will still work

[ItsTechNose (GIANT NOSE)]

Good stuff! Been waiting on this. Currently finishing map changes, but then will remove the previous NetRay and add this new one. Definitely see some things I like and the documentation looks amazing compared to the previous.

I am currently using NetRay and BetterReplication together and my game feels absolutely snappy and almost 0 lag at the time. Should this new update hold up fine with BetterReplication?

BetterReplication | Vastly improve your combat experience by fighting LAG!

BetterReplication V6.1 has released (15/02/2025) and waves goodbye to ByteNet with additional network optimisations! Roblox’ replication system is too slowww for combat games! The issues that arise include: largely delayed player Character positions on the server and other clients any constraints applied to the Character will show delayed to other clients! See an example here! This majorly affects games that have high-paced manouvers and close-combat at their core. As someone who …

[TheYusufGamer (Asta)]

@ItsTechNose

Definitely see some things I like and the documentation looks amazing compared to the previous

Thank you! It took me some time to figure how to set it all up and everything but eventually got there.

If the old version of NetRay worked with BetterReplication then the new one should also, I do not see any reason for it not to anymore

[AlexanderLindholt (Alexander)]

Hi there,

This looks very promising. There are many networking libraries though, so I’d like to know how NetRay stands out from the rest — is it that you don’t have to specify the type?

And thanks for using Signal+.

[tututuana (Dovg)]

You’ve done an incredible job, I noticed a few things while looking at the code and wanted to share them.

Queue Processing Logic (ClientManager / ServerManager)

The StartQueueProcessing logic uses somewhat arbitrary limits and probabilities (math.min(5, …), math.min(3, …), math.random() < 0.5, math.random() < 0.2) to process different priority queues. While this favors higher priorities, it doesn’t strictly guarantee fairness and could potentially starve lower-priority queues under sustained high load on higher priorities. For potentially more predictable behavior (though slightly more complex code and minor optimization), consider a weighted round-robin approach or a token bucket system per queue to ensure lower-priority queues eventually get processed, even if less frequently than higher ones. However, the current approach is simple and likely sufficient for most use cases unless starvation becomes a proven issue.

Rate Limiting Implementation (ServerManager)

CheckRateLimit stores timestamps for every request within the time window in a table (eventRates.Requests, eventRates.BurstRequests). It then iterates and potentially removes old entries during the check. This table manipulation (insertions, removals, iteration) on every check could become a performance bottleneck under very high request rates from a single player for a specific event. You can do few things for performance:

Fixed Window Counter: Store only a requestCount and a windowStartTime. If now > windowStartTime + timeWindow, reset count and start time. Otherwise, increment count and check against the limit. This is much faster but can allow bursts at the window boundary.
Token Bucket: A more robust algorithm that allows bursts but smooths out the average rate. It’s more complex to implement.
For the current implementation: Pre-allocate the playerRates[eventName] table with a reasonable size (table.create) if possible, although predicting the number of different events a player interacts with is hard.

Queue.lua Priority Logic

The Queue.lua implementation includes logic for handling priority arguments during Enqueue. However, the ClientManager and ServerManager seem to handle priorities by using multiple separate queues, one for each priority level. This makes the priority logic within Queue.lua itself likely unused. The priority insertion is also O(N) which isn’t ideal for a generic priority queue (though okay for small queues). You can if the Managers exclusively use multiple queues for prioritization, remove the priority parameter and associated insertion logic from Queue:Enqueue and Queue:_InsertAt. This simplifies the Queue class to be a standard FIFO queue, matching how it’s actually used by the Managers.

Middleware Caching (Middleware.lua)

The caching implementation (Cache, PrecomputedPaths) adds significant complexity.
The primary cache (self.Cache) seems to lack proper LRU (Least Recently Used) eviction. It calculates the size and identifies the oldest key but doesn’t appear to use the lruList structure defined in Utilities.lua to actually remove the oldest entry when the cache is full.
The effectiveness of this caching depends heavily on payload consistency. If event data varies often, the cache hit rate might be low.

You can:
Fix/Implement LRU: Integrate the lruList logic from Utilities.lua into Middleware:AddToCache to correctly evict the least recently used items when MaxCacheSize is reached.
Profile: Before keeping the cache, profile its effectiveness. If the hit rate is low or the overhead is high, consider simplifying or removing it. Simple, fast middleware execution might be better than complex caching.

Also I like the prepareDataForSend function correctly compares the size of the serialized compressed data vs. the serialized original data. This is the optimal way to decide if compression is truly beneficial. This logic looks sound.

Again, you did a wonderful job, keep up the good work.

[sangolemango (Sango)]

If you want high performance networking the only way to do it is writing it yourself (specific to whatever game you are making) or using an IDL compiler

[TheYusufGamer (Asta)]

Hello,

One of the reasons NetRay stands out compared to other networking modules is that you don’t need to specify the type of data, like other modules where you make a packet and specify the specific data type.

Another reason is that NeyRay uses LZW compression and then turns it into a binary string that is then written into a buffer. This mean when sending data that is medium - large your data is compressed saving memory usage for slight CPU usage ( although lzw is very performant).

Also, NetRay natively supports all types of Roblox tables, JSON and binary data. This means that you can send complex deeply nested data or a table with lots of different data types and it will automatically choose the best method or sending it.

And just the features in general like the circuit breaker, priorities, etc

While keeping the original feel of remote events without much additional work

[TheYusufGamer (Asta)]

Thank you very much, I’ll have a look later today ! I appreciate the feedback

[tututuana (Dovg)]

Does anyone do this on Roblox?

[sangolemango (Sango)]

Yeah there’s already a lot of tools to do just that like zap. I do my own networking for my games because that’s the only way to make your networking as efficient as possible

[AlexanderLindholt (Alexander)]

@TheYusufGamer

NeyRay uses LZW compression and then turns it into a binary string that is then written into a buffer

Is this different than e.g. Packet and ByteNet?

[TheYusufGamer (Asta)]

Neither one of them compress data before serialisation, and neither support complex tables JSON and binary types

[TheYusufGamer (Asta)]

Not to my knowledge, only my previous NetRay module seemed to use compression before serialisation

[AlexanderLindholt (Alexander)]

@sangolemango

the only way to make your networking as efficient as possible

That’s simply not true.

Packet and I believe NetRay too has exceeded Zap’s performance, and that is without any form of IDL compiler or hardcoding.

And either way, “as efficient as possible” will require hardcoding everything and avoiding functions as much as possible, which is extremely bad practice. Nobody ever goes for literally the best efficiency possible — just something very close.

About hardcoding things and avoiding functions, I actually do this sometimes, but only when it makes sense. I won’t be doubling the amount of lines and halving the readability just to increase the speed by 1%.

[AlexanderLindholt (Alexander)]

@TheYusufGamer

Neither one of them compress data before serialisation

That’s interesting.
Do you have some tests on data sizes for different types? I’d love to see.

[TheYusufGamer (Asta)]

Yeah I do, I was mainly testing complex tables and large strings etc,
I’ll be able to provide the table and some screenshots from studio once I get back home

[sangolemango (Sango)]

You don’t need to avoid functions. The compiler will inline functions for you where profitable. You simply cannot get good performance with a general purpose solution. That’s performance programming 101

[RobIoxArenaEvents]

Is there any proof via benchmarks that this library is better than Red or ByteNet? So far, I have seen you claim this but have yet to post true benchmarks.

Also, why does every single script of yours use --!optimize 2 and --!native? Roblox, by default, uses optimize 2 on every single script in a game, as far as I’m aware, so the optimization stuff is completely useless. Native is also not needed. You are only supposed to use native in the event of things like mathematical equations where in this case I have yet to find anything as such. Feel free to correct me on that part.

Now look, I’m not trying to downplay this project, I think it definitely has some potential. But I would like to see these things addressed in the future. In the meantime, I made a PR on your repo to fix some things up