Entitas ECS Framework

repository·main·Indexed 27 days ago

A high-performance Entity Component System (ECS) framework for C# and Unity designed to minimize garbage collection overhead. It features an optional code generator to reduce boilerplate and improve type safety, and includes a Unity module for visual debugging of contexts, groups, entities, components, and systems.

Tokens: 4.5K
Snippets: 6
Records: 17
Agent score: 43%

What's inside Entitas

Overview of Entitas ECS Framework
main
Entitas is an open-source Entity Component System (ECS) framework designed specifically for C# and Unity. It is optimized for garbage-collected environments to minimize GC pressure. The framework is built around four core concepts:
- Context: The container that holds entities and manages their lifecycle.
- Entity: A unique object within a context that can hold various components.
- Component: Data containers that are attached to entities.
- Group: Subsets of entities within a context used for high-performance querying (e.g., finding all entities that have both a Position and Velocity component).
https://github.com/sschmid/entitas/blob/main/README.md
Use the Entitas Migration Window in Unity
main
Entitas provides automated migration tools to help upgrade to new versions. In Unity, you can apply automatic migrations by opening the Entitas Migration Window via Tools > Entitas > Migrate....
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md

Upgrade to Entitas 0.10.0

main

If you are upgrading from a version older than 0.10.0, perform these manual renames and deletions to prepare for the new version.

1. Manual Renaming (Pre-installation)

Rename the following classes and methods in your existing project:

Old Name	New Name
`EntityRepository`	`Pool`
`EntityRepository.GetCollection()`	`Pool.GetGroup()`
`EntityCollection`	`Group`
`EntityCollection.EntityCollectionChange`	`Group.GroupChanged`
`EntityRepositoryObserver`	`GroupObserver`
`EntityRepositoryObserver.EntityCollectionEventType`	`GroupObserver.GroupEventType`
`IEntityMatcher`	`IMatcher`
`IEntitySystem`	`IExecuteSystem`
`AllOfEntityMatcher`	`AllOfMatcher`
`EntityRepositoryAttribute`	`PoolAttribute`
`IReactiveSubEntitySystem`	`IReactiveSystem`
`ReactiveEntitySystem`	`ReactiveSystem`

2. Deletions (Pre-installation)

Delete the following:

EntityWillBeRemovedEntityRepositoryObserver
IReactiveSubEntityWillBeRemovedSystem
ReactiveEntityWillBeRemovedSystem

3. Clean up and Install

Delete your existing Entitas, EntitasCodeGenerator, and ToolKit (Note: Entitas no longer depends on ToolKit).
Install Entitas 0.10.0.
Fix Reactive Systems: For any remaining IReactiveSubEntityWillBeRemovedSystem implementations, consider switching to ISystem & ISetPool and using group.OnEntityWillBeRemoved += foobar;.
Run Code Generator: Use the code generator to generate your files.

Upgrade to Entitas 0.12.0
main
To upgrade to Entitas 0.12.0, follow these steps to handle API changes and configuration:
1. Prepare existing code
Before deleting your current version, rename the following method:
- pool.CreateSystem() $\rightarrow$ pool.CreateExecuteSystem()
2. Clean up old installation
Delete your existing versions of:
- Entitas
- EntitasCodeGenerator
- EntitasUnity
3. Install and Configure
1. Install Entitas 0.12.0.
2. Setup Entitas Preferences: Open the Unity preference panel and select Entitas.
  Update the path for the code generator's output folder.
  If using PoolAttribute in components, add all custom pool names used in your application.
  Important: Ensure all custom PoolAttribute classes call the base constructor with the same name as the class (without the 'Attribute' suffix).
3. Run Code Generator: Use the code generator to generate your files.
4. Update API: Use the Unity menu item Entitas/Update API. This automatically updates old Matcher occurrences to the new version (which is prefixed based on the PoolAttribute).
5. Cleanup: Delete all custom PoolAttribute classes.
```
using Entitas.CodeGenerator;

public class CoreGameAttribute : PoolAttribute {
    public CoreGameAttribute() : base("CoreGame") {
    }
}
```
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md
Upgrade to Entitas 0.47.2
main
To upgrade to version 0.47.2, apply Migration 0.47.2 to automatically rename changed keys in your properties files. The following CodeGenerator keys have been renamed to Jenny:
- CodeGenerator.SearchPaths $\rightarrow$ Jenny.SearchPaths
- CodeGenerator.Plugins $\rightarrow$ Jenny.Plugins
- CodeGenerator.PreProcessors $\rightarrow$ Jenny.PreProcessors
- CodeGenerator.DataProviders $\rightarrow$ Jenny.DataProviders
- CodeGenerator.CodeGenerators $\rightarrow$ Jenny.CodeGenerators
- CodeGenerator.PostProcessors $\rightarrow$ Jenny.PostProcessors
- CodeGenerator.CLI.Ignore.UnusedKeys or Ignore.Keys $\rightarrow$ Jenny.Ignore.Keys
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md
Install Entitas
main
You can install Entitas using the following methods:
- GitHub Releases (Recommended): Download the latest version directly from the GitHub releases page.
- NuGet: Entitas and its dependencies are available via NuGet packages.
- Unity Asset Store: Note that the Asset Store version is deprecated and will not receive updates. The last available version is 1.12.3.
https://github.com/sschmid/entitas/blob/main/README.md
Use the Entitas Code Generator
main
The optional Code Generator is a key feature of Entitas that automatically generates classes and methods based on your definitions. This reduces boilerplate code, improves type safety, and makes the API more readable. Instead of manual component management, you can use generated methods like AddPosition, ReplacePosition, or AddAsset directly on entities.
```
// Example of using generated methods
var entity = context.CreateEntity();
entity.AddPosition(Vector3.zero);
entity.AddVelocity(Vector3.forward);
entity.AddAsset("Player");
```
https://github.com/sschmid/entitas/blob/main/README.md
Upgrade to Entitas 0.37.0 (Type-Safety)
main
Version 0.37.0 introduces type-safety, which is a breaking change for existing projects.
Preparation (Before Install)
- Rename SingleEntityAttribute to UniqueAttribute.
- Change namespace of all attributes in CodeGenerator/Attributes to Entitas.CodeGenerator.Api.
- Find/replace using Entitas.CodeGenerator with using Entitas.CodeGenerator.Api in all generated context attributes.
- Find/replace using Entitas.CodeGenerator; with using Entitas.CodeGenerator.Api; in all generated components.
Solving Common Issues
- Components: Generated components now inherit Entitas.Entity instead of using partial class. To fix, you can delete all components and re-generate, or manually use find/replace in the generated folder.
- Systems: All reactive systems must be updated to be type-safe. Manually update method signatures.
- General Type-Safety: Ensure all occurrences of Entity, Group, Context, Collector, and Matcher are typed (e.g., GameEntity, IGroup<GameEntity>, IContext<GameEntity>, Collector<GameEntity>, Matcher<GameEntity>).
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md
Upgrade to Entitas 0.36.0
main
Version 0.36.0 replaces several terms:
- Pool $\rightarrow$ Context (and related classes like Pools $\rightarrow$ Contexts).
- EntityCollector $\rightarrow$ Collector.
- GroupEventType $\rightarrow$ GroupEvent (e.g., OnEntityAdded $\rightarrow$ Added).
Preparation (Before Install)
- Rename Pools.CreatePool() to Pools.CreateContext.
- Rename Pool to Context.
- Rename Pools to Contexts.
- Rename Pools.SetAllPools() to Pools.SetAllContexts().
- Rename PoolAttribute to ContextAttribute.
- Rename EntityCollector to Collector.
- Rename GroupEventType to GroupEvent.
- Rename GroupEventType.OnEntityAdded to GroupEvent.Added.
- Rename GroupEventType.OnEntityRemoved to GroupEvent.Removed.
- Rename GroupEventType.OnEntityAddedOrRemoved to GroupEvent.AddedOrRemoved.
Post-Installation
1. Use MigrationAssistant.exe to apply Migration 0.36.0-2.
2. Manually migrate all systems.
3. Apply Migration 0.36.0-1.
4. Ensure all code generators are selected and generate.
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md
Upgrade to Entitas 0.42.0
main
Breaking Changes
- Removed Entitas.Blueprints.Unity.*.
- Changed ReactiveSystem.GetTrigger method signature.
- context.DestroyEntity(entity) is obsolete; use entity.Destroy() instead.
- context.CreateCollector(matcher, event) is obsolete; use context.CreateCollector(triggerOnEvent) for .Removed or .AddedOrRemoved (e.g., GameMatcher.View.Removed()).
Post-Installation Steps
1. Remove all Entitas.Blueprints.Unity.* related code and the BinaryBlueprints package.
2. Update Entitas.properties by removing Blueprint-related keys.
3. Update ReactiveSystem.GetTrigger() implementations: replace protected override Collector with protected override ICollector.
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md

Upgrade to Entitas 0.41.0

main

Version 0.41.0 restructures projects into DLLs, impacting namespaces.

Post-Installation Steps

Apply Migrations 0.41.0-1, 0.41.0-2, and 0.41.0-3 to update namespaces.
Manually fix any remaining namespace errors.
Update Entitas.properties keys to support the new code generator.

Entitas.properties Configuration Example

Entitas.CodeGeneration.Project = Assembly-CSharp.csproj
Entitas.CodeGeneration.SearchPaths = Assets/Libraries/Entitas, Assets/Libraries/Entitas/Editor, /Applications/Unity/Unity.app/Contents/Managed
Entitas.CodeGeneration.Assemblies = Library/ScriptAssemblies/Assembly-CSharp.dll
Entitas.CodeGeneration.Plugins = Entitas.CodeGeneration.Plugins, Entitas.CodeGeneration.Unity.Editor, Entitas.VisualDebugging.CodeGeneration.Plugins, Entitas.Blueprints.CodeGeneration.Plugins
Entitas.CodeGeneration.DataProviders = Entitas.Blueprints.CodeGeneration.Plugins.BlueprintDataProvider, Entitas.CodeGeneration.Plugins.ComponentDataProvider, Entitas.CodeGeneration.Plugins.ContextDataProvider, Entitas.CodeGeneration.Plugins.EntityIndexDataProvider
Entitas.CodeGeneration.CodeGenerators = Entitas.Blueprints.CodeGeneration.Plugins.BlueprintsGenerator, Entitas.CodeGeneration.Plugins.ComponentContextGenerator, Entitas.CodeGeneration.Plugins.ComponentEntityGenerator, Entitas.CodeGeneration.Plugins.ComponentGenerator, Entitas.CodeGeneration.Plugins.ComponentsLookupGenerator, Entitas.CodeGeneration.Plugins.ContextAttributeGenerator, Entitas.CodeGeneration.Plugins.ContextGenerator, Entitas.CodeGeneration.Plugins.ContextsGenerator, Entitas.CodeGeneration.Plugins.EntityGenerator, Entitas.CodeGeneration.Plugins.EntityIndexGenerator, Entitas.CodeGeneration.Plugins.MatcherGenerator, Entitas.VisualDebugging.CodeGeneration.Plugins.ContextObserverGenerator, Entitas.VisualDebugging.CodeGeneration.Plugins.FeatureClassGenerator
Entitas.CodeGeneration.PostProcessors = Entitas.CodeGeneration.Plugins.AddFileHeaderPostProcessor, Entitas.CodeGeneration.Plugins.CleanTargetDirectoryPostProcessor, Entitas.CodeGeneration.Plugins.MergeFilesPostProcessor, Entitas.CodeGeneration.Plugins.NewLinePostProcessor, Entitas.CodeGeneration.Plugins.WriteToDiskPostProcessor, Entitas.CodeGeneration.Plugins.ConsoleWriteLinePostProcessor, Entitas.CodeGeneration.Unity.Editor.DebugLogPostProcessor
Entitas.CodeGeneration.TargetDirectory = Assets/Sources/
Entitas.CodeGeneration.Contexts = Game, GameState, Input
Entitas.VisualDebugging.Unity.SystemWarningThreshold = 8
Entitas.VisualDebugging.Unity.DefaultInstanceCreatorFolderPath = Assets/Editor/DefaultInstanceCreator/
Entitas.VisualDebugging.Unity.TypeDrawerFolderPath = Assets/Editor/TypeDrawer/

Upgrade to Entitas 0.46.0
main
Upgrading to 0.46.0 involves several breaking changes:
Removed Obsolete Methods
- context.CreateCollector<TEntity>(IMatcher<TEntity> matcher, GroupEvent groupEvent)
- new Context(int totalComponents, int startCreationIndex, ContextInfo contextInfo)
- context.DestroyEntity(TEnity entity)
Post-Installation Steps
1. Edit Generated/Feature.cs to comment or delete lines causing compiler errors.
2. Run auto-import to use the new DesperateDevs.CodeGeneration.Plugins and generate.
Properties Files
- The default properties file is now Preferences.properties (previously Entitas.properties).
- You can use multiple properties files (e.g., Preferences.properties and Roslyn.properties). Unity uses the first one found.
- When using the Code Generator CLI (now called jenny), specify files as follows:
https://github.com/sschmid/entitas/blob/main/EntitasUpgradeGuide.md

Entitas ECS Framework

What's inside Entitas

1. Manual Renaming (Pre-installation)

2. Deletions (Pre-installation)

3. Clean up and Install

1. Prepare existing code

2. Clean up old installation

3. Install and Configure

Preparation (Before Install)

Solving Common Issues

Preparation (Before Install)

Post-Installation

Breaking Changes

Post-Installation Steps

Post-Installation Steps

Entitas.properties Configuration Example

Removed Obsolete Methods

Post-Installation Steps

Properties Files