ppkantorski/Ultrahand-Overlay v2.4.5

Ultrahand Overlay 2.4.5

on GitHub

List of Changes

1. New conditional {if_...} placeholder method.
   • null
     • {if_null(<VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])} returns TRUE_FALLBACK when VALUE resolved to null (the literal returned by an unresolved/missing placeholder).
   • !null
     • {if_!null(<VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])} is the inverse.
   • ==, !=
     • {if_==(<VALUE>,<COMPARE_VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])} and {if_!=(...)} do exact string equality.
   • >, <, >=, <=
     • {if_>(<VALUE>,<COMPARE_VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])}, {if_<(...)}, {if_>=(...)}, and {if_<=(...)} compare numerically when both values are numbers (compared as floats), and fall back to a plain lexicographic (case-sensitive) comparison otherwise.
   • version_>, version_<, version_>=, version_<=
     • {if_version_>(<VALUE>,<COMPARE_VALUE>,<TRUE_FALLBACK>,[FALSE_FALLBACK])}, {if_version_<(...)}, {if_version_>=(...)}, and {if_version_<=(...)} do version-aware comparison.
     • Numeric segments compare as integers (1.10.0 > 1.9.0).
     • - suffix is treated as a pre-release and sorts lower (2.0.1-rc < 2.0.1).
     • + suffix is treated as build metadata and sorts higher (2.0.1+r23 > 2.0.1).
   • The FALSE_FALLBACK is optional in every form. When omitted, the false branch returns VALUE unchanged.
2. New {crc32(<FILE_PATH>)} placeholder method.
   • Returns the CRC32 of a file as 8 uppercase hex characters, or null if the file can't be read.
   • Useful with the {if_...} and matching_* checks for verifying file contents.
3. All placeholders can now be composed to define any source declaration.
   • All placeholder variable declarations are fully resolved in order before being used.
   • All placeholder commands (excluding _source) can be nested and chained to build the final _source declaration.
     • Side-note: No commands are executed at this stage; only placeholder expressions are evaluated.
   • Non-source variable placeholders can now be redefined mid-section in sourced commands.
4. New standalone conditional commands for use in packages.
   • path_exists <PATH>
   • ipc_exists <SERVICE_NAME>
   • module_exists <TID> (true when the module's content folder exists, running or not)
   • module_is_active <TID> (true only when the module is currently running)
   • matching_txt_line <FILE_PATH> <TEXT_LINE>
   • matching_hex_val <FILE_PATH> <OFFSET> <HEX_VALUE>
   • matching_ini_val <FILE_PATH> <SECTION> <KEY> <VALUE>
   • Each runs as its own command and resolves to success or failure, so it can be used mid-script to force a command failure or success (handy with try: logic).
   • Prefix any of them with ! to invert the result (!path_exists, !module_exists, etc.).
5. New ;visibility_condition= option directive for usage with all command objects.
   • ;visibility_condition=<MODE> <ARGS> draws a menu item or section only when the condition is satisfied; otherwise the item is skipped at render time.
   • Accepts any of the conditional modes above (path_exists, ipc_exists, module_exists, module_is_active, matching_txt_line, matching_hex_val, matching_ini_val) with ! negation, and resolves placeholders inside the condition.
   • An empty condition (as well as a successful condition) shows the item; an unknown mode, missing argument (or false condition) hides it.
   • Revised integration from PR #309.
6. New ;toggle_state_condition= option directive.
   • Sets a toggle's initial ON/OFF state from a live condition instead of an on/off path check. Uses the same conditional modes as ;visibility_condition=. A satisfied condition starts the toggle ON.
   • Revised integration from PR #309.
7. New ;hold=true directive for hold-to-activate items.
   • Add ;hold=true to a command list item or a toggle to require the user to hold the action before it fires.
   • While held, the item shows the in-progress symbol; execution is deferred until the hold completes, and the action can be cancelled by releasing early.
   • The hold length is set globally by the new Hold Duration trackbar (see below).
   • The built-in default Reboot/Shutdown package now ships its Shutdown entry with ;hold=true.
8. New module command for starting and stopping sysmodules.
   • module start <TID> launches a sysmodule by program ID.
   • module stop <TID> stops a sysmodule, graceful-first with a force-kill fallback for dynamic modules.
   • Reads the module's toolbox.json for its shutdown contract; static modules with no graceful contract are refused rather than risking an unsafe kill.
   • <TID> accepts a bare 16-hex-character folder name or a 0x-prefixed program ID.
9. New ipc-exec <SERVICE_NAME> <ENUM_CMD> command.
   • Sends a void to void IPC command to a service; success means the dispatch was accepted.
10. New ntp-sync <NTP_URL> command.
    • On-demand clock sync to the NTP host you specify.
    • Checks for internet access internally before attempting the sync.
11. New refresh-return command for sourced commands (dropdown menus).
    • When returning from a sourced selection, refresh-return redraws the entire prior menu and lands the cursor back on the item you came from, instead of a plain back.
    • Calling is optional. Without is faster, so only use refresh-return when the prior menu needs to be rebuilt to reflect changes (e.g. values that conditions key off of).
12. New refresh combos command argument.
    • refresh combos reloads the launch key combos live, so changes take effect without restarting the overlay. This joins the existing refresh theme, refresh package, and refresh wallpaper arguments.
13. New Input Settings section added to Misc.
    • Houses Launch Combos, Swipe to Open, Haptic Feedback, and the two new input options below.
    • New Stick Navigation toggle. When on, the analog stick navigates menus alongside the D-pad; when off, only the D-pad navigates. Applies to all libultrahand v2.4.5+ overlays.
    • New Hold Duration track-bar. Sets the global command hold-A length for all hold-to-activate actions, from 0.5s to 5.0s (default 3.0s).
14. Settings menu reorganized and renamed.
    • Page Recall and Launch Recall toggles have been removed. These behaviors are now always on.
    • The old Features header is now Feature Settings.
    • Auto NTP Sync is renamed NTP Sync Downloads.
15. The handheld / docked ;state= directive renamed to ;device_state=.
    • IMPORTANT: Packages that used ;state= must update to ;device_state=.
16. ini_file_source now supports wildcard paths.
    • A wildcard ini_file_source path enumerates every matching .ini and merges their section names (empty names skipped, duplicates removed, first occurrence wins).
    • Multiple ini_file_source lines now accumulate sections together rather than each one replacing the last.
    • Revised integration from PR #312.
17. The default root package now includes an INI Entry for /bootloader/ini/*.ini entries in Reboot To.
    • Side-note: Users may want to delete /switch/.packages/package.ini to have this command updated.
    • Revised integration from PR #312.
18. mirror- is now accepted as an alias for mirror_ (mirror-copy, mirror-cp).
    • Side-note: This follows the loose convention where - are used with action commands (set-ini-val, sync-ntp, etc) and _ are used to for check commands that simply resolve to success or failure (path_exists, matching_ini_val, etc).
19. The overlay version placeholder {ovl_version(<OVL_PATH>)} now works with relative path resolution (i.e. ./ and ./../).
20. Cleaner dock power-down protocol on reboot and shutdown commands.
    • A USB-PD teardown is now staged before any shutdown so the console signals the dock to cut its 5V rail before the PMIC powers off.
    • Bug fix from Issue #313.
21. New Overlay does not exist! notification for attempting to launch an overlay file that does not exist.
    • Launching a mode whose overlay file is missing now reports the missing overlay directly instead of misreporting it as AMS-incompatible.

New Contributors

• @Niklas080208 made their first contribution in #312
• @rashevskyv made their first contribution in #309

Full Changelog: v2.4.4...v2.4.5

Quick Update

• ;device_state= processing bug fix. - 06/11/2026 8:00 AM PST
• Variable placeholder definition / redefinition and resolutions bug fix. - 06/11/2026 8:00 AM PST

Full Changelog: v2.4.5...9b965b1