# Skynet: A Lua-Based Actor Model Framework for Online Games

> Skynet is a multi-user Lua framework built on the actor model, originally designed for online games and now spreading to other industries. It runs on Linux, macOS, FreeBSD, and OpenBSD, and uses a modified version of Lua 5.5 to support multiple concurrent Lua states.

**cloudwu/skynet** — A lightweight online game framework

- Repository: https://github.com/cloudwu/skynet
- Stars: 14,163 · Forks: 4,272
- Language: C
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cloudwu-skynet

## What Skynet Solves and Who It Is For

Skynet addresses the challenge of building concurrent multi-user server applications for online games. It implements the actor model, where each service is an isolated unit that communicates with others by passing messages rather than sharing memory. This design prevents many classes of concurrency bugs that arise in shared-state architectures.

The README describes Skynet as heavily used in the Chinese game industry, with a growing presence in other industries and among English-speaking developers. The community is English-friendly: contributors can speak English, and issues and discussions can be filed in English at the project's GitHub Discussion page. The wiki and FAQ are written in Chinese, but the README suggests using Google Translate or DeepL to access them.

## How the Actor Model Is Implemented in Skynet

Skynet's architecture centers on Lua services running as independent actors within a shared C runtime. Each actor has its own Lua state, so there is no global Lua heap shared between services. The C layer, whose source lives in `skynet-src/`, handles the message queue, timer, socket I/O, and the module loader. Services communicate through a typed message queue; the kernel dispatches messages to the appropriate Lua handler without blocking other actors.

The `service-src/` directory contains the built-in C services (snlua, logger, gate, harbor), while `lualib-src/` contains C extensions exposed to Lua code: socket, mongo, netpack, memory, multicast, cluster, cryptography, sharedata, stm, debugchannel, datasheet, and sharetable. The `lualib/` directory provides the Lua-side libraries that application code imports. The `examples/` directory shows how to wire services together, including a Gate server and a client launcher.

## Building Skynet from Source

Skynet builds from a single `make` command after cloning the repository. On Linux, you need to install autoconf first because jemalloc (the memory allocator bundled in `3rd/jemalloc/`) requires it. The build process compiles the C runtime, the Lua 5.5 library, jemalloc, and all C extensions.

Clone and build on Linux:

```bash
git clone https://github.com/cloudwu/skynet.git
cd skynet
make linux
```

Or use the environment variable form:

```bash
export PLAT=linux
make
```

Supported platform values are `linux`, `macosx`, `freebsd`, and `openbsd`. On FreeBSD, substitute `gmake` for `make`. The Makefile is defined in `platform.mk` and the workspace-level `Makefile`; both are included in the repository and editable. Switching from the bundled modified Lua 5.5 to an official Lua version requires editing the Makefile to point at a different Lua library.

## Running the Example Nodes

Skynet ships with example configuration in the `examples/` directory. The standard test involves launching a Gate server node and a test client in separate terminal sessions.

In the first terminal:

```bash
./skynet examples/config
```

In a second terminal:

```bash
./3rd/lua/lua examples/client.lua
```

The client accepts text input and relays it to the server. The `examples/config` file shows the format for a basic Skynet configuration: it references the services to load at startup and can include a `standalone` option for single-node deployments. The `examples/` directory also contains configuration files for clustered deployments (`config.c1`, `config.c2`), MongoDB (`config.mongodb`), MySQL (`config.mysql`), and login service variants. The Lua scripts in `examples/` (agent.lua, main.lua, login/, etc.) demonstrate how services register handlers and communicate.

## Lua Version and Compatibility Trade-off

Skynet does not use the standard Lua 5.4 or 5.5 releases. It uses a fork of Lua 5.5.0 maintained at `https://github.com/ejoy/lua/tree/skynet55`, which adds support for running multiple independent Lua states within the same process. This is necessary for the actor model: each service gets its own isolated state.

The README confirms that official Lua versions can be used, but only by editing the Makefile. The trade-off is real: the modified Lua benefits from Skynet's specific concurrency model but diverges from the standard distribution. Libraries that assume global state or use unsafe Lua C API patterns may behave differently or break entirely in the multi-state environment. Teams porting an existing Lua codebase should audit it against this constraint before committing to Skynet.

## Limitations and Cases Where Skynet Is the Wrong Choice

Skynet's documentation is primarily in Chinese. The README notes that the wiki (github.com/cloudwu/skynet/wiki) is written in both English and Chinese, but the FAQ is in Chinese only. For teams who cannot read Chinese and do not want to rely on machine translation for troubleshooting, this is a real friction point.

Skynet is not a web application framework. It has no built-in HTTP routing, REST handler generation, or template engine. Its cluster system (`cluster1.lua`, `cluster2.lua`, `config.c1`, `config.c2` in examples/) handles inter-node communication, but configuring it for a production deployment requires understanding Skynet's service topology concepts. Teams building web APIs would find frameworks built specifically for that purpose more appropriate.

Skynet also does not support Windows. The four supported platforms are Linux, macOS, FreeBSD, and OpenBSD. A game studio operating primarily on Windows workstations would need a Linux server for production deployment and a Linux or macOS machine for development, or would need to use a different framework.

## Release History and License

Skynet v1.8.0 was released on 2025-01-14, following v1.7.0 (2023-11-13) and v1.6.0 (2022-11-17). The last push to the repository was on 2026-09-16, indicating ongoing development. The project is licensed under the MIT license, which places no restrictions on commercial use, redistribution, or modification, provided the copyright notice is retained.

The `HISTORY.md` file at the repository root tracks changes between releases. The `3rd/` directory contains git submodules for jemalloc and the modified Lua runtime; running `git submodule update --init` or the provided `update3rd` Makefile target fetches them.

## Conclusion

Skynet suits teams building multi-user online game servers who are comfortable with Lua and the actor model, and who can read Chinese documentation or use machine translation since the wiki and FAQ are written primarily in Chinese. It is not a good fit for teams that need a REST API framework, a single-threaded scripting environment, or mature English-language documentation out of the box. Before adopting Skynet, verify that your target platform is among the four supported (Linux, macOS, FreeBSD, OpenBSD) and that your team can work with the modified Lua 5.5 runtime, since mixing official Lua versions requires editing the Makefile.

## FAQ

### How do I install Skynet?

Clone the repository with `git clone https://github.com/cloudwu/skynet.git`, then run `make linux` (or the appropriate platform name) from the repository root. On Linux, install autoconf first because the bundled jemalloc build requires it.

### How do I use Skynet?

After building, launch a Skynet node with `./skynet examples/config` using the example configuration, then write Lua services in `lualib/` or a new directory and reference them in your own config file. The wiki at github.com/cloudwu/skynet/wiki documents the service API in both English and Chinese.

### How do I set up Skynet for a project?

Create a configuration file modeled on `examples/config`, specifying the Lua path, the cservice path, and the bootstrap service to launch at startup. For a clustered deployment, use the `config.c1` and `config.c2` files in examples/ as templates and consult the cluster documentation on the wiki.

## Sources

- [cloudwu/skynet on GitHub](https://github.com/cloudwu/skynet)
- [Issues](https://github.com/cloudwu/skynet/issues)
- [License: MIT](https://github.com/cloudwu/skynet/blob/master/LICENSE)
- [README](https://github.com/cloudwu/skynet/blob/master/README.md)
- [Releases](https://github.com/cloudwu/skynet/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cloudwu-skynet