handcrafted/README.md

# Handcrafted — Fabric 26.2 Port

A Fabric-only port of **Handcrafted** for **Minecraft 26.2**, migrated from the original Architectury-based Minecraft 1.21.x project.

This repository keeps the original Handcrafted content and resources while adapting the build, APIs, data formats, models, entities, and interactions required by Minecraft 26.2.

## Platform

- Minecraft: **26.2**
- Mod Loader: **Fabric**
- Java: **25**
- Fabric Loader: **0.19.3**
- Fabric API: **0.161.0+26.2**
- Resourceful Lib: **5.0.4**
- Gradle: **9.7.1**
- Fabric Loom: **1.18-SNAPSHOT**

NeoForge is intentionally excluded from this port.

## Project Structure

The original common + Fabric Architectury project has been collapsed into a single Fabric Loom project while preserving the original source and resource trees as much as practical.

The Architectury `@ExpectPlatform` client renderer bridge has been replaced by a direct Fabric implementation.

## Development Workflow

Development uses the unified workflow scripts:

- Windows: `workflow.bat`
- Linux/macOS: `workflow.sh`

The workflow reads `mod_version`, `minecraft_version`, and `archives_base_name` from `gradle.properties`. It handles the normal development cycle from one script:

1. Compile when the JAR for the current version does not exist.
2. Push source changes to Git.
3. Launch the development client for mod testing.
4. Create the Gitea release and upload the built JAR.

A release artifact follows the version in `gradle.properties`, for example:

```text
build/libs/handcrafted-4.0.15.jar
```

## Porting Overview

Minecraft 26.2 contains substantial API and runtime changes compared with the original Minecraft 1.21.x codebase. This port therefore required source-level migration in addition to updating the build system.

### Build and Fabric migration

- Migrated to a direct Fabric Loom project.
- Updated Gradle to 9.7.1 for the current Fabric Loom 1.18 toolchain.
- Migrated the project to Java 25.
- Removed obsolete Java 21 Mixin compatibility declarations.
- Replaced Architectury-specific platform bridges with direct Fabric implementations.
- Updated block-entity and entity registration for current Minecraft/Fabric APIs.
- Updated Unix helper scripts for macOS Bash 3.2 compatibility.

### Minecraft 26.2 API migration

- Migrated `BlockBehaviour#updateShape` to the current `LevelReader`, `ScheduledTickAccess`, and `RandomSource` signatures.
- Migrated removed `onRemove` behavior to current removal hooks where required.
- Migrated `Painting` / `PaintingVariant` to the current painting package.
- Replaced removed `ItemNameBlockItem` usage.
- Updated registry lookups for current value/holder behavior.
- Migrated Crockery and container persistence to `ValueInput` / `ValueOutput`.
- Migrated item stack persistence to codec-based APIs.
- Migrated furnace fuel duration handling to `FuelValues`.
- Migrated block entity registration to `FabricBlockEntityTypeBuilder`.
- Migrated entity type construction to `ResourceKey<EntityType<?>>`.
- Updated comparator output signatures.
- Added the required Minecraft 26.2 `Entity#hurtServer` implementation for Seat.
- Updated client/server interaction results and POI holder lookup.
- Migrated custom painting entity data toward the current typed entity-data/component APIs.

### Resources, models, recipes, and translations

- Migrated legacy model resources rejected by Minecraft 26.2 model baking.
- Normalized invalid negative/out-of-range UV coordinates in stackable-book and trophy models.
- Rescaled Witch Trophy Y geometry to the modern cuboid boundary.
- Removed invalid block-model dependencies on item-atlas textures.
- Added Minecraft 26.2 client item definitions under `assets/handcrafted/items/` for legacy item models.
- Migrated legacy recipe ingredient objects to the Minecraft 26.x ingredient string syntax.
- Updated the Phantom Trophy recipe from removed `minecraft:chain` to `minecraft:iron_chain`.
- Added missing `item.handcrafted.*` translation aliases.
- Added missing Handcrafted item-tag display translations.
- Added missing Fancy Bed item-model particle references.
- Retargeted the oversized-model Mixin to `CuboidModelElement.Deserializer#getPosition`.

## Seating System

The seating system required several migration passes because Minecraft 26.2 changed both block interaction dispatch and entity riding behavior.

### Interaction handling

Empty-hand seating now runs through `useWithoutItem(...)`. Held-item interactions still use the item-specific path so Handcrafted's cushion customization remains functional.

### Seat entity synchronization

Legacy custom Seat spawn-packet handling was removed so Minecraft 26.2 can use its native entity spawn/tracking and passenger synchronization.

The Seat remains an invisible temporary vehicle and self-discards when it no longer has a passenger or its furniture block is gone.

### Minecraft 26.2 riding gate

Diagnostics eventually isolated the seating failure to `player.startRiding(seat)`: the Seat spawned successfully but mounting returned `false`.

The Seat entity type had been registered with:

```java
.noSave()
```

On Minecraft 26.2 this makes the entity type non-serializable, which prevents it from being used as the riding vehicle. Removing `.noSave()` restored functional seating while retaining the Seat's normal automatic cleanup.

### Final seating behavior

After mounting was restored, seating behavior was refined by furniture type:

- Chairs and sofas with backrests orient the player to the furniture.
- Supported chairs with an optional cushion raise the seating position slightly to reduce visual intersection with the cushion.
- Benches with backrests retain furniture-facing seating.
- Dining Benches use the player's horizontal facing at the moment of sitting, allowing them to be used naturally from either side.

As of **4.0.15**, the tested seating behavior for chairs, sofas, benches, cushions, and Dining Benches is functional.

## Release History

### 4.0.17 — Standalone Cushion facing

- Standalone Cushion now captures the player's horizontal facing when sitting, matching Dining Bench behavior.
- Sitting on a Cushion from opposite directions now produces the corresponding seating direction instead of using the previous free-rotation/fixed initial yaw behavior.

### 4.0.15 — Dining Bench facing

- Dining Bench captures the player's horizontal facing when sitting.
- Sitting from opposite sides now produces the corresponding opposite seating direction.
- Seating direction is independent of the Dining Bench's placement facing.

### 4.0.14 — Bench facing

- Restored furniture-facing orientation for benches with backrests.
- Prevented free rotation from making the seated player visually intersect the backrest.
- Dining Bench behavior remained separate because it has no backrest.

### 4.0.13 — Seating polish

- Preserved the existing chair/sofa vertical seating position when no optional cushion is installed.
- Raised the player slightly when sitting on supported furniture with an added cushion.
- Refined rotation behavior for backless seating.

### 4.0.12 — Minecraft 26.2 riding gate fix

- Diagnostics isolated the failure to `player.startRiding(seat)`.
- Identified `EntityType.Builder.noSave()` as the Minecraft 26.2 riding blocker.
- Removed `.noSave()` while retaining automatic Seat cleanup.

### 4.0.11 — Seat interaction diagnostics

- Reworked seating interaction dispatch around `useWithoutItem(...)`.
- Preserved Handcrafted cushion handling in the held-item path.
- Made `Seat.sit(...)` server-authoritative.
- Added concise server-side Seat attempt/result diagnostics.

### 4.0.10 — Seat rework

- Reworked the invisible Seat entity toward the modern riding implementation.
- Removed the previous delayed-mount workaround.
- Simplified the Seat passenger flow.

### 4.0.9 — Seat synchronization

- Removed legacy custom Seat spawn-packet handling.
- Switched to Minecraft 26.2 native entity spawn/tracking.
- Continued migration of passenger attachment behavior.

### 4.0.4 — Runtime, resource, and data migration

The early release-style builds combined several migration passes:

- Migrated legacy models and Minecraft 26.2 item definitions.
- Fixed recipe identifiers and ingredient syntax.
- Added missing translations.
- Restored empty-hand seating dispatch.
- Updated the oversized-model Mixin.
- Added Fancy Bed particle references.
- Fixed strict Minecraft 26.2 block/item ResourceKey initialization.
- Removed the legacy `Seat.makeBoundingBox()` override after confirming the method is final in Minecraft 26.2.

## Earlier Porting Milestones

Before release-style versioning, development used temporary `port.N` milestones.

### port.2

- Updated the Gradle/Fabric Loom toolchain for Minecraft 26.2.

### port.6

- Migrated block update signatures, removal hooks, painting packages, registry access, Crockery persistence, render-layer handling, annotations, and build-height access.

### port.7

- Corrected malformed braces and stale state comparisons introduced during the removal-hook migration.

### port.8

- Migrated container persistence, fuel APIs, block/entity registration, comparator signatures, and initial entity persistence.
- Fixed macOS Bash 3.2 helper-script compatibility.

### port.9

- Migrated shift-key handling, Seat damage behavior, painting entity data, interaction results, and POI access.
- Isolated the Minecraft 26.2 renderer pipeline as the next major compile category.

### port.10

- Migrated renderer class signatures to the Minecraft 26.2 render-state/submit API.
- Temporarily reduced custom Fancy Painting and Crockery renderer drawing while isolating compile errors.
- Removed obsolete Custom Painting typed-entity-data application pending migration.

### port.11

- Fixed strict Minecraft 26.2 block/item ID initialization (`Block id not set`).

### Port 14 runtime/data fixes

- Migrated recipe ingredient syntax.
- Added missing block-item translations.
- Updated seating interaction response behavior.
- Retargeted the oversized-model Mixin.
- Added missing Fancy Bed particle references.

## Original Maven Coordinates

The previous README documented these upstream dependency coordinates.

### Kotlin DSL

```kotlin
repositories {
    maven(url = "https://maven.teamresourceful.com/repository/maven-public/")
}

dependencies {
    modImplementation(
        group = "earth.terrarium.handcrafted",
        name = "handcrafted-$modLoader-$minecraftVersion",
        version = handcraftedVersion
    )
}
```

### Groovy DSL

```groovy
repositories {
    maven {
        url "https://maven.teamresourceful.com/repository/maven-public/"
    }
}

dependencies {
    modImplementation group: "earth.terrarium.handcrafted",
        name: "handcrafted-$modLoader-$minecraftVersion",
        version: handcraftedVersion
}
```

These coordinates are retained as an upstream project reference; they do not by themselves indicate publication of this Fabric 26.2 port to that Maven repository.

## Credits

Handcrafted is originally developed by its upstream authors. This repository documents the Minecraft 26.2 Fabric port and its compatibility changes.