|
|
|
@@ -1,62 +1,104 @@ |
|
|
|
# Svelto C# Entity Component System framework 3.x |
|
|
|
===================================== |
|
|
|
# Svelto.ECS C# Entity Component System framework |
|
|
|
|
|
|
|
Real ECS framework for c\#. Enables to write encapsulated, decoupled, maintainable, highly efficient, data oriented, cache friendly, code without pain. Although the framework is platform agnostic \(compatible with c\# 7 and .net standard 2.0\), it comes with several Unity extensions. |
|
|
|
Real ECS framework for c\#. Enables to write encapsulated, decoupled, maintainable, highly efficient, data oriented, cache friendly, code without pain. Although the framework is platform agnostic \(compatible with c\# 7 and above and .net standard 2.0 and above\), it comes with several Unity extensions. |
|
|
|
|
|
|
|
## Why using Svelto.ECS with Unity? |
|
|
|
Svelto.ECS wasn't born just from the needs of a large team, but also as a result of years of reasoning behind software engineering applied to game development. Svelto.ECS hasn't been written just to develop faster code, it has been designed to help develop better code. Performance gains is just one of the benefits in using Svelto.ECS, as ECS is a great way to write cache-friendly code. Svelto.ECS has been developed with the idea of ECS being a paradigm and not just a pattern, letting the user shift completely away from Object Oriented Programming with consequent improvements of the code design and code maintainability. Svelto.ECS is the result of years of iteration of the ECS paradigm applied to real game development with the intent to be as foolproof as possible. Svelto.ECS has been designed to be used by a medium-size/large team working on long term projects where the cost of maintainability is relevant. |
|
|
|
## Svelto.ECS in pills |
|
|
|
Svelto.ECS is easy to start with, but full of tricks for expert users. The hardest problem to overcome is usually to shift mentality from OOP programming to ECS programming more than using the framework itself. If you want to read an ECS faq, you can check this article: https://github.com/SanderMertens/ecs-faq |
|
|
|
|
|
|
|
**Svelto.ECS is the only c# framework other than DOTS ECS to be fully compatible with Burst and Jobs.** |
|
|
|
### Svelto.ECS at glance: |
|
|
|
```csharp |
|
|
|
public class SimpleContext |
|
|
|
{ |
|
|
|
//the group where the entity will be built in |
|
|
|
public static ExclusiveGroup group0 = new ExclusiveGroup(); |
|
|
|
|
|
|
|
Svelto.ECS is compatible with Unity 2019.3.x cycle as long as it's not used with DOTS ECS. If DOTS ECS integration is necessary, Svelto.ECS will always target the last stable unity version using DOTS. |
|
|
|
public SimpleContext() |
|
|
|
{ |
|
|
|
var simpleSubmissionEntityViewScheduler = new SimpleEntitiesSubmissionScheduler(); |
|
|
|
//Build Svelto Entities and Engines container, called EnginesRoot |
|
|
|
_enginesRoot = new EnginesRoot(simpleSubmissionEntityViewScheduler); |
|
|
|
|
|
|
|
## Why using Svelto.ECS without Unity? |
|
|
|
The question is just for fun! There are so many c# game engines out there (Stride, Monogame, FlatRedBall, WaveEngine, UnrealCLR, UniEngine just to mention some) and Svelto.ECS is compatible with all of them! |
|
|
|
var entityFactory = _enginesRoot.GenerateEntityFactory(); |
|
|
|
|
|
|
|
## If you decide to use Svelto.ECS |
|
|
|
//Add an Engine to the enginesRoot to manage the SimpleEntities |
|
|
|
var behaviourForEntityClassEngine = new BehaviourForEntityClassEngine(); |
|
|
|
_enginesRoot.AddEngine(behaviourForEntityClassEngine); |
|
|
|
|
|
|
|
Svelto.ECS is an Open Source Project provided as it is, no support is guaranteed other than the help given on the Svelto Discord channel. Issues will be fixed when possible. If you decide to adopt Svelto.ECS, it's assumed you are willing to partecipate to the development of the product if necessary. |
|
|
|
//build a new Entity with ID 0 in group0 |
|
|
|
entityFactory.BuildEntity<SimpleEntityDescriptor>(new EGID(0, ExclusiveGroups.group0)); |
|
|
|
|
|
|
|
## How to clone the repository: |
|
|
|
The folders Svelto.ECS and Svelto.Common, where present, are submodules pointing to the relative repositories. If you find them empty, you need to update them through the submodule command. Check some instructions here: https://github.com/sebas77/Svelto.ECS.Vanilla.Example/wiki |
|
|
|
//submit the previously built entities to the Svelto database |
|
|
|
simpleSubmissionEntityViewScheduler.SubmitEntities(); |
|
|
|
|
|
|
|
## Svelto distributed as Unity Package through OpenUPM [](https://openupm.com/packages/com.sebaslab.svelto.ecs/) |
|
|
|
|
|
|
|
read this article for more information: http://www.sebaslab.com/distributing-svelto-through-openupm/ ~~or just install the package that comes from the link https://package-installer.glitch.me/v1/installer/OpenUPM/com.sebaslab.svelto.ecs?registry=https%3A%2F%2Fpackage.openupm.com~~ |
|
|
|
//as Svelto doesn't provide an engine ticking system, it's the user's responsibility to |
|
|
|
//update engines |
|
|
|
behaviourForEntityClassEngine.Update(); |
|
|
|
} |
|
|
|
|
|
|
|
readonly EnginesRoot _enginesRoot; |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
**Note on the System.Runtime.CompilerServices.Unsafe.dll dependency and the bit of a mess that Unity Package Dependency System is:** |
|
|
|
your first entity descriptor: |
|
|
|
|
|
|
|
Unity Package System has a big deficiency when it comes to dll dependency solving: two packages cannot point to the same dependency from different sources. Since Unity Collection removed the Unsafe.dll dependency, ~~I had to distribute my own package. This means that if you want to use Svelto from UPM, you will need Svelto unsafe dll to be the only unsafe dll in the project. Otherwise you just download the source code and solve dependencies manually.~~ |
|
|
|
```csharp |
|
|
|
public struct EntityComponent : IEntityComponent |
|
|
|
{ |
|
|
|
public int counter; |
|
|
|
} |
|
|
|
|
|
|
|
For Unity Users: to solve the unsafe dependency you need to add the following scopedRegistries in manifest.json: |
|
|
|
class SimpleEntityDescriptor : GenericEntityDescriptor<EntityComponent> |
|
|
|
{} |
|
|
|
``` |
|
|
|
{ |
|
|
|
"scopedRegistries": [ |
|
|
|
|
|
|
|
your first engine executing entities behaviours: |
|
|
|
|
|
|
|
```csharp |
|
|
|
public class BehaviourForEntityClassEngine : IQueryingEntitiesEngine |
|
|
|
{ |
|
|
|
public EntitiesDB entitiesDB { get; set; } |
|
|
|
|
|
|
|
public void Ready() { } |
|
|
|
|
|
|
|
public void Update() |
|
|
|
{ |
|
|
|
"name": "package.openupm.com", |
|
|
|
"url": "https://package.openupm.com", |
|
|
|
"scopes": [ |
|
|
|
"com.sebaslab.svelto.common", |
|
|
|
"com.sebaslab.svelto.ecs", |
|
|
|
"org.nuget.system.runtime.compilerservices.unsafe" |
|
|
|
] |
|
|
|
var (components, count) = entitiesDB.QueryEntities<EntityComponent>(ExclusiveGroups.group0); |
|
|
|
|
|
|
|
for (var i = 0; i < count; i++) |
|
|
|
components[i].counter++; |
|
|
|
} |
|
|
|
], |
|
|
|
"dependencies": { |
|
|
|
"com.sebaslab.svelto.ecs": "3.2.6" |
|
|
|
} |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
## Svelto distributed as Nuget |
|
|
|
learn more about svelto on the Wiki page: https://github.com/sebas77/Svelto.ECS/wiki or on this article: |
|
|
|
|
|
|
|
I am not a Nuget expert, but thanks to our contributors, Svelto.ECS can be found at https://www.nuget.org/packages/Svelto.ECS/ |
|
|
|
* [Svelto ECS 3.0 is finally here](https://www.sebaslab.com/whats-new-in-svelto-ecs-3-0/) \(re-introducing svelto, this article is important for starters!\) |
|
|
|
|
|
|
|
## Official Examples (A.K.A. where is the documentation?) |
|
|
|
## Why using Svelto.ECS with Unity? |
|
|
|
Svelto.ECS wasn't born just from the needs of a large team, but also as a result of years of reasoning behind software engineering applied to game development. Svelto.ECS hasn't been written just to develop faster code, it has been designed to help develop better code. Performance gains is just one of the benefits in using Svelto.ECS, as ECS is a great way to write cache-friendly code. Svelto.ECS has been developed with the idea of ECS being a paradigm and not just a pattern, letting the user shift completely away from Object Oriented Programming with consequent improvements of the code design and code maintainability. Svelto.ECS is the result of years of iteration of the ECS paradigm applied to real game development with the intent to be as foolproof as possible. Svelto.ECS has been designed to be used by a medium-size/large team working on long term projects where the cost of maintainability is relevant. |
|
|
|
|
|
|
|
_Svelto.ECS is lean, it hasn't been designed to move a whole engine from OOP to ECS, therefore it doesn't suffer from unjustifiable complexity overhead to try to solve problems that often are not linked to gameplay development. Svelto.ECS is fundamentally feature complete at this point of writing and new features in new versions are more nice to have than fundamental._ |
|
|
|
|
|
|
|
**Svelto.ECS is fully compatible with DOTS Burst and Jobs.** |
|
|
|
|
|
|
|
Svelto doesn't have official documentation. The reason is that documentation is costly to mantain and...I reckon people don't need it, thanks to the highly documented and simple mini-examples. Please check and study them all regardless the platform you intend to use Svelto with. |
|
|
|
Svelto.ECS is compatible with Unity 2019.3.x cycle as long as it's not used with DOTS ECS. |
|
|
|
Svelto.ECS is also designed to use DOTS ECS as engine library, using the SveltoOnDOTS wrapper. This wrapper is designed to take advantage of DOTS for engine related operations, like rendering, physics and so on. When DOTS ECS integration is necessary, Svelto.ECS will always target the last stable unity version with the most up to date DOTS package. |
|
|
|
|
|
|
|
### * **Mini Examples**: [https://github.com/sebas77/Svelto.MiniExamples](https://github.com/sebas77/Svelto.MiniExamples) \(including articles\) |
|
|
|
## Why using Svelto.ECS without Unity? |
|
|
|
The question is just for fun! There are so many c# game engines out there (Stride, Flax, Monogame, FlatRedBall, Evergine, UnrealCLR, UniEngine just to mention some) and Svelto.ECS is compatible with all of them! |
|
|
|
|
|
|
|
## Performance considerations |
|
|
|
Aside from resizing the database absolutely when necessary, all the Svelto operations are memory allocation free. Some containers may need to be preallocated (and then disposed) but those are already advanced scenarios. When using pure ECS (no EntityViewComponents) components are stored in native collections across all the platforms, which means gaining some performance from losing the managed memory checks. With pure ECS, iterating components is automatically cache-friendly. |
|
|
|
|
|
|
|
_Note: Svelto.ECS has a ton of allocating run-time checks in debug, so if you want to profile you need to profile a release version or use PROFILE_SVELTO define_ |
|
|
|
|
|
|
|
## If you decide to use Svelto.ECS |
|
|
|
Svelto.ECS is an Open Source Project provided as it is, no support is guaranteed other than the help given on the Svelto Discord channel. Issues will be fixed when possible. If you decide to adopt Svelto.ECS, it's assumed you are willing to partecipate to the development of the product if necessary. |
|
|
|
|
|
|
|
## Official Examples (A.K.A. where is the documentation?) |
|
|
|
Documentation is costly to mantain so check the highly documented and simple mini-examples. Please study them all regardless the platform you intend to use Svelto with. |
|
|
|
|
|
|
|
* **Mini Examples**: [https://github.com/sebas77/Svelto.MiniExamples](https://github.com/sebas77/Svelto.MiniExamples) |
|
|
|
* **Unit Tests**: [https://github.com/sebas77/Svelto.ECS.Tests](https://github.com/sebas77/Svelto.ECS.Tests) |
|
|
|
|
|
|
|
After that, you can get all the help you need from the official chat: |
|
|
|
@@ -66,17 +108,6 @@ After that, you can get all the help you need from the official chat: |
|
|
|
* [https://discord.gg/3qAdjDb](https://discord.gg/3qAdjDb) |
|
|
|
|
|
|
|
## Official Articles |
|
|
|
|
|
|
|
**Framework articles:** |
|
|
|
|
|
|
|
* [Svelto ECS 3.0 is finally here](https://www.sebaslab.com/whats-new-in-svelto-ecs-3-0/) \(re-introducing svelto, this article is important for starters!\) |
|
|
|
* [Introducing Svelto ECS 2.9](http://www.sebaslab.com/introducing-svelto-ecs-2-9/) \(shows what's changed since 2.8\) |
|
|
|
* [Introducing Svelto ECS 2.8](http://www.sebaslab.com/introducing-svelto-ecs-2-8/) \(shows what's changed since 2.7\) |
|
|
|
* [Svelto.ECS 2.7: what’s new and best practices](http://www.sebaslab.com/svelto-2-7-whats-new-and-best-practices/) \(shows what's changed since 2.5\) |
|
|
|
* [Introducing Svelto ECS 2.5](http://www.sebaslab.com/svelto-ecs-2-5-and-allocation-0-code/) \(shows what's changed since 2.0\) |
|
|
|
* [Svelto.ECS 2.0 is production ready](http://www.sebaslab.com/svelto-ecs-2-0-almost-production-ready/) \(shows what's changed since 1.0\) |
|
|
|
* [Svelto ECS is now production ready](http://www.sebaslab.com/ecs-1-0/) |
|
|
|
|
|
|
|
**Theory related articles (from the most recent to the oldest, read from the oldest if you are new to it):** |
|
|
|
|
|
|
|
* [OOP abstraction layer in an ECS-centric application](https://www.sebaslab.com/oop-abstraction-layer-in-a-ecs-centric-application/) \(this article is important for starters!\) |
|
|
|
@@ -92,6 +123,7 @@ After that, you can get all the help you need from the official chat: |
|
|
|
|
|
|
|
**Practical articles** |
|
|
|
|
|
|
|
* [Svelto.ECS 3.3 and the new Filters API](https://www.sebaslab.com/svelto-ecs-3-3-and-the-new-filters-api/) |
|
|
|
* [Svelto.ECS Internals: How to avoid boxing when using structs with reflection](https://www.sebaslab.com/casting-a-struct-into-an-interface-inside-a-generic-method-without-boxing/) |
|
|
|
* [Svelto ECS 3.0 Internals: profiling the Entity Collection](https://www.sebaslab.com/svelto-ecs-3-0-internals-the-entity-collection/) |
|
|
|
* [Svelto ECS 3.0 Internals: Support Native Memory Natively](https://www.sebaslab.com/svelto-ecs-3-0-internals-support-native-memory-natively/) |
|
|
|
@@ -105,7 +137,6 @@ After that, you can get all the help you need from the official chat: |
|
|
|
Note: I included the IoC articles just to show how I shifted over the years from using an IoC container to use an ECS framework and the rationale behind its adoption. |
|
|
|
|
|
|
|
## Users Generated Content \(I removed all the outdated articles, so this is a call for new ones!\) |
|
|
|
|
|
|
|
* [A Beginner’s Guide to Svelto.ECS (3.0) with Unity by Jiheh Ritterling](https://jiheh.medium.com/a-beginners-guide-to-svelto-ecs-3-0-with-unity-e9dbc88a2145) |
|
|
|
|
|
|
|
**Svelto Extensions** |
|
|
|
@@ -115,24 +146,53 @@ Note: I included the IoC articles just to show how I shifted over the years from |
|
|
|
* [Foundation for a possible platform agnostic Svelto.ECS inspector](https://github.com/akrogame/svelto-ecs-inspector) |
|
|
|
* [Being able to swap entities between a subset of compound tags to another subset of compound tags](https://gist.github.com/jlreymendez/c2f441aaf6ac7b5f233ecd990314e9cc) |
|
|
|
|
|
|
|
## In case of bugs |
|
|
|
## How to clone the repository: |
|
|
|
The folders Svelto.ECS and Svelto.Common, where present, are submodules pointing to the relative repositories. If you find them empty, you need to update them through the submodule command. Check some instructions here: https://github.com/sebas77/Svelto.ECS.Vanilla.Example/wiki |
|
|
|
|
|
|
|
Best option is to fork and clone [https://github.com/sebas77/Svelto.ECS.Tests](https://github.com/sebas77/Svelto.ECS.Tests), add new tests to reproduce the problem and request a pull. I will then fix the issue. Also feel free to contact me on Discord. |
|
|
|
## Svelto distributed as Unity Package through OpenUPM [](https://openupm.com/packages/com.sebaslab.svelto.ecs/) |
|
|
|
|
|
|
|
## [The Github wiki page](https://github.com/sebas77/Svelto.ECS/wiki) |
|
|
|
or just install the package that comes from the link https://package-installer.glitch.me/v1/installer/OpenUPM/com.sebaslab.svelto.ecs?registry=https%3A%2F%2Fpackage.openupm.com |
|
|
|
|
|
|
|
Completely outdated and could even mislead. Feel free to update it if you have a good understanding of Svelto! I decided I won't update it anymore as it's better for me to focus on other parts of Svelto development. If you need any help, you will need to join the aforementioned discord server. |
|
|
|
**Note on the System.Runtime.CompilerServices.Unsafe.dll dependency and the bit of a mess that Unity Package Dependency System is:** |
|
|
|
|
|
|
|
## I like the project, how can I help? |
|
|
|
Unity Package System has a big deficiency when it comes to dll dependency solving: two packages cannot point to the same dependency from different sources. For this reason I decided to let my packages to point to the unsafe dll distribution from openUPM |
|
|
|
|
|
|
|
to solve the unsafe dependency you need to add the following scopedRegistries in manifest.json: |
|
|
|
``` |
|
|
|
{ |
|
|
|
"scopedRegistries": [ |
|
|
|
{ |
|
|
|
"name": "package.openupm.com", |
|
|
|
"url": "https://package.openupm.com", |
|
|
|
"scopes": [ |
|
|
|
"com.sebaslab.svelto.common", |
|
|
|
"com.sebaslab.svelto.ecs", |
|
|
|
"org.nuget.system.runtime.compilerservices.unsafe" |
|
|
|
] |
|
|
|
} |
|
|
|
] |
|
|
|
} |
|
|
|
``` |
|
|
|
|
|
|
|
this is shown in this example too: https://github.com/sebas77/Svelto.MiniExamples/tree/master/UPM-Integration/UPM |
|
|
|
|
|
|
|
## Svelto distributed as Nuget |
|
|
|
I am not a Nuget expert, but thanks to our contributors, Svelto.ECS can be found at https://www.nuget.org/packages/Svelto.ECS/ |
|
|
|
|
|
|
|
the Hello World example uses the nuget package directly: https://github.com/sebas77/Svelto.MiniExamples/tree/master/Example5-Net-HelloWorld |
|
|
|
|
|
|
|
## In case of bugs |
|
|
|
Best option is to fork and clone [https://github.com/sebas77/Svelto.ECS.Tests](https://github.com/sebas77/Svelto.ECS.Tests), add new tests to reproduce the problem and request a pull. I will then fix the issue. Also feel free to contact me on Discord. |
|
|
|
|
|
|
|
## I like the project, how can I help? |
|
|
|
Hey, thanks a lot for considering this. You can help in several ways. The simplest is to talk about Svelto.ECS and spread the word, the more we are, the better it is for the community. Then you can help with the documentation, updating the wiki or writing your own articles. Svelto.ECS has all the features needed to make a game with the ECS pattern, but some areas are lacking: *A visual debugger and more unit tests are needed*. Other platforms other than Unity could get some love too: Stride Game, Godot, monogame, FNA or whatever supports c#. Porting to other languages, especially c++, would be awesome but probably pointless. Please check the lane dedicated to the community tasks list here: https://github.com/users/sebas77/projects/3 and let me know if you want to take something on! |
|
|
|
|
|
|
|
## Svelto Framework is used to develop the following products\(\*\): |
|
|
|
|
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
 |
|
|
|
|
|
|
|
\*If you want your products made with Svelto here, just send me an email or whatever, I'll be super happy to add them. |
|
|
|
|
|
|
|
|
GitHub
2 年前