# evv1e/waylandcraft architecture

> Architecture diagram of the GitHub repository evv1e/waylandcraft, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evv1e/waylandcraft
- Repository: https://github.com/evv1e/waylandcraft

## Overview

WaylandCraft is a Linux Minecraft mod that runs a Wayland compositor and presents application windows inside the Minecraft world. The main workflow is to launch or connect to an application, receive its surfaces through the native/Java bridge, render them as in-world displays, and forward player input back to the window. The README also documents an app launcher, window manager, window items, Xwayland support, and Iris shader compatibility. Some subsystem links rely on documented capabilities or index references; unsampled implementation details are not asserted.

Main entry points: [`src/main/java/dev/evvie/waylandcraft/WaylandCraft.java`](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/WaylandCraft.java) (Client Startup), [`native/src/lib.rs`](https://github.com/evv1e/waylandcraft/blob/main/native/src/lib.rs) (Wayland Runtime), [`src/main/java/dev/evvie/waylandcraft/bridge/WLCAbstractWindow.java`](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WLCAbstractWindow.java) (Window Surfaces), [`native/src/bridge/java_types.rs`](https://github.com/evv1e/waylandcraft/blob/main/native/src/bridge/java_types.rs) (JNI Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Compositor Runtime"]
  node_entry["Client Startup<br/>[WaylandCraft.java]"]
  node_native["Wayland Runtime<br/>[lib.rs]"]
  node_jni["JNI Bridge<br/>[java_types.rs]"]
  node_java_bridge["Java Bridge"]
  node_windows["Window Surfaces"]
  node_surface["Surface Buffers<br/>[WLCSurface.java]"]
end

subgraph group_interaction["World Interaction"]
  node_display["World Displays<br/>[WindowDisplay.java]"]
  node_input["Input Capture<br/>[WaylandCraft.java]"]
  node_grabs["Pointer Grabs"]
  node_wm["Window Manager"]
end

subgraph group_rendering["Window Rendering"]
  node_framebuffer["Window Framebuffer"]
  node_render_utils["Render Utilities<br/>[RenderUtils.java]"]
end

subgraph group_apps["Apps and Items"]
  node_launcher["App Launcher"]
  node_desktop["Desktop Entries<br/>[DesktopEntry.java]"]
  node_items["Window Items<br/>[WindowItem.java]"]
  node_item_sync["Window Item Sync"]
end

subgraph group_support["Mod Support"]
  node_settings["Settings"]
  node_network["Item Networking"]
  node_server_items["Server Item Manager"]
end

node_player(("Minecraft Player"))
node_linux_apps(("Linux Applications"))
node_xwayland["xwayland-satellite"]

node_player -->|"uses mod"| node_entry
node_entry -.->|"initializes"| node_native
node_native -->|"exposes JNI"| node_jni
node_jni -.->|"bridges calls"| node_java_bridge
node_java_bridge -.->|"updates windows"| node_windows
node_linux_apps -->|"connects through Wayland"| node_native
node_native -->|"starts optionally"| node_xwayland
node_windows -->|"owns root surface"| node_surface
node_surface -->|"renders commits"| node_framebuffer
node_framebuffer -->|"uses rendering helpers"| node_render_utils
node_entry -->|"manages displays"| node_display
node_display -->|"tests window surfaces"| node_windows
node_player -->|"provides input"| node_input
node_input -.->|"forwards input"| node_native
node_entry -->|"manages grabs"| node_grabs
node_wm -->|"selects windows"| node_windows
node_player -->|"opens screen"| node_wm
node_player -->|"opens launcher"| node_launcher
node_launcher -.->|"lists applications"| node_desktop
node_entry -->|"loads desktop entries"| node_desktop
node_player -->|"uses window items"| node_items
node_item_sync -->|"sends item updates"| node_network
node_network -->|"routes item payloads"| node_server_items
node_entry -->|"loads settings"| node_settings

click node_entry "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/WaylandCraft.java"
click node_native "https://github.com/evv1e/waylandcraft/blob/main/native/src/lib.rs"
click node_jni "https://github.com/evv1e/waylandcraft/blob/main/native/src/bridge/java_types.rs"
click node_java_bridge "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WaylandCraftBridge.java"
click node_windows "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WLCAbstractWindow.java"
click node_surface "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WLCSurface.java"
click node_display "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/displays/WindowDisplay.java"
click node_input "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/WaylandCraft.java"
click node_grabs "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/grabs/PointerGrabMap.java"
click node_wm "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/gui/WindowManagerScreen.java"
click node_launcher "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/gui/AppLauncherScreen.java"
click node_desktop "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/desktop/DesktopEntry.java"
click node_items "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/item/WindowItem.java"
click node_item_sync "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/item/WindowItemManager.java"
click node_framebuffer "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/render/WindowFramebuffer.java"
click node_render_utils "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/render/RenderUtils.java"
click node_settings "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/settings/WaylandCraftSettingsManager.java"
click node_network "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/network/WaylandCraftNetworking.java"
click node_server_items "https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/item/ServerItemManager.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_native,node_jni,node_java_bridge,node_windows,node_surface toneBlue
class node_display,node_input,node_grabs,node_wm toneAmber
class node_framebuffer,node_render_utils toneMint
class node_launcher,node_desktop,node_items,node_item_sync toneRose
class node_settings,node_network,node_server_items,node_player,node_linux_apps,node_xwayland toneIndigo
```

## Components

### Compositor Runtime

- [Client Startup](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/WaylandCraft.java): `src/main/java/dev/evvie/waylandcraft/WaylandCraft.java`
- [Wayland Runtime](https://github.com/evv1e/waylandcraft/blob/main/native/src/lib.rs): `native/src/lib.rs`
- [JNI Bridge](https://github.com/evv1e/waylandcraft/blob/main/native/src/bridge/java_types.rs): `native/src/bridge/java_types.rs`
- [Java Bridge](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WaylandCraftBridge.java): `src/main/java/dev/evvie/waylandcraft/bridge/WaylandCraftBridge.java`
- [Window Surfaces](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WLCAbstractWindow.java): `src/main/java/dev/evvie/waylandcraft/bridge/WLCAbstractWindow.java`
- [Surface Buffers](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/bridge/WLCSurface.java): `src/main/java/dev/evvie/waylandcraft/bridge/WLCSurface.java`

### World Interaction

- [World Displays](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/displays/WindowDisplay.java): `src/main/java/dev/evvie/waylandcraft/displays/WindowDisplay.java`
- [Input Capture](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/WaylandCraft.java): `src/main/java/dev/evvie/waylandcraft/WaylandCraft.java`
- [Pointer Grabs](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/grabs/PointerGrabMap.java): `src/main/java/dev/evvie/waylandcraft/grabs/PointerGrabMap.java`
- [Window Manager](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/gui/WindowManagerScreen.java): `src/main/java/dev/evvie/waylandcraft/gui/WindowManagerScreen.java`

### Window Rendering

- [Window Framebuffer](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/render/WindowFramebuffer.java): `src/main/java/dev/evvie/waylandcraft/render/WindowFramebuffer.java`
- [Render Utilities](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/render/RenderUtils.java): `src/main/java/dev/evvie/waylandcraft/render/RenderUtils.java`

### Apps and Items

- [App Launcher](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/gui/AppLauncherScreen.java): `src/main/java/dev/evvie/waylandcraft/gui/AppLauncherScreen.java`
- [Desktop Entries](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/desktop/DesktopEntry.java): `src/main/java/dev/evvie/waylandcraft/desktop/DesktopEntry.java`
- [Window Items](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/item/WindowItem.java): `src/main/java/dev/evvie/waylandcraft/item/WindowItem.java`
- [Window Item Sync](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/item/WindowItemManager.java): `src/main/java/dev/evvie/waylandcraft/item/WindowItemManager.java`

### Mod Support

- [Settings](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/settings/WaylandCraftSettingsManager.java): `src/main/java/dev/evvie/waylandcraft/settings/WaylandCraftSettingsManager.java`
- [Item Networking](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/network/WaylandCraftNetworking.java): `src/main/java/dev/evvie/waylandcraft/network/WaylandCraftNetworking.java`
- [Server Item Manager](https://github.com/evv1e/waylandcraft/blob/main/src/main/java/dev/evvie/waylandcraft/item/ServerItemManager.java): `src/main/java/dev/evvie/waylandcraft/item/ServerItemManager.java`

### Other components

- **Minecraft Player**
- **Linux Applications**
- **xwayland-satellite**

## Connections

- Minecraft Player → Client Startup: uses mod (evidence: `README.md`)
- Client Startup → Wayland Runtime: initializes
- Wayland Runtime → JNI Bridge: exposes JNI (evidence: `native/src/lib.rs`)
- JNI Bridge → Java Bridge: bridges calls
- Java Bridge → Window Surfaces: updates windows
- Linux Applications → Wayland Runtime: connects through Wayland (evidence: `README.md`)
- Wayland Runtime → xwayland-satellite: starts optionally (evidence: `README.md`)
- Window Surfaces → Surface Buffers: owns root surface (evidence: `src/main/java/dev/evvie/waylandcraft/bridge/WLCAbstractWindow.java`)
- Surface Buffers → Window Framebuffer: renders commits (evidence: `src/main/java/dev/evvie/waylandcraft/bridge/WLCSurface.java`)
- Window Framebuffer → Render Utilities: uses rendering helpers (evidence: `src/main/java/dev/evvie/waylandcraft/render/WindowFramebuffer.java`)
- Client Startup → World Displays: manages displays (evidence: `src/main/java/dev/evvie/waylandcraft/WaylandCraft.java`)
- World Displays → Window Surfaces: tests window surfaces (evidence: `src/main/java/dev/evvie/waylandcraft/displays/WindowDisplay.java`)
- Minecraft Player → Input Capture: provides input (evidence: `README.md`)
- Input Capture → Wayland Runtime: forwards input
- Client Startup → Pointer Grabs: manages grabs (evidence: `src/main/java/dev/evvie/waylandcraft/WaylandCraft.java`)
- Window Manager → Window Surfaces: selects windows (evidence: `src/main/java/dev/evvie/waylandcraft/gui/WindowManagerScreen.java`)
- Minecraft Player → Window Manager: opens screen (evidence: `README.md`)
- Minecraft Player → App Launcher: opens launcher (evidence: `README.md`)
- App Launcher → Desktop Entries: lists applications
- Client Startup → Desktop Entries: loads desktop entries (evidence: `src/main/java/dev/evvie/waylandcraft/desktop/XDGDesktopManager.java`)
- Minecraft Player → Window Items: uses window items (evidence: `README.md`)
- Window Item Sync → Item Networking: sends item updates (evidence: `src/main/java/dev/evvie/waylandcraft/item/WindowItemManager.java`)
- Item Networking → Server Item Manager: routes item payloads (evidence: `src/main/java/dev/evvie/waylandcraft/item/ServerItemManager.java`)
- Client Startup → Settings: loads settings (evidence: `src/main/java/dev/evvie/waylandcraft/settings/WaylandCraftSettingsManager.java`)
