--- title: "Requests API - Sorted wiki" description: "Have Sorted take exact amounts of items from the containers around the player, or put them away." url: https://voxelsprout.com/sorted/wiki/requests-api --- [Sorted](https://voxelsprout.com/sorted) [Wiki](https://voxelsprout.com/sorted/wiki) Requests API # Requests API Have Sorted take exact amounts of items from the containers around the player, or put them away. For a mod that knows what the player needs, such as a build's materials list. `SortedRequests` has Sorted's nearby transfer, the one Quick Fill and Smart Empty use, move exactly the amounts you ask for between the player's inventory and the containers in reach and in sight. [BuildPrint](https://voxelsprout.com/buildprint)'s **Take from chests** and **Put away extras** are made with it. From Sorted **0.1.46**. ## Take or put away ```java // Why it can't start now, in the player's language, or null. String why = SortedRequests.problem("take"); if (why != null) { showToPlayer(why); return; } // At most this many of each into the inventory. True when it started. SortedRequests.take("mymod", Map.of("minecraft:stone", 70, "minecraft:glass", 15)); // Or away: Integer.MAX_VALUE is all of it. SortedRequests.putAway("mymod", Map.of("minecraft:oak_planks", 64)); ``` Item ids as `minecraft:stone`. The owner is your mod id: Sorted keeps each owner's last request, so you can read how it went after it finished. ## Follow it ```java // Each tick, until it is over. if (!SortedRequests.isRunning("mymod")) { Map moved = SortedRequests.moved("mymod"); // item id -> count, positive both ways String result = SortedRequests.result("mymod"); // done, partial, stopped or refused tellPlayer(moved, result); } ``` | Result | Means | | ------- | ------------------------------------------------------------------------------------------------------------- | | running | Still going. | | done | Every amount met. | | partial | Finished with some not met: not found nearby, or no room left. | | stopped | By stop, by the player opening a screen or starting a transfer of their own, or the server stopped answering. | | refused | Did not start: problem was not null, or the map asked for nothing. | Sorted says nothing to the player when a request ends. Tell them yourself, from `moved` and `result`. ## How it moves items * Never more of an item than asked: part of a stack is split off. The main inventory comes first, then the hotbar. Armor and the offhand are never touched. * `take` first opens the containers Sorted's [Chest memory](https://voxelsprout.com/sorted/wiki/chest-memory) says hold an item asked for, then the ones it does not know or has not seen lately. One it saw lately without any of them stays shut. It stops once every amount is met or nothing more fits. * `putAway` goes where Smart Empty would put the items: a container that already holds them first, then the best fit. "All of it" means all the player may move, so a request that leaves only kept stacks behind is `done`. * The player's rules stay in charge: the container blacklist is left alone, kept items (keep rules, favorites, slots a mod protects with [SortedProtection](https://voxelsprout.com/sorted/wiki/protection-api)) are not put away, and a `LOCKED` slot gets nothing. * On a server a request takes a while: each container is opened unseen in turn, with Sorted's progress card showing. In singleplayer it is done at once. The containers used light up, as after a Quick Stack. ## When it can not start `problem("take")` and `problem("put_away")` say why, in the player's language: the server turned Quick Fill (take) or Quick Stack (put away) off, the player switched sorting off in Sorted's settings, another nearby transfer is running, or a container screen is open. Only one nearby transfer runs at a time across Sorted, the player's or any mod's. ## Without a compile dependency ```java static boolean takeWithSorted(Map amounts) { try { Class r = Class.forName("com.sorted.api.SortedRequests"); if (r.getMethod("problem", String.class).invoke(null, "take") != null) return false; return (Boolean) r.getMethod("take", String.class, Map.class).invoke(null, "mymod", amounts); } catch (ReflectiveOperationException e) { return false; // Sorted is not installed, or older than 0.1.46. } } ``` ## Reference | SortedRequests | What it does | | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | isAvailable() | Sorted is running, in a world, and not off on this server. | | problem(String kind) | Why a "take" or "put\_away" can not start now, in the player's language. Null when it can. | | take(String owner, Map amounts) | At most that many of each item into the inventory. True when it started (in singleplayer: ran). | | putAway(String owner, Map amounts) | At most that many of each item away. Integer.MAX\_VALUE is all of it. True when it started. | | isRunning(String owner) | Your request is still moving items. | | stop(String owner) | Stops it, as a second press of Quick Stack does. False when it is not running. | | moved(String owner) | What your last request moved, item id to count. Final once it is no longer running. | | result(String owner) | running, done, partial, stopped or refused. Null when you never asked. | ## Next, you may want to * [Keep protected slots out of it Protection API](https://voxelsprout.com/sorted/wiki/protection-api) * [Works with BuildPrint Works with BuildPrint](https://voxelsprout.com/sorted/wiki/works-with-buildprint) [Previous Input API](https://voxelsprout.com/sorted/wiki/input-api) Something missing or wrong on this page? Say so on [Discord](https://discord.gg/CvdkGbEW4y).