Entitas  0.34.0
Entitas is a super fast Entity Component System (ECS) Framework specifically made for C# and Unity
EntitasUpgradeGuide.md
1 # General information
2 Entitas provides an easy way to make upgrading to new versions a breeze.
3 Either use the command line tool `MigrationAssistant.exe` or the Migration menu
4 item in Unity. After that generate again.
5 
6 Example
7 ```
8 $ mono MigrationAssistant.exe
9 usage:
10 [-l] - print all available versions
11 [version] [path] - apply migration of version [version] to source files located at [path]
12 
13 $ mono MigrationAssistant.exe -l
14 ========================================
15 0.18.0
16  - Migrates IReactiveSystem GetXyz methods to getters
17  - Use on folder, where all systems are located
18 ========================================
19 0.19.0
20  - Migrates IReactiveSystem.Execute to accept List<Entity>
21  - Use on folder, where all systems are located
22 ========================================
23 0.22.0
24  - Migrates IReactiveSystem to combine trigger and eventTypes to TriggerOnEvent
25  - Use on folder, where all systems are located
26 ========================================
27 0.26.0
28  - Deactivates code to prevent compile erros
29  - Use on folder, where generated files are located
30 ========================================
31 etc...
32 
33 
34 // Example from Math-One example project
35 $ mono MigrationAssistant.exe 0.26.0 /Path/To/Project/Generated/
36 ```
37 
38 # Entitas 0.34.0 upgrade guide
39 #### Before you install
40 - Rename `GroupObserver` to `EntityCollector`
41 - Rename `.CreateGroupObserver()` to `.CreateEntityCollector()`
42 - Rename `IGroupObserverSystem` to `IEntityCollectorSystem`
43 - Find & Replace `public EntityCollector groupObserver` with `public EntityCollector entityCollector`
44 
45 #### After you intalled
46 - You're fine - nothing to do for you :heart:
47 
48 
49 # Entitas 0.33.0 upgrade guide
50 #### Before you install
51 - Manually rename `IDeinitializeSystem` to `ITearDownSystem`
52 
53 #### After you intalled
54 - You're fine - nothing to do for you :heart:
55 
56 
57 # Entitas 0.32.0 upgrade guide
58 Use the command line tool `MigrationAssistant.exe` to automatically fix compile errors.
59 Entitas 0.32.0 introduces a new Pools class. Using the new PoolsGenerator will require
60 to update your existing project manually. You can still use the old Pools class in your
61 existing project if you want. If so, please use the OldPoolsGenerator instead of the new one.
62 
63 
64 # Entitas 0.30.0 upgrade guide
65 Some code generators got renamed. Apply Migration 0.30.0
66 
67 
68 # Entitas 0.29.0 upgrade guide
69 Marked old PoolMetaData constructor obsolete. If you encounter compile errors
70 please apply Migration 0.26.0, open C# project and generate again.
71 
72 
73 # Entitas 0.28.0 upgrade guide
74 If you're using Entitas with Unity, please open the Entitas preferences and make
75 sure that all your desired code generators are activated.
76 Due to some code generator renamings the ComponentIndicesGenerators inactive.
77 
78 The SystemsGenerator has been removed. Please use `pool.CreateSystem<MySystem>()` instead.
79 
80 
81 # Entitas 0.27.0 upgrade guide
82 If you're using Entitas with Unity, please open the Entitas preferences and make
83 sure that all your desired code generators are activated.
84 Due to some code generator renamings the ComponentLookupGenerator and
85 the ComponentsGenerator are inactive. Activate them (if desired) and generate.
86 
87 
88 # Entitas 0.26.0 upgrade guide
89 Use the command line tool `MigrationAssistant.exe` to automatically fix compile errors.
90 After that generate again.
91 
92 ```
93 $ mono MigrationAssistant.exe
94 usage:
95 [-l] - print all available versions
96 [version] [path] - apply migration of version [version] to source files located at [path]
97 
98 $ mono MigrationAssistant.exe -l
99 0.18.0 - Migrates IReactiveSystem GetXyz methods to getters
100 0.19.0 - Migrates IReactiveSystem.Execute to accept List<Entity>
101 0.22.0 - Migrates IReactiveSystem to combine trigger and eventTypes to TriggerOnEvent
102 0.26.0 - Deactivates code to prevent compile erros
103 
104 // Example from Math-One example project
105 $ mono MigrationAssistant.exe 0.26.0 /Path/To/Project/Generated/
106 ```
107 
108 
109 # Entitas 0.24.0 upgrade guide
110 To fix the compile errors after updating to Entitas 0.24.0, delete in `Pools.cs`
111 
112 ```csharp
113 #if (UNITY_EDITOR)
114 var poolObserver = new Entitas.Unity.VisualDebugging.PoolObserver(_pool, ComponentIds.componentNames, ComponentIds.componentTypes, "Pool");
115 UnityEngine.Object.DontDestroyOnLoad(poolObserver.entitiesContainer);
116 #endif
117 ```
118 
119 and generate again.
120 
121 
122 # Entitas 0.23.0 upgrade guide
123 Entitas 0.23.0 changed and applied naming conventions.
124 Before updating to this version, follow these steps to prepare your project:
125 
126 #### Rename
127 
128  Pool.Count -> Pool.count
129  Group.Count -> Group.count
130  Properties.count -> Properties.count
131 
132 #### Find/Replace in generated folder
133 
134  ": AllOfMatcher " -> ""
135  ": base(new [] { index }) " -> ""
136  "static AllOfMatcher _matcher" -> "static IMatcher _matcher"
137  "public static AllOfMatcher" -> "public static IMatcher"
138  "new Matcher" -> "Matcher.AllOf"
139 
140 #### Delete
141 
142 In generated ...ComponentIds
143 
144  namespace Entitas {
145  public partial class XYZMatcher {
146  public Matcher(int index) {
147  }
148 
149  public override string ToString() {
150  return ComponentIds.IdToString(indices[0]);
151  }
152  }
153  }
154 
155 # Entitas 0.22.0 upgrade guide
156 Entitas 0.22.0 changed IReactiveSystem and IMultiReactiveSystem and renamed IStartSystem.Start to IInitializeSystem.Initialize.
157 
158 Use the command line tool `MigrationAssistant.exe` to automatically migrate IReactiveSystem.
159 
160 ```
161 $ mono MigrationAssistant.exe
162 usage:
163 [-l] - print all available versions
164 [version] [path] - apply migration of version [version] to source files located at [path]
165 
166 $ mono MigrationAssistant.exe -l
167 0.18.0 - Migrates IReactiveSystem GetXyz methods to getters
168 0.19.0 - Migrates IReactiveSystem.Execute to accept List<Entity>
169 0.22.0 - Migrates IReactiveSystem to combine trigger and eventTypes to TriggerOnEvent
170 
171 // Example from Math-One example project, where all the systems are located in the Features folder
172 $ mono MigrationAssistant.exe 0.22.0 /Path/To/Project/Assets/Sources/Features
173 ```
174 
175 
176 # Entitas 0.19.0 upgrade guide
177 Entitas 0.19.0 introduces a few breaking changes:
178 
179 Added new e.OnComponentReplaced and removed all *WillBeRemoved events.
180 
181 If you used `group.OnEntityWillBeRemoved`, you could replace it either with
182 ```cs
183 _group.OnEntityRemoved += (group, entity, index, component) => { //... };
184 ```
185 or with
186 ```cs
187 _group.OnEntityUpdated += (group, entity, index, previousComponent, newComponent) => { // ...};
188 ```
189 If your generated component extensions are not compiling, find/replace `WillRemoveComponent` with `//WillRemoveComponent`
190 to temporarily ignore the errors.
191 
192 IReactiveSystem.Execute takes List<Entity> instead of Entity[]. Use the command line tool `MigrationAssistant.exe` to automatically migrate.
193 
194 ```
195 $ mono MigrationAssistant.exe
196 usage:
197 [-l] - print all available versions
198 [version] [path] - apply migration of version [version] to source files located at [path]
199 
200 $ mono MigrationAssistant.exe -l
201 0.18.0 - Migrates IReactiveSystem API
202 0.19.0 - Migrates IReactiveSystem.Execute
203 
204 // Example from Math-One example project, where all the systems are located in the Features folder
205 $ mono MigrationAssistant.exe 0.19.0 /Path/To/Project/Assets/Sources/Features
206 ```
207 
208 
209 # Entitas 0.18.0 upgrade guide
210 Entitas 0.18.0 changes IReactiveSystem. To upgrade your source files, follow these steps
211 - Install Entitas 0.18.0 (which will result in compiler errors)
212 - Use the command line tool `MigrationAssistant.exe` to automatically migrate
213 
214 ```
215 $ mono MigrationAssistant.exe
216 usage:
217 [-l] - print all available versions
218 [version] [path] - apply migration of version [version] to source files located at [path]
219 
220 $ mono MigrationAssistant.exe -l
221 0.18.0 - Migrates IReactiveSystem API
222 
223 // Example from Math-One example project, where all the systems are located in the Features folder
224 $ mono MigrationAssistant.exe 0.18.0 /Path/To/Project/Assets/Sources/Features
225 ```
226 
227 
228 # Entitas 0.12.0 upgrade guide
229 
230 Entitas 0.12.0 generates prefixed matchers based on the PoolAttribute and introduces some
231 API changes. In your existing project with a Entitas version < 0.12.0 manually rename the
232 following classes and methods.
233 
234 ## Before installing Entitas 0.12.0
235 
236 #### Rename
237 
238  pool.CreateSystem() -> pool.CreateExecuteSystem()
239 
240 Now that you're prepared for integrating the latest version, delete your existing version
241 of Entitas, EntitasCodeGenerator and EntitasUnity.
242 
243 #### Delete
244 
245  Entitas
246  EntitasCodeGenerator
247  EntitasUnity
248 
249 ## Install Entitas 0.12.0
250 
251 #### Setup Entitas Preferences
252 
253  Open the Unity preference panel and select Entitas. Check and update the path to the folder where
254  the code generator will save all generated files. If you are using the PoolAttribute in your components,
255  add all custom pool names used in your application. Make sure that all existing custom PoolAttributes call
256  the base constructor with the same name as the class (without 'Attribute').
257  If you are not using the PoolAttribute in your components, you can skip this process.
258 
259 ```cs
260 using Entitas.CodeGenerator;
261 
262 public class CoreGameAttribute : PoolAttribute {
263  public CoreGameAttribute() : base("CoreGame") {
264  }
265 }
266 ```
267 
268 #### Code Generator
269 
270  Use the code generator and generate
271 
272 #### Update API
273 
274  Click the MenuItem "Entitas/Update API". All occurrences of the old Matcher will be updated
275  to the new version, which is prefixed based on the PoolAttribute.
276 
277 #### Delete
278 
279  Delete all custom PoolAttributes
280 
281 
282 # Entitas 0.10.0 upgrade guide
283 
284 Beside features, Entitas 0.10.0 includes lots of renaming. If your current Entitas
285 version is < 0.10.0, you might want to follow the next few simple renaming steps,
286 to speed up the integration of the latest version of Entitas.
287 In your existing project with a Entitas version < 0.10.0 manually rename the following
288 classes and methods.
289 
290 ## Before installing Entitas 0.10.0
291 
292 #### Rename
293 
294  EntityRepository -> Pool
295  EntityRepository.GetCollection() -> Pool.GetGroup()
296 
297  EntityCollection -> Group
298  EntityCollection.EntityCollectionChange -> Group.GroupChanged
299 
300  EntityRepositoryObserver -> GroupObserver
301  EntityRepositoryObserver.EntityCollectionEventType -> GroupObserver.GroupEventType
302 
303  IEntityMatcher -> IMatcher
304  IEntitySystem -> IExecuteSystem
305  AllOfEntityMatcher -> AllOfMatcher
306  EntityRepositoryAttribute -> PoolAttribute
307  IReactiveSubEntitySystem -> IReactiveSystem
308  ReactiveEntitySystem -> ReactiveSystem
309 
310 #### Delete
311 
312  EntityWillBeRemovedEntityRepositoryObserver -> DELETE
313  IReactiveSubEntityWillBeRemovedSystem -> DELETE
314  ReactiveEntityWillBeRemovedSystem -> DELETE
315 
316 Now that you're prepared for integrating the latest version, delete your existing version
317 of Entitas, EntitasCodeGenerator and ToolKit.
318 
319 #### Delete
320 
321  Entitas
322  EntitasCodeGenerator
323  ToolKit (unless you use classes from ToolKit. The new version of Entitas doesn't depend on ToolKit anymore)
324 
325 
326 ## Install Entitas 0.10.0
327 
328 #### Fix remaining issues
329 
330  IReactiveSubEntityWillBeRemovedSystem
331  - Consider implementing ISystem & ISetPool and use group.OnEntityWillBeRemoved += foobar;
332 
333 #### Code Generator
334 
335  Use the code generator and generate