data-manager

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

// Per-GameObject data (auto-creates DataManager on first use)
const gem = this.add.sprite(100, 100, 'gem');
gem.setData('value', 50);
gem.setData({ color: 'red', level: 2 });
gem.getData('value');            // 50
gem.getData(['value', 'color']); // [50, 'red']

// Increment / toggle helpers
gem.incData('value', 10);       // value is now 60
gem.incData('value', -5);       // value is now 55 (negative to decrement)
gem.toggleData('active');        // false -> true (starts from false if unset)

// Scene-level data (this.data is a DataManagerPlugin)
this.data.set('score', 0);
this.data.get('score');          // 0
this.data.values.score += 100;   // triggers changedata event

// Global registry (shared across ALL scenes)
this.registry.set('highScore', 9999);
// Any scene can read it:
this.registry.get('highScore');  // 9999

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.