Pre- and Post App/ROM launch hooks

[Helaas]

Launch Hooks

This has been suggested a few times in the Discord so I thought I would do a more formal pitch.

I'm currently adding a feature the Shortcuts pak that allow X to Resume to work. What this basically does is sync the states to proper location so that the existing NextUI code picks this up.

The idea

Hooks are platform-specific, just like paks. The launcher reads them from:

$USERDATA_PATH/.hooks/
    pre-launch.d/    # scripts run before launch
    post-launch.d/   # scripts run after launch exits

On device, USERDATA_PATH resolves to:

/mnt/SDCARD/.userdata/$PLATFORM

So the actual hook directories on device are:

/mnt/SDCARD/.userdata/<platform>/.hooks/pre-launch.d/
/mnt/SDCARD/.userdata/<platform>/.hooks/post-launch.d/

Example installed hook path:

/mnt/SDCARD/.userdata/tg5040/.hooks/post-launch.d/shortcuts-resume.sh

If these directories don't exist, nothing happens and there is no overhead.

Environment variables

Hook scripts inherit all standard NextUI environment variables (SDCARD_PATH, PLATFORM, USERDATA_PATH, SHARED_USERDATA_PATH, etc.) plus these launch-specific ones:

Variable	Description
HOOK_PHASE	pre or post
HOOK_TYPE	rom or pak
HOOK_CMD	The raw launch command
HOOK_EMU_PATH	Path to the emulator or pak launch.sh
HOOK_ROM_PATH	Path to the ROM file (empty for pak launches)
HOOK_LAST	Contents of /tmp/last.txt (the last selected menu entry)

These can then be used by the underlying Pak to ingest information about the hook that just occurred.

Writing a hook script

A hook script is any executable .sh file in one of the hook directories. Scripts run in alphabetical order.

#!/bin/sh
# my-hook.sh — log every ROM launch

[ "$HOOK_TYPE" = "rom" ] || exit 0
echo "$(date): launched $HOOK_ROM_PATH" >> "$LOGS_PATH/launches.log"

Rules

• Each script runs in a subshell. A crash or non-zero exit will not affect the launcher or other hooks.
• Script output (stdout/stderr) is suppressed. If you need logging, write to your own log file.
• Pre-launch hooks cannot cancel the launch. They are for observation and setup only.
• Keep hooks fast. A slow hook delays the launch or the return to the menu.
• Unlike auto.sh, each pak should manage their own hook and use a descriptive filename to avoid collisions.

Example: sync after ROM exit

#!/bin/sh
# shortcuts-resume.sh — one-shot resume metadata sync after a ROM exits

[ "$HOOK_TYPE" = "rom" ] || exit 0

SHORTCUTS_PAK="$SDCARD_PATH/Tools/$PLATFORM/Shortcuts.pak"
[ -x "$SHORTCUTS_PAK/shortcuts" ] || exit 0

"$SHORTCUTS_PAK/shortcuts" --resume-sync-hook >> "$LOGS_PATH/shortcuts-resume-sync.txt" 2>&1

See also my resume-hook branch within Shortcuts for an example implementation that uses this system.

Other thoughts

• auto.sh could/should probably be refactored to a similar system where a Pak owns it's own launch-on.boot.sh
• this involves changing the /mnt/SDCARD/.system//paks/MinUI.pak/launch.sh for each platform, so the launch.sh for my355 will also need to be adapted when that platform gets officially added.

[frysee]

I was literally about to start on this, great timing!

[frysee]

Some quick thoughts:

• +1 on refactoring auto.sh, I dont think it is used by many paks right now.
• We could also think about pre/post sleep hooks.
• Badly written hooks and their delays will accumulate, code gets copied around. Depending on how we want to interpret the "Pre-launch hooks cannot cancel the launch. They are for observation and setup only." rule, we could think about hooks being backgrounded.

[josegonzalez]

Should probably just handle auto.sh and have that be an init.sh hook (but also still supporting auto.sh for backwards compatibility).

[Helaas]

I've implemented the suggestions and vibed a little demo app:
https://github.com/Helaas/nextui-hooks-examples

I had it generate the documentation based on my changes so that I can at least show off where I'm going with it. The demo pakz is functional but need the updated scripts to function. Open to suggestions.

The hooks themselves are not vibed, but I still need to validate further and do a lot of testing.