🎮 Player Carpet Extension (PlayerCarpetEx)

A powerful Carpet Mod extension for Minecraft that gives server operators full control over player inventories.

📖 Overview

Player Carpet Extension is a server-side Fabric mod that extends the capabilities of Carpet Mod with advanced player inventory management tools. Designed for server administrators, SMP operators, and mapmakers, this mod provides two core features that revolutionize how you interact with player inventories on your server.

What does this mod do?

This mod adds two major systems to your Minecraft server:

1. Remote Inventory Viewing & Management — Open any player's inventory as a full GUI screen, with bidirectional synchronization. Any changes you make in the viewer are instantly applied to the target player's inventory, and vice versa. You can also use commands to give, remove, swap, set, count, compact, and drop items in any player's inventory slots.

2. Auto-Switch Hotbar System — Automatically refills a player's hotbar when the selected slot runs out. The system pulls items from the next available hotbar slot, and if the entire hotbar is empty, it pulls from the main inventory. When everything is depleted, the main inventory locks to prevent external modifications until new items are provided.

✨ Features

🎯 Inventory GUI Viewer

Open a visual representation of any player's inventory directly in your game client. The viewer displays a 54-slot (9×6) container with a carefully organized layout that mirrors the player's actual inventory structure.

GUI Layout Structure:

The container view is divided into clearly marked sections using decorative glass panes:

Bidirectional Synchronization:

• The viewer inventory syncs to the target player's inventory every 10 ticks (0.5 seconds), ensuring you always see the latest state even if the target player moves items around.
• When you modify items in the viewer (pick up, place, swap), those changes are immediately pushed to the target player's inventory.
• A syncing flag prevents infinite re-entrant sync loops during initialization and modification.
• Glass pane separators are enforced during initialization and preserved across syncs.

🔄 Auto-Switch Hotbar

The auto-switch system continuously monitors a player's selected hotbar slot and automatically refills it when it becomes empty. This is perfect for scenarios like automated farms, PvP servers, or any situation where players need continuous item supply.

How the auto-switch logic works:

1. Hotbar Check — When the selected hotbar slot is empty, the system scans the remaining hotbar slots (wrapping around) for the nearest available item. If found, it moves that item to the selected slot and notifies the player.
2. Inventory Pull — If the entire hotbar is empty, the system searches the main inventory (slots 9–35) for any item and pulls it to the currently selected hotbar slot.
3. Inventory Lock — When all hotbar AND main inventory slots are completely empty, the system locks the main inventory. While locked, external attempts to add items to the main inventory (from dispensers, hoppers, or other mechanisms) are blocked. Items can only be added to the hotbar.
4. Auto-Unlock — If items are somehow detected in the locked inventory, the lock automatically releases and normal operation resumes.

📦 Installation

Requirements

Steps

1. Install Fabric Loader — Download and install Fabric Loader for Minecraft 1.20.4.
2. Install Fabric API — Download the Fabric API for Minecraft 1.20.4 and place it in your mods/ folder.
3. Install Carpet Mod — Download Carpet Mod version 1.4.128 or newer and place it in your mods/ folder.
4. Install PlayerCarpetEx — Download the PlayerCarpetEx-1.3.0.jar file and place it in your server's mods/ folder.
5. Restart Server — Restart your Minecraft server to load all mods.

Verifying Installation

Once the server starts, you should see the following log messages:

[PlayerCarpetEx] Player Carpet Extension initialized!
[PlayerCarpetEx] Player Carpet Extension: game started.
[PlayerCarpetEx] Player Carpet Extension: server loaded.

You can also run /version or check the Carpet Mod rules list — PlayerCarpetEx will appear as a registered Carpet Extension with version 1.3.0.

🛠️ Commands

All commands require permission level 2 (operator status). The base command is /playerex.

Note: Replace <player> with the actual player name in all commands below.

Inventory Management

/playerex <player> inventory (or /playerex <player> inventory view)

Opens a visual GUI viewer displaying the target player's complete inventory (offhand, armor, hotbar, and main inventory). The GUI uses a 9×6 container with glass pane separators for clear organization.

/playerex Steve inventory

/playerex <player> inventory list

Prints a detailed text listing of the target player's inventory contents directly in chat. Shows each slot index, item name, and count, organized by hotbar and main inventory sections.

/playerex Steve inventory list

Example output:

[CarpetEx] Inventory of: Steve
[CarpetEx]  --- Hotbar (Slots 0-8) ---
[CarpetEx]    [0] Diamond Sword x1
[CarpetEx]    [1] empty
[CarpetEx]    [2] Golden Apple x16
[CarpetEx]  --- Main Inventory (Slots 9-35) ---
[CarpetEx]    [9] Oak Planks x64
[CarpetEx]    [10] Cobblestone x32

/playerex <player> inventory info <slot>

Displays detailed information about a specific inventory slot, including the item name, current count, and maximum stack size.

/playerex Steve inventory info 5

/playerex <player> inventory give <slot> <item> [count]

Places a specified item into the target player's inventory at the given slot number. If no count is specified, defaults to 1. The count can range from 1 to 64.

/playerex Steve inventory give 0 minecraft:diamond_sword 1
/playerex Steve inventory give 9 minecraft:golden_apple 64

/playerex <player> inventory remove <slot> [count]

Removes items from the target player's inventory at the specified slot. If the count matches or exceeds the current stack size, the slot is cleared entirely. Defaults to removing 1 item.

/playerex Steve inventory remove 9 32
/playerex Steve inventory remove 0

/playerex <player> inventory clear

Completely clears the target player's entire inventory (hotbar, main inventory, armor, and offhand). Use with caution.

/playerex Steve inventory clear

/playerex <player> inventory swap <slot1> <slot2>

Swaps the contents of two inventory slots in the target player's inventory. Both slot numbers must be between 0 and 40 (slot 40 = offhand).

/playerex Steve inventory swap 0 9
/playerex Steve inventory swap 36 37

/playerex <player> inventory set <slot> <item> [count]

Sets the contents of a specific slot to the specified item and count, replacing whatever was there before. Similar to give but overwrites the existing stack.

/playerex Steve inventory set 0 minecraft:netherite_sword 1

/playerex <player> inventory count <item>

Counts the total number of a specific item across all slots in the target player's inventory. Useful for quickly checking resource amounts.

/playerex Steve inventory count minecraft:diamond

Example output:

[CarpetEx] 47x Diamond

/playerex <player> inventory compact

Consolidates all stackable items in the target player's inventory by merging partial stacks into complete ones. This frees up inventory space by combining items of the same type.

/playerex Steve inventory compact

/playerex <player> inventory drop <slot>

Drops the item from the specified slot on the ground near the target player. The item is physically ejected from the inventory into the world.

/playerex Steve inventory drop 36

Auto-Switch System

/playerex <player> use switch

Toggles the auto-switch hotbar system for the target player on or off. When first enabled, the system will begin monitoring and refilling the player's selected hotbar slot automatically.

/playerex Steve use switch

/playerex <player> use switch true

Explicitly enables auto-switch for the target player.

/playerex Steve use switch true

/playerex <player> use switch false

Explicitly disables auto-switch for the target player. This also releases the inventory lock if it was active.

/playerex Steve use switch false

Slot Reference Guide

🔧 Technical Details

Architecture

The mod is built with a clean, modular architecture consisting of four main components:

1. Commands Module (commands/)

• PlayerInventoryCommand.java — Handles all inventory management commands and the GUI viewer system. Contains the slot mapping logic, glass pane initialization, and bidirectional synchronization engine.
• PlayerUseSwitchCommand.java — Handles the auto-switch toggle command and state management.

2. Handler Module (handler/)

• SwitchHandler.java — The core auto-switch engine. Runs every server tick, checking the selected hotbar slot and performing item rotation, inventory pulling, and lock management.

3. Mixin Module (mixin/)

• PlayerInventoryMixin.java — Hooks into PlayerInventory.setStack(), PlayerInventory.addStack(), and PlayerInventory.markDirty() to intercept inventory modifications and enforce the lock when auto-switch is active with a depleted inventory.
• ServerPlayerEntityMixin.java — Hooks into ServerPlayerEntity.closeHandledScreen() to detect when a player closes the inventory viewer GUI, triggering a final sync from viewer to target.

4. Core Module

• PlayerCarpetExtension.java — The main mod entry point implementing ModInitializer and CarpetExtension. Initializes all systems and registers the Carpet settings manager.

Synchronization System

The bidirectional sync system is one of the most critical parts of the mod. It ensures that both the viewing operator and the target player see a consistent inventory state at all times.

View → Target Sync:

• Triggered when the viewer modifies any item in the GUI (via the SimpleInventory.markDirty() override).
• Iterates through all 54 view slots, checks the VIEW_TO_TARGET mapping array, and copies non-glass items to the corresponding target inventory slots.
• The syncing flag prevents re-entrant calls that could cause infinite loops.

Target → View Sync:

• Triggered every 10 server ticks (0.5 seconds) via ServerTickEvents.END_SERVER_TICK.
• Iterates through all 41 target inventory slots, checks the TARGET_TO_VIEW reverse mapping array, and copies items to the corresponding view slots.
• Only runs when the viewer is not in the initializing phase.

Initialization Guards:

• When the GUI first opens, both syncing and initializing flags are set to true.
• This prevents any side effects during the initial population of the view inventory.
• The initializing flag is cleared after all items and glass panes are placed.
• The syncing flag is cleared after the initialization block completes.

Slot Mapping

The slot mapping system translates between the 54-slot view container and the 41-slot Minecraft player inventory using two lookup arrays:

• VIEW_TO_TARGET[54] — Maps each view container slot (0–53) to the corresponding target inventory slot (-1 for glass/unused).
• TARGET_TO_VIEW[41] — Reverse mapping from target inventory slots to view container slots (-1 for unmapped).

This bidirectional mapping enables efficient synchronization in both directions.

🖼️ Gallery

Image	Description
	Mod banner artwork
	GUI layout diagram showing the organized inventory view
	Feature overview illustration
	Auto-switch hotbar mechanic diagram
	In-game inventory viewer screenshot

🤝 Compatibility

📋 Changelog

v1.3.0 — Inventory GUI Overhaul

• Complete rewrite of the inventory viewing system with a visual GUI container
• Added 54-slot (9×6) GenericContainerScreenHandler based viewer
• Implemented bidirectional synchronization between viewer and target (every 10 ticks)
• Added glass pane separators: blue stained glass for the armor row, gray stained glass for the hotbar/inventory divider
• Added syncing and initializing flags to prevent re-entrant sync during initialization
• Added proper VIEW_TO_TARGET and TARGET_TO_VIEW slot mapping arrays
• New inventory subcommands: give, remove, clear, swap, set, count, compact, drop
• Added Mixin for ServerPlayerEntity.closeHandledScreen() to detect GUI close events
• Added Mixin for PlayerInventory to support auto-switch inventory locking

v1.2.0 — Auto-Switch System

• Added auto-switch hotbar refill system with hotbar rotation, inventory pull, and inventory locking
• Added PlayerInventoryMixin for setStack, addStack, and markDirty interception
• Added SwitchHandler with per-player state management using ConcurrentHashMap

v1.1.0 — Initial Inventory Commands

• Added /playerex <player> inventory list and /playerex <player> inventory info <slot>
• Fixed item disappearing bug when opening inventory view
• Improved command structure with Brigadier argument types

v1.0.0 — First Release

• Basic /playerex command structure
• Initial inventory view command (text-based)
• Carpet Mod extension registration

📄 License

This mod is released under the MIT License. You are free to use, modify, and distribute this mod in any project, provided that the original license notice is included.

MIT License

Copyright (c) 2026 PlayerCarpetEx

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

🔗 Links

• Modrinth: PlayerCarpetEx
• Source Code: GitHub Repository
• Issues: Issue Tracker
• Carpet Mod: gnembon/fabric-carpet

Made with ❤️ for the Minecraft server administration community.