Contextual Inventory

Contextual Inventory is a smart hotbar assistant Fabric mod for Minecraft that automatically selects the most appropriate item based on what you're doing. Whether you're mining, fighting, eating, or exploring dark caves, your hotbar adapts in real time-no manual scrolling required.

The goal is seamless gameplay flow with minimal interruption. The mod reacts to your environment and actions, keeping the right tool, weapon, or item ready while still letting you override its choices when you want full control.

Key Features

• Smart tool selection - Automatically picks the best tool when looking at mineable blocks (pickaxe for stone, axe for wood, shovel for dirt, etc.).
• Combat awareness - Instantly switches to your strongest weapon when hostiles are nearby or when you take damage.
• Food management - Surfaces food items when your hunger is low or your health drops below a threshold.
• Lighting assistance - Selects torches or lanterns when you enter dark areas (light level below threshold).
• Intent Lock system - Manual hotbar changes temporarily disable auto-selection so your choice is respected.
• Audio & visual feedback - Optional action bar messages and sound cues when items are switched.
• Fully configurable - All thresholds, timings, and behaviors can be customized via a JSON config file.

How It Works

Context Detection

Every few game ticks (configurable, default: 4 ticks), the mod analyzes your current situation:

Item Selection Priority

Based on the detected context, the mod selects the most suitable hotbar slot using this priority system:

Supported Tools & Blocks

The mod uses Minecraft's block tags to determine the correct tool:

• Pickaxe - Blocks tagged #minecraft:pickaxe_mineable
• Axe - Blocks tagged #minecraft:axe_mineable
• Shovel - Blocks tagged #minecraft:shovel_mineable
• Hoe - Blocks tagged #minecraft:hoe_mineable
• Shears - Leaves, wool, cobwebs

Hostile Detection

The mod detects the following entities as hostile threats:

• All HostileEntity mobs (zombies, skeletons, creepers, etc.)
• Slimes and Magma Cubes
• Phantoms
• Ender Dragon
• Wither

Weapon Ranking

When selecting a weapon for combat, the mod ranks by attack damage:

• Swords - Base damage + 4
• Axes - Base damage + 3
• Tridents - 8 damage

The highest-damage weapon in your hotbar is selected.

Food Selection

The mod picks the food item with the highest hunger restoration, excluding harmful foods:

• Rotten Flesh
• Spider Eye
• Poisonous Potato
• Pufferfish

Intent Lock System

When you manually change your hotbar slot (scroll wheel or number keys), the mod activates an Intent Lock that temporarily disables auto-selection. This ensures your manual choice is respected.

• Default lock duration: 60 ticks (3 seconds)
• The lock automatically expires after the configured duration
• Auto-selection resumes once the lock expires

This prevents the mod from fighting against you when you deliberately want a specific item.

Controls

The toggle key can be rebound in Minecraft's Controls menu under the "Contextual Inventory" category.

Feedback System

The mod provides optional feedback when it switches items:

• Action Bar Text - Shows the reason for the switch (e.g., [Combat], [Mining], [Dark Area])
• Sound Cue - Plays a subtle click sound when items are switched (500ms cooldown to prevent spam)

Both can be disabled in the config.

Configuration

Config file location: .minecraft/config/contextual-inventory.json

The config file is created automatically on first launch. All options:

{
  "enabled": true,
  "showActionBarText": true,
  "playSoundCue": true,
  "intentLockDurationTicks": 60,
  "contextCheckIntervalTicks": 4,
  "soundVolume": 0.3,
  "lowLightThreshold": 7,
  "hungerThreshold": 14,
  "healthThreshold": 10.0,
  "hostileDetectionRange": 8.0,
  "combatCooldownTicks": 100
}

Config Options Explained

Multiplayer Compatibility

This is a client-side only mod. It runs entirely on your client and does not require server installation.

• Works on singleplayer
• Works on multiplayer servers (if client mods are allowed)
• Works on LAN worlds
• Does not affect other players
• Does not require server-side installation

Since the mod only changes your local hotbar selection, it should be compatible with most servers that allow client mods.

Installation

1. Install Fabric Loader (0.15.6 or newer) for Minecraft 1.20.1.
2. Install Fabric API (0.92.0+1.20.1 or newer).
3. Download the mod JAR file.
4. Place the JAR into your .minecraft/mods folder.
5. Launch Minecraft with the Fabric profile.

Building from Source

Clone the repository and run the Gradle build:

git clone https://github.com/AaravVishal1/Contextual-Inventory
cd contextual-inventory
./gradlew build

The compiled JAR will be in build/libs/.

For development, you can run the client directly:

./gradlew runClient

Requirements

Troubleshooting

The mod isn't switching items

1. Make sure the mod is enabled (press I to toggle).
2. Check that you're not sneaking (sneaking disables auto-selection).
3. Verify the Intent Lock isn't active (wait 3 seconds after manual changes).
4. Ensure the relevant item is in your hotbar (slots 1–9 only).

Items switch too often

• Increase contextCheckIntervalTicks in the config (e.g., 8 or 10).
• Increase intentLockDurationTicks for longer manual override windows.

Sound is too loud/quiet

• Adjust soundVolume in the config (0.0–1.0).
• Set playSoundCue to false to disable sounds entirely.

Torches keep getting selected

• Increase lowLightThreshold to a lower value (e.g., 4 or 5).
• This makes the mod less sensitive to low light.

License

This project is licensed under the MIT License. See LICENSE for details.