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. The framework uses a defineData helper to ensure your data is fully type-safe.

import { defineConfig, defineData } from 'dill-pixel';

// 1. Define your data schema
export const dataSchema = defineData({
  score: 0,
  playerName: '',
  settings: {
    soundEnabled: true,
    musicVolume: 0.5,
  },
});

// 2. Add it to your main config
export default defineConfig({
  // ... other config options
  data: {
    // Initial data values can override the schema defaults
    initial: {
      playerName: 'Hero',
    },
    // 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',
  },
});

Note

By using defineData, the framework automatically infers the shape of your data, providing type-safety and autocompletion wherever you access this.app.data, with no need for manual type definitions.

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

import { defineConfig, defineData } from 'dill-pixel';

export const dataSchema = defineData({
settings: {
  sound: { enabled: true, volume: 0.5 },
  display: { fullscreen: false },
},
});

// Initial data is now part of the main config
export default defineConfig({
  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:

// This example would fail with type-safety unless you provide all fields!
// It's generally safer to use deep merging.
this.app.data.set(
  {
    score: 0,
    playerName: 'New Player',
    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 returns a deep copy of the data at a specific point in time, which is useful for debugging or comparing states.

src/scenes/MyScene.ts

// 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());

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

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');
  }
});