From 7efdbdb39a2e3b90ec8188cdaa0e9b4f1c31a9e2 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sat, 24 Oct 2026 15:42:44 +0200 Subject: [PATCH] docs: remove the surveys of other mods; mod code is never read Removes docs/performance/java-perf-mods.md (a survey of eight Java performance mods' techniques) and docs/research/java-mod-compat.md (notes on how Fabric, NeoForge and Mixin work, with a list of mods to port). Links to them now point at mods.md, which says in two lines why Java jars don't run in Horizon. docs/modpacks.md no longer lists a mod's decompiled code as an input of a port: a mod's code is never decompiled, read, quoted or paraphrased, and ports are written from the mod's observed behaviour (the oracle and the harness), its own data files and its public documentation only. Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 2 +- docs/mod-browser.md | 2 +- docs/modpacks.md | 24 ++-- docs/mods.md | 7 +- docs/performance/java-perf-mods.md | 130 -------------------- docs/research/java-mod-compat.md | 183 ----------------------------- 6 files changed, 18 insertions(+), 330 deletions(-) delete mode 100644 docs/performance/java-perf-mods.md delete mode 100644 docs/research/java-mod-compat.md diff --git a/docs/README.md b/docs/README.md index 2e06b6e89..71e2a9ced 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor - [Benchmark](benchmark.md): Horizon against vanilla 26.3 and vanilla with performance mods, on the same machine, world, path and settings: what is measured, how it is kept fair, how to reproduce it. - [Shader packs](shader-packs.md): how the renderer draws a frame, the Horizon WGSL shader pack format (stages, uniforms, `pack.toml`, hot reload), and the plan to translate OptiFine/Iris packs. - [Extras](extras.md): optional zoom, minimap, FPS and keystroke overlays and auto-reconnect, all off by default. -- [Mods](mods.md): Horizon's own mod system (Rust, sandboxed WebAssembly), how to make and install mods, and [what carries over from Java mods](research/java-mod-compat.md). +- [Mods](mods.md): Horizon's own mod system (Rust, sandboxed WebAssembly), how to make and install mods. - [Modpacks](modpacks.md): porting whole packs (ATM10 and smaller): import, inventory, carry-over, an agent per mod with a harness against the Java original, coverage, and how "10x" is measured. - [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it. - [Versioning](versioning.md): how releases are numbered from 0.2 (`v0.2.x`, `launcher@0.2.x`), how installs from before 0.2 get there, and the steps for the day 0.2 ships. diff --git a/docs/mod-browser.md b/docs/mod-browser.md index 745f51d9b..3146fca67 100644 --- a/docs/mod-browser.md +++ b/docs/mod-browser.md @@ -6,7 +6,7 @@ packs, see how well each one runs before installing it, and install it with its ## What it offers -Horizon doesn't run Java code ([research/java-mod-compat.md](research/java-mod-compat.md)). It ports what a Java mod +Horizon doesn't run Java code ([mods.md](mods.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). diff --git a/docs/modpacks.md b/docs/modpacks.md index c15d0767e..591c5a567 100644 --- a/docs/modpacks.md +++ b/docs/modpacks.md @@ -7,9 +7,8 @@ pipeline, not a list of hand ports. It takes a pack as players download it and p Horizon mods. The pipeline is AI agents in dependency order, each port checked against the original mod running in a dev-only Java instance. -This page is the design. It builds on [mods.md](mods.md) (the mod API, WASM in wasmtime) and -[research/java-mod-compat.md](research/java-mod-compat.md) (why Java jars and Mixins cannot -run in Horizon, so we port instead). The ATM10 inventory behind the numbers below is +This page is the design. It builds on [mods.md](mods.md) (the mod API, WASM in wasmtime, and +why Java jars cannot run in Horizon, so we port instead). The ATM10 inventory behind the numbers below is [modpacks/atm10-mods.csv](modpacks/atm10-mods.csv). ## In one picture @@ -141,12 +140,13 @@ derivative work. These rules are part of the pipeline, not advice to users: has given written permission, recorded in the index entry. The tooling refuses to package anything else. No-derivatives and non-commercial licences (14 in ATM10) are never published. For them, even a local port gets a warning that the licence may not allow it. -4. **Mod code never enters this repository.** Mod jars, decompiled sources, Java oracle builds +4. **Mod code never enters this repository, and nobody reads it.** Mod jars, Java oracle builds with mod code, and ports of mods we have no permission to publish all live outside the repo: in the user's pipeline work directory, or for our own development in - `~/code/horizon-parity/modports/` (dev-only, never pushed). Ports are written from - observed behaviour and the harness, with decompiled code as a local reference only. The - repository holds the pipeline, the API, metadata (ids, names, versions, licences, counts) + `~/code/horizon-parity/modports/` (dev-only, never pushed). A mod's code is never + decompiled, read, quoted or paraphrased, by people or agents. Ports are written only from + the mod's observed behaviour (the oracle and the harness), its own data files and its + public documentation. The repository holds the pipeline, the API, metadata (ids, names, versions, licences, counts) and test fixtures we write ourselves. 5. **Contacting authors or publishing any port is Ludovic's call.** Agents ask first. @@ -177,7 +177,7 @@ frame, chat and command hooks. Server mods do not run yet. What a content pack n | Entities: types, attributes, AI goals and brains, spawning | — | deep (87) | 0.5 | `entity` interface, AI in the mod with vanilla goals reusable | | Custom renderers and animated models (block-entity, entity, item; GeckoLib's format) | — | deep | 0.5 | data models (Bedrock geometry + animations), plus a budgeted draw-list interface for the rest | | Dimensions: dimension types, levels, chunk generators | — | about 10 (Twilight Forest, Aether, Ad Astra, Undergarden, ...) | 0.5 | JSON part with worldgen; custom generators as mod code | -| New hooks into vanilla behaviour (what Mixins do) | — | deep | as asked | each becomes a named hook, added for everyone ([java-mod-compat.md](research/java-mod-compat.md#3-a-porting-guide-outline)) | +| New hooks into vanilla behaviour (what Mixins do) | — | deep | as asked | each becomes a named hook, added for everyone | | Client interfaces: `keys`, `target`, `inventory-read`, `ui`, `render`, `world-read` | planned | client tier (38) | 0.2–0.4 | as in [mods.md](mods.md#planned-interfaces) | Two rules from mods.md stay: **the sandbox** (no files, sockets or processes; memory cap; fuel @@ -711,16 +711,16 @@ For tiers logic, machines and deep, in dependency order, as many agents at once budget allows: - **Input:** the inventory record, the carried-over data, the oracle's exports and traces, the - harness, the Horizon mod API docs, the ports of its dependencies, and the mod's decompiled - code as a local reference (dev-only, in the work directory). + harness, the Horizon mod API docs, the ports of its dependencies, and the mod's public + documentation. Never its code: the agent doesn't decompile, read or quote it. - **Output:** a Rust crate in `mods//port/` built with `cargo horizon-mod build`, and its `.hmod`. - **Loop:** write → build → run the harness → read the differences → fix, until the harness passes or the agent reports what blocks it. Usually that is an API gap, which becomes an issue against the mod API ("needs a scheduled-tick hook"), the way version ports turn differences into work items. -- **Rules:** the agent writes the port from observed behaviour and the harness, not by - transliterating decompiled Java; ports follow the mod's licence ([Licences](#licences)). +- **Rules:** the agent writes the port from observed behaviour, the harness and the mod's + own data files only; ports follow the mod's licence ([Licences](#licences)). Players without an AI agent get the carry-over tiers. A port the licence lets us publish can be downloaded instead of regenerated. diff --git a/docs/mods.md b/docs/mods.md index 4521d312d..bc91c043a 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -3,8 +3,9 @@ Horizon gets its own mod system, written in Rust and run in a sandbox, plus two ways to bring over what Java players use: native Horizon ports of popular mods and the data-driven parts of packs and mods. Fabric and NeoForge jars do -**not** run as they are: [research/java-mod-compat.md](research/java-mod-compat.md) -explains why and what we do instead. +**not** run as they are: their code calls and patches Minecraft's Java classes, and +Horizon has none. What carries over is the data and assets inside a jar +([modpacks.md](modpacks.md)). Mods are **off and absent by default**. A fresh install has no `horizon-mods` folder, loads no runtime and plays exactly like vanilla 26.3. @@ -102,7 +103,7 @@ name (the mod reads it as `args`; API 0.1 has no way to declare argument types). ### Planned interfaces Each is a new capability, added in a 0.x minor version so older mods keep -loading. Ordered by what the first native ports need ([research](research/java-mod-compat.md#port-first)): +loading. Ordered by what the first native ports need: | Interface | For | Notes | |---|---|---| diff --git a/docs/performance/java-perf-mods.md b/docs/performance/java-perf-mods.md deleted file mode 100644 index 62aab88a1..000000000 --- a/docs/performance/java-perf-mods.md +++ /dev/null @@ -1,130 +0,0 @@ -# Java performance mods: which of their techniques apply to Horizon - -A survey of the techniques used by eight Java Edition performance mods. Asked for in #991, from famescare on Discord. For each technique it gives the vanilla cost it targets, whether Horizon already avoids that cost, and whether it is worth measuring here. - -**Rules.** Techniques only, taken from each mod's public description, documentation and changelogs (linked below). No mod code was read or copied. Several of these mods are LGPL-3.0, and Horizon's code stays its own. Anything Horizon adopts is reimplemented against vanilla 26.3's behaviour. It keeps parity, so the harnesses stay unchanged, and it needs before/after numbers like any other perf PR (`docs/benchmark.md`, `docs/profiling.md`). - -**Why many don't apply.** A large share of these techniques work around costs of the JVM, OpenGL or GLFW rather than costs of the game's rules. Examples are object headers and duplicate objects, boxing, lambdas and Streams, garbage collection, JNI upcalls, immediate-mode GL draws and GL error checks. Horizon is Rust on wgpu and winit, so it never pays those costs. The techniques that do carry over remove work the game's rules don't need: sleeping block entities, skipped searches, and cheaper geometry tests. - -Verdicts: -- **has**: Horizon already avoids the cost, by its design or with a merged change. -- **n/a**: the cost comes from the JVM, OpenGL or GLFW, and Horizon doesn't have it. -- **later**: missing, and worth measuring. These are listed in "Worth measuring" below and in the LATER list. -- **no**: missing, but it would change vanilla's behaviour or look, or the gain here is too small to pay for itself. - -## Lithium (server and shared game logic) - -Source: [Lithium's mixin configuration](https://github.com/CaffeineMC/lithium/blob/develop/lithium-fabric-mixin-config.md). Lithium keeps vanilla's behaviour, which is the same rule Horizon follows. - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| Hopper caching, inventory change listeners and hopper sleeping | Every hopper looks up its source and target containers and tries a transfer every tick, even when nothing can move | `game/machines.rs` ticks every hopper on each tick. It checks the block's name and cooldown, then runs the transfer attempt. Nothing is cached or put to sleep | **later** | -| Block entity sleeping (furnaces, brewing stands, campfires, crafters, shulker boxes, sculk) | Idle block entities still tick | `game/block_entity_ticks.rs` ticks every ticker each tick, as vanilla does | **later** | -| Entity collisions: faster block access, chunk caching, the supporting block first | Collision scans read blocks through generic level lookups | Collision scans already run over Horizon's own section arrays (`horizon-world` `block_collision_scan`). A counting cursor that does fewer lookups is open as #659 | **has** (more in #659) | -| Specialised cuboid and empty `VoxelShape`s, precomputed shape arrays | Generic voxel shape intersection and merging | `horizon-core::geometry` has its own immutable shapes and box lists (`docs/collision-geometry.md`) | **has** | -| POI search and portal search | POI lookups go through vanilla's stream-heavy search | Section-indexed POIs (`poi_sections.rs`), searched in vanilla's order | **has** | -| Pathfinding: cached node types per block | Node evaluation reads the same blocks over and over | Not measured. Mob pathfinding costs haven't been profiled against vanilla yet | **later** (profile first) | -| Explosions: one access per block on a ray, skip air, skip exposure work | Each ray step reads the block and the fluid again | `game/explosion.rs` follows vanilla's loop. It hasn't been profiled, and TNT chains are the case to measure | **later** (profile first) | -| Random ticks: roll the chance early, fast block search | Sections with nothing that ticks randomly are still walked | Sections with nothing random-tickable are skipped (`docs/random-tick-eligibility-benchmark.md`) | **has** | -| Tick scheduler: faster collections, packed scheduled ticks | Boxed `ScheduledTick` objects in hash sets | Horizon's own tick heap and index (`horizon-core::ticks`, `docs/scheduled-ticks.md`) | **has** | -| Collections and allocation (fastutil maps, cached `values()`, fewer `BlockPos`, no Streams) | JVM allocation, boxing, GC | Rust value types, no GC | **n/a** | -| Math inlining, a smaller sine table | JIT inlining limits | Compiled and inlined by rustc. Horizon keeps vanilla's `Mth.sin` table where results depend on it | **n/a** | -| Chunk access without debug locks or bounds validation | `PalettedContainer`'s thread-check lock | Horizon doesn't have that lock (`docs/performance/paletted-container-access-results.md`) | **n/a** | -| Palette replacement and compaction | Hash palette resizing on the JVM | Horizon's own paletted containers (`horizon-core::paletted`) | **has** | -| Game event dispatchers made only for sections with a listener | Every section holds a dispatcher | Not checked. This is small next to the items above | **no** (until a profile shows it) | -| Item entity merging grouped by item type (experimental) | Each item entity checks every nearby item to merge with | Not present. It matters only with thousands of dropped items (see #996: fresh worlds drop about twice as many items as vanilla) | **later**, after #996 | -| World border cache, redstone wire double reads, fluid flow reads, framed-map scans | Small repeated reads | Each is minor. Fix them where a profile points at them | **no** | - -## FerriteCore (memory) - -Source: [FerriteCore's summary of its changes](https://github.com/malte0811/FerriteCore/blob/main/summary.md). - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| One `FastMap` of neighbour states per block instead of a table per state | About 600 MB of per-state neighbour tables in large packs | Block states are numeric ids with flat tables, with no object per state | **n/a** | -| Compact property storage per state | A per-state `ImmutableMap` | Same as above | **n/a** | -| Cached multipart predicates, shared multipart models | Hundreds of thousands of model and predicate objects | Models are baked once into a shared library (`docs/shared-model-library-benchmark.md`) | **has** | -| Deduplicated baked-quad vertex arrays | Identical `int[]` per quad | Section meshes are built per section from the shared baked models, and no per-quad arrays are kept | **has** | -| Deduplicated shape caches | Duplicate cached `VoxelShape`s per state | One table of distinct shapes, indexed per state (`horizon-world` `CachedCollisionRegistry`) | **has** | -| String deduplication in model locations | Duplicate `String`s from the constructor's round-trips | No `ModelResourceLocation` objects, so the round-trip doesn't exist | **n/a** | -| Partly loaded chunk NBT kept between loading steps | The whole tag is kept | Chunks are decoded into Horizon's own structures | **n/a** | - -Horizon's process memory is tracked against vanilla in `docs/process-memory.md`. - -## ImmediatelyFast (client draw submission) - -Source: [ImmediatelyFast on Modrinth](https://modrinth.com/mod/immediatelyfast). Its gains show only when the CPU is the bottleneck. - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| A batching buffer for immediate-mode draws (entities, block entities, particles, text, GUI) | Many small draw calls and uploads | The HUD is one atlas and one batch of quads (`hud.rs`). Entities are grouped by material (`gfx/entity_batch.rs`). Terrain uses indirect multi-draws (`gfx.rs`, `gfx/flat.rs`) | **has** | -| HUD batching, fewer GUI draw calls | One draw per GUI element | Same batch (`hud.rs`) | **has** | -| Fast text lookup, a bigger font atlas | Per-character lookups, atlas thrash with large fonts | Glyphs live in maps in `font.rs`, drawn into the same HUD atlas | **has** | -| One texture for all map item textures | One texture per visible map | Not measured. It matters only with walls of maps in item frames | **later** (with a map-wall scene) | -| Cached closed-chest geometry | Re-tessellating chests each frame | Merged in #728 (Online5277) | **has** | -| Buffered sign text instead of redrawing it each frame | Text redrawn every frame | Sign text is recorded as text calls in the batch. Not measured with sign-heavy scenes | **later** (with a sign-heavy scene) | -| Fewer framebuffer switches | GL state changes between render types | wgpu render passes are fixed by Horizon's pipeline | **n/a** | -| GL error checking off | `glGetError` overhead | No GL. Release builds run without wgpu's backend validation and, outside DirectX 12, without its indirect-draw validation (`gfx.rs` `instance_descriptor`) | **n/a** | - -## Gnetum (HUD rendering) - -Source: [Gnetum on Modrinth](https://modrinth.com/mod/gnetum). - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| Draw the HUD into an offscreen buffer in several passes, one pass per frame, and show the last complete buffer | The HUD is redrawn every frame | Horizon redraws its one HUD batch every frame | **no**. The HUD would then update at a lower rate than vanilla's, which changes what players see. Horizon's HUD is already one batch. | -| Adaptive distribution and a separate HUD FPS cap | Same | Same | **no**, for the same reason | - -## ScalableLux (lighting, from Starlight) - -Source: [ScalableLux on Modrinth](https://modrinth.com/mod/scalablelux). - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| Starlight's light engine: per-section light arrays and direct propagation queues | Vanilla's light engine is a bottleneck in fast chunk generation | Horizon has its own engine with vanilla's rules (`light.rs`). New chunks are lit on the streaming worker pool, and edits are relit incrementally (`relight_block`). See `docs/performance/lighting-worker-results.md` | **has** | -| Parallel light updates | One light thread | Chunk lighting already runs on several workers during streaming | **has**. Measure the light share of fresh-chunk generation before doing more. | - -## Structure Layout Optimizer (jigsaw structures) - -Source: [Structure Layout Optimizer on Modrinth](https://modrinth.com/mod/structure-layout-optimizer). - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| An octree of piece boxes instead of a `VoxelShape` for free space | Voxel shape boolean ops slow down as pieces add up | Free space is a container box minus a list of placed boxes (`worldgen/structure/jigsaw.rs` `Free`). That avoids the voxel shapes, but the scan is linear per test | **has**. An octree pays only for structures with hundreds of pieces. | -| Skip jigsaw blocks that face the structure boundary or another piece | Every parent jigsaw is matched against every child | Not present | **later** (time trial chambers and ancient cities first) | -| Skip pool elements already found not to fit at this spot | Weighted pools repeat an element once per weight point, and it is re-tested each time | Not present. Only the variant that keeps the result identical applies (no deduplication of the list, which changes layouts) | **later** | -| Cull positions outside the chunk before processors run | Whole templates are processed and then mostly discarded | Not checked | **later** (same measurement) | -| Palette-based template storage | Templates keep every block and NBT object | Templates are Horizon's own structures. Memory isn't measured | **no** (until memory shows it) | - -## AsyncParticles (particles) - -Source: [AsyncParticles on Modrinth](https://modrinth.com/mod/asyncparticles). - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| Particle culling | Off-screen particles are built anyway | Vanilla already skips quad particles whose position is outside the frustum (`QuadParticleGroup.extractRenderState`, `Frustum.pointInFrustum`). Horizon builds every particle's quad (`particles.rs` `render`). This is a parity gap as well as a cost | **later** (vanilla's frustum point test) | -| Vertex transformation on the GPU | Every particle's quad is built on the CPU and uploaded every frame | Same in Horizon (`particles.rs` `render`). Instancing would upload one record per particle | **later** (measure with 10k+ particles) | -| Particle ticks on another thread | Particle ticks on the client thread | Horizon ticks particles on the game thread | **no**. Vanilla's particle ticks read the level, and racing them against block changes risks parity. Revisit only if a profile shows particle ticks are big. | -| Asynchronous light cache for particles | A light lookup per particle per frame | `particles.rs` looks light up per particle | **later**, with the item above | -| Texture animation one frame late | Animated textures tick on the client tick | Not adopted | **no**, because it changes timing | - -## Ixeris (input and the render thread) - -Source: [Ixeris on Modrinth](https://modrinth.com/project/p8RJPJIC). - -| Technique | Vanilla cost | Horizon | Verdict | -| --- | --- | --- | --- | -| Event polling on the main thread, rendering on its own thread | GLFW event polling and JNI upcalls take time from rendering | winit, without JNI. Input and rendering share the event loop (`game.rs`, `ApplicationHandler`) | **n/a** for the JNI part | -| Buffered raw input (`GetRawInputBuffer`) | One `GetRawInputData` call per event. An 8000 Hz mouse costs a lot on Windows | winit reads `WM_INPUT` one message at a time | **later**. Measure on Windows with a high-polling-rate mouse before changing it. | -| Cached GLFW state | Round trips to the main thread | No GLFW | **n/a** | -| A frame limiter that sleeps, then spins | Imprecise sleeps | Horizon has its own limiter | **no** (no reported problem) | - -## Worth measuring - -Each of these needs a profile or a benchmark first. They are ordered by the expected gain. They are in the LATER list in `~/code/horizon-parity/FEATURES.md`, not filed as issues: - -1. Hopper and block-entity sleeping, with vanilla-identical results (Lithium). Benchmark: a hopper and furnace array. -2. Particles: vanilla's frustum point test (a parity fix too), then GPU-built quads (AsyncParticles). Benchmark: 1,000+ campfires. -3. Jigsaw placement: skip blocked connectors and already-failed elements without changing the layout (Structure Layout Optimizer). Benchmark: trial chambers and ancient cities in fresh worlds, `docs/generation-scan-benchmark.md`. -4. Windows raw input in batches for high-polling-rate mice (Ixeris). Benchmark: an 8000 Hz mouse on Windows. -5. Profile before choosing a technique: mob pathfinding, TNT explosions, item merging after #996, map walls and sign-heavy scenes. diff --git a/docs/research/java-mod-compat.md b/docs/research/java-mod-compat.md deleted file mode 100644 index 8a36b7c48..000000000 --- a/docs/research/java-mod-compat.md +++ /dev/null @@ -1,183 +0,0 @@ -# Java mods and Horizon: what can carry over - -Players ask "will my mods work?". Short answer: **Fabric and NeoForge jars -will not run in Horizon as they are**, and no bridge we could build would -change that for more than a handful of mods. What carries over is the -*content* (data packs, resource packs, the data and assets inside mod jars) -and the *ideas* (native Horizon ports of the mods people use most, written -with [Horizon's own mod system](../mods.md)). This page is the reasoning. - -## How Java mods work - -### Fabric - -- **Fabric Loader** finds jars in `mods/`, reads `fabric.mod.json` - (entrypoints, dependencies, mixin configs, access wideners), and starts the - game through a class loader that can rewrite classes as they load. -- **Mixin** (SpongePowered) is how nearly every mod changes the game: a mixin - class names a Minecraft class (`net.minecraft.client.gui.hud.InGameHud`) and - injects code at points inside its methods (`@Inject(method = "render", at = - @At("TAIL"))`, `@Redirect`, `@ModifyVariable`, `@Overwrite`...). The bytecode - of the vanilla class is rewritten at load time. Access wideners make private - fields and methods public for the same purpose. -- **Fabric API** is a set of modules that give mods events and registries - instead of raw mixins: `fabric-lifecycle-events` (`ClientTickEvents`, - `ServerTickEvents`), `fabric-rendering` (`HudRenderCallback`, - `WorldRenderEvents`), `fabric-command-api`, `fabric-key-binding-api`, - `fabric-networking-api` (custom payloads), `fabric-registry-sync`, - `fabric-resource-loader`, `fabric-screen-api`, `fabric-item-group`, - `fabric-events-interaction` and about forty more. **Fabric API itself is - implemented with mixins** into the same vanilla classes. -- Mods mix the two freely: a mod using Fabric API events still calls - `MinecraftClient.getInstance().player.getBlockPos()`, - `world.getBlockState(pos)`, `DrawContext.drawText(...)`: direct calls into - vanilla's classes, by their mapped names. - -### NeoForge (and Forge) - -- An event bus (`NeoForge.EVENT_BUS`, mod buses) with hundreds of events, - `DeferredRegister` for registries, data attachments and capabilities, - networking payloads, config specs. NeoForge patches vanilla's source - directly (binary patches) to fire its events. -- Mods also use mixins and access transformers, and call vanilla classes - directly, as on Fabric. - -### Data and assets in a jar - -Besides code, a mod jar carries the same folders as packs: -`assets//` (models, blockstates, textures, sounds, language files, -shaders) and `data//` (recipes, loot tables, tags, advancements, -predicates, functions, worldgen: biomes, features, structures). These are -**vanilla formats**, read by vanilla's own code. - -## Why a Java bridge cannot run them - -Horizon is a reimplementation in Rust: there are no `net.minecraft` classes -at runtime, no `InGameHud`, no `ClientPlayerEntity`, no bytecode to rewrite. - -1. **Mixins have nothing to bind to.** A mixin is a patch against a specific - method's bytecode. Without vanilla's classes there is no method, no - injection point and no local variable to modify. This is not a missing - feature we could add: it is the mechanism itself. -2. **Fabric API is mixins too.** A shim Fabric API would have to be - re-implemented from scratch as Java classes calling into Horizon. That part - alone is possible for the event modules. -3. **Mods call vanilla directly.** Even "pure Fabric API" mods use vanilla's - classes for everything else: the player, the world, the block states, the - renderer, the text drawing. Running them means providing Java classes with - vanilla's names and behaviour, backed by Horizon's state: in effect a - second Minecraft, in Java, on top of Horizon. Thousands of classes, in the - mapped names of every mapping set (Yarn, Mojang, intermediary), version by - version. -4. **The JVM itself** would ship with every install (a trimmed JRE is still - 40-60 MB, the full one 150+ MB), start in a second or more, hold a few - hundred MB of heap before any mod loads, and bring garbage-collector pauses - back into the frame: the costs Horizon exists to remove. JNI calls cost - tens to hundreds of nanoseconds each and every one crosses with copies. -5. **No sandbox.** Java mods are fully trusted native-speed code with file - and network access. Horizon's mods are sandboxed and their permissions are - shown; a Java bridge would be the one hole in that. - -**What a bridge could support**, if we ever built one: a stable subset of -Fabric API events (client and server tick, HUD render callback, client -commands, key bindings, custom payloads), with a tiny "vanilla view" API -(player position, held item, chat), for mods written only against that -subset. Surveying the most-downloaded Fabric mods, nearly none qualify: the -popular ones are popular precisely because they reach into rendering, the -world or the UI. The cost (a JVM in the game, a second API surface to keep -stable) is far above the benefit. **We do not build it.** If that changes, -the bridge would sit on top of the WIT API like any other mod runtime, so the -sandbox would still hold. - -## What we do instead - -### 1. Data-driven content (packs and the data in mod jars) - -Horizon already reads vanilla resource packs and data packs (functions, -function tags, predicates today). Extending data-pack coverage to recipes, -loot tables, tags, advancements and worldgen JSON brings most "content" -packs over with no mod code at all, and it is vanilla behaviour, so the parity -harnesses check it. - -For **Fabric/NeoForge jars**, the launcher can offer "import the data": read -`data/` and `assets/` from the jar and load them as a data pack plus a -resource pack. What works: new recipes, loot changes, tags, advancements, -functions, worldgen tweaks that only use vanilla blocks, retextures, language -files. What does not: anything referring to a block, item or entity the jar -registers in Java code (the ids do not exist); the import skips those files and -lists them. With Horizon's planned `registries` interface, a native port can -register those ids and reuse the jar's JSON models, textures, recipes and loot -as they are. - -### 2. Native Horizon ports of popular mods - -Horizon itself covers the performance mods: Sodium, Lithium, FerriteCore, -ModernFix, EntityCulling and ImmediatelyFast exist because vanilla Java is -slow, and Horizon's renderer and simulation are the replacement (see -[benchmark](../benchmark.md)). Zoom (OK Zoomer, Zoomify), FPS and keystroke -overlays, a minimap and auto-reconnect are already built in as -[extras](../extras.md). - -#### Port first - -Ranked by players reached per unit of API work. Each needs the planned -interfaces listed in [mods.md](../mods.md#planned-interfaces). - -| Mod (Java) | What it does | Horizon port | Needs | -|---|---|---|---| -| **Mod Menu** | list mods, open their settings | built in: Options > Mods (done), settings pages next | `ui` | -| **AppleSkin** | food saturation and exhaustion on the HUD and tooltips | SDK mod | `inventory-read`, `ui` | -| **Jade / WTHIT** | what the crosshair points at: block, entity, harvest tool, container contents | SDK mod | `target`, `ui` | -| **JEI / EMI / REI** | browse items, recipes and uses | SDK mod (or built in: Horizon already has the recipe book's data) | `recipes`, `inventory-read`, `ui` | -| **Xaero's Minimap / JourneyMap** | minimap, world map, waypoints | the minimap is an extra; a world map and waypoints as an SDK mod | `world-read`, `render`, `storage` | -| **Litematica** | schematic overlay to build from | SDK mod | `world-read`, `render`, `storage`, `ui` | -| **Mouse Tweaks / Inventory Profiles Next** | drag and sort inventory | built in or SDK mod | `inventory-read` + a sanctioned click API | -| **Continuity / CIT** | connected and custom item textures | built into the renderer (pack formats) | none: resource-pack features | -| **Distant Horizons** | low-detail far terrain | a Horizon renderer feature, not a mod | none | -| **Iris + shader packs** | shaders | a Horizon renderer feature (wgpu shader pipeline), later | none | -| **Simple Voice Chat** | proximity voice | server + client mod | `server`, `net`, audio (later) | - -### 3. A porting guide (outline) - -To be written as `docs/porting-from-fabric.md` once API 0.2 lands: - -1. **Separate logic from glue.** Most of a mod is plain logic (maths, - formatting, data structures): port it to Rust once, unit-test it on the - host. -2. **Map events.** - - | Fabric | Horizon | - |---|---| - | `ClientModInitializer.onInitializeClient` | `Mod::init`, returning a `Registration` | - | `ClientTickEvents.END_CLIENT_TICK` | `Registration::on_tick`, `Mod::tick` | - | `HudRenderCallback` | `hud::set_panel` when the content changes (retained), or `on_frame` | - | `ClientCommandRegistrationCallback` | `Registration::command`, `Mod::command` | - | `ClientReceiveMessageEvents` | `Registration::on_chat`, `Mod::chat` | - | `KeyBindingHelper.registerKeyBinding` | `keys` (planned) | - | `Registry.register(Registries.ITEM, ...)` | `registries` (planned) with JSON in `data/` | - | `ServerPlayNetworking` payloads | `net` (planned) | - | config libraries (Cloth Config, YACL) | `storage` + a `ui` settings page (planned) | - -3. **Replace mixins with hooks.** For each mixin, write down what it observes - or changes. If a WIT hook covers it, use the hook. If not, open an issue - asking for the hook ("I need X before/after Y"): hooks are added to the API - for everyone instead of each mod patching the game. -4. **Declare capabilities** in `horizon-mod.toml`, the least the mod needs. -5. **Reuse assets**: textures, models, language files and recipes move as - they are into the `.hmod`'s `assets/` and `data/` (with `registries`). -6. **Test** with `cargo horizon-mod run` and hot reload; add unit tests for the - logic; publish with a signed `.hmod`. - -## Sources - -- Fabric documentation (`docs.fabricmc.net`): mod structure, Mixin - introduction, Fabric API modules and events. -- SpongePowered Mixin wiki: injection points and how class transformation - works. -- NeoForge documentation (`docs.neoforged.net`): events, registries, - networking. -- Modrinth's most-downloaded Fabric mods, for the porting list. -- Horizon's own Java test mod (`mods/horizon`, built by `tools/build_mod.py` - and the CI `portable-mod` job) is a Fabric mod used by the benchmarks and - parity oracles: it shows the Mixin pattern (`FrameHookMixin`) this page - describes, and stays a developer tool, not a player-facing mod.