minecraft-inventory 0.1.0 → 0.1.2

package/README.md

@@ -130,7 +130,6 @@ import { InventoryOverlay, InventoryProvider, ScaleProvider, TextureProvider } f
         type="chest"
         showBackdrop            // default: true (50% black)
         backdropColor="rgba(0,0,0,0.5)"
-        showHotbar              // default: true
         showJEI
         jeiItems={items}
         jeiPosition="right"
@@ -255,7 +254,24 @@ import { TextureProvider } from 'minecraft-inventory'
 </TextureProvider>
 ```
 
-> **Per-container texture version:** Each inventory definition can carry a `guiTextureVersion` string (e.g. `'1.21.4'`) that is passed to `getGuiTextureUrl` as the second argument. Older containers default to `'1.16.4'`; newer ones (crafter, new smithing table) use `'1.21.4'`. Specify it when [registering custom containers](#adding-new-inventory-types).
+**Bundled GUI textures (mc-assets)** — Use the optional `mc-assets` package to bundle container backgrounds locally and avoid remote requests. Generate the texture map from your inventory registry, then pass the config to `TextureProvider`:
+
+```bash
+pnpm add mc-assets   # optional peer dependency
+```
+
+```tsx
+import { TextureProvider, InventoryOverlay } from 'minecraft-inventory'
+import { localTexturesConfig } from './generated/localTextures'
+
+// GUI container backgrounds (chest, furnace, etc.) load from bundled mc-assets;
+// item/block textures still use the default remote URLs unless you override them.
+<TextureProvider config={localTexturesConfig}>
+  <InventoryOverlay type="chest" ... />
+</TextureProvider>
+```
+
+The generated file imports every `backgroundTexture` from your registry, resolves each to `node_modules/mc-assets/dist/other-textures/<version>/...` (or `latest/` if that version is missing), and exports `allContainerPaths` (inventory name → short path) plus `localTexturesConfig.getGuiTextureUrl(path)` for use with `<TextureProvider config={...}>`. Re-run `pnpm gen:textures` after changing [inventory types](#adding-new-inventory-types).
 
 ---
 
@@ -265,20 +281,74 @@ The connector is the bridge between the GUI and a Minecraft server or bot.
 
 ### Mineflayer connector
 
-```ts
-import { createMineflayerConnector } from 'minecraft-inventory'
-import mineflayer from 'mineflayer'
+Use `createMineflayerConnector(bot)` to plug the GUI into a [mineflayer](https://github.com/PrismarineJS/mineflayer) bot. The connector turns slot clicks, drags, and drops into `bot.clickWindow()` (and plugin APIs for villager trades, enchantment table, anvil, beacon), and subscribes to mineflayer inventory events so the UI stays in sync.
 
-const bot = mineflayer.createBot({ ... })
+**Example — overlay when a container opens:**
 
-bot.on('windowOpen', (window) => {
-  const connector = createMineflayerConnector(bot)
+```tsx
+import React, { useState, useEffect } from 'react'
+import { createRoot } from 'react-dom/client'
+import mineflayer from 'mineflayer'
+import {
+  InventoryProvider,
+  ScaleProvider,
+  TextureProvider,
+  InventoryOverlay,
+  createMineflayerConnector,
+} from 'minecraft-inventory'
 
-  // Mount <InventoryGUI connector={connector} type={window.type} />
+const bot = mineflayer.createBot({
+  host: 'localhost',
+  port: 25565,
+  username: 'InventoryViewer',
 })
+
+function App() {
+  const [connector, setConnector] = useState(null)
+  const [windowType, setWindowType] = useState(null)
+  const [open, setOpen] = useState(false)
+
+  useEffect(() => {
+    const onOpen = () => {
+      setConnector(createMineflayerConnector(bot))
+      setWindowType(bot.currentWindow?.type ?? 'generic_9x1')
+      setOpen(true)
+    }
+    const onClose = () => {
+      setOpen(false)
+      setConnector(null)
+    }
+
+    bot.on('windowOpen', onOpen)
+    bot.on('windowClose', onClose)
+    return () => {
+      bot.removeListener('windowOpen', onOpen)
+      bot.removeListener('windowClose', onClose)
+    }
+  }, [])
+
+  if (!open || !connector || !windowType) return null
+
+  return (
+    <TextureProvider>
+      <ScaleProvider scale={2}>
+        <InventoryProvider connector={connector}>
+          <InventoryOverlay
+            type={windowType}
+            onClose={() => bot.closeWindow(bot.currentWindow)}
+            showJEI
+            jeiItems={[]}
+          />
+        </InventoryProvider>
+      </ScaleProvider>
+    </TextureProvider>
+  )
+}
+
+createRoot(document.getElementById('root')).render(<App />)
 ```
 
-The connector translates GUI actions (slot clicks, drag, drop, etc.) into `bot.clickWindow()` calls and subscribes to mineflayer inventory events to keep the GUI in sync.
+**Hotbar “open inventory” button:** If you render a hotbar with the `container` option (e.g. mobile open-inventory button), the connector handles the `open-inventory` action: it calls `openPlayerInventory()`, which opens the player inventory GUI, or the ridden entity’s inventory (e.g. llama) when mounted. No extra wiring needed once the connector is passed to `InventoryProvider`.
 
 ### Demo connector (for local testing)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-inventory",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "license": "MIT",
   "release": {
@@ -17,13 +17,24 @@
     "@types/node": "^25.4.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "mc-assets": "*",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "minecraft-data": "^3.105.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "@xmcl/text-component": "^2.1.3"
   },
-  "dependencies": {
-    "@xmcl/text-component": "^2.1.3",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4"
+  "dependencies": {},
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@xmcl/text-component": "*",
+    "mc-assets": "*"
+  },
+  "peerDependenciesMeta": {
+    "mc-assets": {
+      "optional": true
+    }
   },
   "repository": "https://github.com/zardoy/minecraft-inventory",
   "engines": {
@@ -31,7 +42,8 @@
   },
   "scripts": {
     "dev": "rsbuild dev",
-    "build": "rsbuild build",
-    "preview": "rsbuild preview"
+    "build": "pnpm gen:textures && rsbuild build",
+    "preview": "rsbuild preview",
+    "gen:textures": "node scripts/generate-texture-imports.mjs"
   }
 }

package/src/components/CursorItem/CursorItem.tsx

@@ -3,16 +3,7 @@ import { useInventoryContext } from '../../context/InventoryContext'
 import { useScale } from '../../context/ScaleContext'
 import { ItemCanvas } from '../ItemCanvas'
 import { useMobile } from '../../hooks/useMobile'
-
-// Global mouse tracker — always knows cursor position, even before item is picked up
-const globalMouse = { x: -9999, y: -9999 }
-
-if (typeof window !== 'undefined') {
-  window.addEventListener('mousemove', (e) => {
-    globalMouse.x = e.clientX
-    globalMouse.y = e.clientY
-  }, { passive: true, capture: true })
-}
+import { globalMouse } from '../../utils/globalMouse'
 
 /**
  * CursorItem — optimized to bypass React re-renders on mouse move.

package/src/components/InventoryOverlay/InventoryOverlay.tsx

@@ -1,17 +1,24 @@
 import React, { useCallback, useState } from 'react'
 import { useInventoryContext } from '../../context/InventoryContext'
 import { useScale } from '../../context/ScaleContext'
+import { getInventoryType } from '../../registry'
 import { InventoryWindow } from '../InventoryWindow'
 import { CursorItem } from '../CursorItem'
-import { Hotbar } from '../Hotbar'
 import { JEI } from '../JEI'
 import type { JEIItem } from '../JEI'
+import { Notes } from '../Notes'
+import type { Note } from '../Notes'
 import { RecipeInventoryView } from '../RecipeGuide'
 import type { RecipeGuide, RecipeNavFrame } from '../../types'
 
 export interface InventoryOverlayProps {
   type: string
   title?: string
+  /**
+   * Extra properties forwarded to InventoryWindow. For the 'hotbar' type these
+   * control special features: `showOffhand` (1/0) and `container` (1/0).
+   */
+  properties?: Record<string, number>
   /** Show semi-transparent backdrop behind inventory (default: true) */
   showBackdrop?: boolean
   /** Backdrop color (default: 'rgba(0,0,0,0.5)') */
@@ -24,18 +31,30 @@ export interface InventoryOverlayProps {
   jeiPosition?: 'left' | 'right'
   jeiOnGetRecipes?: (item: JEIItem) => RecipeGuide[]
   jeiOnGetUsages?: (item: JEIItem) => RecipeGuide[]
-  /** Show hotbar below inventory */
-  showHotbar?: boolean
+  /** Enable Notes sidebar (uses localStorage by default if callbacks not provided) */
+  enableNotes?: boolean
+  /** Callback to get notes. If not provided and enableNotes is true, uses localStorage. */
+  notesOnGet?: () => Note[] | Promise<Note[]>
+  /** Callback to save notes. If not provided and enableNotes is true, uses localStorage. */
+  notesOnSave?: (notes: Note[]) => void | Promise<void>
+  /** Storage key for localStorage (default: 'mc-inv-notes') */
+  notesStorageKey?: string
+  /**
+   * Content shown in the left side-panel area (e.g. custom panels).
+   * Width is auto-computed as (overlayWidth - inventoryWidth) / 2 - padding.
+   * Note: If enableNotes is true, Notes will be shown in addition to leftPanel.
+   */
+  leftPanel?: React.ReactNode
   className?: string
   style?: React.CSSProperties
-  /** Style applied to the inner content container (around inventory + JEI) */
-  contentStyle?: React.CSSProperties
   children?: React.ReactNode
+  debugBounds?: boolean
 }
 
 export function InventoryOverlay({
   type,
   title,
+  properties,
   showBackdrop = true,
   backdropColor = 'rgba(0,0,0,0.5)',
   onClose,
@@ -44,15 +63,26 @@ export function InventoryOverlay({
   jeiPosition = 'right',
   jeiOnGetRecipes,
   jeiOnGetUsages,
-  showHotbar = true,
+  enableNotes = false,
+  notesOnGet,
+  notesOnSave,
+  notesStorageKey,
+  leftPanel,
   className,
   style,
-  contentStyle,
   children,
+  debugBounds = false,
 }: InventoryOverlayProps) {
   const { heldItem, sendAction, setHeldItem } = useInventoryContext()
   const { scale } = useScale()
 
+  const def = getInventoryType(type)
+  const invUnscaledW = def?.backgroundWidth ?? 176
+  const sideGapPx = 5 * scale // gap from overlay edge and from inventory edge
+
+  // Full height for side panels = overlay height minus edge gaps
+  const sidePanelHeight = `calc(100% - ${sideGapPx * 2}px)`
+
   // Recipe navigation stack — when non-empty, RecipeInventoryView replaces InventoryWindow
   const [recipeNavStack, setRecipeNavStack] = useState<RecipeNavFrame[]>([])
 
@@ -102,6 +132,26 @@ export function InventoryOverlay({
     />
   ) : null
 
+  const notesPanel = enableNotes ? (
+    <Notes
+      onGetNotes={notesOnGet}
+      onSaveNotes={notesOnSave}
+      storageKey={notesStorageKey}
+    />
+  ) : null
+
+  // Full height side panels; width fills the space between overlay edge and inventory center
+  const sidePanelBase: React.CSSProperties = {
+    position: 'absolute',
+    top: sideGapPx,
+    bottom: sideGapPx,
+    width: `calc(100% / 2 - ${invUnscaledW * scale}px / 2 - ${sideGapPx}px * 2)`,
+    height: sidePanelHeight,
+    zIndex: 5,
+    display: 'flex',
+    flexDirection: 'column',
+  }
+
   return (
     <>
       <div
@@ -110,39 +160,56 @@ export function InventoryOverlay({
         style={{
           position: 'absolute',
           inset: 0,
+          width: '100%',
+          height: '100%',
           background: showBackdrop ? backdropColor : 'transparent',
           cursor: 'default',
           zIndex: 1,
           ...style,
         }}
       >
-        {/* Centered anchor — inventory always stays centered */}
-        <div
-          className="mc-inv-overlay-center"
-          style={{
-            position: 'absolute',
-            left: '50%',
-            top: '50%',
-            transform: 'translate(-50%, -50%)',
-          }}
-        >
-          <div className="mc-inv-overlay-content" style={{ position: 'relative', ...contentStyle }}>
-            {/* JEI on left — stopPropagation so clicks on JEI don't close the overlay */}
+        {/* ── Left side panel (leftPanel prop, Notes, and/or JEI-left) ── */}
+        {(leftPanel || enableNotes || (showJEI && jeiPosition === 'left')) && (
+          <div
+            className="mc-inv-overlay-side mc-inv-overlay-side-left"
+            onClick={(e) => e.stopPropagation()}
+            style={{ ...sidePanelBase, left: sideGapPx, pointerEvents: 'auto' }}
+          >
+            {enableNotes && (
+              <div className="mc-inv-overlay-notes" style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }}>
+                {notesPanel}
+              </div>
+            )}
+            {leftPanel && (
+              <div style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }}>
+                {leftPanel}
+              </div>
+            )}
             {showJEI && jeiPosition === 'left' && (
               <div
                 className="mc-inv-overlay-jei mc-inv-overlay-jei-left"
-                onClick={(e) => e.stopPropagation()}
-                style={{
-                  position: 'absolute',
-                  right: `calc(100% + ${4 * scale}px)`,
-                  top: 0,
-                  zIndex: 5,
-                }}
+                style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column', width: '100%' }}
               >
                 {jeiPanel}
               </div>
             )}
+          </div>
+        )}
 
+        {/* ── Inventory centered anchor — flex centering, no transform ── */}
+        <div
+          className="mc-inv-overlay-center"
+          style={{
+            position: 'absolute',
+            inset: 0,
+            width: '100%',
+            height: '100%',
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'center',
+          }}
+        >
+          <div className="mc-inv-overlay-content" style={{ position: 'relative' }}>
             {/* Inventory / Recipe view — stopPropagation so clicks inside don't close the overlay */}
             <div className="mc-inv-overlay-window" onClick={(e) => e.stopPropagation()}>
               {recipeNavStack.length > 0 ? (
@@ -153,41 +220,44 @@ export function InventoryOverlay({
                   onPushFrame={handleRecipePushFrame}
                 />
               ) : (
-                <InventoryWindow type={type} title={title} />
+                <InventoryWindow type={type} title={title} properties={properties} />
               )}
             </div>
+          </div>
+        </div>
 
-            {/* Hotbar — stopPropagation */}
-            {showHotbar && (
-              <div
-                className="mc-inv-overlay-hotbar"
-                onClick={(e) => e.stopPropagation()}
-                style={{ marginTop: 8 * scale }}
-              >
-                <Hotbar />
-              </div>
-            )}
+        {/* ── Right side panel (JEI-right) ── */}
+        {showJEI && jeiPosition === 'right' && (
+          <div
+            className="mc-inv-overlay-side mc-inv-overlay-side-right"
+            onClick={(e) => e.stopPropagation()}
+            style={{ ...sidePanelBase, right: sideGapPx, pointerEvents: 'auto' }}
+          >
+            <div
+              className="mc-inv-overlay-jei mc-inv-overlay-jei-right"
+              style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column', width: '100%' }}
+            >
+              {jeiPanel}
+            </div>
+          </div>
+        )}
 
-            {/* JEI on right — stopPropagation */}
-            {showJEI && jeiPosition === 'right' && (
-              <div
-                className="mc-inv-overlay-jei mc-inv-overlay-jei-right"
-                onClick={(e) => e.stopPropagation()}
-                style={{
-                  position: 'absolute',
-                  left: `calc(100% + ${4 * scale}px)`,
-                  top: 0,
-                  zIndex: 5,
-                }}
-              >
-                {jeiPanel}
-              </div>
-            )}
+        {/* Extra children (overlay-level) */}
+        {children}
 
-            {/* Extra children (notes, etc.) */}
-            {children}
-          </div>
-        </div>
+        {/* Debug bounds */}
+        {debugBounds && (
+          <div
+            className="mc-inv-overlay-debug-marker"
+            style={{
+              position: 'absolute',
+              inset: 0,
+              border: '2px solid yellow',
+              pointerEvents: 'none',
+              boxSizing: 'border-box',
+            }}
+          />
+        )}
       </div>
 
       <CursorItem />

package/src/components/InventoryWindow/HotbarExtras.tsx

@@ -0,0 +1,180 @@
+import React from 'react'
+import { useInventoryContext } from '../../context/InventoryContext'
+import { useScale } from '../../context/ScaleContext'
+import { useTextures } from '../../context/TextureContext'
+import { Slot } from '../Slot'
+import type { ItemStack } from '../../types'
+
+interface HotbarExtrasProps {
+  showOffhand: boolean
+  container: boolean
+  offhandItem: ItemStack | null
+}
+
+/** Renders a sprite from the widgets.png using the same inner-div+transform approach as InventoryBackground */
+function WidgetSprite({
+  url,
+  srcX,
+  srcY,
+  srcW,
+  srcH,
+  scale,
+  style,
+}: {
+  url: string
+  srcX: number
+  srcY: number
+  srcW: number
+  srcH: number
+  scale: number
+  style?: React.CSSProperties
+}) {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        width: srcW * scale,
+        height: srcH * scale,
+        overflow: 'hidden',
+        imageRendering: 'pixelated',
+        pointerEvents: 'none',
+        ...style,
+      }}
+    >
+      <div
+        style={{
+          width: srcW,
+          height: srcH,
+          overflow: 'hidden',
+          transform: `scale(${scale})`,
+          transformOrigin: 'top left',
+        }}
+      >
+        <img
+          src={url}
+          alt=""
+          aria-hidden
+          draggable={false}
+          style={{
+            position: 'absolute',
+            top: -srcY,
+            left: -srcX,
+            imageRendering: 'pixelated',
+            userSelect: 'none',
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Hotbar-specific extras rendered inside InventoryBackground alongside the regular slots.
+ * Mirrors layouts.mjs Hotbar children:
+ *   - Active slot indicator (always)
+ *   - Offhand slot left of the strip (when showOffhand)
+ *   - Open-inventory button right of the strip (when container)
+ */
+export function HotbarExtras({ showOffhand, container, offhandItem }: HotbarExtrasProps) {
+  const { playerState, sendAction } = useInventoryContext()
+  const { scale } = useScale()
+  const textures = useTextures()
+
+  const activeSlot = playerState?.activeHotbarSlot ?? 0
+  const hotbarUrl = textures.getGuiTextureUrl('1.15/textures/gui/widgets.png')
+
+  // Sprite regions within widgets.png (native pixels):
+  //   Hotbar strip : [0, 0, 182, 22]
+  //   Active box   : [0, 22, 24, 24]
+  //   Offhand box  : [24, 22, 24, 24]
+  const GAP = 2
+
+  return (
+    <>
+      {/* ── Active slot indicator ── */}
+      <WidgetSprite
+        url={hotbarUrl}
+        srcX={0}
+        srcY={22}
+        srcW={24}
+        srcH={24}
+        scale={scale}
+        style={{
+          left: (activeSlot * 20 - 1) * scale,
+          top: -1 * scale,
+          zIndex: 2,
+        }}
+      />
+
+      {/* ── Offhand slot (left of hotbar) ── */}
+      {showOffhand && (
+        <div
+          className="mc-inv-hotbar-offhand"
+          style={{
+            position: 'absolute',
+            left: -(24 + GAP) * scale,
+            top: 0,
+            width: 24 * scale,
+            height: 22 * scale,
+          }}
+        >
+          <WidgetSprite
+            url={hotbarUrl}
+            srcX={24}
+            srcY={22}
+            srcW={24}
+            srcH={22}
+            scale={scale}
+            style={{ left: 0, top: 0 }}
+          />
+          {/* Item at slot 45 (offhand) */}
+          <div style={{ position: 'absolute', top: 3 * scale, left: 3 * scale }}>
+            <Slot index={45} item={offhandItem} size={16 * scale} noBackground />
+          </div>
+        </div>
+      )}
+
+      {/* ── Open-inventory button (right of hotbar) ── */}
+      {container && (
+        <div
+          className="mc-inv-hotbar-open-inv"
+          title="Open inventory"
+          style={{
+            position: 'absolute',
+            left: (182 + GAP) * scale,
+            top: 0,
+            width: 24 * scale,
+            height: 22 * scale,
+            cursor: 'pointer',
+          }}
+          onClick={() => sendAction({ type: 'open-inventory' })}
+        >
+          <WidgetSprite
+            url={hotbarUrl}
+            srcX={24}
+            srcY={22}
+            srcW={24}
+            srcH={22}
+            scale={scale}
+            style={{ left: 0, top: 0 }}
+          />
+          {/* Three white dots centered */}
+          {[0, 1, 2].map((i) => (
+            <div
+              key={i}
+              style={{
+                position: 'absolute',
+                left: (6 + i * 4) * scale,
+                top: 10 * scale,
+                width: 2 * scale,
+                height: 2 * scale,
+                background: 'white',
+                pointerEvents: 'none',
+              }}
+            />
+          ))}
+        </div>
+      )}
+    </>
+  )
+}

package/src/components/InventoryWindow/InventoryBackground.tsx

@@ -18,7 +18,7 @@ export function InventoryBackground({
   const textures = useTextures()
   const { scale } = useScale()
 
-  const bgUrl = textures.getGuiTextureUrl(definition.backgroundTexture, definition.guiTextureVersion)
+  const bgUrl = textures.getGuiTextureUrl(definition.backgroundTexture)
   const w = definition.backgroundWidth * scale
   const h = definition.backgroundHeight * scale
 
@@ -80,8 +80,8 @@ export function InventoryBackground({
           className="mc-inv-background-title"
           style={{
             position: 'absolute',
-            top: 6 * scale,
-            left: 8 * scale,
+            top: (6 + (definition.titleOffset?.y ?? 0)) * scale,
+            left: (8 + (definition.titleOffset?.x ?? 0)) * scale,
             fontSize: 7 * scale,
             fontFamily: "'Minecraftia', 'Minecraft', monospace",
             pointerEvents: 'none',

package/src/components/InventoryWindow/InventoryWindow.tsx

@@ -9,6 +9,7 @@ import { InventoryBackground } from './InventoryBackground'
 import { ProgressBar } from './ProgressBar'
 import { VillagerTradeList } from './VillagerTradeList'
 import { EnchantmentOptions } from './EnchantmentOptions'
+import { HotbarExtras } from './HotbarExtras'
 
 interface InventoryWindowProps {
   type: string
@@ -58,6 +59,7 @@ export function InventoryWindow({
   const effectiveTitle = type === 'player' ? undefined : (title ?? windowState?.title ?? def.title)
   const isVillager = type === 'villager'
   const isEnchanting = type === 'enchanting_table'
+  const isHotbar = type === 'hotbar'
 
   const resolveItem = (slotIndex: number) => {
     const fromProp = effectiveSlots.find((s) => s.index === slotIndex)
@@ -114,6 +116,15 @@ export function InventoryWindow({
             y={14}
           />
         )}
+
+        {/* Hotbar extras: active slot indicator, offhand slot, open-inventory button */}
+        {isHotbar && (
+          <HotbarExtras
+            showOffhand={Boolean(effectiveProperties.showOffhand)}
+            container={Boolean(effectiveProperties.container)}
+            offhandItem={resolveItem(45)}
+          />
+        )}
       </InventoryBackground>
     </div>
   )