Jazz2::PreferencesCache class
#include <Jazz2/PreferencesCache.h>

Provides access to a user preferences.

Static, process-wide store of all persisted settings (graphics, gameplay, input, language) plus per-episode continuation states. Loaded on startup and written back to the configuration file, it is queried throughout the engine to read the current configuration.

Public static variables

static bool FirstRun: Whether the application is running for the first time.
static bool IsStandalone: Whether the application is running as progressive web app (PWA).
static UnlockableEpisodes UnlockedEpisodes: Currently unlocked episodes if compiled with SHAREWARE_DEMO_ONLY.
static RescaleMode ActiveRescaleMode: Active rescale mode.
static bool EnableFullscreen: Whether the application is running in fullscreen.
static std::int32_t MaxFps: Maximum frace rate.
static bool PhysicsProbe: Whether the movement probe takes over the first player.
static PerformanceMetricsLevel PerformanceMetrics: How much of the performance metrics is visible.
static bool KeepAspectRatioInCinematics: Whether cinematics should keep original aspect ratio.
static bool ShowPlayerTrails: Whether player trails are visible.
static bool ShowMinimap: Whether the minimap is shown in multiplayer (if provided by the server).
static bool LowWaterQuality: Whether low quality water effects are enabled.
static bool UnalignedViewport: Whether viewport should be unaligned.
static bool PreferVerticalSplitscreen: Whether vertical splitscreen is preferred.
static bool PreferZoomOut: Whether viewport zoom out is preferred.
static bool BackgroundDithering: Whether background dithering should be used.
static bool BlurEffects: Whether blur effects are allowed.
static std::uint8_t LightingResolutionPercent: Lighting resolution percent (of the rendering resolution).
static std::uint8_t RenderingResolutionPercent: Rendering resolution percent.
static ParticleQuality Particles: Particle quality.
static std::uint16_t SafeArea: Safe area inset per screen edge, in tenths of a percent of the view (see SafeAreaEdge).
static bool EnableReforgedGameplay: Whether reforged gameplay is enabled.
static bool EnableReforgedCamera: Whether the reforged camera is enabled.
static bool EnableReforgedHUD: Whether reforged HUD is enabled.
static bool EnableReforgedMainMenu: Whether reforged main menu is enabled.
static bool EnableContinuousJump: Whether continuous jump is enabled.
static bool EnableLedgeClimb: Whether ledge climbing is enabled.
static WeaponWheelStyle WeaponWheel: Current weapon wheel style.
static bool SwitchToNewWeapon: Whether a newly acquired weapon is automatically selected.
static bool EnableRgbLights: Whether RGB light effects are enabled.
static bool AllowUnsignedScripts: Whether unsigned scripts can be loaded.
static bool TutorialCompleted: Whether tutorial is completed.
static bool ResumeOnStart: Whether the last state should be resumed on start.
static bool AllowCheats: Whether cheats are enabled by user.
static bool AllowCheatsLives: Whether unlimited lives are enabled.
static bool AllowCheatsUnlock: Whether all episodes are unlocked.
static EpisodeEndOverwriteMode OverwriteEpisodeEnd: Whether the last progress is overwritten on the end of episode.
static char Language: Current language.
static bool BypassCache: Whether the cache should be bypassed.
static float MasterVolume: Master sound volume.
static float SfxVolume: SFX volume.
static float MusicVolume: Music volume.
static std::int32_t AudioSampleRate: Sample rate the audio device mixes at in Hz, or 0 to keep the platform's default.
static bool ToggleRunAction: Whether toggle Run action is enabled.
static GamepadType GamepadButtonLabels: Active gamepad button labels.
static std::uint8_t GamepadRumble: Gamepad rumble intensity.
static bool PlayStationExtendedSupport: Whether PlayStation controller extended support is enabled.
static bool UseNativeBackButton: Whether native Back button should be used.
static bool EnableTouchJoystick: Whether D-pad is replaced by a floating analog joystick.
static bool EnableTouchVibration: Whether device vibration is used for touch button press feedback.
static TouchButtonLayout TouchButtons: Per-button layout configuration for all configurable touch buttons.
static Uuid UniquePlayerID: Unique player ID.
static Uuid UniqueServerID: Unique server ID.
static String PlayerName: Player display name.
static std::uint32_t PlayerFurColor: Player character recolor as 4 packed bytes (one per fur section).
static PlayerColorMode PlayerColors: When the custom player character color is applied (see PlayerColorMode).
static bool EnableDiscordIntegration: Whether Discord integration is enabled.

Public static functions

static void Initialize(AppConfiguration& config): Initializes preferences cache from a given application configuration.
static void Save(): Serializes current preferences to file.
static void DescribeNextMemoryCardFile(StringView shortDescription, StringView longDescription): Describes the next file written to a memory card to the console's file manager.
static auto GetDirectory() -> StringView: Returns directory path of the preferences file.
static void ApplyRenderingResolution(): Applies RenderingResolutionPercent to the graphics device.
static void ApplyPerformanceMetrics(): Collects the frame statistics exactly while PerformanceMetrics is at the level that shows them.
static auto GetDeviceID() -> String: Returns device ID of the device currently running this application.
static auto GetEffectivePlayerName() -> String: Returns effective player name.
static auto GetEpisodeEnd(StringView episodeName, bool createIfNotFound = false) -> EpisodeContinuationState*: Returns information about episode completion.
static auto GetEpisodeContinue(StringView episodeName, bool createIfNotFound = false) -> EpisodeContinuationStateWithLevel*: Returns information about episode continuation.
static void RemoveEpisodeContinue(StringView episodeName): Removes information about episode continuation (resets progress).
static void ResetTouchButtons(): Resets all touch button layouts to their default positions and sizes.
static void ResetSafeArea(): Resets all SafeArea insets back to zero, i.e. to the whole view.
static auto IsSafeAreaEnabled() -> bool: Returns true if any SafeArea edge is set, so the callers can skip the whole thing.
static auto GetSafeAreaInset(SafeAreaEdge edge, Vector2i viewSize) -> float: Returns the SafeArea inset of a single edge in view pixels.
static auto ApplySafeArea(const Rectf& bounds, Vector2i viewSize) -> Rectf: Returns the given rectangle narrowed by the SafeArea insets.

Constants

static std::int32_t UnlimitedFps constexpr: Value of MaxFps that specifies unlimited frame rate.
static std::int32_t UseVsync constexpr: Value of MaxFps that specifies the frame rate of the monitor being used.
static std::uint16_t MaxSafeArea constexpr: Largest value a single SafeArea edge can hold, i.e. 30% of the view.

Function documentation

static void Jazz2::PreferencesCache::DescribeNextMemoryCardFile(StringView shortDescription, StringView longDescription)

Describes the next file written to a memory card to the console's file manager.

A file on a VMU is more than its contents: in front of them sits a header that names the save, describes it and carries the 32×32 icon the file manager lists it with. A file without one is shown as unusable data that can only be deleted, so both files this game saves - the settings and the resumable state - get one.

KallistiOS attaches the header itself when the file handle closes, taking the one set here for any file that doesn't already carry its own (which a file opened for writing never does), so this has to be called before the file is opened and what it sets stays in force until the next call. shortDescription is what the file manager lists the save as and is limited to 16 characters, longDescription is shown beside it and is limited to 32.

static void Jazz2::PreferencesCache::ApplyRenderingResolution()

Applies RenderingResolutionPercent to the graphics device.

A no-op everywhere but on the PS Vita's native backend, where the whole frame is rendered into a surface smaller than the panel and stretched at present time (see IGfxDevice::setDrawableSize()): the preference sizes that surface, and the logical view then follows the drawable size as on any other display.

static Rectf Jazz2::PreferencesCache::ApplySafeArea(const Rectf& bounds, Vector2i viewSize)

Returns the given rectangle narrowed by the SafeArea insets.

The insets are a fraction of viewSize rather than of bounds, so the same margin comes off whatever is passed in: the whole view, a split-screen viewport, or a rectangle that has already been narrowed for something else (the HUD hands in what the touch controls left it, so the margin ends up measured from the buttons rather than from the screen edge). The result is clamped to stay a valid rectangle even when the insets are wider than what was passed in.

Variable documentation

static bool Jazz2::PreferencesCache::IsStandalone

Whether the application is running as progressive web app (PWA).

static bool Jazz2::PreferencesCache::PhysicsProbe

Whether the movement probe takes over the first player.

Set with /physics-probe. The player is driven through a fixed list of scenarios with scripted input and its position and speed are logged every tick, so the result can be compared against the same run in the original game (see Tests::PhysicsProbe). Combine with /log:file: to get the trace into a file and /max-fps: to pin the tick rate being measured.

static PerformanceMetricsLevel Jazz2::PreferencesCache::PerformanceMetrics

How much of the performance metrics is visible.

Apply a change with ApplyPerformanceMetrics(), which is what starts or stops collecting the statistics the detailed level shows.

static std::uint8_t Jazz2::PreferencesCache::RenderingResolutionPercent

Rendering resolution percent.

The most the scene is rendered at, as a fraction of the default view size (see Rendering::UpscaleRenderPass::CalculateViewSize()); a display smaller than that keeps getting a view of its own size. On PS Vita it sizes the frame surface itself instead, see ApplyRenderingResolution().

static ParticleQuality Jazz2::PreferencesCache::Particles

Particle quality.

ParticleQuality::High everywhere but the consoles that cannot spare the fill rate for it - the PlayStation 2, Dreamcast, GameCube and Nintendo 64 start at ParticleQuality::Low.

static std::uint16_t Jazz2::PreferencesCache::SafeArea

Safe area inset per screen edge, in tenths of a percent of the view (see SafeAreaEdge).

Keeps the interface clear of the parts of the picture a particular display does not show. Zero on every edge by default, which is the whole view and the behaviour of every build before this option existed; each edge is capped at MaxSafeArea. Applied through ApplySafeArea(), which the HUD, the in-game console and the menu all narrow themselves with.

static bool Jazz2::PreferencesCache::EnableReforgedCamera

Whether the reforged camera is enabled.

Separated from EnableReforgedGameplay because the camera is a local, purely visual concern – a client may well want the original's camera in a session whose physics the server decides. A configuration written before this option existed derives it from EnableReforgedGameplay.

static std::int32_t Jazz2::PreferencesCache::AudioSampleRate

Sample rate the audio device mixes at in Hz, or 0 to keep the platform's default.

Honoured only by the software-mixing backends whose cost is linear in this rate (the PSP, the PS2, the 3DS and the Amiga, see IAudioDevice::setMixingFrequency()); every other backend ignores it.

static bool Jazz2::PreferencesCache::UseNativeBackButton

Whether native Back button should be used.

static std::uint32_t Jazz2::PreferencesCache::PlayerFurColor

Player character recolor as 4 packed bytes (one per fur section).

Each byte is a sprite-palette gradient start; 0x00000000 means "use the original colors" (see ContentResolver::BuildPlayerColorPalette).

static std::uint16_t Jazz2::PreferencesCache::MaxSafeArea constexpr

Largest value a single SafeArea edge can hold, i.e. 30% of the view.

Well past what any display crops - the classic title-safe area is 5% an edge - but the range is wide enough to serve a badly misaligned projector, or simply someone who wants the interface gathered in. Past 25.5% it no longer fits a byte, which is why the value is stored as a word.