MassSample: a working reference for Unreal's experimental ECS plugin
My understanding of Unreal Engine 5's experimental ECS plugin with a small sample project.
At a glance
- What is it?
- MassSample is an MIT licensed Unreal Engine 5 sample project that documents the Mass entity component system, with a crowd of cones parading along a ZoneGraph, a line traced projectile simulation, a hashgrid and Mass spawners for zonegraph and EQS. The documentation is candid that the ECS plugin changes often and the information may be out of date.
- Who is it for?
- MassSample is a good pick for an Unreal team trying to learn Mass from working code rather than from documentation, because every concept in the plugin has a matching scene in the sample and the README's table of contents maps one to one onto the source; it is the wrong pick if you need stable documentation, because the authors state plainly that the plugin changes often and the information might not be accurate, and before you start you should install Git LFS, since the zip downloads of the repository will not work without it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 118 days ago.
- What is it written in?
- Mainly C++, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A community reading of an unstable plugin
MassSample is described as its authors' somewhat work-in-progress understanding of Unreal Engine 5's experimental Entity Component System plugin, with a small sample project attached. The two authors are Karl Mavko and Alvaro Jover, and the disclaimer is specific about two things.
First, they are not affiliated with Epic Games. Second, this system is actively being changed often, so the information might not be totally accurate.
That framing explains the whole shape of the repository. This is not an official sample and it is not a tutorial with a fixed curriculum. It is two developers writing down what they have learned about a plugin that is still moving, and shipping a project that proves their notes compile and run.
The README also carries a version history that reads like a changelog of the plugin rather than of the project. A 5.7 update moved the code to 5.7 with the note that the readme will have to be updated over time. A 5.6 update brought the code up to 5.6 with many small improvements and fixes, along with an apology for the lack of response to pull requests and questions because the authors had been busy at work.
The most useful line in that section is the warning about the code examples. A lot of the documentation is still valid, but some of the code examples will need a full redo because they may use outdated pre-5.6 code, and the guidance given is that when in doubt the code is always the most reliable indicator of how the API should be called. That is a candid statement about the state of a wiki written alongside moving target, and it is more useful to a reader than a false promise of completeness.
The licence is MIT, the primary language is C++, and the last push was on 2026-06-27.
Fragment, processor, and the renaming of everything
Mass uses different words from the rest of the ECS world, and the README has a table for the translation because the differences would otherwise cause confusion with existing Unreal code.
Entity stays entity. Component becomes Fragment. System becomes Processor.
The README then explains the conceptual difference from ordinary Unreal gameplay code, and this is the part worth reading even if you know ECS already. Typical Unreal game code is expressed as Actor objects that inherit from parent classes to change their data and functionality based on what they are. In an ECS, an entity is only composed of fragments that get manipulated by processors based on which fragments they have.
The distinction is what they are versus what they have, and it changes how you write the code. An actor hierarchy encodes behaviour in the type. An entity is a small unique identifier pointing at some fragments, and a processor defines a query that filters for entities with specific fragments. The example given is a basic movement processor querying for entities that have a transform and a velocity component, so it can add the velocity to the current transform position.
The performance claim follows from the storage model. Fragments are stored in memory as tightly packed arrays of other identical fragment arrangements called archetypes, so the movement processor can be incredibly high performance because it does a simple operation on a small amount of data all at once.
The README also places Mass in the wider landscape, noting that internally it is similar to the existing Unity DOTS and FLECS archetype-based ECS libraries, and that there are many more.
The sample project is the curriculum
The sample project section is where the concepts become concrete, and the list of features reads like a table of contents for what Mass can do.
There is a bare minimum movement processor to show how to set up processors, which is the entry point for anyone learning the plugin. There is an example of how to use Mass spawners for zonegraph and EQS. There is a Mass-simulated crowd of cones that parades around the level following a ZoneGraph shape with lanes, which is the most visually obvious demonstration and the one that makes the archetype model legible, because you can watch thousands of entities move along a path.
There is a linetraced projectile simulation example, which shows the collision side of the system. There is a simple 3d hashgrid for entities, which is the spatial acceleration structure that makes the linetrace example work at scale. There is very basic Mass blueprint integration, which is the part that connects the ECS world to the rest of an Unreal project.
Read together, that list walks through the whole stack: fragments and processors, spawning, spatial queries, movement, collision, and the bridge to the engine's own object model. That is a well-chosen progression, and it is one you can run and look at rather than only read about.
The repository layout supports it. The top level holds MassSampleProject.uproject as the Unreal project file, Source/ for the C++ code, Plugins/ for the plugin modules the sample needs, Config/ for the project settings, Content/ for the assets, and Images/ for the documentation screenshots. The .vsconfig file at the root points at the Visual Studio components needed to build it, and .gitattributes carries the Git LFS configuration the project depends on.
Cloning it needs Git LFS, and that is not optional
The very first line of the README is a warning that will save you an afternoon if you read it before starting.
The project requires Git LFS for it to work properly, and zip downloads will not work. That is stated in bold at the top, before anything else, because the failure mode is silent in the sense that a zip download gives you a repository that opens and appears to work until the content is missing.
The requirements are Unreal Engine 5.6, described as the latest version as of writing, from the Epic Games launcher, Git for version control with links for Windows, Linux, Unix and macOS, and Git Large File Storage.
The download instructions for Windows are given in a way that assumes the Git Bash shell, since the first step is to right-click where the project should live and press Git Bash Here. Then the clone and the LFS pull:
git clone https://github.com/Megafunk/MassSample.gitgit lfs pullAnd once LFS finishes, close the terminal.
The reason for the separate LFS pull step is that a fresh clone does not automatically fetch the large files in every case, and the assets in Content/ are the bulk of the repository. A clone without the LFS pull gives you a project with missing or stub content.
The project is currently built for the Unreal Engine 5 latest version binary from the Epic Games launcher, which is a specific instruction: it expects the launcher build of the engine, not a source build, and it expects a particular version of the plugin to be present.
What the table of contents tells you about the API
The README's table of contents is the best evidence of how much surface the Mass plugin has, and it is worth reading as an API map rather than as a reading list.
After the Mass and ECS overview and the sample project, the contents go into the concepts in a deliberate order. Entities come first, then Fragments, and within fragments a subsection on Shared Fragments, then Tags, then Subsystems, then the archetype model with subsections on tags and fragments within it. Processors and Queries follow, and Queries has four subsections: access requirements, presence requirements, iterating queries, and mutating entities with Defer(). Then Traits, then Observers with two subsections on their limitations and on observing multiple fragments and tags, and finally Multithreading.
That ordering is a sensible pedagogy because each concept depends on the previous one. You cannot understand the archetype model without knowing what a fragment and a tag are, and you cannot understand observers without queries.
Three of those entries hint at the parts of the API that are fiddly. The access and presence requirements for queries are two different things, which are worth keeping distinct when you write a query. The Defer() mechanism for mutating entities is the standard escape hatch for structural changes during iteration, and having it documented separately suggests it is not obvious. And observers come with an explicit limitations subsection, which is a warning that observers are the part of the system with rough edges.
After the concepts, the table of contents lists common Mass operations for spawning, destroying and operating on entities, then the Mass plugins and modules section covering MassEntity, MassGameplay and MassAI, and finally other resources.
Where this sample is the wrong tool
The clearest boundary is the one the authors state themselves. This is a community reading of an experimental plugin that changes often, the information might not be totally accurate, and the code is the only reliable guide. If your requirement is documentation you can rely on for a decision, that is not this repository, and the honest answer for an Epic plugin in flux is the plugin's own source and Epic's team.
The second boundary is scope. MassSample is a small sample project with a sample scene, and the sample features are described as a list of small demonstrations, a bare minimum movement processor, a basic hashgrid, very basic blueprint integration. It is not a framework, a template, or a starting point for a production game. If you want to ship a game with Mass, you are starting from the engine, not from this repository.
The third boundary is the ecosystem around it. The plugin is experimental, so the tooling around it is thinner than around a shipping system, and MassGameplay and MassAI exist as separate modules with their own maturity levels. A team evaluating Mass for a live project should be looking at the engine version they will ship with, not at a sample whose README explicitly flags parts of its own documentation as outdated.
The fourth is a practical one about maintenance. The authors apologise for a slow response to pull requests and questions because they were busy at work, and the 5.7 update note says the readme will have to be updated over time. That is an entirely reasonable way to run a personal project, and it means the value of this repository is highest for a reader who wants working examples today and is prepared to adapt them as the plugin moves. A team that needs maintained examples in a year should not count on them.
Editorial conclusion
MassSample is a good pick for an Unreal team trying to learn Mass from working code rather than from documentation, because every concept in the plugin has a matching scene in the sample and the README's table of contents maps one to one onto the source; it is the wrong pick if you need stable documentation, because the authors state plainly that the plugin changes often and the information might not be accurate, and before you start you should install Git LFS, since the zip downloads of the repository will not work without it.
Frequently asked questions
What is MassSample and who wrote it?
It is a small Unreal Engine 5 sample project documenting the experimental Mass entity component system plugin, written by Karl Mavko and Alvaro Jover. The authors state they are not affiliated with Epic Games and that the system changes often, so the information might not be totally accurate.
Why do I need Git LFS to use MassSample?
The project requires Git LFS for it to work properly and zip downloads will not work. After cloning with git clone, you run git lfs pull, and the project is built for the Unreal Engine 5 binary from the Epic Games launcher with Unreal Engine 5.6 listed as the requirement.
How does Mass terminology differ from other ECS libraries?
Component becomes Fragment and System becomes Processor, while Entity stays Entity. An entity is a small unique identifier pointing at fragments, and a processor defines a query filtering for entities that have specific fragments, with fragments stored as tightly packed archetype arrays.
What does the MassSample project demonstrate?
A bare minimum movement processor to show processor setup, Mass spawners for zonegraph and EQS, a crowd of cones parading around the level along a ZoneGraph with lanes, a linetraced projectile simulation, a simple 3d hashgrid for entities, and basic Mass blueprint integration.
Is the MassSample documentation up to date?
Partly, by the authors' own account. They note that a lot of the documentation is still valid but some code examples may use outdated pre-5.6 code, and they advise that when in doubt the code is the most reliable indicator of how the API should be called.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/megafunk-masssample)Was this useful?