Desktop API Interactive Guide

Mental Model

Decision Path

1. Does the feature use a real server menu? If not, keep it outside Salt or build a custom session model first.
2. Are the displayed items real slots? Use Salt slot routing for real slots and virtual entries for fake items.
3. Does the screen send custom packets? Convert screen-global packets to Salt session payloads.
4. Does the texture include player inventory? Crop the machine area and do not draw duplicated player inventory.

What You Usually Build

public final class MyCompat {
    public static void initClient() {
        SaltsInventoryDesktopApi.registerClientWindow(MyMenus.MY_MENU, new MyWindow());
    }

    public static void initServer() {
        SaltsInventoryDesktopApi.registerServerWindow(MyMenus.MY_MENU, new MyServerWindow());
    }
}

A simple storage menu might only need real slot positions. A furnace-like machine usually also needs a cropped background, progress textures, and a recipe-book button. A terminal often needs virtual entries and custom payloads.

Showstoppers

If any box applies, write the compat layer around that behavior first. Unknown modded menus should keep opening their original screens until the integration is explicit.

Pick A Pattern

Rework Checklist

1. Extract the machine/container UI from the old Screen renderer.
2. Move client-only UI state into the desktop state object or synced data.
3. Replace screen-global packets with Salt payloads for session-specific actions.
4. Return real menu slot ids from slotAt.
5. Test normal click, shift-click, drag distribution, double-click, carried stacks, ghost pin, and reopen.

Basic Registration

public static void initClient() {
    MenuType<MyMenu> menu = findMenu("other_mod:my_menu");
    if (menu != null) {
        SaltsInventoryDesktopApi.registerClientWindow(menu, new MyWindow());
    }
}

public static void initServer() {
    MenuType<MyMenu> menu = findMenu("other_mod:my_menu");
    if (menu != null) {
        SaltsInventoryDesktopApi.registerServerWindow(menu, new MyServerWindow());
    }
}

Register both sides for a captured modded menu. A client-only definition can exist, but it does not make an unknown server menu desktop-managed by itself.

Predicate Registration

SaltsInventoryDesktopApi.registerClientWindowPredicate(
    Identifier.fromNamespaceAndPath("my_mod", "dynamic_storage"),
    100,
    context -> context.sourceKey().startsWith("block:"),
    context -> new DynamicStorageWindow()
);

Use predicates when one MenuType has multiple layouts or when the source key decides which desktop window should be used.

Optional Compat

private static @Nullable MenuType<?> findMenu(String id) {
    Identifier key = Identifier.tryParse(id);
    return key == null ? null : BuiltInRegistries.MENU.getOptional(key).orElse(null);
}

Keep optional mod references guarded. Prefer registry ids, optional entrypoints, or small reflection helpers over hard class references in always-loaded code.

Lifecycle Hooks

Minimal Slot Window

public final class MyWindow implements DesktopWindowDefinition<MyMenu, MyWindow.State> {
    public static final class State {
        int scroll;
    }

    @Override
    public State createState(DesktopWindowSetupContext<MyMenu> context) {
        return new State();
    }

    @Override
    public DesktopWindowSize defaultSize(DesktopWindowSetupContext<MyMenu> context) {
        return DesktopWindowSize.of(8 + 9 * 18 + 8, 16 + 8 + 3 * 18 + 8);
    }

    @Override
    public void render(DesktopRenderContext<MyMenu, State> context) {
        int x = context.contentX();
        int y = context.contentY();
        for (int i = 0; i < 27; i++) {
            context.renderSlot(i, x + i % 9 * 18, y + i / 9 * 18);
        }
    }
}

Window Size vs Content Size

Start drawing at context.contentX() and context.contentY(). Return a defaultSize large enough for title bar, padding, and content. In current examples that is usually 8 + contentWidth + 8 wide and 16 + 8 + contentHeight + 8 tall.

Real Slot Routing

@Override
public DesktopSlotHit slotAt(DesktopSlotContext<MyMenu, State> context, double mouseX, double mouseY) {
    int x = context.contentX();
    int y = context.contentY();

    DesktopSlotHit input = context.hitSlot(0, x + 56, y + 17, mouseX, mouseY);
    if (input != null) return input;

    return context.hitSlot(1, x + 116, y + 35, mouseX, mouseY);
}

Return the index into menu.slots, not visual order. If you think in container slot indexes, use containerSlot(...), containerSlotHit(...), and menuSlotId(...).

Slot Rendering Choices

Text Input

public static final class State {
    final DesktopTextBoxState search = new DesktopTextBoxState();
}

@Override
public void render(DesktopRenderContext<MyMenu, State> context) {
    DesktopWidgets.renderTextBox(context, context.state().search, context.contentX(), context.contentY(), 120);
}

@Override
public boolean mouseClicked(DesktopInputContext<MyMenu, State> context, MouseButtonEvent event, boolean doubleClick) {
    return DesktopWidgets.clickTextBox(context.state().search, event, context.contentX(), context.contentY(), 120);
}

@Override
public boolean wantsTextInput(DesktopWindowContext<MyMenu, State> context) {
    return DesktopWidgets.wantsTextInput(context.state().search);
}

Always implement wantsTextInput for focused text boxes. That tells Salt to suppress movement and normal UI hotkeys while the player is typing.

Virtual Items

List<DesktopVirtualItem> visible = entries.stream()
    .map(entry -> new DesktopVirtualItem(entry.stack(), entry.count()))
    .toList();

DesktopWidgets.renderVirtualItemGrid(context, visible, firstIndex, gridX, gridY, columns, rows);

int index = DesktopWidgets.virtualItemIndexAt(
    event.x(), event.y(), gridX, gridY, columns, rows, firstIndex, visible.size()
);
if (index >= 0) {
    context.sendPayload(PULL_CHANNEL, new PullPayload(index), PullPayload.CODEC);
    return true;
}

Virtual entries are not slots. Do not return DesktopSlotHit for them.

Server Handler

public final class MyServerWindow implements DesktopServerWindowHandler<MyMenu, MyServerWindow.State> {
    public static final class State {
        long lastHash;
    }

    @Override
    public State createState(DesktopServerSessionContext<MyMenu, State> context) {
        return new State();
    }

    @Override
    public void tick(DesktopServerSessionContext<MyMenu, State> context) {
        context.broadcastChanges();
    }
}

Hidden ghost sessions still tick and validate through the desktop session manager. closed means the live session is really ending, not just becoming a ghost preview.

Typed And Raw Payloads

public record ModePayload(int mode) {
    public static final StreamCodec<RegistryFriendlyByteBuf, ModePayload> CODEC =
        StreamCodec.composite(ByteBufCodecs.INT, ModePayload::mode, ModePayload::new);
}

SaltsInventoryDesktopApi.registerServerPayload(MyMenus.MY_MENU, MY_CHANNEL, ModePayload.CODEC, (context, payload) -> {
    context.menu().setMode(payload.mode());
    context.broadcastChanges();
});

context.sendPayload(MY_CHANNEL, new ModePayload(2), ModePayload.CODEC);

SaltsInventoryDesktopApi.registerServerPayload(MyMenus.MY_MENU, MY_CHANNEL, context -> {
    byte[] data = context.data();
    int mode = decodeMode(data);
    context.menu().setMode(mode);
    context.broadcastChanges();
});

context.sendPayload(MY_CHANNEL, encodeMode(2));

Keep payloads small and session-scoped. Salt's networking layer is designed around a 32 KiB cap.

When To Use Payloads

• Use normal slot clicks for real inventory slots.
• Use sendMenuButton for vanilla-style menu buttons.
• Use payloads for selected tabs, terminal actions, custom sort modes, fake entries, and special server commands.

Cropped Furnace-Like Background

private static final Identifier MY_SCREEN_TEXTURE =
    Identifier.fromNamespaceAndPath("my_mod", "textures/gui/my_machine.png");
private static final int TEXTURE_WIDTH = 256;
private static final int TEXTURE_HEIGHT = 256;
private static final int MACHINE_WIDTH = 176;
private static final int MACHINE_HEIGHT = 84;

@Override
public DesktopWindowSize defaultSize(DesktopWindowSetupContext<MyMenu> context) {
    return DesktopWindowSize.of(8 + MACHINE_WIDTH + 8, 16 + 8 + MACHINE_HEIGHT + 8);
}

@Override
public void render(DesktopRenderContext<MyMenu, State> context) {
    int x = context.contentX();
    int y = context.contentY();

    context.texture(MY_SCREEN_TEXTURE, x, y, 0, 0,
        MACHINE_WIDTH, MACHINE_HEIGHT,
        MACHINE_WIDTH, MACHINE_HEIGHT,
        TEXTURE_WIDTH, TEXTURE_HEIGHT);

    context.texturelessSlot(0, x + 56, y + 17);
    context.texturelessSlot(1, x + 56, y + 53);
    context.texturelessSlot(2, x + 116, y + 35);
}

Use texturelessSlot only when your cropped texture already has slot backgrounds. Otherwise use renderSlot or draw slotBackground first.

Recipe Book

@Override
public RecipeBookComponent<?> createRecipeBook(DesktopWindowContext<MyMenu, State> context) {
    return MyClientReflect.createRecipeBook(context.menu());
}

@Override
public boolean mouseClicked(DesktopInputContext<MyMenu, State> context, MouseButtonEvent event, boolean doubleClick) {
    if (recipeButton.contains(event.x(), event.y())) {
        context.toggleRecipeBook();
        return true;
    }
    return false;
}

On 1.20.1 and 1.21.1, return raw RecipeBookComponent instead of RecipeBookComponent<?>.

Resize And Snap

@Override
public DesktopResizePolicy resizePolicy(DesktopWindowContext<MyMenu, State> context) {
    return DesktopResizePolicy.STORAGE_GRID;
}

@Override
public DesktopWindowSize snapSize(DesktopWindowContext<MyMenu, State> context) {
    int columns = Math.max(1, context.contentWidth() / 18);
    int rows = Math.max(1, context.contentHeight() / 18);
    return DesktopWindowSize.of(8 + columns * 18 + 8, 16 + 8 + rows * 18 + 8);
}

Use fixed windows for functional machine UIs. Use storage-grid resizing only when the window can add or remove visible rows or columns cleanly.

Inherited Desktop Behavior

Do not rebuild these features in your definition. Add hooks such as ghosted() only for local visual state or preview-specific effects.

Common Failure Modes

Debug Checklist

1. Log the menu registry id and slot count when registering.
2. Render temporary labels for menu slot ids while aligning hitboxes.
3. Test one slot click before adding custom widgets.
4. Test one payload before adding complex state syncing.
5. Compare behavior with the original screen for shift-click and result slots.

Context Quick Reference

Version Summary