From a4d9b843dc894c46df43a8625fb32b204dc79936 Mon Sep 17 00:00:00 2001 From: Barryrowe Date: Tue, 25 Oct 2016 22:11:19 -0400 Subject: [PATCH] Document managed state of ImmutableArray Document the fact that the Engine may modify the underlying contents of the ImmutableArray that is returned from Engine.getEntities. This addresses issue #224 --- .../src/com/badlogic/ashley/core/Engine.java | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/ashley/src/com/badlogic/ashley/core/Engine.java b/ashley/src/com/badlogic/ashley/core/Engine.java index 755a6760..9101e005 100644 --- a/ashley/src/com/badlogic/ashley/core/Engine.java +++ b/ashley/src/com/badlogic/ashley/core/Engine.java @@ -98,6 +98,29 @@ public void removeAllEntities() { entityManager.removeAllEntities(delayed); } + /** + * Returns an {@link ImmutableArray} of {@link Entity} that is managed by the the Engine + * but cannot be used to modify the state of the Engine. This Array is not Immutable in + * the sense that its contents will not be modified, but in the sense that it only reflects + * the state of the engine. + * + * The Array is Immutable in the sense that you cannot modify its contents through the API of + * the {@link ImmutableArray} class, but is instead "Managed" by the Engine itself. The engine + * may add or remove items from the array and this will be reflected in the returned array. + * + * This is an important note if you are looping through the returned entities and calling operations + * that may add/remove entities from the engine, as the underlying iterator of the returned array + * will reflect these modifications. + * + * The returned array will have entities removed from it if they are removed from the engine, + * but there is no way to introduce new Entities through the array's interface, or remove + * entities from the engine through the array interface. + * + * Discussion of this can be found at https://github.com/libgdx/ashley/issues/224 + * + * @return An unmodifiable array of entities that will match the state of the entities in the + * engine. + */ public ImmutableArray getEntities() { return entityManager.getEntities(); }