Screensaver๏ƒ

Inherits: Object

Runtime singleton for Windows screensaver modes (/s, /p, /c, /a).

Description๏ƒ

Screensaver is compiled only when the screensaver module is enabled. Command-line switches apply only when blazium/screensaver/enabled is true in the exported project. Password hashes are stored per-user (HKCU on Windows, user://screensaver_password.cfg elsewhere) and never as plaintext in the PCK.

Windows 11 Screen Saver Settings (desk.cpl) launches the same .scr with /p hwnd, /p:hwnd, or /s hwnd for the dropdown preview (a WS_CHILD of the pane, not a centered popup); /c, /c:hwnd, /c hwnd, or older /cHWND (no colon or space) for Settings; and bare /s with no HWND for the Preview button or idle desktop cover. Settings (/c) and change-password (/a) open a visible owned dialog above desk.cpl; they are never embedded in the preview pane. A missing, zero, or invalid configure HWND stays /c and never falls through to fullscreen /s. Only bare /s covers the desktop. A .scr with no arguments is configure, not run. application/run/main_scene is the /s / /p animation. Do not set it to unlock_scene. unlock_scene is shown only when dismissing /s if a password is enabled and set. Settings (/c) and change-password (/a) never load unlock; a missing configure or change-password scene falls back to the builtin dialog. The desk.cpl checkbox On resume, display logon screen is Windows ScreenSaverIsSecure, not unlock_scene.

/s run coverage is selected by blazium/screensaver/cover_mode (single, virtual, or clone), or by --screensaver-cover. A Windows host launch (explorer.exe / winlogon.exe /S, including the .scr open verb) spans every monitor even when the packed cover mode is single. desk.cpl / rundll32.exe is not an idle host launch. cover_all_screens=true falls back to virtual for CreateProcess child launches. --screen N, /s:N, /s N, or blazium/screensaver/screen pin a borderless windowed cover to that monitor and override virtual. Indexes are 0-based: 0 is the primary monitor, then remaining displays left-to-right. A Windows-style value equal to the monitor count maps to the last display. Launching a .scr through Explorer or PowerShell uses the Windows open verb and only passes /S, so --screen and --screensaver-cover never reach the process. Use CreateProcess (not ShellExecute), or set BLAZIUM_SCREENSAVER_SCREEN and BLAZIUM_SCREENSAVER_COVER. Placement uses a native popup SetWindowPos every frame (not Godot window_set_mode / window_set_flag) so DisplayServer cannot snap the HWND back to the primary. The cover fills the chosen display. If a virtual span is clipped to one monitor, the other displays are covered with clone windows. clone still copies the other monitors. Run mode never uses exclusive fullscreen. Chrome is forced borderless again each frame so Godot cannot restore a titled Main Menu window.

Methods๏ƒ

Error

clear_password(current_plain: String)

Mode

get_mode() const

bool

has_password() const

bool

is_password_enabled() const

bool

is_preview() const

void

request_exit()

Error

set_password(old_plain: String, new_plain: String)

void

set_password_enabled(enabled: bool)

bool

verify_password(plain: String) const

Signals๏ƒ

password_changed() ๐Ÿ”—

Emitted after set_password() succeeds.

unlock_failed() ๐Ÿ”—

Emitted when unlock verification fails.

unlock_succeeded() ๐Ÿ”—

Emitted when unlock verification succeeds, just before quit.

Enumerations๏ƒ

enum Mode: ๐Ÿ”—

Mode MODE_DISABLED = 0

Screensaver project setting is off, or no Control Panel switch was applied.

Mode MODE_RUN = 1

Borderless desktop cover (/s or /s:N). A .scr with no switch is configure, not run. Cover modes: single (one monitor), virtual (one window spanning the virtual desktop), clone (one fullscreen window per monitor).

Mode MODE_PREVIEW = 2

Embedded preview (/p, /p:hwnd, /s hwnd, or a bare HWND). Parent as a WS_CHILD at 0,0 in the desk.cpl preview pane. Never a centered standalone window.

Mode MODE_CONFIGURE = 3

Configure dialog (/c, /c:hwnd, /c hwnd, /cHWND, or a .scr with no arguments). A failed HWND stays configure. Shown as a visible owned dialog above desk.cpl, never embedded. Never shows unlock_scene.

Mode MODE_CHANGE_PASSWORD = 4

Change-password dialog (/a). Visible owned dialog, never embedded in the preview pane.

Method Descriptions๏ƒ

Error clear_password(current_plain: String) ๐Ÿ”—

Clears the stored password hash after verifying current_plain.

Mode get_mode() const ๐Ÿ”—

Returns the active screensaver mode, or MODE_DISABLED when the project setting is off.

bool has_password() const ๐Ÿ”—

Returns true if a password hash is stored for this application.

bool is_password_enabled() const ๐Ÿ”—

Returns the per-user stored override if set_password_enabled() has been called, otherwise blazium/screensaver/password_enabled.

bool is_preview() const ๐Ÿ”—

Returns true when launched with /p (Control Panel preview). Preview never prompts for a password.

void request_exit() ๐Ÿ”—

Starts dismiss. In run mode with a password, opens the unlock UI instead of quitting.

Error set_password(old_plain: String, new_plain: String) ๐Ÿ”—

Sets or changes the password. An empty new_plain clears the secret. The hash is never written to project.blazium.

void set_password_enabled(enabled: bool) ๐Ÿ”—

Persists whether unlock is required on dismiss. Stored per-user (HKCU on Windows, user://screensaver_password.cfg elsewhere) so Control Panel /c survives an exported .scr.

bool verify_password(plain: String) const ๐Ÿ”—

Returns true if plain matches the stored salt+SHA-256 hash.