An audio quality-of-life mod for Gen1Recomp: the low-HP battle siren beeps a set number of times instead of looping for the rest of the fight.
Works on Red, Blue, Yellow and Gold/Silver (mod api 2). It requests no
permissions and touches no other audio; every knob is a row in
MODS → Gen1SoundQOL → OPTIONS, including VANILLA, which puts the
original behaviour back exactly.
- Download
gen1_sound_qol-<version>.zipfrom Releases. - In the game: MODS → Import mod .zip, pick the file, enable Gen1SoundQOL.
The manifest already carries "github": "wild1walker/Gen1SoundQOL", so the
launcher offers updates and other versions on its own.
Vanilla mirrors the Game Boy exactly: once your Pokémon's HP bar goes red,
audio/low_health_alarm.asm runs the two-tone siren every frame until the
mon heals, faints, or the battle ends. On original hardware that is correct;
over a long battle it is also the single most complained-about sound in the
game.
With this on, the siren plays six beeps when the bar enters the red — about three seconds, long enough to register as a warning — and then goes quiet. It plays again when you take another hit (so a hit still sounds like a hit), and again if you heal out of the red and drop back in.
Set LOW HP BEEP to ONCE for a single beep, raise or lower BEEP COUNT
anywhere from 1 to 8, or pick VANILLA to get the endless siren back.
| Row | Values | Default | What it does |
|---|---|---|---|
LOW HP BEEP |
ONCE / N BEEPS / VANILLA |
N BEEPS |
VANILLA restores the endless loop, byte for byte |
BEEP COUNT |
1–8 |
6 |
how many siren cycles N BEEPS plays (one cycle ≈ half a second) |
BEEP EACH HIT |
on / off | on | beep again each time you lose HP while still in the red |
This is done through the engine's own battle.low_health_alarm hook: the mod
reshapes the on/off toggle and lets the engine start and stop the loop. It
never touches the audio system, and it never changes the engine's internal
wLowHealthAlarm latch — so the alarm's own rules (a running siren rides out
the HP drain, a heal silences it, a KO clears it) are all still the engine's.
0.1.0 shipped a "mute the game when another app is playing audio" feature. It was removed in 0.2.0 because it could not be made to work.
The mod detected background audio from the OS audio-session events
(audiosuspend / audioreset — Android audio-focus loss, iOS
AVAudioSession interruptions). Those fire for phone calls, Siri and
headphone changes, but not when you simply have Music or a podcast
playing and open the game: LÖVE's iOS session uses a mixable category, so
nothing interrupts and no event is ever delivered.
The correct signal does exist — love.system.hasBackgroundMusic(), which
reads secondaryAudioShouldBeSilencedHint on iOS and
AudioManager.isMusicActive() on Android — but a mod cannot reach it:
love.system is blocked in the mod sandbox, and mod.device forwards only
powerInfo(). Making this work is an engine change (forwarding that one call
through mod.device), not a mod change. Rather than ship a feature that
quietly does nothing, it is gone.
Stored bg_mute_* values from 0.1.0 are simply ignored — nothing to migrate,
nothing to clean up.
manifest.json— identity, version, load ordermain.lua— the entry chunk; loads the modules below throughmod:readsrc/options.lua— the option schema and the validating readersrc/alarm.lua— thebattle.low_health_alarmwrappertests/— the headless suite (no ROM needed)
You need a Gen1Recomp checkout.
Put this repo at mods/gen1_sound_qol inside it (a symlink is fine):
git clone https://github.com/wild1walker/Gen1SoundQOL
ln -s "$PWD/Gen1SoundQOL" path/to/gen1recomp/mods/gen1_sound_qolThen, from the engine root:
python3 tools/modkit.py validate gen1_sound_qol # manifest + real merge
python3 tools/modkit.py lint gen1_sound_qol # no ROM-derived content
python3 tools/modkit.py gen2check mods/gen1_sound_qol
luajit mods/gen1_sound_qol/tests/gen1_sound_qol_test.luaThe suite is ROM-free: it merges into the engine's fixture dataset, so it
runs anywhere the engine checks out. .github/workflows/ci.yml runs exactly
those four commands on every push and pull request.
For the 10-minute loop, run the engine with POKEPORT_DEV=1 love . and press
F5 to hot-reload after an edit.
Releases are cut by CI. To ship a version:
- Bump
versioninmanifest.json. - Add the matching
## <version>section toCHANGELOG.md(CI fails if the two disagree). - Merge to
main.
.github/workflows/release.yml then runs CI, resolves the version, packs
every mod file into gen1_sound_qol-<version>.zip with manifest.json at
the archive root, and publishes a GitHub Release with the zip and a
sha256sums.txt. Version resolution, first rule that applies:
- the
versioninput of a manual Run workflow, [release X.Y.Z]anywhere in the commit message,manifest.json's own version, when it is ahead of every existing tag.
If none of the three apply — a push that changes code or artwork but not the version — the run stops after CI and publishes nothing, noting so in the run summary. A release is always a deliberate version bump.
Whichever rule wins is written into the manifest.json inside the archive, so
a shipped mod never reports a different version than the release it came from.
An existing tag or release is never clobbered — the run fails instead.
By Wild.
Built on the battle.low_health_alarm seam of Pokemon Gen1Recomp, and on the pret
disassembly of Pokemon Red, Blue and Yellow: audio/low_health_alarm.asm is the
vanilla siren, and the ONCE mode is measured against it byte for byte.
MIT. See LICENSE.

