Use this skill when using the Phaser 4 DataManager to store custom key-value data on game objects, listen for data change events, or manage game state. Triggers on: setData, getData, data events, custom data storage.

DataManager Phaser's DataManager provides key value storage with event driven change tracking. It operates at three levels: per GameObject ( sprite.setData / getData ), per Scene ( this.data ), and global ( this.registry ). Every set/change/remove operation emits events, enabling reactive data binding between game systems without tight coupling. Key source paths: src/data/DataManager.js , src/data/DataManagerPlugin.js , src/data/events/ , src/gameobjects/GameObject.js (setData/getData/incData/toggleData) Related skills: ../scenes/SKILL.md, ../events system/SKILL.md Quick Start Core Concepts DataManager ( Phaser.Data.DataManager ) The base class that stores key value pairs in an internal list object. It provides: set(key, value) stores a value; emits setdata (new key) or changedata + changedata {key} (existing key). Accepts an object to set multiple keys at once. get(key) retrieves a value, or pass an array of keys to get an array of values. inc(key, amount) increments a numeric value (defaults to +1). Creates from 0 if key does not exist. toggle(key) flips a boolean value. Creates from false if key does not exist. remove(key) deletes a key; emits removedata . Accepts an array of keys. has(key) returns true if the key exists. getAll() returns a shallow copy of all key value pairs as a plain object. query(regex) returns all entries whose keys match the given RegExp. each(callback, context, ...args) iterates all entries. Callback signature: (parent, key, value, ...args) . merge(data, overwrite) bulk imports from an object. overwrite defaults to true ; set false to skip existing keys. pop(key) retrieves and deletes a key in one call; emits removedata . reset() clears all data and unfreezes. freeze / setFreeze(bool) when frozen, all set/remove/inc/toggle operations silently no op. count read only property returning the number of stored entries. The values proxy object allows direct property access with event emission: Scene Data Plugin ( Phaser.Data.DataManagerPlugin ) Extends DataManager. Registered as the data scene plugin, accessible as this.data in any Scene. It uses the Scene's event emitter ( scene.sys.events ), so data events fire on the Scene's event bus. The plugin auto cleans on scene shutdown (removes its shutdown listener) and fully destroys on scene destroy. Registry (Global Data Store) The registry is a plain DataManager instance on the Game object ( game.registry ). It has its own dedicated EventEmitter (not shared with any scene). Every scene gets a reference as this.registry via the injection map. The registry persists for the lifetime of the Game. It is never automatically cleared on scene restart or shutdown. Per GameObject Data GameObjects do NOT have a DataManager by default. It is created lazily on first call to setData() , getData() , incData() , or toggleData() . You can also explicitly call setDataEnabled() . The DataManager's event emitter is the GameObject itself (which extends EventEmitter), so data events fire directly on the GameObject: Common Patterns Setting and Getting Data Listening for Changes Global Registry for Cross Scene State Complex Data and Objects Merging Data Querying Data by Pattern Freezing Data Data Persistence Pattern Events All data events are defined in Phaser.Data.Events . The emitter depends on context: for GameObjects it is the GameObject itself; for scene data it is scene.sys.events ; for the registry it is registry.events . Constant String Fired When Callback Args SET DATA 'setdata' A new key is created (parent, key, value) CHANGE DATA 'changedata' An existing key's value changes (parent, key, value, previousValue) CHANGE DATA KEY 'changedata ' Specific key changes (append key name) (parent, value, previousValue) REMOVE DATA 'removedata' A key is removed (parent, key, value) DESTROY 'destroy' DataManager's parent is destroyed (none) The parent argument is the owner of the DataManager (the GameObject, Scene, or Game instance). Note: CHANGE DATA KEY is a prefix. The actual event string is 'changedata ' + the key name. For example, setting a key called score emits 'changedata score' . API Quick Reference GameObject Convenience Methods Method Returns Description setDataEnabled() this Explicitly creates the DataManager (normally auto created) setData(key, value) this Set one key or pass an object for multiple getData(key) Get one value or pass an array for multiple incData(key, amount?) this Increment numeric value (default +1, negative to decrement) toggleData(key) this Toggle boolean value DataManager Methods Method Returns Description set(key, value) this Set single key or object of key value pairs get(key) Get value(s) string or array of strings getAll() object Shallow copy of all entries query(regex) object All entries with keys matching the RegExp each(cb, ctx, ...args) this Iterate all entries merge(data, overwrite?) this Bulk import; overwrite defaults to true remove(key) this Delete key(s) string or array pop(key) Get and delete in one call has(key) boolean Check if key exists inc(key, amount?) this Increment (default +1) toggle(key) this Toggle boolean setFreeze(bool) this Freeze/unfreeze modifications reset() this Clear all data and unfreeze count number Read only entry count freeze boolean Get/set frozen state values object Proxy object for direct property access get() vs values Copies vs Live References Understanding the difference between get() and values is critical for correct data updates: Event Emitter Routing Data events emit on different targets depending on where the DataManager lives: DataManager Owner Events Emit On Example Listener GameObject The GameObject itself sprite.on('changedata hp', ...) Scene ( this.data ) Scene event bus ( this.events ) this.events.on('changedata score', ...) Registry ( this.registry ) Registry's own emitter this.registry.events.on('changedata score', ...) The key specific event 'changedata {key}' fires only for that exact key, while the generic 'changedata' fires for every key change. Always prefer key specific listeners for performance. Gotchas Keys Are Case Sensitive 'gold' and 'Gold' are two different keys. Be consistent with naming conventions. values Proxy Requires set() First You must call set(key, value) to create a key before modifying it via data.values.key . Direct assignment to values for a brand new key will NOT create the event proxy it creates a plain property that emits no events. Object/Array Mutation Does Not Trigger Events Mutating a stored object or array in place does not emit changedata because the reference has not changed. You must re set the key with a new reference to trigger the event. Registry Listeners Persist Across Scene Restarts The registry lives on the Game object. Listeners added to this.registry.events are NOT cleaned up when a scene restarts. Always remove them on SHUTDOWN : Frozen DataManagers Fail Silently When freeze is true , all write operations ( set , remove , inc , toggle , pop , merge ) silently do nothing. No error is thrown and no event is emitted. This can be confusing if you forget you froze the data. Scene Data Plugin Shutdown vs Destroy The DataManagerPlugin removes its shutdown listener on shutdown but does NOT clear data on shutdown. Data persists if the scene restarts. It only fully resets on scene destroy. If you need a clean slate on restart, manually reset in a shutdown listener: inc() on Non Numeric Values inc() uses the + operator internally. On strings it concatenates rather than adds numerically. On booleans, they coerce to 0 or 1 before incrementing. Only use inc() on keys you know hold numbers. reset() Emits No Events Calling reset() clears all data silently no removedata events fire for the deleted keys. If you need removal events for each key, iterate and call remove() individually instead. Freezing Can Interrupt Batch Operations setFreeze(true) takes effect immediately. If you freeze mid way through a series of set() calls, subsequent calls in the batch silently no op. Always freeze only after all writes are complete. getAll() Returns a Snapshot getAll() returns a new plain object each time. It is a shallow copy primitive values are independent, but object/array values still share references with the DataManager's internal storage. First Argument in changedata key Callbacks For the generic changedata event, the callback receives (parent, key, value, previousValue) . For the key specific changedata {key} event, the key argument is omitted: (parent, value, previousValue) . This difference is easy to miss. Source File Map Path Description src/data/DataManager.js Core DataManager class set, get, each, merge, remove, query, freeze, events src/data/DataManagerPlugin.js Scene plugin extending DataManager; registered as this.data src/data/events/index.js Event constant exports (CHANGE DATA, SET DATA, REMOVE DATA, CHANGE DATA KEY, DESTROY) src/data/events/SET DATA EVENT.js 'setdata' emitted when a new key is created src/data/events/CHANGE DATA EVENT.js 'changedata' emitted when an existing key's value changes src/data/events/CHANGE DATA KEY EVENT.js 'changedata ' per key change event prefix src/data/events/REMOVE DATA EVENT.js 'removedata' emitted when a key is removed src/data/events/DESTROY EVENT.js 'destroy' DataManager listens for this from its parent src/gameobjects/GameObject.js setData, getData, incData, toggleData, setDataEnabled convenience methods src/core/Game.js Creates game.registry the global DataManager instance src/scene/Scene.js Exposes this.registry (injected from Game) and this.data (DataManagerPlugin)

data-manager