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:

Context	What It Checks
Targeted Block	The block you're looking at and its tool requirements
Nearby Hostiles	Hostile mobs within detection range (default: 8 blocks)
Light Level	Combined block and sky light at your position
Hunger	Your current food level vs. the hunger threshold
Health	Your current HP (triggers at ≤30% max health)
Recent Actions	Whether you recently attacked, were attacked, or were mining
Special States	Sneaking, submerged in water, on fire

Item Selection Priority

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

Priority	Trigger	Action
1. Combat (High)	Recently attacked, took damage, or hostiles nearby	Selects best weapon (sword > axe > trident)
2. Food (Medium)	Low health (≤30%) or hunger below threshold	Selects best food (excludes harmful items)
3. Mining (Low)	Looking at a mineable block	Selects correct tool for the block type
4. Lighting (Low)	Light level below threshold	Selects torch, soul torch, lantern, or soul lantern

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

Key	Action
I (default)	Toggle the mod on/off
Sneak (hold)	Temporarily disable auto-selection while held

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

Option	Default	Description
`enabled`	`true`	Master toggle for the mod
`showActionBarText`	`true`	Show reason text above hotbar when switching
`playSoundCue`	`true`	Play a click sound when switching items
`intentLockDurationTicks`	`60`	How long manual slot changes lock auto-selection (60 ticks = 3 sec)
`contextCheckIntervalTicks`	`4`	How often to check context (lower = more responsive, higher = better performance)
`soundVolume`	`0.3`	Volume of the switch sound (0.0–1.0)
`lowLightThreshold`	`7`	Light level below which torches are suggested
`hungerThreshold`	`14`	Food level below which food is suggested (max is 20)
`healthThreshold`	`10.0`	Health value for "low health" food priority (max is 20)
`hostileDetectionRange`	`8.0`	Range in blocks to detect hostile mobs
`combatCooldownTicks`	`100`	How long "recently attacked" state lasts (100 ticks = 5 sec)

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

Install Fabric Loader (0.15.6 or newer) for Minecraft 1.20.1.
Install Fabric API (0.92.0+1.20.1 or newer).
Download the mod JAR file.
Place the JAR into your .minecraft/mods folder.
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

Dependency	Version
Minecraft	1.20.1
Fabric Loader	0.15.6+
Fabric API	0.92.0+1.20.1

Troubleshooting

The mod isn't switching items

Make sure the mod is enabled (press I to toggle).
Check that you're not sneaking (sneaking disables auto-selection).
Verify the Intent Lock isn't active (wait 3 seconds after manual changes).
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.