Idea: one path for randomizers, restoration mods and co-op, with a mod interface in tiers #42

New issue

Open

opened 2026-11-12 23:57:07 +00:00 by mooki · 1 comment

mooki commented

2026-11-12 23:57:07 +00:00

The idea

Players should be able to choose a randomizer seed or restoration mod, then play without finding a separate Longshot fork. I would also like multiplayer to use that same mod system as its first module, rather than land as a special case in the core, and I accept that this delays it.

What exists on Longshot

The inherited RomFS loader loads file-replacement mods, orders competing paths by name, and works with the button-prompt resource-size-table merge. It explicitly leaves ExeFS patches out. Clawshot used this file-mod route on Hookshot; that is not a claim that the renamed Longshot/Clawshot combination has been tested here.
The earlier Mods-tab proposal covered ordering, merged size tables, build-time ExeFS patches and data cheats. It has not appeared as a Longshot pull request in the current inventory. I would build on a port of that work, not start a competing loader or assume its features are on main.
The launcher now has its own repository and open implementation PR, replacing the closed in-tree proposal. It includes save copying/import/export, but its README still lists separate profiles as planned. Longshot's merged save-import PR already supplies command-line copying from Hookshot and emulators. Neither settles mod discovery, per-seed profiles or a module interface.
The local control bridge has local-user access checks and protocol version 1. Its state/map events are not a complete history of checked locations or successful item grants. My sampled-state proposal is not such a history either.
My earlier co-op draft has an internal session interface, not a loadable mod interface. itzdaface and I agreed to combine our co-op work there; this proposal is the additional interface work it would need before becoming a module.
Clawshot's placement hook and optional multiworld patch steps remain generation-side proposals, not a Longshot runtime bridge. Following hiKareeem's review, their AP CLI, slot format and synchronization contract have moved out to the world repository. We should agree our side with those authors rather than promise Archipelago compatibility now.

Proposed tiers

Files and recipes: keep RomFS mods working. A community index could point to recipes that build from the player's own dump, never host generated game files.
Small data tables: let a mod describe supported changes, starting with chest rewards and their displayed models. Agree progression, save ownership and conflicts before fixing a format.
Companion programs: extend the existing local bridge with checked locations, successful grants and safe incoming grants. A tracker or multiworld client should not need raw memory writes.
Trusted native modules, later: a small versioned C interface with named hooks, explicit ownership and restart-required loading. Co-op would be its first consumer. Native modules are trusted code, not a sandbox for unknown downloads.

These are proposed interfaces, not finished features. A scripting or WebAssembly layer could use the same services later; I would not add a VM first. Longshot compiles the game's instructions ahead of time: the interfaces would call compiled host services, not patch instructions while the game runs. A checked location and a granted item must remain different events, because another player's reward can complete a check without adding anything locally.

Anything else

Questions for the maintainers:

Should this remain a focused interface issue, or be discussed with the next Longshot port of the Mods-tab work?
Is the first extension best kept to RomFS plus a small chest table, or should we prove bridge item/check operations first?
Should the catalog start as community-maintained recipes, or wait for an official launcher/catalog decision in LongshotLauncher?
For longer-term code mods, should we explore trusted native modules, prefer companions only, or defer that decision until the shared item service is proven?
My preference is to make co-op the first module, accepting the delay. Would you rather have it that way too, or have co-op land in the core first and be extracted later?

With your agreement, I can test the existing RomFS path on Linux with a locally generated Clawshot seed, copied saves and controller prompts, then test the expanded Mods work when its Longshot port is available. I can bring a small chest-table draft and a written item/check interface for review with hiKareeem and the Archipelago author; the two questions to Clawshot are still open. Those tests would not establish native-module support, Archipelago compatibility or Windows behavior.

Moved from NotRexed/Hookshot#2892.

### The idea Players should be able to choose a randomizer seed or restoration mod, then play without finding a separate Longshot fork. I would also like multiplayer to use that same mod system as **its first module**, rather than land as a special case in the core, and I accept that this delays it. #### What exists on Longshot - The inherited [RomFS loader](https://git.magicbean.dev/MagicBeanDev/Longshot/src/commit/d4a69456c9de5131589af1fcf9a09adba4c403d1/host/mods.c) loads file-replacement mods, orders competing paths by name, and works with the button-prompt resource-size-table merge. It explicitly leaves ExeFS patches out. Clawshot used this file-mod route on Hookshot; that is not a claim that the renamed Longshot/Clawshot combination has been tested here. - The earlier Mods-tab proposal covered ordering, merged size tables, build-time ExeFS patches and data cheats. It has not appeared as a Longshot pull request in the current inventory. I would build on a port of that work, not start a competing loader or assume its features are on main. - The launcher now has [its own repository and open implementation PR](https://git.magicbean.dev/MagicBeanDev/LongshotLauncher/pulls/1), replacing [the closed in-tree proposal](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/12). It includes save copying/import/export, but its README still lists separate profiles as planned. Longshot's [merged save-import PR](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/20) already supplies command-line copying from Hookshot and emulators. Neither settles mod discovery, per-seed profiles or a module interface. - The [local control bridge](https://git.magicbean.dev/MagicBeanDev/Longshot/src/commit/d4a69456c9de5131589af1fcf9a09adba4c403d1/docs/control.md) has local-user access checks and protocol version 1. Its state/map events are not a complete history of checked locations or successful item grants. My [sampled-state proposal](https://github.com/NotRexed/Hookshot/issues/2292) is not such a history either. - My [earlier co-op draft](https://github.com/NotRexed/Hookshot/issues/2274) has an internal session interface, not a loadable mod interface. itzdaface and I agreed to combine our co-op work there; this proposal is the additional interface work it would need before becoming a module. - Clawshot's [placement hook](https://github.com/hiKareeem/Clawshot/pull/5) and [optional multiworld patch steps](https://github.com/hiKareeem/Clawshot/pull/6) remain generation-side proposals, not a Longshot runtime bridge. Following hiKareeem's review, their AP CLI, slot format and synchronization contract have moved out to the world repository. We should agree our side with those authors rather than promise Archipelago compatibility now. #### Proposed tiers 1. **Files and recipes:** keep RomFS mods working. A community index could point to recipes that build from the player's own dump, never host generated game files. 2. **Small data tables:** let a mod describe supported changes, starting with chest rewards and their displayed models. Agree progression, save ownership and conflicts before fixing a format. 3. **Companion programs:** extend the existing local bridge with checked locations, successful grants and safe incoming grants. A tracker or multiworld client should not need raw memory writes. 4. **Trusted native modules, later:** a small versioned C interface with named hooks, explicit ownership and restart-required loading. Co-op would be its first consumer. Native modules are trusted code, not a sandbox for unknown downloads. These are proposed interfaces, not finished features. A scripting or WebAssembly layer could use the same services later; I would not add a VM first. Longshot compiles the game's instructions ahead of time: the interfaces would call compiled host services, not patch instructions while the game runs. A checked location and a granted item must remain different events, because another player's reward can complete a check without adding anything locally. ### Anything else Questions for the maintainers: 1. Should this remain a focused interface issue, or be discussed with the next Longshot port of the Mods-tab work? 2. Is the first extension best kept to **RomFS plus a small chest table**, or should we prove **bridge item/check operations** first? 3. Should the catalog start as **community-maintained recipes**, or wait for an **official launcher/catalog decision** in LongshotLauncher? 4. For longer-term code mods, should we explore **trusted native modules**, prefer **companions only**, or defer that decision until the shared item service is proven? 5. My preference is to **make co-op the first module**, accepting the delay. Would you rather have it that way too, or have co-op **land in the core first and be extracted later**? With your agreement, I can test the existing RomFS path on Linux with a locally generated Clawshot seed, copied saves and controller prompts, then test the expanded Mods work when its Longshot port is available. I can bring a small chest-table draft and a written item/check interface for review with hiKareeem and the Archipelago author; [the two questions to Clawshot](https://github.com/hiKareeem/Clawshot/issues/17) are still open. Those tests would not establish native-module support, Archipelago compatibility or Windows behavior. --- Moved from NotRexed/Hookshot#2892.

👍 1

mooki referenced this issue

2026-11-13 01:32:08 +00:00

WIP: feat(coop): add relay rooms, accepted progress sync and a Co-op tab #68

mooki referenced this issue

2026-11-13 02:30:20 +00:00

WIP: test(mods): exercise the documented RomFS file contract #93

mooki commented

2026-11-13 02:30:29 +00:00

Author

There is a small part we can do without deciding the later interfaces: document the RomFS loader we already have and exercise an authored example through it. That is now pull request 93 (work in progress), without a new manifest, loader or runtime behavior. The example checks full-path ordering, nested discovery, disabling and restart, both mod-root choices and ignored ExeFS content. It uses invented text only, not a game dump or seed. The command is python -I -B tests/test_mods_size_table.py; the expanded test also passes against main's loader.

One distinction matters for the next step: pull request 51, head d5b2ff117, supplies the shared menu text editor (text_edit, MkwVkHost.take_text), not the older Mods-tab proposal. Pull request 68, head cca2aebb, uses that editor and implements co-op in the core. Its coop_on_event and coop_on_message are internal session hooks, not a loadable-module interface. It has progress-schema checks and save-backup/acceptance gates, but no public checked-location or successful-grant service.

The remaining choices are still open:

Question in this issue	Options	What each would cost
1. Focused interface issue or the next Mods-tab port?	Keep interface decisions here and let a Mods-tab port use them; or review them together with that port.	Separate work can document existing behavior now, but needs one agreed owner for any later manifest. Combining them delays interface review until a port exists and makes the first review larger. Neither 51 nor 68 supplies that Mods tab.
2. Chest table first or bridge operations first?	Prove a small reward/model table; or define checked-location, successful-grant and incoming-grant operations first.	The table needs agreed progression rules, save ownership and conflict handling before a format. The bridge needs stable identifiers, separate check/grant outcomes, replay/reconnect rules and safe game-thread application. Co-op's current state merge is useful evidence, not a substitute for these event semantics.
3. Community recipes or an official catalog?	Start with links to reviewed recipes that build from a player's own dump; or wait for a launcher/catalog design.	A recipe index needs moderation, provenance and compatibility expectations. An official catalog also needs launcher ownership, install/update behavior and profile isolation. The new signed builder releases do not establish trust or compatibility for mods.
4. Trusted native modules, companions only, or defer?	A small versioned C interface with restart-required loading; companion-only services; or defer native loading until the item/check service works.	Native loading adds a trusted-code boundary, ABI/version refusal, hook/thread/ownership rules and Windows/Linux packaging. Companions need bridge services and cannot simply reuse in-process co-op callbacks. Deferring avoids an early ABI promise, but delays the module route.
5. Co-op as the first module or core first?	Keep 68 WIP and extract it onto an agreed interface; or review its core implementation first and extract later.	Module-first proves a real consumer but delays co-op and requires interface/extraction work. Core-first can reuse more of 68 now, but accepts the socket/library/save integration in the core and commits to a later extraction. The author's preference here remains module-first.

My recommendation is to keep the independent RomFS example small, then agree question 2 and the save/identity rules with the Clawshot and Archipelago authors before fixing a new format. Nothing in the example chooses a catalog, claims Archipelago compatibility or changes the module-first preference.

No game run is claimed. The example is a filesystem test and cannot show chest rewards or controller prompts in play. A separate real-mod proof would use a locally generated Clawshot seed and disposable copied saves: a bounded five-minute start, seed load, known changed reward and prompt inspection, then a one-minute restart with the mod disabled. That would show only the file route on that build and platform, not the later tiers.

There is a small part we can do without deciding the later interfaces: document the RomFS loader we already have and exercise an authored example through it. That is now [pull request 93](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/93) (work in progress), without a new manifest, loader or runtime behavior. The example checks full-path ordering, nested discovery, disabling and restart, both mod-root choices and ignored ExeFS content. It uses invented text only, not a game dump or seed. The command is `python -I -B tests/test_mods_size_table.py`; the expanded test also passes against main's loader. One distinction matters for the next step: [pull request 51](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/51), head `d5b2ff117`, supplies the shared menu text editor (`text_edit`, `MkwVkHost.take_text`), not the older Mods-tab proposal. [Pull request 68](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/68), head `cca2aebb`, uses that editor and implements co-op in the core. Its `coop_on_event` and `coop_on_message` are internal session hooks, not a loadable-module interface. It has progress-schema checks and save-backup/acceptance gates, but no public checked-location or successful-grant service. The remaining choices are still open: | Question in this issue | Options | What each would cost | |---|---|---| | 1. Focused interface issue or the next Mods-tab port? | Keep interface decisions here and let a Mods-tab port use them; or review them together with that port. | Separate work can document existing behavior now, but needs one agreed owner for any later manifest. Combining them delays interface review until a port exists and makes the first review larger. Neither 51 nor 68 supplies that Mods tab. | | 2. Chest table first or bridge operations first? | Prove a small reward/model table; or define checked-location, successful-grant and incoming-grant operations first. | The table needs agreed progression rules, save ownership and conflict handling before a format. The bridge needs stable identifiers, separate check/grant outcomes, replay/reconnect rules and safe game-thread application. Co-op's current state merge is useful evidence, not a substitute for these event semantics. | | 3. Community recipes or an official catalog? | Start with links to reviewed recipes that build from a player's own dump; or wait for a launcher/catalog design. | A recipe index needs moderation, provenance and compatibility expectations. An official catalog also needs launcher ownership, install/update behavior and profile isolation. The new signed builder releases do not establish trust or compatibility for mods. | | 4. Trusted native modules, companions only, or defer? | A small versioned C interface with restart-required loading; companion-only services; or defer native loading until the item/check service works. | Native loading adds a trusted-code boundary, ABI/version refusal, hook/thread/ownership rules and Windows/Linux packaging. Companions need bridge services and cannot simply reuse in-process co-op callbacks. Deferring avoids an early ABI promise, but delays the module route. | | 5. Co-op as the first module or core first? | Keep 68 WIP and extract it onto an agreed interface; or review its core implementation first and extract later. | Module-first proves a real consumer but delays co-op and requires interface/extraction work. Core-first can reuse more of 68 now, but accepts the socket/library/save integration in the core and commits to a later extraction. The author's preference here remains module-first. | My recommendation is to keep the independent RomFS example small, then agree question 2 and the save/identity rules with the Clawshot and Archipelago authors before fixing a new format. Nothing in the example chooses a catalog, claims Archipelago compatibility or changes the module-first preference. No game run is claimed. The example is a filesystem test and cannot show chest rewards or controller prompts in play. A separate real-mod proof would use a locally generated Clawshot seed and disposable copied saves: a bounded five-minute start, seed load, known changed reward and prompt inspection, then a one-minute restart with the mod disabled. That would show only the file route on that build and platform, not the later tiers.