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:
+108
-30
@@ -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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user