Cytoid: a community-driven touchscreen music game built on a Unity core

A Unity core inside a Flutter application

Cytoid is a community-driven touchscreen music game, available on the App Store and on Google Play, with the project home at cytoid.io. The interesting part for an engineer is not the game but how it is put together, because the repository separates a Unity gameplay core from a Flutter application layer and connects them with a documented protocol.

The gameplay core lives at engines/unity/ and is built with Unity 6000.0.75f1 in the Personal edition, which the project pins explicitly. That is a large Unity version, and pinning it in the documentation rather than leaving it to a project settings file means a contributor knows what to install before anything else.

The Unity core is embedded in the Flutter side through the cytoid_game_core Flutter plugin, which sits at engines/unity/flutter_plugin/. The plugin's stated job is to provide an engine-agnostic JSON host protocol, and the current specification is in docs/host-protocol-v2.md. The version two in that filename matters, because a host protocol that changes shape between major versions is exactly the kind of thing that needs a version in its name.

The repository layout matches the split: engines/ holds the game and the plugin, docs/ holds the protocol and vendor documentation, tools/ holds supporting tooling, and there is an AGENTS.md at the root for agent-driven contributions alongside a .vsconfig, a .github/ directory and the LICENSE file.

Why the runtime is exclusive on both platforms

The two platform notes in the README are short and they are the most revealing technical detail in the project.

On Android the runtime presentation is an exclusive Unity Activity, explicitly not a platform view fragment. On iOS it is an exclusive Unity window, explicitly not a platform view. The double negative in both lines is doing work: it says the Unity surface takes over the screen for the game rather than being embedded inside the Flutter view hierarchy alongside native widgets.

That is a significant architectural decision, and it explains why the host protocol exists at all. If the game were drawn inside a platform view, the Flutter tree and the Unity tree would share the screen, and the two runtimes would have to agree about focus, about input routing and about lifecycle. Making the Unity side exclusive removes that class of problem, at the cost of the Flutter UI disappearing while a game is running. For a music game that is a full-screen interactive surface, the trade is usually the right one, and it also means the plugin needs a well-defined way to hand control back and forth, which is what the JSON host protocol provides.

The practical consequence for anyone reading the code is that the protocol document is the contract between the two halves, not a convenience. Changes to it affect the Flutter shell and the Unity core at the same time, which is why the specification lives in docs/ rather than in a comment.

The asset problem: a maintainer bundle you cannot get

This is the part of the project that will stop a contributor who is not already inside the community, and it is described without ambiguity.

The licensed Unity packages are optional. You unzip a maintainer Assets/Vendor/ bundle at engines/unity/, and the details are in docs/vendor.md. If you do not have that bundle, the in-repo fallbacks are used instead, and the example given is the storyboard shaders. In other words, the repository carries enough to compile and to run with a reduced visual fidelity, but not enough to reproduce what ships.

On top of that, you need to install Native Audio from the Asset Store, which the README notes has been free since 2025-09-22. It is a separate dependency that the repository cannot vendor for you, so a clean checkout is not a buildable game without at least one manual step outside the source tree.

That combination, a maintainer-only asset bundle plus an Asset Store dependency, is the real cost of contributing here. It is also a normal pattern for a commercial-era Unity project that was later opened up, where the art and the audio plugins carry licences that cannot be redistributed in a public repository, and the code was released under a copyleft licence while the assets were not.

The honest reading is that the fallback path exists for developers and contributors, and the maintainer bundle exists for builds that need to look like the shipped game. Anyone planning to publish a build from this repository needs to sort out the asset licensing first, and the graphical assets are outside the GPL grant.

What the GPL-3.0 licence actually covers

The licence statement is one sentence and it contains the important qualifier: the source code, excluding graphical assets unless stated otherwise, is distributed under the GPL-3.0 License.

That qualifier is the whole story for anyone thinking about redistribution. The code is copyleft, and the images are not. A fork that ships the code inherits the GPL obligations for that code, but the art has to come from somewhere else, either from the maintainer bundle under its own terms or from a different source. A build that mixes the two has two sets of terms to track, and the README does not claim otherwise.

This also explains the vendor bundle design. The maintainer holds the licensed Unity packages, distributes them to people who should have them, and keeps them out of the public tree so the repository does not redistribute assets it does not have the rights to. The Assets/Vendor/ directory in the tree is where that bundle is unzipped on a machine that has it.

The repository is not archived, the licence file is at the root, and the last push was on 2026-10-19, so the project is still being worked on. The licence terms themselves are the standard GNU GPL version 3, so the practical obligations for a modified distribution are the familiar ones. This is not legal advice, and the licence text is the authority, but the split between code and art is specific enough to this project that it is worth checking rather than assuming.

Getting set up: editor version, folders and docs

There is no install script in the repository and no build pipeline described in the README, which is normal for a Unity project. The setup path is the standard Unity one, with three specifics from the project itself.

First, the editor version. The gameplay core is built with Unity 6000.0.75f1 in the Personal edition, and that exact version is what the README names, so install that rather than whatever Unity version happens to be on your machine. Second, the plugin path. The cytoid_game_core plugin is at engines/unity/flutter_plugin/, and the Flutter side consumes it through its JSON host protocol, so the protocol document, docs/host-protocol-v2.md, is the thing to read before changing anything across the boundary. Third, the assets, which are the maintainer bundle and the Native Audio plugin described above.

The repository also carries a .vsconfig, which is the Visual Studio configuration file that pins the recommended C# tooling and workload for the project, and an AGENTS.md, which suggests the project expects contributions driven by coding agents and wants the instructions for them in the tree rather than in a wiki.

The docs/ directory is small and specific. It holds the host protocol specification, the vendor documentation for the Assets/Vendor/ bundle, and whatever else the project needs to explain. The tools/ directory holds supporting tooling rather than game code, and engines/ is where the actual work lives.

Because the core is a Unity project embedded in a Flutter app, a contributor touching the host side needs both toolchains, and the protocol document is the only place that describes the contract between them.

A community project with a storefront presence

The framing in the project description is community-driven, and the repository topics back that up: chart, community, customization, cytus, game, music-game and unity. The tags describe a game whose content and appearance come from its players rather than only from its developers, and the projects are hosted on the two mobile stores, with links for the App Store listing and the Google Play listing under the package name me.tigerhix.cytoid.

The release history tells you where the project is. Versions v2.1.2, v2.1.3 and v2.1.4 were all tagged in 2025, with v2.1.3 and v2.1.4 landing on the same day, 2025-11-30, which reads as a packaging fix rather than a feature release. The last push was on 2026-10-19, ten months after the newest tag, and the repository is not archived. So the honest maintenance description is that the code is still being worked on, while the store builds move in their own rhythm, and the tag list is not a reliable guide to how current a shipped build is.

There is a Discord community linked from the README, and the site is cytoid.io. For a project of this shape, that community is not decoration: charts and customisation are the content, the asset pipeline is partly closed, and the people who run the server side of that are the people who will answer a question about how the game is meant to be extended.

The engineering takeaway is that this repository is most valuable as a reference implementation of a Unity core driven by a Flutter host over a JSON protocol, and as a working game. It is less useful as a build you can clone and ship without talking to the maintainers.

Editorial conclusion

Adopt Cytoid if you want to study or contribute to a music game where the Unity gameplay core and the Flutter application shell are separated by a documented protocol, or if you want to play a community-driven game that ships on both mobile stores. Do not adopt the repository as a build you can reproduce from source alone, because the licensed Unity packages live in a maintainer bundle and Native Audio has to be installed separately from the Asset Store, and do not assume the graphical assets are GPL, since the licence covers the source code only. Before you start, read docs/host-protocol-v2.md and docs/vendor.md, pin the editor to Unity 6000.0.75f1 as the project specifies, and expect a gap between the last release in 2025 and the most recent push in 2026.

Frequently asked questions

Official sources

1. Cytoid/Cytoid on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases