`config` (Konfiguration)

Import

Das statische Attribut config der Klasse Controller kann über einen statischen Import eingebunden werden:

import static pi.Controller.config;

Java-Properties-Datei `engine-pi.properties`

Die Standardeinstellungen der Engine Pi können mithilfe einer Konfigurationsdatei names engine-pi.properties verändert werden. Dabei handelt es sich um eine Java-Properties-Datei, also ein sehr einfaches, selbsterklärend Format. Beim Starten eines Projekts sucht die Engine Pi im Ausführungsordner der Anwendung nach dieser Datei. Falls keine solche Datei vorhanden ist, erstellt die Engine eine engine-pi.properties mit den Standardwerten:

game_instantMode=true

graphics_framerate=60
graphics_windowWidth=768
graphics_windowHeight=576
graphics_windowPosition=NONE
graphics_colorScheme=Gnome
graphics_pixelMultiplication=1
graphics_screenRecordingNFrames=2

sound_soundVolume=0.5
sound_musicVolume=0.5

debug_enabled=false
debug_renderActors=true
debug_actorCoordinates=false
debug_renderAABBs=false
debug_useANSIcolors=false

coordinatesystem_linesNMeter=-1
coordinatesystem_labelsOnIntersections=false

Konfigurationsgruppen der Engine

Die einzelnen Einstellmöglichkeiten sind in Konfigurationsgruppen, die jeweils ein Präfix haben, organisiert:

game_: GameConfig
graphics_: GraphicsConfig
sound_: SoundConfig
debug_: DebugConfig
coordinatesystem_: CoordinatesystemConfig

Das statische Attribut Controller.config der Klasse Controller bietet Zugriff auf alle Einstellmöglichkeiten.

import pi.Controller;
Controller.config.graphics.windowWidth()

Das config-Objekt kann auch über einen statischen Import eingebunden werden: import static pi.Controller.config;. Statt Controller.config kann dann etwas kürzer config geschrieben werden.

import static pi.Controller.config;
config.graphics.windowWidth()

Das folgende Codebeispiel testet alle Einstellmöglichkeit mit den Standardwerten:

import static pi.Controller.config;

assertEquals(true, config.game.instantMode());

assertEquals(768, config.graphics.windowWidth());
assertEquals(576, config.graphics.windowHeight());
assertEquals(Direction.NONE, config.graphics.windowPosition());
assertEquals(32.0, config.graphics.pixelPerMeter());
assertEquals(0.05, config.graphics.zoomChange());
assertEquals(60, config.graphics.framerate());
assertEquals("Gnome", config.graphics.colorScheme());
assertEquals(1, config.graphics.pixelMultiplication());
assertEquals(2, config.graphics.screenRecordingNFrames());

assertEquals(0.5, config.sound.soundVolume());
assertEquals(0.5, config.sound.musicVolume());

assertFalse(config.debug.enabled());
assertTrue(config.debug.renderActors());
assertFalse(config.debug.actorCoordinates());
assertFalse(config.debug.renderAABBs());
assertFalse(config.debug.useANSIcolors());

assertEquals(-1, config.coordinatesystem.linesNMeter());
assertFalse(config.coordinatesystem.labelsOnIntersections());

Benutzerdefinierte Konfigurationsgruppen

Die Engine Pi bietet die Möglichkeit, auch eigene Konfigurationsgruppen zu definieren und dem Controller#config-Objekt hinzuzufügen.¹

Im folgenden Beispiel definiert die Klasse MyConfigGroup eine Einstellmöglichkeit in Form eines Attributs mit dem Namen myInt. Die dazugehörenden Getter- und Setter-Methoden haben - wie in der Engine Pi üblich - kein get- bzw. set-Präfix:

import pi.annotations.Getter;
import pi.annotations.Setter;
import pi.config.ConfigGroup;
import pi.config.ConfigGroupInfo;

@ConfigGroupInfo(prefix = "custom_")
public class MyConfigGroup extends ConfigGroup
{
    private int myInt = 23;

    @Getter
    public int myInt()
    {
        return myInt;
    }

    @Setter
    public void myInt(int myInt)
    {
        set("myInt", myInt);
    }
}

Im Setter sollte die Methode set(String,T) (set("myInt", myInt);) anstatt des Zuweisungsoperator (this.myInt = myInt;) verwendet werden, damit der ConfigurationChangedListener benachrichtigt werden kann.

Die Annotationen @Getter und @Setter sind nicht zwingend notwendig, die Annotation @ConfigGroupInfo jedoch schon. Die Annotation @ConfigGroupInfo(prefix = "custom_") bewirkt, dass das Attribut myInt als custom_myInt in die Properties-Datei geschrieben wird.

Benutzerdefinierte Konfigurationsgruppen müssen mit Hilfe der Methode addGroup(ConfigGroup...) erst zum statischen Singleton-config-Objekt hinzugefügt werden.

import static pi.Controller.config;

import pi.Scene;

public class CustomConfigGroupDemo extends Scene
{
    static
    {
        MyConfigGroup custom = new MyConfigGroup();
        config.addGroup(custom);
    }
}

Dann kann die Konfigurationsgruppe über die Methoden getGroup(Class)

MyConfigGroup custom = config.getGroup(MyConfigGroup.class);
System.out.println(custom.myInt());

oder getGroup(String)

MyConfigGroup custom = (MyConfigGroup) config.getGroup("custom_");
System.out.println(custom.myInt());

wieder abgerufen werden.

Damit die benutzerdefinierte Konfigurationsgruppen in die engine-pi.properties-Datei geschrieben werden, muss ConfigLoader#save() aufgerufen werden.

import static pi.Controller.config;
config.save();

Eigene `*.properties` Datei nutzen

Die der Engine eigenen Konfigurationen werden in einer Datei mit dem Namen engine-pi.properties verwaltet. Zu dieser Datei können eigene Konfigurationen hinzugefügt werden. Bei größeren Projekten bietet es sich an, eine eigene Properties-Datei zu verwenden. Mithilfe der Klasse ConfigLoader können eigene Konfigurationsgruppen in einer separaten Datei verwaltet werden. Als erstes Argument im Konstruktor kann der Dateipfad entweder als Zeichenkette oder als Pfad angegeben werden. Das folgende Code-Beispiel erzeugt eine Properties-Datei mit dem Namen custom.properties:

ConfigLoader config = new ConfigLoader("custom.properties");
MyConfigGroup group = new MyConfigGroup();
config.addGroup(group);
group.myInt(42);
config.save();

Beobachter bei Konfigurationsänderungen

Die Engine Pi bietet die Möglichkeit, Beobachter / Listener zu registrieren. Diese werden informiert, wenn Konfigurationswerte geändert werden.

Die Verwaltung der Beobachter für alle registrierten Konfigurationsgruppen erfolgt über die folgenden Methoden:

Beobachter für eine Konfigurationsgruppe lassen sich mit diesem Methoden an- und abmelden.

https://litiengine.com/docs/configuration/ ↩

config (Konfiguration)

Java-Properties-Datei engine-pi.properties