= detailed
:revnumber: 2.1
:revdate: 2020/07/25



== Entity System Details


=== Hello ES

This wiki is dedicated to who want to do research about Entity System.

You should 've read a brief introduction here: xref:es/entitysystem/introduction.adoc[entitysystem:introduction]

And if you still have some concerns you are in the right place!


[IMPORTANT]
====
This wiki is a collection of known sources, authors from internet and our forum. Corrections are welcome! The main source is the discussion in this topic: link:https://hub.jmonkeyengine.org/t/entity-system-topic-united/27193[https://hub.jmonkeyengine.org/t/entity-system-topic-united/27193]
====



=== Why you here?

'Cause:

.  You may read famous T-machine article about entity systems in MMORPGs.
.  You may come from Unity, UDK, or another engine that used it
.  You may come from Database and web world
.  You read a lot of articles, forums and try few projects with dramatic debates

But:

.  You still un sure/ clear about OOP ,COP, data driven…
.  You doubt ES concept, find its impossible to do ES right
.  You want to learn more

I hope this page will help you 30% the way to reach the destination. It's the place where we concern about the design wisdom of ES, and consider its detailed implementation in Java, eventually integrate in JME3 for a real-time game.


[IMPORTANT]
====
Before you start, I also want to mention that there are few implementations of ES in JME3, after read this page, you can judge the design of each one accordingly and choose one. Also read the interviews with each authors about their approaches!
====



=== Scope & Structure of this page

1) Introduction:

.  Basic idea of ES : Entity, Processor(System), other terms.
.  Core elements and its alternative
.  What is NOT an ES…

2) Why, when, where ES matter.

.  Pros – cons?
.  Know issues
.  OOP to COP, or else
.  Change of mindset


==== COP’s Entity System in OOP java

Entity System in turn is the Core and fundamental and most obvious implementation design of COP (Component oriented programming) in real-time application scale!!!

In fact the implementation details of Entity systems vary, some may resemble database core, some may have troubles with OOP incompatibility, some may appear to get all the good of Functional language…

but note that Entity System really stand on its own terminology on this single page:

[WARNING]
====
We are talking about the ES within COP, but implemented by a pure OOP like Java.

====



== Ideas & Concepts


=== Idea


=== Concept

Slides

Pictures


=== Core elements and its alternative

NOTE: Definition notations:

*  Normal is clearly/no doubt in the definition.
*  *Bold* is keywork.
*  _Italic_ is example
*  +++<u>Underling</u>+++ is doubt
*  +++<strike>Strike-though</strike>+++ is implementation detail, not in the definition


==== Entity

An Entity is simply *an unique Id*. _Every Unit, Item, Bullet, etc. in your game will be represented by one of there entity Ids_.


==== Component

A Component is a class which only contains data. +++<strike>This means it has a constructor and only getter methods</strike>+++.
_Examples for Components can be:
  * PositionComponent
  * MovementComponent
  * CollsisionComponent_

Components are *added* to the Entities.

There can *only exist one component* of the same class for one entity at the same time.

As you can see *Entities are made flexible up of different Components*. _You need your Armored Robot?_ No Problem, you only need to combine the right components. Besides you are able to remove/change/add components during the game +++<strike>which is a huge benefit of Entity Systems.</strike>+++


==== Systems

Simply all other classes *except the components and the entities* can we consider as systems. You need to pay attention when you read about other Entity Systems because they can have different ideas of what a system is.

In the systems you can request all Entities which have special components.
_For example you can say that you want all entities who have a position and a movement component and now calculate the new position for these Entities +++<strike>by overwriting the old position component with a new one</strike>+++._


=== Ideas similarity:

from Component oriented architecture:

.  Decoupling
.  Reusable
.  Primitive Unit

from Data driven architecture:

.  Data who decide

from Data oriented architecture:

.  Everything is data
.  Repository existence
.  Homogeneous data
.  Regular workload
.  Simple dataflow

Short explanation

.  Decoupling : each piece can work together without aware of each other.
.  Reusable : can be easily bring to use again somewhere else
.  Primitive unit : each piece from a simplest form which contains, fulfills itself.
.  Data who decide: data decide each and every result, activities of the software
.  Everything is Data: all piece in the software system is Data
.  Repository existence: exist a place to keep all the data, the one door to reach them
.  Homogeneous data : data is treat the same
.  Regular workload : software that run at regular rate, kind of balance trade off between performance and complexity
.  Simple dataflow: the flow of the data is easy to watch, inspect, start stop, manipulate. As the root reason for regular workload!


Ideas similarities here actually is resulted from with decades of history of revolving of the paradigm. That's why you will see the same concepts of Entity system appear every where from a database to a repository. Of course because it have the same root.Check Pros and Cons chapter for full, detailed idea and design goals and successes.



== Terms


[IMPORTANT]
====
Here are some terms that will be mentioned below but usually have misunderstood or misplaced because of their confusions. Try to do another research to make sure you understand clearly all the terms first!
====


*  Object Oriented Programming
*  Data Oriented Programming
*  Component Oriented Programming
*  Data driven programming
*  Data driven solution (architecture)

Here is a short one to help you get start quickly : xref:es/entitysystem/terms.adoc[terms]


== What is NOT an ES ?

From more 'open' perspective the core elements can be viewed as, but remember the name as a noun can be mislead:
_This resulted as a discussion of @pspeed and toolforger, eventually is form a skeptical question, it's really interesting by how we all see this problem confused at first!!_

]
Entity -> ID. It just binds the components together, in the sense that there is one function that creates a bunch of components with the same ID, and one function to destroy all components for an ID. An entity is the set of objects that have the same ID, entities don’t exist as coherent objects inside the code.

Component -> Facet. A position is a facet of an entity, as its velocity, its health, its armor, its whatever. If entities were Java objects, facets would be groups of interrelated properties.

System -> Processor. A function that operates on a slice of components.

This often result in mislead skepticism about the design. So get back to read it carefully one more time and some gotchas and practical wisdom below.


== Gotchas & Practical wisdom


[TIP]
====
This area contain some best gotchas and practical wisdom when working with ES. I change this to upper position in the page be cause I think practical works save us more than theories. This page can be called a "`Design`" course after all without this section!!!
====



=== System ~ Processor?


In a pure ES, this is not a thing, really. Some implementations force this on you because they couldn’t think how to do the ES job efficiently… but it’s still not a thing. All of your code that isn’t an ES is a "`system`", technically.


System = everything that isn’t an Entity or a Component but uses Entities and Components.


=== Entity ~ GameObject?

Entity should just be interpreted as a bunch of its Component. GameObject or anything else represented by an Entity is by accident. So no force to represent "`all-every`" gameobject as Entity; and no force that "`all-every`" Entity is gameobject.


=== Has ~ Is?

From software designer POV, Relationship in COP is a sensitive topic; by nature, Component is against (or override) Relation.

The deception '`Has`' relationship between Entity and its Component actually represent everything in various meaning from the literature '`Is`' , or literature '`Has`'.. to '`related to`'. BUT keep in mind, this is blurry and it's almost always implemented as indirect access, not like a property in an object but involves processing-lookup under the curtain! So you may find this difficult to extract and detect these different from your traditional OOP software design!


=== Some insights

This is the place to share the "`real`" world difficulties when working with ES, here in JME3 or in other engines. In Practical Wisdom, we will raise some known solutions for them. This section may revive some part of the Cons or known issues sections but practically.


=== Practical wisdom


== ES done right

Because this topic is so debatable, there is no solid candidate for ES done right now in my POV, but Zay-ES and Artemis are closest one, Zay-ES a little bit better as its the later born.


=== Why debatable [Short]?

Because apply to each game, the scenarios and usecases are very different. Situation changes, a design which should be right can be a failure!  You may see the point.

This topic start flame in almost every discussions I've come through, someone should be like OOP versus COP, ES is not for all,..etc. At first, the debate should focus into a specific scope, specific genre. Here (this page) we still arrange the statements like general scope. But later in the interviews you can see some "`real`" applications and implementations.


==== Should be?

Theoretically a Java ES done right should be:

.  Pure data : very debatable
..  – Mutable : as bean with setter and getter
..  – Immutable : as bean with getter, should be replaced if changed.

.  Multi-threading, concurrency enable : very debatable
..  – As my experience, pure data or not is not clear contract to multi-threading success. Consider other things happen outside of ES scope, so it not an solid warranty that those component will not be touched by any other thread.
..  – Also if there is a contract that no other thread touching those data, in Java style via synchronization or other paradigm like actor… multi-threading also consider success but just more complicated!

.  Communication: very debatable
..  – Event messaging enable
..  – No event or messaging : update beat, no need of inter-com or events. How can we do network messaging?

.  Is database (and other kind of persistent) friendly
..  – Save to XML?
..  – Send over network?
..  – Change sets are resembling Database concept, what about transactions?

.  Is enterprise friendly (expandable/ extensible/ modularizable)
..  – Spring, as lazy loaded, injected?

.  Script possibilities
..  – Can be script, non trivial work in pure data!
..  – Can be use with other JVM language than java like groovy, or scala, jython?

.  Restrictions and limitations
..  – No dynamic Java object methods in Component ? What about Entities and Systems ( Processors)
..  – An overall way to manage and config Systems, freely chose? How to hook to its routine?

.  Dependencies
..  – The separation of components are clear, as no dependencies at all. Hard cored, scripted or injected will break the overall contract!
..  – The separation of Entities. What about dependencies of entities? Ex: parent/ child relationship in JME spatial. How the framework handle that?
..  – The separation of Systems. Ex: any contract about that?


Detailed explanation : xref:es/entitysystem/points.adoc[points]


== Design


[IMPORTANT]
====
In Design phase, even don't know any of implementation detail, we judge upon the design concepts and its Infrastructure!!!. Detailed implementation judge will be considered later!
====


[IMPORTANT]
====
This is a short checklist that help you open your mind before going to design an ES. It's short and trusted; the Pos and cons section needed previewing and under heavy concerning!
====



=== Why, when, where ES matter.


==== Why?

.  BLOB aka The fall of inheritance: Complex type can not be represent as class in java OOP!
.  Tired of OOP. Compose over old-skool programming . Like artists.
.  Reusable via prefab (well, this is very debatable as compare OOP!!)
.  …


==== When?

.  Trade off between complexity and performance is carefully considered.
.  Input and output are well setup. Assets are all in good format, output are well defined, workflow and routines are fixed. Seen in commercial 3D game engine.


==== Where?

.  Mainly to handles/ manage your data and entities.
.  Usually in MMO where BLOB happen.
.  Batch/ cache processing environment, device, GPU, others.


=== Why not?

.  It’s easy to get it wrong as you often come from OOP world (of course, because you are Java developer).
.  Can result in done wrong too much time, that un affordable!!
.  It’s *not* an certainly proved technology (that why we here)
.  Its have bad issues
.  Only suite for cases (not every)
.  No good IDE, +++<abbr title="Graphical User Interface">GUI</abbr>+++ support in Java or JME3 world currently


==== When not?

.  Limited time and first try! ( can be good if in limited time but ES is production mode ready)
.  Small game, simple gameplay …


=== Pros – cons?

Here, I listed the pros – cons of the COP and Pure data ES.

[WARNING]
====
needed previewing and under heavy concerning!
====



[IMPORTANT]
====
You can see I try as the one who repeat sentences that speak out by others in various sources as a short manner! So this list and information need clarification of correction afterward!
====



=== Pros:

.  No BLOB anti-pattern, no deep inheritance consider bad effects

Read: link:http://gamearchitect.net/Articles/GameObjects1.html[http://gamearchitect.net/Articles/GameObjects1.html]

A lot of good things come if done "`right`"!

.  Simple, intuitive
.  Communication made simple
.  What you see is what you have → composing
.  Reusable with prefab
.  Batch / Concurrent processing/caching as in modern CPU, GPU
.  … ten more

//link:http://piemaster.net/2011/07/entity-component-primer/[http://piemaster.net/2011/07/entity-component-primer/]


=== Cons:


[IMPORTANT]
====
'Problem' here means the 'problem' to solve not a bad situation!
====


.  No OOP: COP Done "`right`" means forget about almost all OOP things: Pure data, Class become Type, no inheritance, encapsulation…etc , no best of both world!
.  Splitting dilemma: Same with OOP Classify problem: How to split, how to change the data when you change the splits?
.  Duplicated component: Same root as confusion in component splitting but, this problem about how can we made a more than one component of a kind per object entity… Ex: Car with 4 wheels, the component will be a 1stWheel, 2ndWheel, or a single list of WheelComponent… ?
.  Data resampling problem in game, data such as textures, text, 3d models everything … should be crafted: made, converted again to suite with existing data model – that’s the component in the ES.
.  Mindset change problem: One will have to re-code a few times to implement an ES, in initial, half ass and full level.
.  Flat table problem: Because ES is a big table by nature, with component set is a row. It’s as efficient even less than a big table, which form the flat table problem as seen in many indexed base database. Tree, Graph and other data structure will almost immediately break the ES contract!!
.  Observation problem: As update beat over listening method, ES restrict the observation methods a lot.
.  Security problem : No encapsulation, kind of no private POJO mean no java power in protecting data, a lot of security holes! ES implementations and COP forget all about security danger as Component contracted to be processed by Processor but not hiding its content.
.  Scale : In theory, ES should scale well..!!! But read this carefully or mislead it, enterprise system need much more than just a way to organize your data!!!

////
[TIP]
====
Because a lot of people find interests about the downside of ES, I've listed them carefully here xref:jme3/contributions/entitysystem/detailed/cons.adoc[cons]. After knowing the acceptable solutions from the authors, I will remove or marked the solved problem! [Peace! :p]
====
////

=== ES consider good design in real-time app?


[WARNING]
====
Of course, ES has its missing features!!!!
====


But for some reason its designs are considered good for real-time application like a "`common`" video Game, or "`common`" simulation; especially common in MMO world.

Here is a short of '`why`' answers from a software architecture designer view, explain based on its borrowed ideas: [This is very different from various sources you've read, because it's not embedded any implementation details!!!]

.  Decoupling : each piece can work together without aware of each other.
.  Reusable : can be easily put to use again somewhere else.
.  Composable : pieces can work together

have fundamental relationship with decoupling.

.  Primitive unit : each piece from a simplest form which contains, fulfills itself.

have fundamental relationship with decoupling.

(*) These lead to advantages in development:

.  do it in one place only when doing implementation (coding, configs…), .
.  intuitive and ease of development jobs (compose entity with component drag and drop)
.  distributed jobs, assets
.  reuse data, code which in existed component
.  unit test
.  [more]

——————————————————————————————

.  Data who decide: data decide each and every result, activities of the software
.  Everything is Data: all piece in the software system is Data
.  Repository existence: exist a place to keep all the data, the one door to reach them

(*) These open the world of complex gameplay and distributed persistent like seen in MMO. A single data change can result in change in the gameplay; a
——————————————————————————————

.  Homogeneous data : data is treat the same
.  Regular workload : software that run at regular rate, kind of balance trade off between performance and complexity
.  Simple dataflow: the flow of the data is easy to watch, inspect, start stop, manipulate. As the root reason for regular workload!

(*) These lead to a lot of simple but efficient algorithm to get high performance in runtime for a software such like a "`common`" video game, which run in console, GPU, CPU which involve and share the same model with cache and batch instructions, an a certain heartbeat…Notice the bottleneck of CPU-GPU and between different processing unit, platform is the most headache of Game designer for decade is ease with the regular workload; let the game run smoothly and stable, result into nice visual representation..


=== ES consider bad design in …?

From @pspeed:

It is a bad design choice where:
- there aren’t many entities and/or the behavior is so clearly defined that you’d just implement it one or two classes. Thing card games, a lot of puzzle games, etc..
- the game is so simple that it’s just implemented as JME controls and a few app states. You could use an ES here but it would be wasted.
- the game logic cuts across all objects nearly all the time. (I think of card games and puzzle games again.) This usually implies that there are few entities, though.
- the team doing the work will have trouble understanding an ES. To me this is a huge one. Sometimes our choice of technologies is not dictated by what might be technically best… but what is technically best for the skills of the team. For example, if your artist only knows Sketchup then Blender is probably not the right tool even if it is superior in many ways.


=== Known issues:

Even if done right, the ES also have it underlying issues which noticed by its authors, (that means annoying things)!

*Why this section has things from the Cons section but consider differently?*


The Cons section describes problems should be concerned, likely to be done wrong, or the limit of the design they can be solved in implementations or not is not important!



Known issue means the problem persists in even the well designed; or persist due to the underlying infrastructure, application, programming language, etc!!



==== Communication:

Happens in non pure data solution, when Components don’t function independently of each other. Some means of communication is necessary.

* Two approaches (both viable):
** Direct communication using dynamic cast and function calls
** Indirect communication using message passing

In pure data solution, by not query or just loop through interested component at one update cycle, the Processor eases out the need of other communication, but in complex scenario, such as combine with outer event handling such as Network, where message passing is nature, the problem still persist!

//as describled in reference [6]
//Read: link:http://acmantwerp.acm.org/wp-content/uploads/2010/10/componentbasedprogramming.pdf[http://acmantwerp.acm.org/wp-content/uploads/2010/10/componentbasedprogramming.pdf]


==== Script

The "`script problem`" happens for the same reason with the "`communication problem`" mixed with "`pure`" data or "`not`" problem. When a component is hard to inspect, its outer relationship hard to define and its property is rejected to change, how can you script it?

Read: link:http://blog.gemserk.com/2011/11/13/scripting-with-artemis/[http://blog.gemserk.com/2011/11/13/scripting-with-artemis/]

Nearly one end up back to half-assed solution, not a pure data ES if their really need scripting in.


==== Arbitrary Routine and Query

link:https://hub.jmonkeyengine.org/t/in-range-detection-with-lots-of-entities/26910[https://hub.jmonkeyengine.org/t/in-range-detection-with-lots-of-entities/26910]


== Implementation Approaches


== OOP to COP . or else?

+++<u>@atomix POV:</u>+++

As said, as a long term Java developer and also an artist. I can not see a strong, confident reason why we should switch over to COP at the moment.

BLOB is not a problem with a carefully designed software, same as hard as split your components… Deep inheritance even multi inheritance problem can not be reached in an indie project, and even it reached, maintain it always easier than redesign a 3D model to change the export pipeline!!!

Also the tangled wires between inheritance form the nature of programming and matter in the universal. :p

*BUT* They have IDE support, profiler, proved technologies, lot more… We talking about a no IDE support paradigm with plain text editor, table and some black magic, tell me more about the company will approve your plan?

Some alternative solutions may solve almost your design goals when you are likely to use an ES:

.  Smart bean framework : try Spring, EJB. For Enterprise, if you've known EJB and Spring, you will not bet in home grown ES, don't you?
.  Actor framework: try AKKA
.  If you see Java as a failure, try Scala’s trail …


[WARNING]
====
So, my last advice is: If you are not doing MMO *Take a look in other alternative technologies.* !!!!
====


//.  Take a look at reference [7] and link:http://lambdor.net/?p=171[http://lambdor.net/?p=171] , the guy suggest you to switch to Functional reactive programming :p
.  Try Scala and AKKA and read more about concurrency , don't use flat table!!!


== Change of mindset


[IMPORTANT]
====
I think this should be in another page or even in a book! :p
====

This chapter dedicated to people still who really want to *switch to this new paradigm* after all the warnings and awarenesses.
So this chapter will mainly answer the BIG question:

*What should be changed to adapt to this new paradigm?*


=== What will we face


=== What should be change


=== OOP Object Modeling vs COP Object Modeling


=== Team management


== Java Entity System projects

Some open source Entity System implementation projects:


=== Artemis: General

GoogleCode: link:https://code.google.com/archive/p/artemis-framework/[https://code.google.com/archive/p/artemis-framework/]

Website: link:http://gamadu.com/artemis/index.html[http://gamadu.com/artemis/index.html]

Wiki: link:http://entity-systems.wikidot.com/artemis-entity-system-framework[http://entity-systems.wikidot.com/artemis-entity-system-framework]

////
[IMPORTANT]
====
Review: HERE! xref:jme3/contributions/entitysystem/interviews/artemis.adoc[artemis] because I can not contact with author of Artemis at the moment so I will have a short review of it with some of my experience working on it and base on its source code!
====
////


==== Spartan: [used for Slick. abandoned]

GoogleCode: link:https://code.google.com/archive/p/spartanframework/[https://code.google.com/archive/p/spartanframework/]


=== JME integrated


==== Zay-ES : @pspeed

Post: link:https://hub.jmonkeyengine.org/t/my-es-in-contrib-zay-es/25702[https://hub.jmonkeyengine.org/t/my-es-in-contrib-zay-es/25702]

Forum : link:https://hub.jmonkeyengine.org/c/user-code-projects/zay-es[https://hub.jmonkeyengine.org/c/user-code-projects/zay-es]

Wiki: xref:es/entitysystem/entitysystem.adoc[entitysystem]

Links: link:https://hub.jmonkeyengine.org/t/zay-es-links-more-chars-because-forum-is-dumb/27135[https://hub.jmonkeyengine.org/t/zay-es-links-more-chars-because-forum-is-dumb/27135]

Interview:


==== EntityMonkey : @zzuegg

Post: link:https://hub.jmonkeyengine.org/t/entitymonkey-a-simple-entity-system-for-jme/23235[https://hub.jmonkeyengine.org/t/entitymonkey-a-simple-entity-system-for-jme/23235]


==== Private : @Empire phoenix

Interview:


=== Implementation and scope of each project:

The comparisons will focus in these below points, follow with the scope, status of each projects

.  Initial philosophy
.  Pure data or not?
.  Multi-threading, concurrency enable or not?
.  Communication: Event messaging enable or not?
.  Is database (and other kind of persistent) friendly or not?
.  Is enterprise friendly (expandable/ extensible/ modulizable) or not?
.  Script possibilities?
.  Restrictions and limitation
.  Dependencies
.  Current status: Long term, stable, community?

[More]


[IMPORTANT]
====
The comparison table is in Google Docs: Help me fill it!!!!
====


link:https://docs.google.com/document/d/1pRTZPFtHz7pUzYcoFiSTm-mUCA-BVYvFpUp6diIsuEo/edit?usp=sharing[https://docs.google.com/document/d/1pRTZPFtHz7pUzYcoFiSTm-mUCA-BVYvFpUp6diIsuEo/edit?usp=sharing]


== Researches & Articles

Link to articles, researches and papers you should read:

*Start of the wave*

pass:[[1]] link:http://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/[http://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/]

*Sploreg ES in JME introduction in indiedb*

pass:[[2]] link:http://www.indiedb.com/games/attack-of-the-gelatinous-blob/news/the-entity-system[http://www.indiedb.com/games/attack-of-the-gelatinous-blob/news/the-entity-system]

*Worth to read, pspeed conversation with Michael Leahy, also lead another ES project TyphonRT*

pass:[[3]]
link:http://t-machine.org/index.php/2011/06/24/using-an-entity-system-with-jmonkeyengine-mythruna/[http://t-machine.org/index.php/2011/06/24/using-an-entity-system-with-jmonkeyengine-mythruna/]

*Our wiki link*

pass:[[4]] xref:es/entitysystem/introduction.adoc[entitysystem:introduction]

*Beside of BLOB anti pattern, explain why ES suite as data in modern GPU, CPU!*

pass:[[5]]
link:http://gamesfromwithin.com/data-oriented-design[http://gamesfromwithin.com/data-oriented-design]

*Worth to read, paper of another C++ ES leader of cistron project link:https://code.google.com/archive/p/cistron/[https://code.google.com/archive/p/cistron/]*

//pass:[[6]] link:http://acmantwerp.acm.org/wp-content/uploads/2010/10/componentbasedprogramming.pdf[http://acmantwerp.acm.org/wp-content/uploads/2010/10/componentbasedprogramming.pdf]


*Link to other entity system approaches in its own wikidot!*

pass:[[8]] link:http://entity-systems.wikidot.com/es-approaches[http://entity-systems.wikidot.com/es-approaches]

//[9] An interesting write up in GDD about ES and Events in a game engine. And some production,workflow concerns

//link:http://stefan.boxbox.org/2012/11/14/game-development-design-1-the-component-system/[http://stefan.boxbox.org/2012/11/14/game-development-design-1-the-component-system/]

*[More?]*
