Guides Behaviours Store Small Settings with Preferences

Behaviours 2 min read Updated Apr 2026

Store Small Settings with Preferences

`Preferences` is Lenga's built-in API for small local settings.

Use it for simple values that should still be there the next time the player opens your game. Good examples are:

  • master volume
  • music volume
  • sound effects volume
  • fullscreen on/off
  • language
  • invert Y
  • mouse sensitivity
  • last selected profile
  • small non-critical flags

Do not use Preferences for full save-game data, world state, inventories, quest state, or sensitive information such as passwords or tokens.

How Preferences Work

The full workflow is:

  1. Read a value with a default.
  2. Change the value when the player updates a setting.
  3. Call Preferences::save() when you want to write the changes to disk.

Lenga stores preferences in an engine-managed per-user location. Your code does not choose a file path, and it does not need direct filesystem access.

The values are cached in memory while the game is running. Calling setInt, setFloat, setString, or setBool updates the cached value. Calling save() writes the cached values to the preferences file.

Use Preferences from a Behaviour

The code below belongs in a Behaviour class attached to a normal GameObject in your scene.

For example, create a GameObject called Settings Manager, attach this Behaviour to it, and call the public methods from your menu buttons or sliders.

<?php

namespace Platformer\Scripts\Menus;

use Lenga\Engine\Core\Behaviour;
use Lenga\Engine\Core\Preferences;

final class SettingsMenu extends Behaviour
{
    private float $musicVolume = 1.0;

    public function start(): void
    {
        $this->musicVolume = Preferences::getFloat('audio.musicVolume', 0.75);
    }

    public function setMusicVolume(float $volume): void
    {
        $this->musicVolume = max(0.0, min(1.0, $volume));

        Preferences::setFloat('audio.musicVolume', $this->musicVolume);
        Preferences::save();
    }
}

In this example:

  • Preferences::getFloat('audio.musicVolume', 0.75) returns the saved music volume if it exists.
  • If the key does not exist yet, Lenga returns the default value, 0.75.
  • Preferences::setFloat(...) updates the value in memory.
  • Preferences::save() writes the preferences file.

Supported Value Types

Preferences supports these value types:

  • int
  • float
  • string
  • bool

Use the matching getter and setter for each type.

Preferences::setInt('video.width', 1920);
Preferences::setInt('video.height', 1080);
Preferences::setBool('video.fullscreen', true);
Preferences::setString('language', 'en');
Preferences::setFloat('mouse.sensitivity', 0.8);

Preferences::save();

Read them back with defaults:

$width = Preferences::getInt('video.width', 1280);
$height = Preferences::getInt('video.height', 720);
$fullscreen = Preferences::getBool('video.fullscreen', false);
$language = Preferences::getString('language', 'en');
$sensitivity = Preferences::getFloat('mouse.sensitivity', 1.0);

Check and Remove Values

Use hasKey when your code needs to know whether a preference was saved before.

if (!Preferences::hasKey('language')) {
    Preferences::setString('language', 'en');
    Preferences::save();
}

Use deleteKey to remove one preference.

Preferences::deleteKey('lastSelectedProfile');
Preferences::save();

Use deleteAll when you are building a reset-settings button.

Preferences::deleteAll();
Preferences::save();

Limits to Keep in Mind

Preferences is designed for small local preferences and simple scalar state.

These workflows are not handled by Preferences:

  • full save-game slots
  • large structured save data
  • inventories, world state, quest state, or checkpoint data
  • local databases
  • encrypted or secure secret storage

For those cases, build or use a dedicated save-game system instead of storing everything in preferences.

Related Pages