paper-plugin/README.md

# DreamWall AfterBlock Paper Bridge

This is the Minecraft server bridge for DreamWall: AfterBlock Museum.

The hackathon Space is the official submission surface. This plugin scaffold is the live-demo layer: it connects a Paper server to the Space API and prepares the path for placing generated wall art inside Minecraft.

## Current Demo Behavior

- `/dreamwall` shows the configured Space endpoint.
- `/dreamwall fetch` calls the Space app domain and confirms the bridge can reach Hugging Face.
- `/dreamwall pack` asks the player client to load the Hugging Face-hosted `AfterBlockMuseum.zip` resource pack.
- `/dreamwall demo` places a safe local pedestal proof, spawns an `ItemDisplay` relic, engraves the name/caption in-world, adds a lectern passport book and profile button, and gives the player a Paper item with `CustomModelData 730002`.
- `/dreamwall import` calls the live `quick_curate` Gradio endpoint, parses the returned `dreamwall.museum.v1` packet, places a packet-derived pedestal/`ItemDisplay`/engraved nameplate/lectern passport/profile button/item at the artifact coordinates, marks the living entry atlas, paints a lit route from `YOU ARE HERE` to that plot, and gives the player a route compass.
- `/dreamwall import object | story | @owner` lets a visitor paste the command generated by the Hugging Face Space so their own object, story, and signature are imported without server-owner config changes.
- `/dreamwall import here` uses the same live packet but places it two blocks in front of the player for fast video proof.
- `/dreamwall museum where` prints the coordinate contract used by the Space and server.
- `/dreamwall museum build` creates the 12 x 12 living museum campus at the configured origin, with plot pads, memory rails, hall gates, banner markers, a physical entry atlas, and a `YOU ARE HERE` entry.
- `/dreamwall museum check` verifies that all 144 plot pads, relic focus blocks, the entry beacon, and the living entry atlas exist in the current world.
- A scheduled task can be extended to poll approved museum artifacts.
- The Space now emits `dreamwall.museum.v1`, the main AfterBlock packet for the hackathon demo.
- The Space also emits `living_canvas.mc.v1` for the secondary wall/canvas mode.

## Planned Placement Behavior

The main Space endpoint is `quick_curate`, which emits `dreamwall.museum.v1` with:

- artifact title
- owner handle
- hall and zone
- plot and coordinates
- block palette/materials
- plaque text
- spirit first line
- passport QR payload
- curation scores
- resonance links

Implemented `/dreamwall import` V1 behavior:

1. Fetch latest artifact packet.
2. Place pedestal/sign/painting marker at coordinates.
3. Display plaque line and owner handle.
4. Place a written-book passport on a lectern so visitors can open the relic profile/history in Minecraft.
5. Mark the entry atlas and paint a lit route from the entry beacon to the generated plot.
6. Set the player's compass target and give a named route compass for the relic.
7. Optionally create particles or a simple animation based on artifact type.

The legacy `generate_art` endpoint emits a `dreamwall.mc.v1` JSON packet with:

- `job_id`
- `player`
- `prompt`
- `gallery_zone`
- `origin`
- `palette`
- `plot`
- `market`
- `grid.row_runs`
- WorldEdit preview lines

The secondary canvas path uses `living_canvas.mc.v1` from the `living_canvas` endpoint:

- `tile_size_blocks`: `32 x 32`
- `canvas_size_tiles`: `12 x 12`
- `minecraft_wall_size_blocks`: `384 x 384`
- `tiles[].minecraft_origin`
- `tiles[].minecraft_bounds`
- `tiles[].stage`
- `tiles[].weather`
- `fusion_links`
- `evolution_events`
- `minecraft_animation_plan`

The plugin should treat each tile as a stable wall address. Motion comes from particles, map updates, or block-frame updates, not from moving the artifact to a new plot.

The next plugin step is converting `grid.row_runs` into wall block placement:

```text
origin + (x, -y, 0) -> block
```

The Space also emits a `neuropets.mc.v1` packet from the `hatch_pet` endpoint. The server can use it to create:

- named creature sign
- armor stand / mob placeholder
- habitat marker
- particle effect
- leaderboard entry

For the hackathon video, the safest route is:

1. Run AfterBlock Museum in the Space.
2. Copy the `dreamwall.museum.v1` packet or call the Gradio API.
3. Place one artifact pedestal/sign at `museum.coordinates`.
4. Add signs for owner, title, hall, plaque, and spirit first line.
5. Use particles around the pedestal for the artifact spirit.
6. Walk through the museum gallery.

## Flat World Canvas

Recommended V1 canvas:

- Flat Paper world
- `12 x 12` plots
- `32 x 32` blocks per plot
- Canvas origin: `-192, 80, -192`
- Use signs or floating text later for creator, prompt, value, and fusion history.

The Space assigns the plot. The plugin should trust the packet and place the mural at:

```text
canvas_origin + plot.x * plot_size, y=80, canvas_origin_z + plot.z * plot_size
```

For `living_canvas.mc.v1`, the packet already includes `tiles[].minecraft_origin`, so the plugin can skip recomputing the address.

## Build

GitHub Actions builds the jar through `.github/workflows/build-plugin.yml`.

Local build, if Maven is installed:

```bash
mvn package
```

The jar will be in `target/dreamwall-paper-bridge-0.1.0.jar`.

## Install

1. Stop the PebbleHost Paper server.
2. Upload the jar to `plugins/`.
3. Upload or link the `resource-pack/AfterBlockMuseum/` zip as a server resource pack if you want custom item rendering. The default config can also request the Hugging Face-hosted pack with `/dreamwall pack`.
4. Start the server.
5. Edit `plugins/DreamWall/config.yml` if needed.
6. Run `/dreamwall fetch` in game or console.
7. Run `/dreamwall pack` in game and accept the resource pack.
8. Run `/dreamwall museum build` once to create the coordinate-accurate museum campus and physical entry atlas.
9. Run `/dreamwall museum check` to confirm the built world matches the Space coordinate map and atlas contract.
10. Run `/dreamwall demo` in game to place a pedestal proof, visible `ItemDisplay`, engraved name/caption, lectern passport, profile button, and receive the AirPods demo item.
11. Run `/dreamwall import object | story | @owner` from the Space to place a live Hugging Face artifact packet at its generated plot, update the route trail, receive the route compass, and right-click the profile button for the relic history, or `/dreamwall import here object | story | @owner` for a nearby proof.

## Local Server Proof

Codex verified the plugin in a temporary Paper server:

```text
Paper 1.21.4 build 232
Java Temurin 21.0.11
commands: dreamwall, dreamwall fetch, dreamwall pack, stop
```

Proof artifact:

```text
artifacts/stress/paper_plugin_local_load_test.json
```