From 41f82e8db01e61bcdd6a003c4e4f2e7c9141a618 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Thu, 15 Oct 2026 14:42:42 +0200 Subject: [PATCH] Resource packs: audit of every 26.3 pack feature with its proof Co-Authored-By: Claude Opus 5.5 --- docs/README.md | 1 + docs/resource-packs.md | 98 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/resource-packs.md diff --git a/docs/README.md b/docs/README.md index 7e225de9f..59fbdb2da 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,6 +10,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. - [Extras](extras.md): optional zoom, minimap, FPS and keystroke overlays and auto-reconnect, all off by default. - [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it. +- [Resource packs](resource-packs.md): everything a 26.3 resource pack can change, whether Horizon honours it, and the proof. - [Opt-in data collection](telemetry.md): the consent, exactly what is sent, how it is stored and sent. - [Benchmark report format](benchmark-report.md): the versioned JSON every benchmark writes (game, launcher, `tools/perf_bench.py`), the local log and, with consent, the upload. - Menus: the title, world list, create world, multiplayer, options and pause screens share the launcher's design tokens and fonts (`crates/horizon-theme`), drawn by `ui_theme` over a live frozen backdrop (`game/backdrop.rs`, blurred and graded by `post.rs`). Options → Interface → Menu style switches to vanilla's screens (Classic, kept in `horizon.txt`; `HORIZON_MENU_STYLE=horizon|classic` overrides it, and scripted runs default to Classic). [Title](media/menu-title.png) ([webm](media/menu-title.webm)), [worlds](media/menu-worlds.png), [options](media/menu-options.png), [pause](media/menu-pause.png). diff --git a/docs/resource-packs.md b/docs/resource-packs.md new file mode 100644 index 000000000..7faa75a48 --- /dev/null +++ b/docs/resource-packs.md @@ -0,0 +1,98 @@ +# Resource packs: what works + +Java Edition resource packs load in Horizon: put the folder or `.zip` in `resourcepacks/`, pick it on the Resource Packs +screen (the same screen as vanilla's) or in game, and every loader reloads from it. This page lists everything a +26.3 resource pack can change and whether Horizon honours it, with the proof. + +## How it works + +`packs.rs` finds the packs (`FolderRepositorySource`: folders and zips, plus the built-in Programmer Art and High +Contrast), reads `pack.mcmeta` (format range, overlays, filters) and builds one overlay directory that layers the +selected packs over the prepared vanilla resources, later packs winning. Files vanilla reads as a resource *stack* +(language files, `sounds.json`, font definitions, atlas definitions) are merged layer by layer as vanilla merges them. +Every loader then reads that one tree; `game/packs.rs` (`reload_packs`) reloads all of them in game, as +`Minecraft.reloadResourcePacks` does. Unchanged selections reuse the overlay ([reuse-pack-overlays.md](reuse-pack-overlays.md)). + +Vanilla 26.3's reload listeners (`Minecraft.`, `Gui`, `Hud`): languages, textures, shaders, sounds, atlases, +fonts, grass / foliage / dry foliage colour maps, models (block states, block models, item definitions), equipment +assets, paletted textures, entity and block entity renderers, particles, the game renderer (post effects), the level +renderer, clouds, GPU warn list, regional compliance, splashes and waypoint styles. Every row below comes from one +of them. + +## The table + +**Works**: Horizon reads it from the pack and draws or plays it like vanilla. **Partly**: some of it. +**No**: ignored (the vanilla version stays). Proof: a parity harness in `tools/` (compares with the pinned 26.3 +client), a unit test, or the loader reading the overlay (vanilla's files go through the same loader, and the +harness named checks that loader against vanilla). + +| Feature | Files | State | Proof | +| --- | --- | --- | --- | +| Pack metadata: description, icon, `min_format`/`max_format`, old `supported_formats`, compatibility warning | `pack.mcmeta`, `pack.png` | works | `test_pack_screen_parity`, `test_pack_selection_parity` | +| Overlays per format | `pack.mcmeta` `overlays` | works | `test_resource_pack_parity` (an overlay for 26.3 applied, an older one not) | +| Filters | `pack.mcmeta` `filter` | works | `test_resource_pack_parity` (`packs/pattern.rs` regex subset) | +| Folder and zip packs, order, built-in packs | `resourcepacks/` | works | `test_resource_pack_parity`, `test_pack_selection_parity` | +| Other namespaces | `assets//` | works | `test_resource_pack_parity` | +| Block states: variants, multipart, weights, rotations, uvlock | `blockstates/` | works | `test_blockstate_model_parity`, `test_model_choice_parity`, `test_blockstate_transform_parity` | +| Block models: parents, elements, rotations, faces, cullface, tint, shade, light emission, ambient occlusion | `models/block/` | works | `test_model_resolution_parity`, `test_model_baking_parity`, `test_section_mesh_parity` | +| Item definitions and item models (all model types, display transforms, tints) | `items/`, `models/item/` | works | `test_item_model_parity` | +| Entity models | (code in vanilla) | n/a | entity models aren't resource files in 26.3 (`test_entity_model_parity` checks the code ones) | +| Textures, any resolution (16x to 512x) | `textures/` | works | atlases stitched from the overlay; Faithful 32x, Default HD 128x and FPBR measured in [reuse-pack-overlays.md](reuse-pack-overlays.md) | +| Texture animation: frames, frame time, frame size | `*.png.mcmeta` `animation` | works | `test_sprite_animation_parity` | +| Texture animation: `interpolate` | `*.png.mcmeta` `animation` | **no** | frames step instead of blending (vanilla's own prismarine, magma, stems, lit furnaces and campfires, command blocks, sculk too): fix in progress | +| Mipmap strategy, alpha cutoff bias | `*.png.mcmeta` `texture` | works | `test_mipmap_parity` | +| `blur` / `clamp` | `*.png.mcmeta` `texture` | partly | vanilla's own files (vignette, pumpkin blur, shadow, glint, nausea) are drawn with their vanilla sampling; a pack that changes the flags is ignored | +| Atlases and sprite sources: `directory`, `single`, `filter`, `unstitch`, `paletted_permutations` | `atlases/` | works | `test_resource_pack_parity` (merged source lists), `atlas_sources.rs` tests | +| GUI sprites | `textures/gui/sprites/` | works | `test_hud_parity`, `test_screen_layout_parity` | +| GUI sprite scaling: `nine_slice` border | `*.png.mcmeta` `gui` | works | `ui.rs` reads the border; vanilla's buttons, sliders and frames use it | +| GUI sprite scaling: `width`/`height`, `stretch_inner`, `tile`, `stretch` | `*.png.mcmeta` `gui` | partly | the border is taken in texels, so HD GUI sprites get thin borders; `stretch_inner` (vanilla's tooltip frame) and `tile` aren't read | +| Fonts: `bitmap`, `space`, `unihex`, `reference` | `font/*.json`, `textures/font/` | works | `test_resource_pack_parity` (merged provider lists) | +| Fonts: `ttf` | `font/*.json` | **no** | no TrueType rasteriser yet | +| Fonts picked by text components (`"font": "..."`, custom fonts) | `font/` | partly | the default font and the enchanting table's `alt` glyphs are drawn; other fonts named by a text component use the default | +| Languages, translations | `lang/*.json` | works | `test_resource_pack_parity` (key by key, as `ClientLanguage`) | +| New languages | `pack.mcmeta` `language` | works | `lang.rs` reads every pack's `language` section into the language list | +| Sounds and sound events (`replace`, weights, streams, event references) | `sounds.json`, `sounds/` | works | `test_resource_pack_parity`, `test_sound_event_parity`, `test_sound_engine_parity` | +| Splashes | `texts/splashes.txt` | works | `title.rs` reads it from the overlay | +| Credits, end poem | `texts/credits.json`, `end.txt`, `postcredits.txt` | **no** | Horizon has no credits screen yet (Options → *Credits & Attribution* opens nothing) | +| Grass, foliage and dry foliage colours | `textures/colormap/` | works | `biome.rs` reads the overlay; `test_section_mesh_parity` checks the tints | +| Entity textures and variants | `textures/entity/` | works | `test_entity_model_parity`, loaded from the overlay | +| Block entities: chests, signs, beds, banners, shields, shulker boxes, decorated pots | `atlases/`, `textures/entity/` | works | `test_block_entity_render_parity` | +| Villager hats | `*.png.mcmeta` `villager` | **no** | the type layer's hat is always drawn; vanilla hides it under a profession hat marked `full`/`partial` | +| Equipment (armour, horse/llama/wolf/nautilus armour, wings, dyeable layers) | `equipment/`, `textures/entity/equipment/` | works | `game/armor_stands.rs`, `mobs/render.rs` read the overlay | +| Armour trims on items | `atlases/items.json`, `textures/trims/items/` | works | `paletted_permutations` (`atlas_sources.rs` tests) | +| Armour trims on worn armour | `textures/trims/entity/`, `textures/palettes/`, `palette` metadata | **no** | worn trims aren't drawn yet (`PalettedTextureManager`) | +| Particles | `particles/`, `textures/particle/` | works | `test_particle_providers_parity` | +| Sky: sun, moon phases, stars, end sky, clouds, rain and snow | `atlases/celestials.json`, `textures/environment/` | works | `test_environment_render_parity`, `test_cloud_render_parity`, `test_weather_render_parity` | +| Title panorama | `textures/gui/title/background/` | works | `gfx/panorama.rs` loads it from the overlay | +| Screen overlays: vignette, pumpkin, powder snow, nausea, underwater, world border | `textures/misc/` | works | `test_world_border_render_parity`, `test_hud_parity`; loaded from the overlay | +| Enchantment glint | `textures/misc/enchanted_glint_*` | works | `item_render/gui.rs`, `entity.wgsl` | +| Maps: background, decorations | `textures/map/`, `atlases/map_decorations.json` | works | loaded from the overlay | +| Paintings, mob effect icons | `atlases/paintings.json`, `textures/mob_effect/` | works | loaded from the overlay | +| Locator bar styles | `waypoint_style/` | **no** | the locator bar isn't drawn yet | +| Post effects (spectating a creeper, spider or enderman; glowing outlines) | `post_effect/`, `shaders/post/` | **no** | Horizon's effects are WGSL; a pack's GLSL post chain isn't run | +| Core shaders | `shaders/core/`, `shaders/include/` | **no** | Horizon draws with WGSL; packs that replace core shaders need the GLSL translation of [shader-packs.md](shader-packs.md) | +| GPU warn list, regional compliance | `gpu_warnlist.json`, `regional_compliancies.json` | n/a | OpenGL driver warnings and play-time notices for some regions; not used | + +Summary: 44 rows; 31 work, 3 partly, 8 don't (interpolated animation, TrueType fonts, credits and end poem, +villager hats, trims on worn armour, locator bar styles, post effects, core shaders), 2 don't apply. Except the +shaders, the missing pieces are missing vanilla features too, and each vanilla parity fix covers the pack case as well. + +## Gaps and their work + +| Gap | Size | Where | +| --- | --- | --- | +| Animation `interpolate` | small | fix PR (`gfx.rs` `animate_sprites`) | +| GUI scaling `width`/`height`, `stretch_inner`, `tile`, `stretch` | small | next fix PR (`ui.rs`) | +| Villager hats | small | [#334](https://github.com/ludovic111/horizon/issues/334) | +| `blur`/`clamp` from packs | small | [#335](https://github.com/ludovic111/horizon/issues/335) | +| Text component fonts, TrueType fonts | medium | [#336](https://github.com/ludovic111/horizon/issues/336) | +| Trims on worn armour (paletted textures) | medium | [#337](https://github.com/ludovic111/horizon/issues/337) | +| Credits and end poem screen | medium | [#338](https://github.com/ludovic111/horizon/issues/338) | +| Locator bar | medium | [#339](https://github.com/ludovic111/horizon/issues/339) | +| Post effects and core shaders | large | [shader-packs.md](shader-packs.md) | + +## Testing a pack + +`tools/test_resource_pack_parity.py` builds small packs (folder and zip, overlays, a filter, textures, languages, +sounds, fonts, atlases), and a Java oracle answers what vanilla's loaders read from them; Horizon's loaders must +give the same answers. Never commit third-party packs: build test packs in the harness or the test.