Proposal: one path for randomizers, restoration mods and co-op (a mod interface in tiers) #2892

Open

opened 2026-11-12 19:01:04 +00:00 by github-sync · 0 comments

github-sync commented

2026-11-12 19:01:04 +00:00

Owner

@mooki000 opened on GitHub · 2026-11-12 18:33 UTC · original

The idea

Players should be able to choose a randomizer seed or restoration mod, then play without finding a separate Hookshot fork.
I would also like multiplayer to be built on 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

hiKareeem added the RomFS loader in #321. Clawshot already uses it and gives each seed its own saves. [1]
hckrman101's draft #2478 adds the Mods tab, mod ordering, merged size tables, build-time ExeFS patches and data cheats. I would build on that, not replace it. [2]
Launcher work is already underway in hckrman101's #2739 and madebyjordan's #2373. timstr97's #1958 covers Linux save profiles. [3]
hckrman101's control bridge already has local access checks and protocol version 1. My #2292 adds sampled state, not a complete history of item grants or checked locations. [4]
My co-op draft #2274 has an internal session-layer interface. It is not a loadable mod interface. itzdaface and I have agreed to combine our co-op work there. [5]
Clawshot's Archipelago proposals #5/#6 are generation-side work. Their external bridge is not supplied there, and hiKareeem has asked to keep the proposed AP contracts outside Clawshot for now. [6]

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 and conflicts before fixing a format.
Companion programs: use the existing local bridge for 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. I would make co-op its first consumer. That adds real work to co-op's schedule, and I think it is worth it.

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

Questions for maintainers

Should this live as a focused interface issue, or as a design thread under #1007/#2478?
Is the first extension best kept to RomFS plus a small chest table, or should we prove bridge item/check operations first?
Should the proposed catalog start as community-maintained recipes, or wait for an official launcher/catalog decision?
For long-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 for co-op is to make it the first module on that interface rather than land #2274 in the core first, accepting the delay. Would you rather have it that way too, or have co-op land in the core now and be extracted later?

What I can offer first

With your agreement, I can test #2478 on Linux with a locally generated Clawshot seed, copied saves and the controller prompts.
I can then bring a small chest-table draft and a written item/check interface for review with hiKareeem and the Archipelago author.
The first test would not establish Archipelago compatibility, native-module support or Windows behavior.

Sources

[1] Hookshot 65a4d874, host/mods.c:1–13; Clawshot 755317b3, src/clawshot/pack/runtime.py:135–163.
[2] #2478 f654ef20, host/mods.c:1–28, host/cheats.c:1–20.
[3] #2739 123e14a6, launcher/README.md:3–23; #2373 5ccc2f16, builder/linux/hookshot_launcher.py:1–15; #1958 61d19af6, builder/linux/profiles.py:1–10.
[4] Hookshot 65a4d874, docs/control.md:30–88; #2292 45310b24, docs/control.md:264–301.
[5] #2274 a4c080e0, host/coop.h:63–137; agreement with itzdaface.
[6] Clawshot #6 3111c69f, docs/archipelago.md:8–34,84–90; hiKareeem's scope decision.

> [@mooki000](https://github.com/mooki000) opened on GitHub · 2026-11-12 18:33 UTC · [original](https://github.com/NotRexed/Hookshot/issues/2892) ## The idea Players should be able to choose a randomizer seed or restoration mod, then play without finding a separate Hookshot fork. I would also like multiplayer to be built on 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 - hiKareeem added the RomFS loader in #321. Clawshot already uses it and gives each seed its own saves. [1] - hckrman101's draft #2478 adds the Mods tab, mod ordering, merged size tables, build-time ExeFS patches and data cheats. I would build on that, not replace it. [2] - Launcher work is already underway in hckrman101's #2739 and madebyjordan's #2373. timstr97's #1958 covers Linux save profiles. [3] - hckrman101's control bridge already has local access checks and protocol version 1. My #2292 adds sampled state, not a complete history of item grants or checked locations. [4] - My co-op draft #2274 has an internal session-layer interface. It is not a loadable mod interface. itzdaface and I have agreed to combine our co-op work there. [5] - Clawshot's Archipelago proposals #5/#6 are generation-side work. Their external bridge is not supplied there, and hiKareeem has asked to keep the proposed AP contracts outside Clawshot for now. [6] ## 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 and conflicts before fixing a format. 3. **Companion programs:** use the existing local bridge for 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. I would make co-op its first consumer. That adds real work to co-op's schedule, and I think it is worth it. These are proposed interfaces, not features I am claiming are finished. A scripting or WebAssembly layer could use the same services later; I would not add a VM first. Hookshot compiles the game's instructions ahead of time. These interfaces would call compiled host services, not patch instructions while the game runs. [1] A checked location and a granted item must remain different events: another player's reward can complete a check without adding anything locally. [6] ## Questions for maintainers 1. Should this live as a focused interface issue, or as a design thread under #1007/#2478? 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 proposed catalog start as **community-maintained recipes**, or wait for an **official launcher/catalog decision**? 4. For long-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 for co-op is to **make it the first module on that interface** rather than land #2274 in the core first, accepting the delay. Would you rather have it that way too, or have co-op **land in the core now and be extracted later**? ## What I can offer first With your agreement, I can test #2478 on Linux with a locally generated Clawshot seed, copied saves and the controller prompts. I can then bring a small chest-table draft and a written item/check interface for review with hiKareeem and the Archipelago author. The first test would not establish Archipelago compatibility, native-module support or Windows behavior. ## Sources [1] Hookshot `65a4d874`, [host/mods.c:1–13](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/65a4d874fd83a2c8fe2e230befb144f1668b900c/host/mods.c#L1-L13); Clawshot `755317b3`, [src/clawshot/pack/runtime.py:135–163](https://github.com/hiKareeem/Clawshot/blob/755317b359baece69be8c20cda60e3d641bb56eb/src/clawshot/pack/runtime.py#L135-L163). [2] #2478 `f654ef20`, [host/mods.c:1–28](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/f654ef20560dddc30a0ab3f11440012be389cb62/host/mods.c#L1-L28), [host/cheats.c:1–20](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/f654ef20560dddc30a0ab3f11440012be389cb62/host/cheats.c#L1-L20). [3] #2739 `123e14a6`, [launcher/README.md:3–23](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/123e14a69bd11904e0c18191bc61aa8d08be229b/launcher/README.md#L3-L23); #2373 `5ccc2f16`, [builder/linux/hookshot_launcher.py:1–15](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/5ccc2f16ea8af4428958f32afd282bca67a7043a/builder/linux/hookshot_launcher.py#L1-L15); #1958 `61d19af6`, [builder/linux/profiles.py:1–10](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/61d19af64de86b8f73735a83ac0bd1a7febcab86/builder/linux/profiles.py#L1-L10). [4] Hookshot `65a4d874`, [docs/control.md:30–88](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/65a4d874fd83a2c8fe2e230befb144f1668b900c/docs/control.md#L30-L88); #2292 `45310b24`, [docs/control.md:264–301](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/45310b247d99f83cbd89ec0c165e703d0bde3c8d/docs/control.md#L264-L301). [5] #2274 `a4c080e0`, [host/coop.h:63–137](https://git.magicbean.dev/MagicBeanDev/Hookshot/src/commit/a4c080e00df180e29624c9c148955d7240fadd43/host/coop.h#L63-L137); [agreement with itzdaface](https://git.magicbean.dev/MagicBeanDev/Hookshot/pulls/2578). [6] Clawshot #6 `3111c69f`, [docs/archipelago.md:8–34,84–90](https://github.com/hiKareeem/Clawshot/blob/3111c69fdbf8eca4f124f08c899bbb3b1a821135/docs/archipelago.md#L8-L34); [hiKareeem's scope decision](https://github.com/hiKareeem/Clawshot/pull/5#issuecomment-6826505214).

github-sync referenced this issue

2026-11-12 19:01:26 +00:00

feat(coop): co-op rooms: a relay, progress sync, and a Co-op tab to make, join and accept #2274

github-sync referenced this issue

2026-11-12 19:01:35 +00:00

feat(mods): a Mods tab, merged resource size tables, ExeFS patches and Atmosphere cheats #2478

Commenting is not possible because the repository is archived.