Merge the updated stack base (with origin/main) into fix/server-end-gateways

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-23 01:57:17 +02:00
42 changed files with 4864 additions and 239 deletions
+108 -30
View File
@@ -1,25 +1,69 @@
# The launcher's mod browser
Search Modrinth (and CurseForge, once the launcher has a key) for packs Horizon loads, see how well each one runs,
and install it with its checksum checked. This is item 16 of the roadmap and issue #577. The code is in
Search Modrinth (CurseForge support is coming soon) for Java mods, modpacks, resource packs and shader
packs, see how well each one runs before installing it, and install it with its checksum checked. This is item 16 of the roadmap and issue #577. The code is in
`launcher/src/browser.rs` and `launcher/src/browser/`.
## What it offers
Only what Horizon actually loads is offered. Java mod jars (Fabric, NeoForge, Forge) don't run in Horizon
([mods.md](mods.md), [research/java-mod-compat.md](research/java-mod-compat.md)), so they are never searched.
Horizon `.hmod` mods aren't on Modrinth or CurseForge yet (Modrinth has no `horizon` loader).
Horizon doesn't run Java code ([research/java-mod-compat.md](research/java-mod-compat.md)). It ports what a Java mod
carries as data (blocks, items, recipes, loot tables, tags, worldgen, textures, names) with `horizon-port-pack`, and
says before install which of the mod's features that leaves out. Horizon `.hmod` mods aren't on Modrinth or CurseForge
yet (Modrinth has no `horizon` loader).
| Kind | Goes to | How well it runs |
|---|---|---|
| Java mods (Fabric, NeoForge, Forge, Quilt) | ported into `horizon-mods/<mod id>/` and turned on | Checked from its jar before install: **Works**, **Partly** or **Doesn't run** ([below](#java-mods)) |
| Resource packs | `resourcepacks/` beside `options.txt` | **Works** when made for 26.3 ([resource-packs.md](resource-packs.md) lists what Horizon reads). Older packs are **Partly**: they load with vanilla's compatibility warning |
| Shader packs (Iris, OptiFine) | `shaderpacks/` | **Partly**: translated to WGSL, the full-screen passes draw and the world and shadow passes don't yet ([shader-packs.md](shader-packs.md)). Packs for other loaders (Canvas, core-shader packs) **don't run** and can't be installed |
| Modpacks (`.mrpack`, CurseForge zip) | the Modpacks page's import | **Partly**: Horizon runs the mods it can port, from the player's own downloads ([modpacks.md](modpacks.md)) |
By default a search shows only what runs: resource packs made for 26.3, shader packs for Iris or OptiFine, and every
modpack. **Show everything** lists the rest of the kind too, each marked with how well it runs; what doesn't run is
By default a search shows only what runs: Java mods made for 26.3, resource packs made for 26.3, shader packs for Iris
or OptiFine, and every modpack. **Show everything** lists the rest of the kind too, each marked with how well it runs; what doesn't run is
never offered for install.
## Java mods
Before a mod is offered for install, the launcher reads its jar. For each result it picks the version it would
install (the newest for 26.3; with **Show everything**, else the newest for 1.21 or later, the versions port-pack
upgrades from), downloads that file with the checks below, and runs `horizon-port-pack check` on it
([modpacks.md](modpacks.md#the-pipeline-horizon-port-pack)): the jar is carried over into a folder content mod and its
class files are read, not run, for what the carry can't take. Two checks run at once; the row says **Checking** until
its answer comes.
- **Works**: content only. Its blocks, items, recipes, loot, tags and worldgen port, and its code only registers
them. Blocks take the closest vanilla block's shape, hardness and sounds (a block's numbers live in Java code; the
NeoForge oracle that reads them for modpacks is a developer tool).
- **Partly**: the content ports; the row lists what doesn't: blocks with no vanilla block to copy, recipes of the
mod's own types, block entities (machines, containers), menus, mobs and entities, blocks and items with behaviour
of their own, worldgen written in Java, Mixins, the game events it reacts to.
- **Doesn't run**: nothing to port (performance mods, libraries, everything in code), a jar made for 1.20 or older,
or a mod id with characters Horizon mods can't use (`fabric-api`). Never offered for install.
The answer is kept in `mod-browser/checks-1/<checksum>/` under the game folder, with the carry when something
ports; the jar itself isn't kept. A file is checked once. On ten 26.3 jars a check took 0.2 to 3 s (24 s for an
18 MB jar with 9,360 recipes).
**Install** copies the carry into `horizon-mods/<mod id>/`, turns it on in `horizon-mods.txt` (the game's Options >
Mods lists it) and records it in `mod-browser.json` with its verdict and what didn't port, which the Installed list
shows. Its required mods that port are installed with it; one with nothing to port (a library such as Cloth Config
or GeckoLib) is listed as not ported. A mod that shares its id or a namespace with an installed one is refused. The
game reads mod content when it starts: start it again after installing. **Remove** deletes the folder and turns it
off.
### End-to-end check
`tools/mod_browser_harness.py [--mod SLUG] [--query TEXT] [--keep]` runs the whole path a player takes, in a scratch
game folder: the launcher's `mods search --kind mod`, `mods check` and `mods install` (Modrinth), then the game
opens a survival world with the mod offscreen (horizon-ctl), places one of its blocks, and crafts one of its recipes
from vanilla ingredients on a crafting table and takes the result. It times the world's load with and without the
mod and prints a JSON summary; it exits 1 when a step fails. It needs the launcher, the game and horizon-ctl built
and the prepared 26.3 resources in `.local`.
On the Mac mini (M4 Pro, offscreen) with Macaw's Fences and Walls (the default): check 4.0 s, install 3.1 s, world
load 5.4 s without mods and 7.3 s with it (resources 1.1 s and 2.6 s: the mod content folder is built on the first
start); the hedge places and its recipe crafts 4.
## Checks on every download
- The file must come from Modrinth's or CurseForge's file servers (`cdn.modrinth.com`, `edge.forgecdn.net`,
@@ -32,13 +76,49 @@ never offered for install.
## The Mods page
The launcher's **Mods** page has the three kinds as tabs, a search field (Enter searches), **Show everything** and,
once CurseForge is set up, a Modrinth / CurseForge switch. Each result is an index row: its summary, author,
The launcher's **Mods** page has the four kinds as tabs (Mods, Modpacks, Resource packs, Shader packs), a search field (Enter searches), **Show everything** and
the source: Modrinth, with **CurseForge (coming soon)** beside it, disabled. Each result is an index row: its summary, author,
downloads, source and licence, how well it runs (and why), **Page** (the project's page on its source) and
**Install** (**Import** for a modpack). Installed packs are listed above the results with their version, source,
**Install** (**Import** for a modpack). The Modpacks tab lists the imported packs first, with their coverage
report, **Port** and **Play** ([modpacks.md](modpacks.md)). Installed packs are listed above the results with their version, source,
file and the checksum they were checked against, with **Update to …** when a newer version runs and **Remove**
(asked twice).
### Project pages, filters and icons
A result's title opens its page inside the launcher, not in a web browser: its icon, authors, downloads, followers,
last update, licence and source, how well it runs (for a Java mod, what ports and what doesn't, from its check) with
**Install** or **Import**, the project's links (its page on the source, source code, issues, wiki, Discord,
donations; `https://` only, opened in the system browser), then three tabs: **Description** (the project's Markdown,
drawn by the launcher's renderer), **Gallery** and **Versions** (each version's date, loaders, game versions, file
and size, and the verdict of any version already checked). The data is `browser::details` (`Source::details`; on
Modrinth `GET /project/{id}` and `/project/{id}/members`, then `/project/{id}/version`).
**Filters** sit above the results: the order (best match, relevance, downloads, follows, newest, updated) and, under
**Filters**, the loader, game version, environment (client, server) and categories, with the values the source lists
for the kind (Modrinth's `/tag/category`, `/tag/loader`, `/tag/game_version`, asked once per run). A loader or version
picked replaces the default (Java mod loaders and 26.3 for mods); a version other than 26.3 checks and installs the
newest file for 1.21 or later, as **Show everything** does. Changing tabs clears the filters. CurseForge support
is coming soon; its source already maps the order and the game version.
**Icons and gallery images** are the projects' own, fetched at run time from the source's image server
(`browser::images`): HTTPS from `cdn.modrinth.com` (or CurseForge's `media.forgecdn.net` / `edge.forgecdn.net`) only,
at most 8 MB each, decoded (PNG, JPEG, WebP, GIF, at most 8192 pixels a side), scaled (icons 128 px, gallery 960 px)
and kept as PNGs in `mod-browser/images/` under the game folder, which is kept under 128 MB by dropping the oldest
files. A plate with the project's initial stands in until the icon arrives. Nothing of a project's art is in the
launcher or the repository.
**Vanilla Minecraft** is marked with a grass block drawn at run time from the player's own prepared game files
(`assets/minecraft/textures/block/grass_block_*.png`, tinted with the plains grass colour): the game-version filter
shows it. No Mojang file or logo is in the launcher or the repository.
**Source logos.** Modrinth's logo is not shown: Modrinth's own repository says its branding is all rights reserved and
"the use of Modrinth branding elements, including but not limited to the wrench-in-labyrinth logo, ... is strictly
prohibited without explicit written permission from Rinth, Inc." (`packages/assets/COPYING.md` in
[modrinth/code](https://github.com/modrinth/code/blob/main/packages/assets/COPYING.md)), and its
[terms](https://modrinth.com/legal/terms) ask for prior written permission to use its marks. Results name their source
in text ("from Modrinth") until Rinth, Inc. agrees. CurseForge support, and so its logo, is coming soon.
## Installing, updating, removing
`mod-browser.json` beside `options.txt` lists every file the browser installed: its source, project, version, file
@@ -51,14 +131,20 @@ same name the player put there is never overwritten.
Packs, as in vanilla and Iris.
- **Update** installs the newer version and removes the old file.
- **Remove** deletes the file and its entry. Packs installed as dependencies stay.
- **A modpack** is downloaded (checked the same way) into `ports/downloads/` and imported on the Modpacks page,
which says what of it Horizon runs and ports it.
- **A modpack** is downloaded (checked the same way) into `ports/downloads/`, imported, and ported straight away
for the selected version when it is prepared (`modpacks::import_and_port`): the jars of the mods Horizon can carry
over come from the pack's links or Modrinth, and the message says how many of its files play. **Play** on the
Modpacks tab starts it with every ported mod on together. A ported mod that owns a namespace an earlier one owns
(the game would refuse it) is left off before the game starts and listed under the pack ("Left off: ..."); the
coverage list says why each mod that didn't port didn't. A port that fails leaves the pack imported, with **Port**
to try again. Measured on three packs in [modpacks.md](modpacks.md#three-packs-through-the-mod-browser-measured).
From a terminal (or an agent):
```sh
horizon-launcher mods search faithful # --kind resource|shader|modpack, --everything, --source
horizon-launcher mods install faithful-32x # id or slug; a modpack is imported
horizon-launcher mods search faithful # --kind mod|modpack|resource|shader, --everything, --source
horizon-launcher mods check macaws-fences-and-walls # a Java mod's verdict, what ports and what doesn't (--json)
horizon-launcher mods install faithful-32x # id or slug; a Java mod is ported, a modpack imported and ported
horizon-launcher mods list # --json
horizon-launcher mods update [faithful-32x] [--check]
horizon-launcher mods remove faithful-32x
@@ -69,21 +155,13 @@ horizon-launcher mods remove faithful-32x
**Modrinth.** The public API (`api.modrinth.com/v2`) needs no key. The launcher names itself in its user agent, as
Modrinth asks.
### CurseForge
### CurseForge (coming soon)
CurseForge's API (`api.curseforge.com/v1`) needs an API key from its developer console. Ludovic approved CurseForge
for the browser on 2026-10-21; the key is his (agents never sign up for him). Until a key exists the CurseForge source
is off and the browser searches Modrinth only.
CurseForge support is coming soon. Its API (`api.curseforge.com/v1`) needs a paid key, so for now the launcher
doesn't use it: the Mods page shows **CurseForge (coming soon)** beside the Modrinth switch, disabled, and no search
or install goes to CurseForge (`browser::sources()` is Modrinth only; `horizon-launcher mods ... --source curseforge`
says it is coming soon). The CurseForge source (`browser/curseforge.rs`) is kept for when it comes.
To turn it on:
1. Ludovic gets a key at <https://console.curseforge.com/> (sign in, API keys). CurseForge's terms for a launcher
that ships the key apply: the key is built into the binary, so anyone with the binary can read it.
2. He stores it in the 1Password **Agents** vault as an item `CurseForge API`, field `credential`.
3. It goes into the repository secret `HORIZON_CURSEFORGE_API_KEY`
(`~/fleet/op read "op://Agents/CurseForge API/credential" | gh secret set HORIZON_CURSEFORGE_API_KEY`).
The launcher workflow passes it to the build, which builds it in (`option_env!`).
At run time `HORIZON_CURSEFORGE_API_KEY` in the environment overrides the built-in key; empty means none. A file
whose author allows downloads from CurseForge's own site only (no `downloadUrl` in the API) is shown but can't be
installed.
A CurseForge modpack zip or instance the player already has still imports, since that needs no key: its jars come
from the player's installed instance or, when Modrinth has the same file, from Modrinth. A jar only CurseForge serves
is listed under the pack as "CurseForge downloads coming soon".
+49 -4
View File
@@ -240,6 +240,10 @@ How the game loads them, without touching vanilla's path:
when its Java original ships them so (`namespaces = ["kaisyn", "towns_and_towers"]` for Towns
and Towers, mod id `t_and_t`; docs/mods.md). No namespace has two owners: a mod whose id or
listed namespace another mod that is on already owns is left out, with both named in the log.
`horizon-port-pack` avoids that inside a pack: a namespace two carried mods both claim (YUNG's
structure mods all ship files under `yungsapi`, the namespace of YUNG's API, whose own jar isn't
carried) is left to none of them, and its files stay outside. The launcher applies the game's
rule before it starts a pack (`pipeline::loadable`) and lists what it left off.
- The overlay is built on the first start with a set of mods and kept for later starts. A stamp
(`horizon-mod-content.stamp`) hashes the game executable, the base tables and every mod file's
size and mtime. Adding, removing or editing a mod, or a new build of Horizon, rebuilds it. For
@@ -302,12 +306,28 @@ cargo run -p horizon-port-pack -- report ~/.horizon/ports/pack # coverage
cargo run -p horizon-port-pack -- port ~/Downloads/pack.zip ~/.horizon/ports/pack [--from <folder>] [--resources <root>]
```
`check <jar> <out>` takes one mod jar on its own, as the launcher's mod browser installs it
([mod-browser.md](mod-browser.md)): it carries the jar into `<out>/carry/` and reads its class
files (constant pool, superclass, declared methods; no decompiling) for what the carry can't
take, then writes the verdict to `<out>/check.json`. **Works**: content only, and the code just
registers it. **Partly**: the content ports, and the code features listed don't (block entities,
menus, entities, blocks and items with behaviour of their own, recipe types, Mixins, game events).
**Doesn't run**: nothing to port, or a jar made for 1.20 or older. Each mod class is followed up to
the first game class it extends; a block subclass that only overrides how it looks or is placed
(`getStateForPlacement`, `rotate`...) is registration. Game classes are read by Mojang's names
(26.1 and later, and NeoForge since 1.20.5); older Fabric jars name them in intermediary, so a
class extending one counts as code that can't be read. On ten 26.3 jars (2026-10-22): Macaw's
Fences, Windows and Furniture, Ecologics, Compressed Blocks, More Decorative Blocks and Moog's
Nether Structures are Partly; Sodium and GeckoLib don't run (Mixins, renderers, nothing to port);
Fabric API doesn't run (its id has a dash, which content mods can't use). A check takes 0.2 s to
3 s, and 24 s for Compressed Blocks (18 MB, 9,360 recipes, writing the carry dominates).
`fetch` gets each jar the player's way, never from us: copied from a folder they have (matched
by SHA-1, or through a CurseForge app instance's `minecraftinstance.json`), else downloaded from
the link the pack itself gives (a `.mrpack`'s, on the format's hosts only) or, for a CurseForge
pack, the same file on Modrinth's public CDN, found by its SHA-1. A jar is kept only when its
hash matches. A file only CurseForge has is listed as needing a CurseForge API key (Ludovic's
decision; open question below), with the player's installed instance as the way round it.
hash matches. A file only CurseForge has is listed as "CurseForge downloads coming soon" (its API
needs a paid key; Ludovic, 2026-10-22), with the player's installed instance as the way round it.
`<work>/fetch.json` says what happened to each file. On All the Mods 10 8.3's CurseForge zip
(2026-10-17): of the 54 data-tier content mods, 42 come from Modrinth's CDN (84 MB) and 12 need
the key or the instance; `port` then carries the 42 over (0 ported, 42 partial: the harness is a
@@ -1031,10 +1051,35 @@ What is missing, ranked by how much a player notices:
6. **Smaller gaps:** Mo' Structures' mixin that keeps lakes out of its structures and its two
block-ageing processors, and the 5 missing block models.
### Three packs through the mod browser, measured
2026-10-22, Mac mini M4 Pro (offscreen, a debug launcher, release-profile `horizon-port-pack` and game), while
other sessions kept the CPU at 85 to 93 %, so times are upper bounds. The two Modrinth packs were imported with
`horizon-launcher mods install <slug>` (the browser's Import), ATM10 from its CurseForge zip with `modpack import`
(CurseForge support is coming soon), then each ported with `--resources` for 26.3 and opened as a survival
world with every ported mod on (horizon-ctl `launch --dev-mod ...`, from a scratch script).
| Pack | Files | Import | Port | Ported mods | Coverage | Declared | World load (resources) | Crashes |
|---|---|---|---|---|---|---|---|---|
| Vanilla Perfected 26.3 (Fabric, small) | 108 | 30.4 s | 1.0 s | 2 | 2 partial, 79 not yet, 27 not needed | 0 blocks (a trail effect, a torch-flower texture) | 5.2 s (2.1 s) | none |
| Slimes Adventure 1.13.4 (Fabric 1.21.1, medium) | 105 | 18.8 s | 22.8 s | 20 | 20 partial, 46 not yet, 39 not needed | 8,208 blocks, 41 items, 1,376 recipes | 23.0 s (15.0 s) | none |
| All the Mods 10 8.3 (NeoForge 1.21.1, CurseForge zip) | 496 | 3.1 s | 29.4 s | 42 | 42 partial, 333 not yet, 121 not needed | 10,000 blocks, 1,273 items, 4,178 recipes | 38.3 s (28.7 s) | none |
The same world with no mods loads in 5.4 s (resources 1.1 s). Import is the pack download and Modrinth's answers by
file hash; Vanilla Perfected's 30 s is mostly its 108 lookups and its download. Port is the jars (downloaded for the
two Modrinth packs; ATM10's 42 copied from a folder, 12 more are on CurseForge only: CurseForge downloads coming soon) and the carry,
which writes tens of thousands of small files. World load grows with the blocks the pack declares: ATM10 adds
about 155,000 block states, and loading their models and textures is most of its 28.7 s.
Every world loaded and stayed up, with no panic and no error in the log. Before the namespace fix above, Slimes
Adventure lost three of YUNG's mods at start ("both use the namespace yungsapi"); after it all 20 load. As a share of
the mods that need porting (not counting performance mods and libraries), 2 of 81 ported partly, 20 of 66 and 42 of
375. Every ported mod is Partial: their Java code (block entities, entities, Mixins) doesn't come along.
## Open questions for Ludovic
- Contacting authors of permissively licensed mods to publish ports (none contacted).
- Whether players should run code-port agents themselves (their own Claude Code or Codex
login, as Zenith does) or only download published ports.
- A CurseForge API key for the launcher (CurseForge grants them to launchers on request). Until
then, CurseForge packs import from an installed instance.
- CurseForge: dropped for now (its API needs a paid key; Ludovic, 2026-10-22), shown as coming
soon. CurseForge packs import from their zip or an installed instance.