Enhance BridgeConnection and PlayerDataStore functionality

- Introduced a timeout for synchronous bridge calls to prevent indefinite blocking.
- Updated the subscribe method to handle EnumValue for priority.
- Improved event handling for command events to avoid deadlocks.
- Enhanced player data storage to resolve player data directory dynamically.
- Added new properties to the Player class for better interaction with player states (e.g., is_hand_raised, is_blocking, etc.).
- Updated loot generation methods to return Item objects instead of dicts for better type safety and usability.
- Implemented fallback mechanisms in task decorators to handle transient bridge issues.

Author: Omena0

docs/src/core/player.md

@@ -138,6 +138,48 @@ Whether the player is sneaking (shift held).
 
 Whether the player is sprinting.
 
+### is_hand_raised
+
+- **Type:** `bool`
+
+Whether the player is currently using an item (holding right-click).
+
+### hand_raised
+
+- **Type:** [`EquipmentSlot`](enums.md) `| None`
+
+Which hand is currently being used (`EquipmentSlot.HAND` or `EquipmentSlot.OFF_HAND`). `None` if the player is not using an item.
+
+### is_blocking
+
+- **Type:** `bool`
+
+Whether the player is actively blocking (for example with a shield).
+
+### item_in_use
+
+- **Type:** [`Item`](item.md) `| None`
+
+The item currently being used by the player.
+
+### item_in_use_ticks
+
+- **Type:** `int`
+
+How many ticks the current `item_in_use` has been used.
+
+### is_sleeping
+
+- **Type:** `bool`
+
+Whether the player is currently sleeping in a bed.
+
+### sleep_ticks
+
+- **Type:** `int`
+
+How long the player has been sleeping, in ticks.
+
 ### scoreboard
 
 - **Type:** [`Scoreboard`](scoreboard.md)

docs/src/extensions/loottable.md

@@ -70,6 +70,18 @@ Generate loot from all pools.
   - `luck` *(float)* — Luck factor for bonus rolls.
 - **Returns:** `list[dict]` — Item dicts with `"material"` and `"amount"` keys.
 
+#### .generate_into(inventory, context=None, luck=0.0)
+
+Generate loot and insert directly into an inventory.
+
+- **Parameters:**
+  - `inventory` (`Inventory`) — Target inventory.
+  - `context` *(Any)* — Context passed to conditions.
+  - `luck` *(float)* — Luck factor for bonus rolls.
+- **Returns:** `list[Item]` — Inserted items.
+
+Items are spread across random slots (vanilla-style chest distribution).
+
 #### .generate_stacked(context=None, luck=0.0)
 
 Generate loot and combine items of the same material into stacks.
@@ -95,7 +107,7 @@ pool = LootPool(name="pool", rolls=1, bonus_rolls=0)
 Add an entry to this pool.
 
 - **Parameters:**
-  - `item` — Material name string or item dict (`{"material": ..., "amount": ...}`).
+  - `item` — Material name string, `Item` object, or item dict (`{"material": ..., "amount": ...}`).
   - `weight` *(int)* — Relative probability weight. Default `1`.
   - `min_amount` *(int)* — Minimum stack size. Default `1`.
   - `max_amount` *(int)* — Maximum stack size. Default `1`.
@@ -118,6 +130,18 @@ Generate loot from this pool only.
 
 - **Returns:** `list[dict]`
 
+#### .generate_into(inventory, context=None, luck=0.0)
+
+Generate pool loot and insert into an inventory.
+
+- **Parameters:**
+  - `inventory` (`Inventory`) — Target inventory.
+  - `context` *(Any)* — Context passed to conditions.
+  - `luck` *(float)* — Luck factor for bonus rolls.
+- **Returns:** `list[Item]`
+
+Items are spread across random slots (vanilla-style chest distribution).
+
 ---
 
 ## LootEntry

pjb

@@ -7,6 +7,7 @@ Usage:
 """
 
 import re
+import shutil
 import sys
 from pathlib import Path
 
@@ -237,6 +238,7 @@ def build_symbol_index(docs_dir):
         lines = content.split("\n")
 
         class_name = md_file.stem.capitalize()
+        is_enum_doc = md_file.stem == "enums"
         section = ""
         subtitle = ""
         in_code_block = False
@@ -276,6 +278,40 @@ def build_symbol_index(docs_dir):
             elif stripped.startswith("## ") and not stripped.startswith("### "):
                 section = stripped.lstrip("# ").strip()
 
+                # docs/src/helpers/enums.md stores enum "classes" as ## headings.
+                # Index them as top-level symbols so queries like "ItemFlag" work.
+                if is_enum_doc and " " not in section:
+                    class_name = section
+                    desc = _get_desc_after(lines, i)
+                    symbols.append({
+                        "class_name": class_name,
+                        "name": None,
+                        "section": None,
+                        "qualified": class_name,
+                        "desc": desc,
+                        "file": str(md_file.relative_to(docs_dir).with_suffix('')),
+                        "line": i + 1,
+                        "enum_section_line": i + 1,
+                    })
+
+            elif is_enum_doc and class_name and stripped.startswith("| `"):
+                # docs/src/helpers/enums.md stores enum values in markdown tables.
+                # Index values as members so queries like "ItemFlag." work.
+                m = re.match(r"\|\s*`([^`]+)`\s*\|", stripped)
+                if m:
+                    member = m.group(1).strip()
+                    if member and member != "Name":
+                        symbols.append({
+                            "class_name": class_name,
+                            "name": member,
+                            "section": "Values",
+                            "qualified": f"{class_name}.{member}",
+                            "desc": "",
+                            "sig": None,
+                            "file": str(md_file.relative_to(docs_dir).with_suffix('')),
+                            "line": i + 1,
+                        })
+
             elif stripped.startswith("### "):
                 member = stripped.lstrip("# ").strip()
                 # Only index code-like symbols (no spaces = identifier)
@@ -329,6 +365,73 @@ def _get_signature(lines, heading_idx, member):
                 return f"({m.group(1)})"
     return None
 
+def _load_stub_enum_values():
+    """Load enum constants from bridge __init__.pyi for richer completion."""
+    candidates = [
+        SCRIPT_DIR.parent / "src" / "main" / "resources" / "python" / "bridge" / "__init__.pyi",
+        SCRIPT_DIR / "src" / "main" / "resources" / "python" / "bridge" / "__init__.pyi",
+        Path.cwd() / "src" / "main" / "resources" / "python" / "bridge" / "__init__.pyi",
+    ]
+    stub_path = next((p for p in candidates if p.is_file()), None)
+    if stub_path is None:
+        return {}
+
+    out = {}
+    current_class = None
+    for raw in stub_path.read_text(encoding="utf-8").splitlines():
+        m_class = re.match(r"^class\s+(\w+)\(EnumValue\):", raw)
+        if m_class:
+            current_class = m_class.group(1)
+            out.setdefault(current_class, [])
+            continue
+
+        if current_class is None:
+            continue
+
+        if raw.startswith("class "):
+            current_class = None
+            continue
+
+        m_member = re.match(r"^\s+([A-Z][A-Z0-9_]*)\s*:\s*ClassVar\[", raw)
+        if m_member:
+            out[current_class].append(m_member.group(1))
+
+    return out
+
+def _merge_stub_enum_symbols(symbols):
+    """Add enum constants from stubs when docs are incomplete."""
+    enum_values = _load_stub_enum_values()
+    if not enum_values:
+        return symbols
+
+    class_meta = {}
+    for s in symbols:
+        if s.get("name") is None:
+            class_meta.setdefault(s["class_name"], s)
+
+    existing = {(s["class_name"], s.get("name")) for s in symbols}
+    for class_name, members in enum_values.items():
+        meta = class_meta.get(class_name)
+        if meta is None:
+            continue
+        for member in members:
+            key = (class_name, member)
+            if key in existing:
+                continue
+            symbols.append({
+                "class_name": class_name,
+                "name": member,
+                "section": "Values",
+                "qualified": f"{class_name}.{member}",
+                "desc": "",
+                "sig": None,
+                "file": meta.get("file", "helpers/enums"),
+                "line": meta.get("line", 1),
+            })
+            existing.add(key)
+
+    return symbols
+
 def _strip_md(line):
     """Strip markdown formatting from a line for terminal display."""
     line = re.sub(r'\[([^\]]*)\]\([^)]*\)', r'\1', line)  # links
@@ -341,6 +444,34 @@ def _sort_key(s):
     """Sort key that orders _ after letters (replace _ with ~ which sorts after z)."""
     return s.lower().replace('_', '~')
 
+def _print_compact_members(members):
+    """Print members as a width-wrapped comma-separated list."""
+    values = []
+    for s in members:
+        sig = s.get('sig', '') or ''
+        values.append(f".{s['name']}{sig}")
+
+    term_cols = shutil.get_terminal_size((120, 20)).columns
+    indent = "  "
+    max_width = max(30, term_cols - len(indent))
+
+    line_parts = []
+    line_len = 0
+    for value in values:
+        part = value if not line_parts else f", {value}"
+        part_len = len(part)
+
+        if line_parts and line_len + part_len > max_width:
+            print(f"{indent}\033[36m{''.join(line_parts)}\033[0m")
+            line_parts = [value]
+            line_len = len(value)
+        else:
+            line_parts.append(part)
+            line_len += part_len
+
+    if line_parts:
+        print(f"{indent}\033[36m{''.join(line_parts)}\033[0m")
+
 
 # Extension doc file stems (matches Extensions section in docs/build.py)
 _EXT_FILES = {
@@ -572,14 +703,57 @@ def _get_member_doc(md_path, heading_line):
 
     return "\n".join(collapsed)
 
+def _get_enum_section_doc(md_path, heading_line):
+    """Extract a ## section block (used for enum docs in enums.md)."""
+    content = md_path.read_text(encoding="utf-8")
+    lines = content.split("\n")
+
+    out = []
+    in_code_block = False
+    start = max(0, heading_line - 1)
+
+    for j in range(start, len(lines)):
+        line = lines[j]
+        stripped = line.strip()
+
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+
+        if not in_code_block and j > start and stripped.startswith("## "):
+            break
+
+        if in_code_block:
+            out.append(f"  {_highlight_python(line.rstrip())}")
+        elif stripped.startswith("## ") and j == start:
+            title = stripped.lstrip('# ').strip()
+            out.append(f"  \033[36;1m# {title}\033[0m")
+        elif stripped.startswith("- "):
+            out.append(f"  {_strip_md(line.rstrip())}")
+        elif stripped:
+            out.append(f"  {_strip_md(line.rstrip())}")
+        else:
+            out.append("")
+
+    while out and not out[-1].strip():
+        out.pop()
+
+    collapsed = []
+    for line in out:
+        if not line.strip() and collapsed and not collapsed[-1].strip():
+            continue
+        collapsed.append(line)
+
+    return "\n".join(collapsed)
+
 def cmd_search(query):
     docs_dir = find_docs_dir()
     if docs_dir is None:
         print("Error: Could not find docs/src directory.")
         print("Run this from the PyJavaBridge project root.")
         sys.exit(1)
 
-    symbols = build_symbol_index(docs_dir)
+    symbols = _merge_stub_enum_symbols(build_symbol_index(docs_dir))
 
     if query.endswith("."):
         # "Player." → list all members of that class
@@ -591,14 +765,28 @@ def cmd_search(query):
         ext = _EXT_TAG if Path(members[0]['file']).stem in _EXT_FILES else ""
         print(f"\033[1m{members[0]['class_name']}\033[0m  \033[90m({members[0]['file']}.md)\033[0m{ext}")
         current_section = None
-        for s in members:
-            section = s['section'] or ''
+        section_members = []
+        for s in members + [None]:
+            if s is None:
+                section = None
+            else:
+                section = s['section'] or ''
+
             if section != current_section:
+                if current_section and section_members:
+                    if current_section == "Values":
+                        _print_compact_members(section_members)
+                    else:
+                        for m in section_members:
+                            sig = m.get('sig', '') or ''
+                            print(f"  \033[90m###\033[0m \033[36m.{m['name']}{sig}\033[0m")
+                section_members = []
                 current_section = section
                 if section:
                     print(f" \033[90m## {section}\033[0m")
-            sig = s.get('sig', '') or ''
-            print(f"  \033[90m###\033[0m \033[36m.{s['name']}{sig}\033[0m")
+
+            if s is not None:
+                section_members.append(s)
 
     elif "." in query:
         # "Player.name" → find specific member(s)
@@ -647,13 +835,22 @@ def cmd_search(query):
         if any(s["class_name"].lower() == q for s in classes):
             classes = [s for s in classes if s["class_name"].lower() == q]
         if classes:
+            members_by_class = {}
+            for sym in symbols:
+                if sym.get("name"):
+                    members_by_class.setdefault(sym["class_name"], []).append(sym)
             lines_printed = 0
             for s in classes:
                 ext = _EXT_TAG if Path(s['file']).stem in _EXT_FILES else ""
                 # Show the class-level doc text (everything before first ### member)
                 md_path = docs_dir / f"{s['file']}.md"
                 if md_path.exists():
-                    doc = _get_class_doc(md_path, ext)
+                    if s.get("enum_section_line"):
+                        doc = _get_enum_section_doc(md_path, s["enum_section_line"])
+                        if ext:
+                            doc = doc.replace("\033[0m", f"\033[0m{ext}", 1)
+                    else:
+                        doc = _get_class_doc(md_path, ext)
                 else:
                     doc = f"  \033[36;1m{s['class_name']}\033[0m{ext}"
                 doc_lines = doc.count('\n') + 1
@@ -664,6 +861,14 @@ def cmd_search(query):
                 print(doc)
                 lines_printed += doc_lines
 
+                # For exact class matches, also show indexed members (useful for enums).
+                if s["class_name"].lower() == q:
+                    members = members_by_class.get(s["class_name"], [])
+                    if members:
+                        members = sorted(members, key=lambda m: _sort_key(m["name"]))
+                        print("  \033[90m## Values\033[0m")
+                        _print_compact_members(members)
+
         else:
             # No class match → search member names across all classes
             results = []