Setting Menu

Settings Menu

Overview

The Settings Menu allows players to configure the game's audio and display settings.

The same reusable SettingsPanel is used in both:

• The standalone Settings screen opened from the Main Menu.
• The Settings view opened from the in-game Pause Menu.

This keeps the behaviour and appearance of Settings consistent across the game.

Settings are saved using UserSettings and persist between game sessions.

---

Settings Menu

Audio Settings

The Settings Menu provides the following audio controls:

Setting	Description
Master Volume	Controls the overall game audio level.
Music Volume	Controls background music volume.
Sound Effects	Controls gameplay and UI sound-effect volume.
Mute	Mutes all audio without changing the saved volume values.

Volume sliders range from 0% to 100% in increments of 5%.

The final output volume is calculated using the Master Volume together with the individual audio channel.

Effective Music Volume = Master Volume × Music Volume
Effective SFX Volume = Master Volume × Sound Effects Volume

For example:

Master Volume = 50%
Music Volume = 60%

Effective Music Volume = 30%

When Mute is enabled, the effective music and sound-effect volumes become 0, while the original slider values are preserved.

---

Display Settings

The Settings Menu also provides display controls.

Setting	Description
FPS Cap	Sets the maximum foreground FPS.
Fullscreen	Enables or disables fullscreen mode.
VSync	Enables or disables vertical synchronisation.
Resolution	Selects an available display mode.

The FPS value must be a positive whole number.

Valid examples:

30
60
120
144

Invalid examples:

0
-60
60.5
abc

If the FPS value is invalid, none of the pending settings are saved.

---

Menu Actions

The Settings Menu contains three main actions.

Reset

Resets all controls to their default values.

Default values:

Setting	Default
FPS	60
Fullscreen	Off
VSync	On
Master Volume	100%
Music Volume	100%
Sound Effects	100%
Mute	Off

Reset does not immediately save the settings.

The player must press Apply to save the default values.

The following feedback is displayed:

Defaults restored. Click Apply to save.

Back

Returns to the previous menu.

From the standalone Settings screen:

Settings → Main Menu

From the Pause Menu:

Pause Menu → Settings → Pause Menu

Unsaved changes are discarded when leaving without pressing Apply.

Apply

Validates the selected values, saves them, and immediately applies them to the game.

When successful:

Settings applied.

---

Validation and Feedback

The Settings Menu provides feedback when applying settings.

Invalid FPS

If the FPS input is invalid:

Invalid FPS. Enter a positive whole number.

No settings are written.

Other pending changes remain in the menu so the player can correct the FPS input without re-entering their other settings.

Failed Apply

If the settings cannot be written:

Could not apply settings. Please try again.

The current pending settings remain available so the player can retry.

Successful Apply

After settings are successfully written:

Settings applied.

Changing any control clears the previous feedback message.

---

Settings Persistence

Persistent settings are handled by:

UserSettings

Settings are stored in:

DECO2800Game/settings.json

The following values are stored:

fps
fullscreen
vsync
masterVolume
musicVolume
soundEffectsVolume
muted
displayMode

If no settings file exists, the default values are used.

Older settings files that do not contain the new audio values remain compatible because the missing audio settings use default values.

Volume values are normalised into the range:

0.0 - 1.0

before they are saved or applied.

---

Main Menu Integration

The Main Menu opens the standalone SettingsScreen.

The main structure is:

SettingsScreen
    |
    v
SettingsMenuDisplay
    |
    v
SettingsPanel

SettingsMenuDisplay provides the Settings screen background and layout.

SettingsPanel contains all Settings controls and logic.

Pressing Back returns the player to the Main Menu.

---

Pause Menu Integration

The Pause Menu uses the same SettingsPanel.

PauseMenuDisplay
    |
    v
SettingsPanel

The Settings interface is displayed inside the Pause Menu instead of changing to another game screen.

This means:

• The current run is preserved.
• Gameplay remains paused.
• Settings can be changed without leaving the run.
• Back returns to the Pause Menu.
• The same Settings implementation is reused across both menu locations.

---

Audio Integration

The Settings system communicates with the audio system through:

AudioSettingsApplier

The architecture is:

SettingsPanel
     |
     v
UserSettings
     |
     v
AudioSettingsApplier
     |
     v
AudioService

UserSettings calculates the effective Music and Sound Effects volume before passing the values to the audio system.

For example:

Master Volume = 0.5
Music Volume = 0.6

Effective Music Volume = 0.3

AudioService then applies the value to the currently playing music and future playback.

When the audio settings service is registered through ServiceLocator, the saved settings are immediately applied.

---

UML Diagram

The Settings system follows the structure below:

SettingsScreen
      |
      v
SettingsMenuDisplay
      |
      v
SettingsPanel <---------------- PauseMenuDisplay
      |
      v
UserSettings
      |
      +-----------------> FpsValidator
      |
      v
ServiceLocator
      |
      v
AudioSettingsApplier
      ^
      |
AudioService

SettingsPanel is the shared UI component.

UserSettings handles persistence and applies the selected values.

AudioSettingsApplier separates the Settings system from the implementation details of AudioService.

---

Adding a New Setting

To add another setting:

1. Add the value to UserSettings.Settings.
2. Add the appropriate UI control to SettingsPanel.
3. Load the current value when creating the panel.
4. Read the value inside applyChanges().
5. Apply the setting through UserSettings or the relevant game service.
6. Update copyOf() in SettingsPanel.
7. Add tests for the new setting.

Settings controls should remain inside the shared SettingsPanel so that both the Main Menu and Pause Menu receive the same behaviour.

---

Testing

The Settings system contains automated tests for:

• Loading current settings.
• Audio volume values.
• Mute behaviour.
• Settings persistence.
• Older settings-file compatibility.
• FPS validation.
• Reset behaviour.
• Apply feedback.
• Failed writes.
• Settings Panel behaviour.
• Pause Menu and Settings integration.

Tests can be run from the source directory:

./gradlew core:test

The game can be manually tested using:

./gradlew desktop:run

Example manual test:

Main Menu
→ Settings
→ Change Music Volume
→ Apply
→ Back
→ Open Settings again
→ Confirm saved value

Map
→ Pause
→ Settings
→ Change Settings
→ Apply
→ Back
→ Resume

The active run should remain unchanged when using Settings through the Pause Menu.