ioGame clusters a Java game server without middleware or a database

A networking framework aimed at long lived connections

ioGame is described as a lock-free, asynchronous, event-driven Java Netty framework for building high-performance network applications, lightweight and dependency free, supporting distributed and decentralised clusters without requiring external middleware or databases. The project positions it for game servers, IoT and long-lived connection systems.

That last category is the interesting framing. A game server or an IoT backend differs from a typical web service in three ways: connections stay open for a long time, each connection belongs to a player or a device whose state must survive a code change, and the traffic is not request and response but a stream of small messages. A framework that treats a connection as a resource with an owner, rather than as a request that ends, has to be designed differently from a servlet container or a typical RPC framework.

The stated audience is a Java developer with no game development experience, and the claim is that if you know basic Java or web MVC you already know how to use it. The API is described as MVC style with non-intrusive Java Beans, and the project makes a point of what it calls preventing class explosion, which is the usual complaint about frameworks that generate a class per message type. That is a design position rather than a benchmark, and it is one of the more concrete reasons to look at the framework even if you never ship a game.

The technical constraints are clear from the badges and the manifest. It targets JDK 21, it is pure JavaSE with no hard dependency on Spring, and it integrates with Spring, Vert.x, Quarkus and Solon. The documentation lives at iohao.github.io/game with an introduction page, and the project is maintained in Chinese with a Chinese README alongside the English one and a mirror on Gitee.

Three parts, fused or separate

The architecture is three deployable pieces, and the design decision is that each one can be run independently or fused together.

The External Server is the piece that faces players. The Broker is the gateway. The Game Logic Server holds the actual game logic. In the smallest deployment all three are the same process, and in a large one they are separate processes on separate machines, and the framework supports both ends of that range.

The multi-server single-process mode is the part that changes how a team works. The project describes it as a way to debug distributed systems as easily as a monolith, and there is a dedicated run-one/ module in the repository that appears to be exactly that harness. For anyone who has tried to develop a genuinely distributed server, the appeal is obvious: the same code, the same routing, the same failure behaviour in development and in production, with the split introduced when the load requires it rather than on day one.

The claim is that the architecture eliminates the N times N scaling problem that the project attributes to traditional frameworks. The reason given is that there are no third-party dependencies for clustering and distribution, so a JVM is all you need. That is a strong claim and it is the load-bearing one, because the usual way to make a game server scale is to add a gateway tier, a session store and a service discovery system, and each of those is a thing to run.

The trade-off is implicit in the design. A system that does its own distribution owns the failure handling. There is no external broker to lose, but there is also no external broker doing the hard parts of cluster membership and message durability, and the project's own answers to those questions are the part you would want to read before committing.

Communication primitives, tracing and access control

The feature list is long, and a few entries describe mechanisms rather than adjectives.

Communication between logic servers is the core primitive: logic servers can talk across machines directly, and there is cross-process and cross-machine communication between them, with a dynamic player-to-server binding so that a player can be routed to the logic server holding their state, and moved when it moves. The protocol is described as hot-swappable, meaning protocols can be added or removed without restarting the gateway or the External Server and without disconnects for connected players, which is a substantial operational property for a live service.

One codebase supports TCP, WebSocket and UDP simultaneously with no code changes, extensible to KCP and QUIC, and one codebase also handles the data format, Protobuf and JSON among others. The client side is handled by interactive code generation for any frontend, with the topic list naming Unity, Unreal Engine, Godot, Cocos Creator and FXGL among the ecosystems it is used with, and the repository's widget/ directory holding the web side pieces.

Route-level access control is built in, which for a game server means a permission can be attached to a route rather than checked in every handler, and there is built-in full-link distributed tracing, so a call that crosses process boundaries can be followed end to end.

Two more entries are about correctness rather than features. Built-in per-player thread safety means the framework handles the concurrency for a player's own messages, which removes a class of bug that is otherwise a permanent feature of game server code. And JSR380 validation with assertion and exception patterns is used, with code as documentation, so the contract of a message is expressed in the type system rather than in a comment.

For deployment, the components can run independently or fused together, and the project insists on no hard dependency on Spring, which means it drops into an existing stack without owning it.

The startup and throughput numbers are the project's own

The README leads with a set of numbers, and it is worth quoting them as claims rather than as measurements.

The headline is 11.52 million business operations per second in a single thread, described as near-native performance. The startup figures are a boot typically under 1 second, minimal memory footprint, and a package size of about 15 MB as a jar.

These are the numbers the project publishes, and the repository overview does not describe the benchmark method, the hardware, or the definition of a business operation. For a lock-free, event-driven design with a per-player threading model, the shape of the claim is plausible, since the framework's own contribution is to avoid locks on the hot path, but the figure cannot be compared with another framework's figure because the definitions are not given. If the throughput number matters to your decision, the honest position is that you have to reproduce it on your own hardware, and the fact that the code is a jar of 15 MB with no third-party dependencies makes that reproduction unusually cheap.

The startup and size figures are the more useful ones for planning, because they are easy to check and they describe an operational property. A 15 MB jar that starts in under a second is a service you can scale out quickly, and a framework with no clustering middleware has fewer things to install on a new machine.

The licence is AGPL 3.0, and the project explains the choice in a way that is unusual and worth reading. There is no commercial edition, it says, and never has been and never will be, every feature is open source, and the commitment is to at least ten years of active maintenance starting from 2022-03-01. The stated reason is fairness to developers, arguing that a developer who leaves a company retains legitimate rights to the project they helped build, in contrast to permissive licences where the work becomes someone else's asset. Whether or not you accept that reasoning, the effect is a licence whose obligations apply to a server that users connect to over a network.

Version numbers in the twenties, and an uneven release trail

The versioning is the first thing that puzzles people who arrive from a Java project.

The releases are 21.31 on 2026-01-22, 21.32 on 2026-01-31 and 21.34 on 2026-02-17, so the numbers track the JDK line rather than a conventional major and minor scheme, and they are tied to the Java version the framework targets, which the badge puts at 21. The last push was on 2026-08-02, and the repository is not archived, so the source is current, but there has been no tag since February 2026.

That combination, active source with a six month old tag, is worth planning around. It is a common pattern in projects with a single dominant maintainer, and it usually means the developer's time goes into the work rather than into the release ceremony. For an adopter it means the repository, rather than a published artefact, is where the current state lives, and the changeLog_ioGame.md file at the root is where the movement since the last tag is recorded.

The repository layout matches the architecture. The common/ directory holds the shared code, external/ the external server, net-bolt/ the broker and gateway, run-one/ the single process development harness, and widget/ the web pieces, with a single pom.xml at the root aggregating them, a history/ directory, a doc_maven.txt, a BACKERS.md for the funding, and the English and Chinese READMEs side by side.

The project also keeps a Gitee mirror and a code quality badge from Codacy, and its documentation site has separate pages for the introduction and for topics like the protocol fragmentation problem, which suggests the documentation goes into design detail rather than stopping at a hello world.

Editorial conclusion

ioGame suits a Java team building a game server, an IoT backend or any system with many persistent connections that wants clustering without adding external middleware or a database to operate, and it suits teams that want to develop a distributed system as a single process. It is the wrong choice if your organisation cannot accept AGPL 3.0 for a server that users connect to, and a poor match if you need a framework with a stable public API and a long published release history, because the version numbers are in the twenties and the tagged releases in early 2026 have not been followed by a newer tag. Before adopting, read the AGPL 3.0 terms against the way you intend to deploy, run the single process mode to see the API before splitting the services, and check the change log to see how far the current source has moved past the 21.34 release.

Frequently asked questions

Official sources

1. iohao/ioGame on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases