Data Adapter

Overview

Dill Pixel provides a robust data management system through its DataAdapter class. This system allows you to:

• Store and retrieve game data
  • increment numeric values
  • append strings
  • concatenate arrays
  • deep merge data
• Persist data to localStorage
• Listen for data changes
• Selectively backup specific data keys

Basic Configuration

Configure data management in your dill-pixel.config.ts:

export type Data = {
  score: number;
  playerName: string;
  settings: {
    soundEnabled: boolean;
    musicVolume: number;
  };
};
export const config = defineConfig<Data>({
  // ... other config options
  data: {
    // Initial data values
    initial: {
      score: 0,
      playerName: '',
      settings: {
        soundEnabled: true,
        musicVolume: 0.5,
      },
    },
    // Keys to backup to localStorage
    backupKeys: ['settings'],
    // Whether to backup all data (alternative to specifying keys)
    backupAll: false,
    // Optional namespace for localStorage keys
    namespace: 'my-game',
  },
});

Data Manipulation Methods

The DataAdapter provides several methods for managing game data. Each has specific use cases and behaviors.

set() Method

The set() method allows updating single or multiple values, with optional deep merging:

// Update a single value
this.app.data.set('score', 100);

// Update multiple values with deep merge (default)
this.app.data.set({
  score: 100,
  settings: {
    soundEnabled: false, // Only updates soundEnabled, preserves other settings
  },
});

Type Safety

Type safety is enforced for the set() method. If you pass an object that doesn’t match the expected shape, TypeScript will throw an error.

this.app.data.set('score', 'pickle'); // will throw a ts error

Deep Merge Behavior

You can also use the merge parameter to control the merge behavior. By default, the set() method will merge the new data with the existing data, passing false will replace the entire data object.

Merge: true (default)

When using set() with merge: true (default), the DataAdapter performs a deep merge:

dill-pixel.config.ts

// Initial data, set in dill-pixel.config.ts
defineConfig<Data>({
  // ... other config options
  data: {
    initial: {
      settings: {
        sound: { enabled: true, volume: 0.5 },
        display: { fullscreen: false },
      },
    },
  },
});

src/scenes/MyScene.ts

// Update with deep merge
this.app.data.set({
  settings: {
    sound: { volume: 0.8 }
  }
});

  /* Result:
  {
    settings: {
      sound: { enabled: true, volume: 0.8 },
      display: { fullscreen: false }
    }
  }
  */

Merge: false

With the merge parameter set to false, the entire data object is replaced. Be sure to include all required fields:

// Replace entire data object (no merge)
this.app.data.set(
  {
    score: 0,
    settings: {
      soundEnabled: true,
      musicVolume: 1.0,
    },
  },
  false, // do not merge
);

get() Method

The get() method retrieves data from storage:

// Get entire data object
const allData = this.app.data.get();

// Get specific field
const score = this.app.data.get('score');
const settings = this.app.data.get('settings');

clear() Method

The clear() method removes data both from memory and localStorage:

// Clear all data
this.app.data.clear();

// Clear specific field
this.app.data.clear('score');

increment() Method

The increment() method provides a type-safe way to increment numeric values:

// Set initial value (could also be set in dill-pixel.config.ts)
this.app.data.set('score', 0);

// Increment by 1 (default)
this.app.data.increment('score'); // score is now 1

// Increment by specific amount
this.app.data.increment('score', 10); // score is now 11

Type Safety

The increment() method only works with numeric properties. Attempting to increment a non-numeric property will result in a TypeScript error.

// property value must be defined as a number
this.app.data.increment('someStringValueKey', 10); // will throw a ts error

concat() Method

The concat() method allows you to append values to array properties:

// E.G. the `inventory` property has previously been defined as an array of strings

// Initialize empty array
this.app.data.set('inventory', ['sword']);
// Add single item
this.app.data.concat('inventory', 'shield');
// Add multiple items
this.app.data.concat('inventory', ['potion', 'book']);
// Result: inventory = ['sword', 'shield', 'potion', 'book']

Type Safety

The concat() method maintains type safety for array elements. The values being concatenated must match the array’s element type.

// property value must be defined as an array
this.app.data.concat('inventory', [1, 2, 3]); // will throw a ts error

append() Method

The append() method is used to concatenate strings with optional separators:

// E.G. the `stuff` property has previously been defined as a string

// set the initial value
this.app.data.set('stuff', 'things');
// Append a single string
this.app.data.append('stuff', 'more', '-');
// Result: stuff = 'things-more'

// set the initial value
this.app.data.set('stuff2', 'things');
// Append multiple strings, uses the ' ' separator
this.app.data.append('stuff2', ['more', 'stuff'], ' ');
// Result: stuff2 = 'things more stuff'

Type Safety

The append() method only works with string properties and automatically enforces this at compile time.

snapshot() Method

The snapshot() method creates a deep copy of your game data, useful for:

• Creating save states
• Comparing data changes
• Debugging
• Implementing undo/redo functionality

// Get snapshot of all data
const fullSnapshot = this.app.data.snapshot();

// Get snapshot of specific field
const scoreSnapshot = this.app.data.snapshot('score');

Deep Copy

The snapshot() method performs a deep copy using JSON serialization, ensuring that the returned data is completely disconnected from the original data object. This means modifications to the snapshot won’t affect the actual game data.

Example Use Cases

Save States

// Create a save point
const savePoint = this.app.data.snapshot();

// Later, restore the save point
this.app.data.set(savePoint, false); // false = don't merge

Debugging

// Log data at specific points without worrying about reference issues
console.log('Game state before battle:', this.app.data.snapshot());
startBattle();
console.log('Game state after battle:', this.app.data.snapshot());

Performance Note

Since snapshot() creates a deep copy, it should be used judiciously with large data structures to avoid performance impacts. Consider snapshotting only the specific keys you need rather than the entire data object.

Change Signal

All data modifications emit change events that you can listen to:

this.app.data.onDataChange.add((detail) => {
  const { key, value, restore } = detail;

  // Single key updates (from save())
  if (typeof key === 'string') {
    console.log(`${key} updated to:`, value);
  }

  // Multiple key updates (from set())
  if (Array.isArray(key)) {
    console.log('Updated keys:', key);
  }

  // Restoration from localStorage
  if (restore) {
    console.log('Data restored from localStorage');
  }
});