1C - Bugfixes and QoL

Author: Omena0

README.md

@@ -10,3 +10,11 @@ Put your scripts to plugins/pyjavabridge/scripts and they will be ran on boot.
 ## Docs
 
 See [The documentation](docs/index.md)
+
+## Examples
+
+See [examples](examples/index.md)
+
+## Changelog
+
+See [changelog.md](changelog.md)

changelog.md

@@ -0,0 +1,37 @@
+
+# Changelog
+
+## 1C
+
+API cleanup
+
+Changes:
+
+- Added call_sync and field_or_call_sync helpers
+- Turned most attribute-like methods into attributes
+- Made all attributes synchronous
+- Added create classmethods to most classes
+- Added optional args to world.spawn_entity
+- Allowed spawning of non-living entities
+- Fixed player UUID lookups
+- Chat event return value is now the chat message format for that event
+- Bugfixes
+
+## 1B
+
+API expansion
+
+Changes:
+
+- Implemented most missing APIs
+- Added proper command argument parsing
+- Added docs
+- Bugfixes
+
+## 1A
+
+Initial release
+
+Changes:
+
+- Added most common APIs

docs/index.md

@@ -29,9 +29,11 @@ PyJavaBridge is a java plugin that manages and exposes APIs to python scripts vi
 - [Team](#team)
 - [Advancement](#advancement)
 - [AdvancementProgress](#advancementprogress)
-- [ItemMeta](#itemmeta)
 - [Difficulty](#difficulty)
 - [Objective](#objective)
+- [Chat](#chat)
+- [Raycast](#raycast)
+- [RaycastResult](#raycastresult)
 - [Enums](#enums)
   - [EntityType](#entitytype)
   - [EffectType](#effecttype)
@@ -53,11 +55,16 @@ Base event proxy. Event payloads may expose additional fields depending on event
 - `location`: [`Location`](#location) — The location involved in the event, if any.
 - `player`: [`Player`](#player) — The player involved in the event, if any.
 - `world`: [`World`](#world) — The world involved in the event, if any.
+- `slot`: int — Slot index for inventory click events.
 
 ### Methods
 
 - `cancel()` — Cancel the event if it is cancellable. Returns an awaitable that resolves to `None`.
 
+### Chat formatting
+
+For `player_chat` handlers, returning a string will cancel the original chat event and broadcast the returned string instead. Returning `None` (or no return value) leaves chat unchanged.
+
 ### Event types
 
 Events are resolved dynamically from handler names using snake_case to PascalCase plus `Event` (for example, `player_join` → `PlayerJoinEvent`).
@@ -83,19 +90,31 @@ Special cases:
 
 Common examples: `server_boot`, `player_join`, `block_break`, `block_place`, `block_explode`, `entity_explode`, `player_move`, `player_quit`, `player_chat`, `player_interact`, `inventory_click`, `inventory_close`, `entity_damage`, `entity_death`, `world_load`, `world_unload`, `weather_change`.
 
-## Server
+## Item
 
-`Server`-level API.
+Item (ItemStack) API.
 
 ### Attributes
 
-- `max_players`: int — Maximum player count.
-- `motd`: str — Server message of the day.
-- `name`: str — Server name.
-- `version`: str — Server version string.
+- `amount`: int — Item amount.
+- `type`: [`Material`](#material) — Item material.
+- `name`: str | None — Display name.
+- `lore`: list[str] — Lore lines.
+- `custom_model_data`: int | None — Custom model data.
+- `attributes`: list[dict] — Attribute modifiers.
+- `nbt`: dict — Serialized NBT map.
 
 ### Methods
 
+- `clone()` — Clone this item. Returns an awaitable that resolves to [`Item`](#item).
+- `is_similar(other: [`Item`](#item))` — Check if items are similar. Returns an awaitable that resolves to bool.
+- `max_stack_size()` — Get max stack size. Returns an awaitable that resolves to int.
+- `set_amount(value: int)` — Set item amount. Returns an awaitable that resolves to `None`.
+- `set_name(name: str)` — Set display name. Returns an awaitable that resolves to `None`.
+- `set_lore(lore: list[str])` — Set lore. Returns an awaitable that resolves to `None`.
+- `set_custom_model_data(value: int)` — Set custom model data. Returns an awaitable that resolves to `None`.
+- `set_attributes(attributes: list[dict])` — Set attribute modifiers. Returns an awaitable that resolves to `None`.
+- `set_nbt(nbt: dict)` — Set NBT map. Returns an awaitable that resolves to `None`.
 - `broadcast(message: str)` — Broadcast a message to all players and console. Returns an awaitable that resolves to `None`.
 - `create_boss_bar(title: str, color: [`BarColor`](#barcolor), style: [`BarStyle`](#barstyle))` — Create a boss bar. Returns an awaitable that resolves to [`BossBar`](#bossbar).
 - `get_advancement(key: str)` — Get an advancement by namespaced key. Returns an awaitable that resolves to [`Advancement`](#advancement).
@@ -104,6 +123,10 @@ Common examples: `server_boot`, `player_join`, `block_break`, `block_place`, `bl
 - `players()` — Return the online players. Returns an awaitable that resolves to a list of [`Player`](#player).
 - `scoreboard_manager()` — Get the scoreboard manager. Returns an awaitable that resolves to a scoreboard manager object.
 - `scheduler()` — Get the server scheduler. Returns an awaitable that resolves to a server scheduler object.
+- `wait(ticks: int = 1, after: callable | None = None)` — Wait for ticks then optionally run a callback. Returns an awaitable that resolves to `None`.
+- `frame()` — Async context manager that batches calls into one send.
+- `atomic()` — Async context manager that batches calls as an atomic group.
+- `flush()` — Send all pending batched requests immediately. Returns an awaitable that resolves to `None`.
 - `world(name: str)` — Get a world by name. Returns an awaitable that resolves to [`World`](#world).
 - `worlds()` — Return all loaded worlds. Returns an awaitable that resolves to a list of [`World`](#world).
 
@@ -124,6 +147,7 @@ Base entity proxy.
 - `custom_name()` — Get custom name. Returns an awaitable that resolves to any name value.
 - `fire_ticks()` — Get fire ticks. Returns an awaitable that resolves to int.
 - `is_dead()` — Check if entity is dead. Returns an awaitable that resolves to bool.
+- `is_alive()` — Check if entity is alive. Returns an awaitable that resolves to bool.
 - `is_valid()` — Check if entity is valid. Returns an awaitable that resolves to bool.
 - `passengers()` — Get passengers. Returns an awaitable that resolves to a list of [`Entity`](#entity).
 - `remove()` — Remove the entity. Returns an awaitable that resolves to `None`.
@@ -139,6 +163,10 @@ Base entity proxy.
 
 `Player` API (inherits [`Entity`](#entity)).
 
+### Constructor
+
+- `Player(uuid: str | None = None, name: str | None = None)` — Resolve a player by UUID or name.
+
 ### Attributes
 
 - `food_level`: int — Hunger level.
@@ -158,6 +186,14 @@ Base entity proxy.
 - `exp()` — Get experience progress $0..1$. Returns an awaitable that resolves to float.
 - `give_exp(amount: int)` — Give raw experience points. Returns an awaitable that resolves to `None`.
 - `has_permission(permission: str)` — Check a permission. Returns an awaitable that resolves to bool.
+- `is_alive()` — Check if the player is alive. Returns an awaitable that resolves to bool.
+- `add_permission(permission: str, value: bool = True)` — Add or set a permission (LuckPerms-aware). Returns an awaitable that resolves to bool.
+- `remove_permission(permission: str)` — Remove a permission (LuckPerms-aware). Returns an awaitable that resolves to bool.
+- `permission_groups()` — Get permission groups (LuckPerms-aware). Returns an awaitable that resolves to list of str.
+- `primary_group()` — Get primary permission group (LuckPerms-aware). Returns an awaitable that resolves to str or `None`.
+- `has_group(group: str)` — Check group membership (LuckPerms-only). Returns an awaitable that resolves to bool.
+- `add_group(group: str)` — Add a permission group (LuckPerms-only). Returns an awaitable that resolves to bool.
+- `remove_group(group: str)` — Remove a permission group (LuckPerms-only). Returns an awaitable that resolves to bool.
 - `is_flying()` — Check if the player is flying. Returns an awaitable that resolves to bool.
 - `is_op()` — Check if the player is op. Returns an awaitable that resolves to bool.
 - `is_sneaking()` — Check if sneaking. Returns an awaitable that resolves to bool.
@@ -286,16 +322,24 @@ Item (ItemStack) API.
 ### Attributes
 
 - `amount`: int — Stack amount.
-- `meta`: [`ItemMeta`](#itemmeta) — Item metadata.
 - `type`: [`Material`](#material) — Item material.
+- `name`: str | None — Display name.
+- `lore`: list[str] — Lore lines.
+- `custom_model_data`: int | None — Custom model data.
+- `attributes`: list[dict] — Attribute modifiers.
+- `nbt`: dict — Serialized NBT map.
 
 ### Methods
 
 - `clone()` — Clone this item. Returns an awaitable that resolves to [`Item`](#item).
 - `is_similar(other: [`Item`](#item))` — Check if items are similar. Returns an awaitable that resolves to bool.
 - `max_stack_size()` — Get max stack size. Returns an awaitable that resolves to int.
 - `set_amount(value: int)` — Set item amount. Returns an awaitable that resolves to `None`.
-- `set_meta(meta: [`ItemMeta`](#itemmeta))` — Set item meta. Returns an awaitable that resolves to `None`.
+- `set_name(name: str)` — Set display name. Returns an awaitable that resolves to `None`.
+- `set_lore(lore: list[str])` — Set lore. Returns an awaitable that resolves to `None`.
+- `set_custom_model_data(value: int)` — Set custom model data. Returns an awaitable that resolves to `None`.
+- `set_attributes(attributes: list[dict])` — Set attribute modifiers. Returns an awaitable that resolves to `None`.
+- `set_nbt(nbt: dict)` — Set NBT map. Returns an awaitable that resolves to `None`.
 
 ## Chunk
 
@@ -368,6 +412,10 @@ None.
 
 Active potion effect.
 
+### Constructor
+
+- `Effect(effect_type: EffectType | str, duration: int = 0, amplifier: int = 0, ambient: bool = False, particles: bool = True, icon: bool = True)` — Create a value effect.
+
 ### Attributes
 
 - `ambient`: bool — Whether the effect is ambient.
@@ -386,26 +434,37 @@ Active potion effect.
 
 Inventory. Can belong to an entity or block entity, or exist as a standalone open inventory screen.
 
+### Constructor
+
+- `Inventory(size: int = 9, title: str = "", contents: list[Item] | None = None)` — Create a value inventory.
+
 ### Attributes
 
 - `contents`: list of [`Item`](#item) — Inventory contents.
 - `holder`: any — Inventory holder.
 - `size`: int — Inventory size.
+- `title`: str — Inventory title.
 
 ### Methods
 
 - `add_item(item: [`Item`](#item))` — Add an item to the inventory. Returns an awaitable that resolves to any add result.
 - `clear()` — Clear inventory contents. Returns an awaitable that resolves to `None`.
+- `close(player: [`Player`](#player) | None = None)` — Close this inventory for a player. Returns an awaitable that resolves to `None`.
 - `contains(material: [`Material`](#material), amount: int = 1)` — Check if inventory contains a material. Returns an awaitable that resolves to bool.
 - `first_empty()` — Get first empty slot index. Returns an awaitable that resolves to int.
 - `get_item(slot: int)` — Get item in a slot. Returns an awaitable that resolves to [`Item`](#item).
+- `open(player: [`Player`](#player))` — Open this inventory for a player. Returns an awaitable that resolves to any open result.
 - `remove_item(item: [`Item`](#item))` — Remove an item from the inventory. Returns an awaitable that resolves to any remove result.
 - `set_item(slot: int, item: [`Item`](#item))` — Set item in a slot. Returns an awaitable that resolves to `None`.
 
 ## Material
 
 Material enum proxy, such as diamond, netherite, wood.
 
+### Constructor
+
+- `Material(name: str)` — Create a material enum value (case-insensitive).
+
 ### Attributes
 
 None.
@@ -540,21 +599,6 @@ None.
 - `remaining_criteria()` — Get remaining criteria. Returns an awaitable that resolves to a set of str.
 - `revoke_criteria(name: str)` — Revoke a criterion. Returns an awaitable that resolves to bool.
 
-## ItemMeta
-
-Item metadata proxy.
-
-### Attributes
-
-- `custom_model_data`: int — Custom model data value.
-- `has_custom_model_data`: bool — Whether custom model data exists.
-
-### Methods
-
-- `has_lore()` — Check if lore exists. Returns an awaitable that resolves to bool.
-- `lore()` — Get lore lines. Returns an awaitable that resolves to a list of str.
-- `set_custom_model_data(value: int)` — Set custom model data. Returns an awaitable that resolves to `None`.
-- `set_lore(lore: list[str])` — Set lore lines. Returns an awaitable that resolves to `None`.
 
 ## Difficulty
 
@@ -585,6 +629,34 @@ None.
 - `set_display_name(name: str)` — Set display name. Returns an awaitable that resolves to `None`.
 - `set_display_slot(slot: any)` — Set display slot. Returns an awaitable that resolves to `None`.
 
+## Chat
+
+Chat helper API.
+
+### Methods
+
+- `broadcast(message: str)` — Broadcast a chat message to all players and console. Returns an awaitable that resolves to `None`.
+
+## Raycast
+
+Raycast helpers.
+
+### Methods
+
+- `raycast(world, start, direction, max_distance=64.0, ray_size=0.2, include_entities=True, include_blocks=True, ignore_passable=True)` — Raycast in a world. `world` can be a world object or name. `direction` is a `(yaw, pitch)` tuple. Returns an awaitable that resolves to a [`RaycastResult`](#raycastresult) or `None` when no hit.
+
+## RaycastResult
+
+Raycast result data.
+
+### Attributes
+
+- `x`, `y`, `z`: float — Hit position.
+- `entity`: [`Entity`](#entity) | None — Hit entity.
+- `block`: [`Block`](#block) | None — Hit block.
+- `start_x`, `start_y`, `start_z`: float — Start position.
+- `yaw`, `pitch`: float — Direction angles used for the ray.
+
 ## Enums
 
 ## EntityType

examples/command.py

@@ -1,10 +1,53 @@
 from bridge import *
 
+# Test auto-generated usage
 @command("Hello world command")
 async def helloworld(event: Event):
     event.player.send_message("Hello, World!")
 
+# Test command args
 @command("Greet command")
 async def greet(event: Event, name: str = None):
     event.player.send_message(f"Hello, {name or event.player.name}!")
 
+# Test raycast / teleport
+@command("Teleport to spawn")
+async def spawn(event: Event):
+    ray:RaycastResult = await raycast('world', (0.5, 320, 0.5), (0, 90), 384, 0.5, False)
+    event.player.teleport((0.5, ray.y+0.5, 0.5))
+
+# Test Inventory API
+@command("open test gui")
+async def gui(event: Event):
+    inv = Inventory(3*9, title="Test GUI", contents=[Item('light_gray_stained_glass_pane').set_name(" ") for _ in range(3*9)])
+
+    inv.set_item(9+4, Item('totem_of_undying').set_name("Bing chilling"))
+
+    inv.open(event.player)
+
+# Test Inventory Click event
+@event
+async def inventory_click(event: Event):
+    if event.inventory.title != 'Test GUI':
+        return
+
+    event.cancel()
+
+    if event.slot == 9+4:
+        event.player.play_sound('item_totem_use')
+        event.player.send_message('Bing chilling')
+        event.inventory.close()
+
+@event
+async def inventory_drag(event: Event):
+    if event.inventory.title == 'Test GUI':
+        event.cancel()
+
+@command("Open someones inv")
+async def invsee(event: Event, p: str):
+    if p == event.player.name:
+        event.player.send_message("You cannot open your own inventory!")
+        event.player.play_sound('block_note_block_bass')
+        return
+
+    Player(p).inventory.open(event.player)

examples/index.md

@@ -0,0 +1,4 @@
+
+# Examples
+
+This folder contains some examples. They *should* all work on the latest dev version.