# Ground Items
* **Smart Filtering**: Match items by name, ID, or regex patterns
* **Priority System**: Set custom pickup priorities for different items
* **Distance Management**: Control pickup range and movement
* **Combat Awareness**: Handle pickup during combat situations
* **Inventory Management**: Check for available space before pickup
* **Noted Item Support**: Handle both noted and unnoted items
* **RS3 Loot Interface**: Automatically interact with RuneScape 3's looting interface
The framework integrates with RuneScape 3's built-in looting system, automatically opening and managing the loot interface when multiple items are available for pickup, as shown below:
This allows for efficient bulk pickup of items while maintaining the priority system and filtering rules you've configured.
### 🚀 Quick Access
The ground item pickup framework is accessed through the scene property:
class MyScript : SuspendableScript() {
val pickup = this.scene.pickup {
item(itemName = "Red Dragonhide", itemPriority = PickupItemPriority.VERY_HIGH)
item("Leather gloves", itemPriority = PickupItemPriority.VERY_LOW)
}
override suspend fun onLoop() {
pickup.pickup()
}
}
### 📚 Available Methods
The pickup framework provides several configuration methods:
* `global(config)` - Set global defaults for all items
* `item(name/id/regex)` - Add items to pickup list
* `items(vararg items)` - Add multiple items at once
* `build(script)` - Create the pickup instance
🎨 DSL Pattern (Recommended)
#### Basic Configuration
```kotlin
val pickup = this.scene.pickup {
item("Dragon hide") // Pickup by name
item(12345) // Pickup by ID
item(Regex(".*gloves.*")) // Pickup by regex pattern
}
```
#### Advanced Item Configuration
```kotlin
val pickup = this.scene.pickup {
global {
distance(15) // Maximum pickup distance
itemPriority(PickupItemPriority.MEDIUM) // Default priority
pickupInCombat(true) // Allow pickup during combat
priorityOrder( // Main sorting order
PickupPriority.DISTANCE,
PickupPriority.QUANTITY,
PickupPriority.PRICE
)
}
item("Rare item",
amount = 5, // Specific amount to pickup
notedStatus = NotedStatus.NOTED_ONLY, // Only pickup noted versions
distance = 20, // Custom distance for this item
pickupInCombat = true, // Allow pickup in combat
itemPriority = PickupItemPriority.VERY_HIGH // High priority
)
item("Common item", itemPriority = PickupItemPriority.LOW)
}
```
🔧 Builder Pattern
#### Traditional Builder Usage
```kotlin
val pickup = ScenePickupBuilder()
.global {
distance(10)
itemPriority(PickupItemPriority.MEDIUM)
pickupInCombat(false)
}
.item("Iron ore")
.item("Coal")
.item("Gold ore", itemPriority = PickupItemPriority.HIGH)
.build(this)
```
### 📊 Pickup Results
The framework provides detailed result information through `PickupMessages` enum:
| Result | Description |
| ------------------- | ------------------------------------- |
| `NO_ITEMS_FOUND` | No matching items found on ground |
| `LOOTING_INTERFACE` | Successfully opened looting interface |
🎯 Pickup Priority / Sorting
Primary Priority (Item Priority)
Item Priority Levels
The framework uses a two-tier priority system:
**Primary Priority (Item Priority)**
| Priority | Description | Pickup Order |
| ----------- | ---------------------- | --------------------------------------- |
| `VERY_HIGH` | Highest priority items | Picked up first, regardless of distance |
| `HIGH` | High priority items | Second priority |
| `MEDIUM` | Default priority level | Third priority |
| `LOW` | Low priority items | Fourth priority |
| `VERY_LOW` | Lowest priority items | Picked up last |
**Secondary Priority (Main Sorting)**
Applied within the same priority group:
| Sorting Type | Description | Order |
| ------------ | ---------------------- | ------------------------ |
| `DISTANCE` | Distance-based sorting | Closer items first |
| `QUANTITY` | Quantity-based sorting | Higher quantities first |
| `PRICE` | Value-based sorting | Higher value items first |
#### Priority Examples
```kotlin
// Example: Dragon hide is closer, but gloves have higher priority
.item("Dragon hide", itemPriority = PickupItemPriority.LOW) // Distance 2
.item("Leather gloves", itemPriority = PickupItemPriority.VERY_HIGH) // Distance 10
// Result: Gloves picked up first, then Dragon hide
// Even though Dragon hide is much closer!
```
Secondary Priority (Main Sorting)
| Sorting Type | Description | Order |
| ------------ | ---------------------- | ------------------------ |
| `DISTANCE` | Distance-based sorting | Closer items first |
| `QUANTITY` | Quantity-based sorting | Higher quantities first |
| `PRICE` | Value-based sorting | Higher value items first |
> **Note**: You can reorder the global priority ordering by changing the sequence in the `priorityOrder()` method. For example, to prioritize quantity over distance, use `priorityOrder(PickupPriority.QUANTITY, PickupPriority.DISTANCE, PickupPriority.PRICE)`.
### 🔄 Integration Example
The pickup framework integrates seamlessly with `SuspendableScript`:
```kotlin
class TestScript : SuspendableScript() {
val item = this.scene.pickup {
item(itemName = "Red Dragonhide", itemPriority = PickupItemPriority.VERY_HIGH)
item("Leather gloves")
}
override suspend fun onLoop() {
println(item.pickup().name)
}
}
```
### 🔍 Search Modes
The framework supports three search modes for item identification:
* `NAME` - Exact name matching (case-insensitive)
* `ID` - Item ID matching
* `REGEX` - Pattern matching with regular expressions
```kotlin
.item("Dragon bones")
.item(12345)
.item(Regex(".*dragon.*"))
```
### 📋 Noted Item Support
Control pickup of noted vs unnoted items:
* `UNNOTED` - Only pickup unnoted items
* `NOTED_ONLY` - Only pickup noted items
* `BOTH` - Pickup both noted and unnoted items
```kotlin
.item("Dragon bones", notedStatus = NotedStatus.NOTED_ONLY)
.item("Rare item", notedStatus = NotedStatus.UNNOTED)
```
***
---
# 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:
```
GET https://kxapi.gitbook.io/kxapi/scene/ground-items.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.