> For the complete documentation index, see [llms.txt](https://docs.quickclient.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quickclient.cc/en/examples/auto-soup.md).

# Auto soup

A script that eats mushroom stew on low health and restores the slot.

When health drops, the script eats mushroom stew: it switches to it in the hotbar, holds it for a couple of ticks, presses the right mouse button and switches the slot back. The example shows how to work with a slot handle, count time in ticks and avoid getting in the way of the player's own actions.

```java
package my;

import hex.script.api.CheckBox;
import hex.script.api.HeldSlot;
import hex.script.api.Script;
import hex.script.api.Slider;

import java.util.Random;

public class AutoSoup extends Script {

    private static final String SOUP = "mushroom_stew";

    private final Slider health = slider("Health", 12f, 1f, 19f, 1f);
    private final Slider delayFrom = slider("Delay from", 3f, 0f, 20f, 1f).postfix("t");
    private final Slider delayTo = slider("Delay to", 5f, 0f, 20f, 1f).postfix("t");
    private final Slider holdTicks = slider("Hold before eating", 2f, 0f, 20f, 1f).postfix("t");
    private final CheckBox keepItemUse = checkBox("Don't interrupt item use", true);

    private final Random random = new Random();

    private HeldSlot held;
    private int sinceSoup;
    private int sinceHold;
    private int nextDelay;

    @Override
    public String description() {
        return "Eats soup when health is low and restores the slot";
    }

    @Override
    public void activate() {
        held = null;
        sinceSoup = 0;
        nextDelay = 0;
    }

    @Override
    public void deactivate() {
        release();
    }

    @Override
    public void onTick() {
        sinceSoup++;
        if (!player().present()) {
            release();
            return;
        }

        if (held != null) {
            holdTick();
            return;
        }

        int soup = inventory().findHotbar(SOUP);
        boolean handFree = !keepItemUse.value() || !player().using();
        if (soup >= 0 && handFree && player().health() <= health.value() && sinceSoup >= nextDelay) {
            held = slots().select(soup);
            sinceHold = 0;
        }
    }

    private void holdTick() {
        if (!inventory().slot(held.slot()).is(SOUP)) {
            release();
            return;
        }
        if (++sinceHold < holdTicks.intValue()) return;

        interaction().useItem(false);
        release();
        rollDelay();
        sinceSoup = 0;
    }

    private void release() {
        if (held == null) return;
        held.restoreWhenSafe();
        held = null;
    }

    private void rollDelay() {
        int from = delayFrom.intValue();
        int to = delayTo.intValue();
        nextDelay = to <= from ? from : from + random.nextInt(to - from);
    }
}
```

## How it works

**Slot selection and click in different ticks.** `slots().using(...)` would do both at once. Here the slot is selected with `slots().select(...)`, held for `holdTicks` ticks, and only then the click happens. That is what the manual `HeldSlot` form is for. `restoreWhenSafe()` restores the slot on the next tick and does not interrupt item use.

**Checking the handle every tick.** While the slot is held, the soup can disappear from it: it was eaten, dropped or moved by another module. Then the `is(SOUP)` check fails and the slot is restored right away. The most common mistake in scripts like this is a handle that was never released, so `deactivate()` releases it too.

**Random pause between soups.** Two sliders set a range, and `rollDelay()` picks a number inside it after each soup. The interval is different every time.

**Counting in ticks.** `tasks()` counts real time, while the server cares about ticks. Counters in fields and `onTick()` give exactly the timing the server sees.

**The keepItemUse setting.** Right click is not only for eating. Without this setting the script would interrupt a drawn bow or a potion the player is drinking.

**Soup from the hotbar only.** The script cannot move soup from the inventory to the hotbar: the API only allows clicks in an open container, not in your own inventory. More in [Containers and screens](/en/game/containers.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.quickclient.cc/en/examples/auto-soup.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.