libgdx-collections-json

libGDX Collections, Pooling, JSON & Utilities

Quick reference for com.badlogic.gdx.utils.* — libGDX's GC-friendly collections, object pooling, JSON serialization, and utility classes. These replace java.util.* equivalents to reduce garbage collection pressure, especially on Android.

Array<T> — ArrayList Replacement

Array<String> arr = new Array<>();                   // also: new Array<>(capacity), new Array<>(ordered, capacity)

Public fields: T[] items (backing array), int size (element count), boolean ordered.

Key methods: add, get, set, insert, swap, pop, peek, first, clear, sort, reverse, shuffle, truncate, shrink, ensureCapacity, isEmpty, notEmpty, select(predicate).

CRITICAL — identity parameter required: removeValue(item, identity), contains(item, identity), indexOf(item, identity), lastIndexOf(item, identity). identity=true uses ==, identity=false uses .equals(). There is no single-argument overload.

There is NO remove(Object) method. It is removeValue(value, identity) or removeIndex(int).

Gotchas:

• items array may be larger than size — iterate with for (int i = 0; i < arr.size; i++), never items.length.
• items[i] past size contains stale references — always check i < size.
• DO NOT modify Array during for-each iteration. Use DelayedRemovalArray, SnapshotArray, or manual index loop.
• When ordered is false, removeIndex() swaps the last element into the gap (O(1)) instead of shifting (O(n)).

DelayedRemovalArray<T> / SnapshotArray<T>

Both wrap begin()/end() around iteration. DelayedRemovalArray queues removals during iteration, applies at end() (returns void from begin()). SnapshotArray takes a snapshot; begin() returns T[] to iterate, modifications go to a copy. Both support nested begin()/end(). Used internally by Scene2D.

ObjectMap<K,V> — HashMap Replacement

ObjectMap<String, Integer> map = new ObjectMap<>();
map.put("hp", 100);                                  // returns old value or null
map.get("hp");  map.get("hp", 0);                    // null or default
map.remove("hp");  map.containsKey("hp");
map.containsValue(100, false);                        // identity param on values too