Skip to content

Package Reference

Jump to bottom
ppkantorski edited this page Apr 21, 2026 · 15 revisions

Current as of: Ultrahand Overlay v2.4.1

This page covers everything needed to create and configure Ultrahand packages: folder layout, header fields, page/tab definitions, boot and exit hooks, language support, and the config.ini state file. For a complete list of available commands, see the Command Reference.

Table of Contents

  1. Package Structure
  2. Package Headers
  3. Tab / Page Headers
  4. Command Headers
  5. Boot and Exit Hooks
  6. Special Root-Level Packages
  7. The config.ini State File
  8. Language Translations
  9. Complete Example

Package Structure

Packages live in /switch/.packages/<YOUR_PACKAGE_NAME>/ and are driven by a package.ini file.

/switch/.packages/
└── MyPackage/
    ├── package.ini          ← required: commands and headers
    ├── config.ini           ← auto-generated: runtime state
    ├── boot_package.ini     ← optional: commands run on launch
    ├── exit_package.ini     ← optional: commands run on close
    └── lang/
        ├── en.json          ← optional: English translations
        └── ja.json          ← optional: Japanese translations

A minimal package.ini looks like this:

;title='My Package'
;version=1.0.0
;creator=YourName
;about='A short description.'

[Section Header]
copy /path/to/source /path/to/dest

[*Dropdown Command]
;mode=option
list_source '(Option A, Option B, Option C)'

Paths in commands are relative to the SD card root. Use ./ as a shortcut for the package's own folder (e.g. ./config.ini resolves to /switch/.packages/MyPackage/config.ini). You can also use .. to reference the directory above the package folder.

Package Headers

Package headers are ;key=value directives placed at the top of package.ini, before any [Section] headers. Values containing spaces should be wrapped in single quotes.

Header Description
;title=<TEXT> The display name shown on the Packages menu.
;display_title=<TEXT> An alternative title displayed inside the package (overrides ;title= for the in-package header).
;version=<TEXT> The version string. Exposed via the {package_version} placeholder.
;creator=<TEXT> The author name.
;about=<TEXT> A short description of the package.
;credits=<TEXT> Credits or acknowledgements.
;color=<VALUE> Color for the package title. Accepts named colors (red, green, blue, yellow, orange, purple, pink, white) or a hex value (e.g. #a264fa).
;show_widget=true/false When true, renders the system status widget alongside the package header.
;show_version=true/false When true, displays the package version in the subtitle instead of the current section name. false by default.

Example:

;title='Alchemist'
;display_title='Alchemist '
;creator=ppkantorski
;version=1.0.5
;about='Manage, convert, and install mods.'
;credits='Special thanks to contributors.'
;color=#a264fa
;show_widget=true

Tab / Page Headers

A package can define two navigable pages using empty sections prefixed with @. The first [@Name] becomes the left tab; the second becomes the right tab. Users switch between them with the D-Pad left/right buttons.

[@Enhance]

[*Patch Mods]
;mode=forwarder
package_source './include/patches.ini'

[@Integrate]

[*Install Mods]
;mode=forwarder
package_source './include/install.ini'

Command Headers

Command headers are placed directly under a [Section Title] line, before any commands. They control how the list item is displayed and how it behaves.

Display & Behaviour

Header Description
;mode=<mode> Sets the command mode.
;footer=<TEXT> Pre-defines a default footer label when no saved value exists in config.ini.
;footer_highlight=true/false When true, draws the footer using the highlight color.
;mini=true/false Renders the list item in reduced-height "mini" mode.
;selection_mini=true/false Renders dropdown/option selection items in mini mode.
;hold=true/false Requires the user to hold A for ~3 seconds before executing. Compatible with default, option, and slot modes.
;progress=true/false Shows the in-progress throbber during toggle execution.
;grouping=<VALUE> Controls how file_source results are grouped into section headers. See Grouping Modes.

Conditional Visibility

These headers control whether the list item is rendered at all. They can be combined.

Header Description
;system=erista/mariko Restricts the item to a specific hardware revision.
;state=handheld/docked Only renders the item in the specified console state.
;hos_version=<CONDITION> Only renders when HorizonOS satisfies the condition (e.g. >=18.0.0). Supports >=, <=, >, <.
;ams_version=<CONDITION> Only renders when Atmosphere satisfies the condition. Supports the same operators.

Table Headers

These headers apply only to [Section Title] entries with ;mode=table.

Header Description
;alignment=left/center/right Text alignment within the table.
;background=true/false Draws the table background.
;header_indent=true/false Draws a single header indent on the left side.
;spacing=<INTEGER> Row spacing.
;gap=<INTEGER> Gap after the table (alias for ;end_gap=).
;start_gap=<INTEGER> Gap before the table.
;end_gap=<INTEGER> Gap after the table.
;offset=<INTEGER> Horizontal offset for table content.
;scrollable=true/false Enables scrolling. Must be explicitly set to true to enable.
;top_pivot=true/false Makes the top of the table selectable/focusable.
;bottom_pivot=true/false Makes the bottom of the table selectable/focusable.
;wrapping_mode=<none|char|word> Text wrapping mode for section text.
;wrapping_indent=true/false Draws an indent on wrapped continuation lines.
;polling=true/false When true, placeholder values update approximately once per second.
;section_text_color=<COLOR> Color for section text. Accepts theme color names or hex values.
;info_text_color=<COLOR> Color for info/value text.

Trackbar Headers

These headers apply to trackbar-mode entries.

Header Description
;min_value=<INTEGER> Minimum value.
;max_value=<INTEGER> Maximum value.
;steps=<INTEGER> Number of discrete steps (for step_trackbar).
;units=<STRING> Units label displayed alongside the value (e.g. %, MHz).
;unlocked=true/false Marks the trackbar as unlocked for immediate interaction.
;on_every_tick=true/false Executes commands on every tick rather than only on release.

Boot and Exit Hooks

Per-Package Boot Hook

Place a boot_package.ini file inside your package folder. The [boot] section runs each time the package is opened (can be suppressed per-package by enabling Quick Launch in the package settings).

; /switch/.packages/MyPackage/boot_package.ini
[boot]
try:
path_exists ./initialized.flag
refresh

Per-Package Exit Hook

Place an exit_package.ini file inside your package folder. The [exit] section runs each time the package is closed.

; /switch/.packages/MyPackage/exit_package.ini
[exit]
set-ini-val ./config.ini State last_closed {timestamp(%Y-%m-%d)}

Special Root-Level Packages

Ultrahand recognizes two special packages at the root of /switch/.packages/:

File Behaviour
/switch/.packages/boot_package.ini [on-boot] runs once on system startup. [boot] runs each time the Packages menu is opened, and again after overlay hiding.
/switch/.packages/exit_package.ini [exit] runs each time Ultrahand is fully closed.

The config.ini State File

Ultrahand automatically creates a config.ini file in your package's folder to persist runtime state — toggle on/off states, option footer selections, trackbar values, and custom footers set by set-footer. You do not need to create or manage this file manually.

You can read values from config.ini using the ini_file source function:

[Show Last Setting]
;mode=table
ini_file ./config.ini
'Current Mode'='{ini_file(MySection, mode)}'

Language Translations

Packages can include their own language translation JSON files in a lang/ subfolder. Ultrahand loads the file matching the currently selected overlay language and applies it to all drawn strings. Keys are the original text; values are the translated strings.

/switch/.packages/MyPackage/lang/
├── en.json
├── ja.json
└── zh-hans.json

{
  "Enable Feature": "機能を有効にする",
  "Reboot Now": "今すぐ再起動"
}

This mirrors the language system used by libultrahand overlays.

Complete Example

The following demonstrates a complete, well-structured package:

;title='Example Package'
;display_title='Example '
;version=1.2.0
;creator=YourName
;about='Demonstrates common Ultrahand package patterns.'
;color=#a264fa
;show_widget=true

[@Main]

; === System Info Table (live-polling) ===
[System Info]
;mode=table
;alignment=left
;polling=true
'Atmosphere'='{ams_version}'
'HorizonOS'='{hos_version}'
'IP Address'='{local_ip}'

; === Download and Install (hold-to-confirm) ===
[Install Update]
;hold=true
try:
download https://example.com/mod.zip ./downloads/
unzip ./downloads/mod.zip /
delete ./downloads/mod.zip
notify-now 'Update installed! Reboot to apply.'
try:
!path_exists ./downloads/mod.zip
set-footer Installed ✓

[@Controls]

; === Volume Slider ===
[Volume]
;mode=trackbar
;min_value=0
;max_value=150
;units=%
;on_every_tick=true
volume {value}

; === Auto Brightness Toggle ===
[Auto Brightness]
;mode=toggle?off
on:
backlight auto on
off:
backlight auto off

; === Reboot Options Dropdown ===
[*Reboot To]
;mode=option
list_source '(System, Hekate, UMS)'
try:
path_exists /bootloader/hekate_ipl.ini
reboot {list_source(0)}
notify Rebooting...

; === Named Step Trackbar ===
[Performance Mode]
;mode=named_step_trackbar
list_source '(Eco, Normal, Boost, Turbo)'

For more examples, visit the examples/ directory or browse Ultrahand Packages.

License

This project is licensed and distributed under GPLv2 with CC-BY-4.0 code.

Copyright (c) 2023-2026 ppkantorski

ko-fi sponsor

Notice: Documentation is currently a work-in-progress. For clean examples, look at some of the more well-crafted Ultrahand Packages out there for guidance.

Clone this wiki locally