rivencraft/ports/mc263/README.md

# Minecraft 26.3 beta port workspace

This is an **experimental beta port** for issues #97–#104, not gameplay parity
with the Minecraft 1.21.1 release. The 26.3 backend persists separate Ages and
their seeds. Books, the Book Binder, and the Ink Mixer work, and the Binder can
author Standard, Amplified, Island, Flat, Void, or Cave terrain with supported
biome-distribution pages. Other terrain families, feature/material effects,
portals, and much of
the 1.21.1 gameplay remain unported. Use a test world and keep a backup; do not
substitute this JAR for the 1.21.1 mod or import 1.21.1 saves.

The entries below record how the port was built, including earlier alpha-only
limitations that were addressed by later slices.

The creative tab contains the two Books, Crystal Block and Crystal Shard;
the player verified these in game. Unbound Linking Books use the Legacy
sprite, and four Crystal Shards craft into a Crystal Block; both were also
verified in game. The current local iteration adds Budding Crystal and all
four blue crystal growth stages with vanilla-style harvesting. Natural crystal
formation generation is not yet ported; use Creative or commands to obtain a
Budding Crystal for this test. The player verified the growth chain in game.
The next local slice adds the Link Panel Page as a separate creative entry,
using the existing item texture. Blank Pages remain unavailable in Creative;
the player verified the Link Panel's appearance in game. Ink Vials now use
the existing crafting recipe and animated sprite. With paper in the other
hand, an Ink Vial prepares a Link Panel for two of its sixteen ink uses, as
in the current 1.21.1 default. The player verified the Ink Vial interaction
in game. Symbol writing remains unported.
A prepared Link Panel can now be combined shapelessly with leather to craft
an unwritten Linking Book, as in 1.21.1. This custom recipe rejects a blank
Page and extra ingredients. The first Book Binder slice now assembles random-Age
Descriptive Books from leather and a Link Panel. Authored pages remain later.

The next local `1.0.1.10-alpha.1` slice exposes all eight combinations of
plain, Disarm, Maintain Momentum, and Intra-Linking Link Panels in the Link
Pages creative tab. Leather crafting preserves those flags on the Linking
Book. Intra-Linking permits same-dimension travel; Maintain Momentum rotates
horizontal speed to the destination yaw; Disarm leaves the player's inventory
at the departure point after a successful teleport. These are development
variants until the Ink Mixer is ported; other Link Panel modifiers are not
implemented in 26.3. The player passed this modifier slice in game.

The local `1.0.1.11-alpha.1` slice adds a craftable Book Binder with persistent
leather, Link Panel, and output slots. Name an Age in its GUI and press Bind;
the server creates a random prototype Age and places its completed Descriptive
Book in the output. Disarm and Maintain Momentum carry from the panel into the
book; Intra-Linking has no effect on Age creation. Symbol-page authoring and
the Ink Mixer remain unported. This slice passes the build and dedicated-server
smoke test. The player passed crafting and travel in game, but found that E
closed the focused title field and the provisional layout did not match the
existing 1.21.1 Binder GUI.

The local `1.0.1.12-alpha.1` follow-up reuses the 1.21.1 Binder layout: title
bar, cover and output at opposite sides, and a central Link Panel page strip.
The title persists in the block, the missing-panel cue pulses red, and a
focused title field consumes inventory/hotbar keys. Click the output once to
bind, then click again to take the completed book. Authored symbol strips and
the full 1.21.1 Binder grammar remain unported. This same slice also ports the
1.21.1 Ink Mixer block, menu, animation, modifier additives, 16-ink-per-panel
cost, and automatic vial exchange. The creative tab includes it and its
vanilla-shaped recipe is available. This slice needs an in-game Binder visual/
keyboard check and Ink Mixer interaction check.

The local `1.0.1.13-alpha.1` iteration makes Binder assembly place the new
Descriptive Book directly on the cursor with one click. It also renders the
five-page strip from the 1.21.1 GUI and refreshes the Mixer's virtual result
in the same server click that changes paper or ink. The Mixer now consumes
one ink unit and one paper per Link Panel (16 panels per full vial); additive
chances reset when a panel is taken. In-game retest of the first-update
behavior and Binder visual/click flow is pending.

The local `1.0.1.14-alpha.1` follow-up compares the current 26.3 Binder against
the new dev-image sequence. The Binder no longer paints five permanently empty
pages: the first strip page appears when a Link Panel is inserted or carried,
and the missing-panel cue remains above it. Clicking that page inserts/removes
the Link Panel using the same server-owned cursor flow as 1.21.1. Its tooltip
also shows the stored panel. Multi-page symbol writing and strip scrolling
cannot be exercised yet because symbol pages are still unported to 26.3.

The local `1.0.1.15-alpha.1` Binder polish uses the Link Panel's actual 16×16
item icon for the missing-panel cue instead of a full-size page sprite. The
red pulse and tooltip remain confined to that icon.

The local `1.0.1.16-alpha.1` slice adds the bundled 1.21.1 symbol-page
identities to the 26.3 creative menu, grouped by category. Their names and
descriptions are reused from the 1.21.1 translations, and the Page item now
persists each symbol ID. These pages currently use the generic symbol-page
artwork; the Legacy-style runtime glyph compositor has not been ported.
They cannot yet be inserted into the Binder or change Age generation. This is
the page-data foundation for the next authored-writing slice.

The local `1.0.1.17-alpha.1` follow-up derives biome pages from the active
26.3 biome registry instead of only the older bundled list. It excludes the
TerraBlender staging placeholder and separates cave/Nether biomes. Full-block
materials and true source-fluid blocks also receive registry-derived pages,
covering eligible new and modded blocks. Five 26.3 feature symbols cover
poplar trees, fallen poplars, shelf mushrooms, red shrubs, and abandoned
camps. These feature pages are identities only until their Age-generation
handlers are ported. Biome, material, and feature pages still use generic
artwork and cannot yet be placed in the Binder.

The local `1.0.1.18-alpha.1` follow-up restores the 1.21.1 animated redaction
for Corrupted Page names and descriptions. It does not yet port the dynamic
glyph artwork used for other symbol pages.

The local `1.0.1.19-alpha.1` slice ports the runtime glyph compositor for
symbol Page items. It uses the shared Legacy component sheet and page
parchment with a bounded 256-texture client cache; generated textures are
released on resource reload. Registry-derived biome and material pages use
the same deterministic four-word poem pattern as 1.21.1. No per-symbol PNGs
are generated in the source tree. Binder insertion and authored Age generation
are still unported.

The local `1.0.1.20-alpha.1` visual follow-up enlarges symbol artwork on Page
items, slightly thickens the component strokes, and centers number glyphs at a
larger size so they remain readable in inventory and creative-menu icons.

The local `1.0.1.21-alpha.1` slice ports the Binder's ordered, scrollable
symbol-page strip. Pages persist in its block inventory and can be inserted,
removed, and moved via the cursor or shift-click. A Binder with symbol pages
cannot yet produce a book: authored Age compilation is the next port step, and
silently producing a random Age would consume the player's writing incorrectly.

The local `1.0.1.22-alpha.1` visual follow-up gives large Binder pages the
transparent, full-size Legacy glyph composition. Item icons retain their
separate parchment-backed, reduced-size artwork.

The local `1.0.1.23-alpha.1` follow-up places Binder glyph overlays in a later
26.3 GUI stratum than the page atlas, preventing texture batching from drawing
the opaque page backgrounds over the dynamic artwork.

The local `1.0.1.24-alpha.1` follow-up renders Binder page glyphs through
their working special item model, scaled to the page thumbnail. Direct GUI
blitting of the generated texture remained blank in the 26.3 client.

The local `1.0.1.25-alpha.1` follow-up marks temporary Binder preview stacks
for glyph-only special-model rendering. The full-size transparent artwork now
uses the working item pipeline without drawing a second, smaller page outline.

The local `1.0.1.26-alpha.1` corrects the temporary preview component's codec
registration, which NeoForge 26.3 requires during bootstrap.

The local `1.0.1.27-alpha.1` slice applies the first authored Age subset:
Standard terrain plus at most one Biome page. The selected biome is persisted
with the Age and used by a fixed-biome Overworld noise generator on creation
and reload. Ordered page IDs are stored on the finished book. Other page
combinations remain in the Binder and cannot yet be assembled, preventing
silent loss of unsupported writing. Multi-biome distribution, other terrain
profiles, and feature/material pages still need their 26.3 generation ports.

The `1.0.1.28`–`1.0.1.32` slices add Tiled, Grid, Native, and five scaled
biome distributions; multiple authored Biome pages; Amplified and Island
terrain; and saved terrain/biome plans across reload. A Binder or Ink Mixer
beside another block no longer hides that block's faces. Unsupported authoring
still stays in the Binder rather than silently producing an incorrect Age.

The local `1.0.1.33-beta.1` slice adds Flat and Void terrain to Binder
authoring. Flat uses vanilla's superflat layers; Void has no generated floor
and uses the selected Biome for its environmental rules. Each accepts zero or
one authored Biome page. Unsupported multi-biome Flat/Void books remain in the
Binder until their custom generator is ported. The operator probe can create
test Ages with `rivencraft_port age create <name> <seed> flat|void`.

The local `1.0.1.34-beta.1` follow-up starts Flat's solid layers at Y=0
(bedrock at 0, dirt at 1–2, grass at 3) and lands players at the ground surface
instead of creating an elevated fallback platform. This affects newly
generated Flat chunks; previously generated Age chunks are not rewritten.

The local `1.0.1.35-beta.1` follow-up enables biome decoration on newly
generated Flat chunks, allowing the selected biome's trees, vegetation, and
other placed features to appear on the Flat surface. Void remains undecorated.

The local `1.0.1.36-beta.1` slice accepts multiple Biome pages with Flat and
Void terrain. It ports the 1.21.1 authored-biome Flat generator to 26.3, so
Tiled, Grid, and scaled regions affect climate in both terrain types and
surface decoration in Flat. Void continues to generate no floor or biome
decoration. The operator-only `age create_multi` probe creates two-biome test
Ages for the dedicated-server smoke test.

The local `1.0.1.37-beta.1` slice adds the Cave terrain page to Binder
authoring. It uses Minecraft's caves noise settings, accepts Cave and Nether
biome pages (including multi-biome distribution), and searches below Y=64 for
a safe arrival instead of landing on the roof. The 26.3 vanilla Cave preset
defaults to water below Y=32, so this port derives a dry Cave setting with
air as its default fluid and the sea level below the world floor. This applies
to newly generated Cave chunks; it does not drain existing chunks. Cave-specific Nether surface
materials from 1.21.1 are not ported yet. The dedicated-server smoke now
creates and reloads Cave Ages alongside the other terrain families.

The dry-Cave follow-up is packaged as `1.0.1.38-beta.1`; no 26.3 release is
published until the in-game check passes and publication is explicitly requested.

The local `1.0.1.39-beta.1` follow-up rejects fluid at both feet and head
height during safe-landing searches. It also refuses to carve the fallback
platform into submerged space if no dry footing can be found.

The `1.0.1.40-beta.1` port slice seeds terrain and biome selection for
Descriptive Books with no authored symbol pages. It uses the same terrain and
biome-controller rank weights as the 1.21.1 line, freezes the resulting plan
in the Age index, and accepts the result after restart. The operator-only
`age create_random <name> <seed>` probe exercises this path. Random feature,
sky, weather, and instability choices are not yet ported; this slice covers
terrain and biomes only.

The `1.0.1.41-beta.1` slice establishes an Age-scoped decoration wrapper
for 26.3 and accepts one Block material page immediately before a Rocks feature
page. Newly generated surface chunks place small rock clusters made from that
block without modifying the shared biome registry. The selected block and
generator survive a restart. Cave and Void terrain remain unsupported for this
first surface-feature path; unsupported combinations stay in the Binder.
Random feature selection, unpaired materials, duplicate feature pages, and
instability scoring remain future port steps.

From the repository root:

```sh
./gradlew -p ports/mc263 build
```

This standalone Gradle build uses Minecraft 26.3, NeoForge 26.3.0.99,
ModDevGradle 2.0.148, and Java 25. The repository root remains the independent
Minecraft 1.21.1/Java 21 build:

```sh
./gradlew build
```

The beta JAR is under `ports/mc263/build/libs`. Continue the port and its
full dual-version validation in issues #98–#104 before calling 26.3 stable.

The dedicated development server uses `build/run-server`, with its own world
and properties. Set a nonconflicting `server-port` there before running if
another Minecraft server is active. The prototype restores all indexed Ages
during the Overworld load, before initial chunk preparation completes.