# Callbacks, part 2 of 3

Part 2 of 3 of [Callbacks](https://bloxd.io/docs/callbacks.md). It covers onPlayerAttemptOpenChest to onPlayerMoveInvenItemWithAmt. [llms.txt](https://bloxd.io/docs/llms.txt) lists every part.

## onPlayerAttemptOpenChest
Called when a player attempts to open a chest

Return "preventOpen" to prevent the player from opening the chest

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that is attempting to open the chest |
| x | `number` | The x coordinate of the chest that the player is attempting to open |
| y | `number` | The y coordinate of the chest that the player is attempting to open |
| z | `number` | The z coordinate of the chest that the player is attempting to open |
| isMoonstoneChest | `boolean` | Whether the chest is a moonstone chest |
| isIronChest | `boolean` | Whether the chest is an iron chest |


### Returns:
`void \| "preventOpen"`

## onPlayerAttemptSpawnMob
Called when a player attempts to spawn a mob, e.g. using a spawn orb.

Return "preventSpawn" to prevent the mob from spawning.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player |
| mobType | `MobType` | The type of mob |
| x | `number` | The potential x coordinate of the mob |
| y | `number` | The potential y coordinate of the mob |
| z | `number` | The potential z coordinate of the mob |


### Returns:
`void \| "preventSpawn"`

## onPlayerAttemptSpawnVehicle
Called when a vehicle is spawned on a player's behalf.

Return "preventSpawn" to prevent the vehicle from spawning.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player |
| vehicleType | `MeshEntityVehicleType` | The type of vehicle |
| x | `number` | The potential x coordinate of the vehicle |
| y | `number` | The potential y coordinate of the vehicle |
| z | `number` | The potential z coordinate of the vehicle |


### Returns:
`void \| "preventSpawn"`

## onPlayerBoughtShopItem
Called after a player successfully buys a shop item

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that bought the item |
| categoryKey | `ShopCategoryKey` | The shop category key |
| itemKey | `ShopItemKey` | The shop item key |
| item | `BoughtShopItem` | The resolved shop item (with per-player overrides applied, internal properties stripped) |
| userInput | `string` | The user input provided, if the item has a userInput config |

## onPlayerBreakMeshEntity
Called when a player breaks a mesh entity

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player breaking the mesh entity |
| entityId | `EntityId` | The id of the mesh entity being broken |

## onPlayerChangeBlock
In World Code, called once after all attempt callbacks allow a player block change, before the block is set.

The current block and its data are still available. Return "preventChange" to cancel the request.

Return "preventDrop" to stop the engine item drop, or [x, y, z] to set its position.

Drop returns do not skip built-in validation or change notifications; any "preventDrop" takes precedence over a position.

A block written here with api.setBlock is preserved, with normal drops/inventory charges unless the request is cancelled.

Cancellation does not undo your own script effects. Built-in change effects run after this callback.

For growing EZ placements this runs at request time only; completion validates again without repeating this callback.

Writing the target yourself completes that EZ request immediately, without delayed growth or a growth refund.

Native games/plugins receive uninterrupted before-commit notifications and must veto in onPlayerAttemptChangeBlock.

When placing, fromBlock is Air, or the slab a matching slab completes. When breaking, toBlock is Air.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that changed the block |
| x | `number` | The x coordinate of the block that was changed |
| y | `number` | The y coordinate of the block that was changed |
| z | `number` | The z coordinate of the block that was changed |
| fromBlock | `BlockName` | The old block that was replaced |
| toBlock | `BlockName` | The new block that was placed |
| droppedItem | `BlockName \| null` | The item that was dropped |
| fromBlockInfo | `MultiBlockInfo` | The info of the old block that was replaced |
| toBlockInfo | `MultiBlockInfo` | The info of the new block that was placed |
| dropsPrevented | `boolean` | Whether earlier notifications prevented drops; false during World Code validation |


### Returns:
`void \| "preventChange" \| "preventDrop" \| [number, number, number]`

## onPlayerChat
Called when a player sends a chat message

Return false or null to prevent the broadcast of the message.

Return a string or CustomTextStyling to add a prefix to message.

Return for most flexibility: an object where keys are playerIds -

the value for a playerId being false means that player won't receive the message.

Otherwise playerId values should be an object with (optional) keys

prefixContent and chatContent to modify the prefix and the chat.

CustomTextStyling[] prefixContent is expected, e.g. [["prefix"]] or [[{ str: "prefix" }]].

World code is not permitted to specify chatContent, it will be ignored.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that sent the message |
| chatMessage | `string` | The message that the player sent |
| channelName | `string` | The name of the channel that the message was sent in |


### Returns:
`boolean \| void \| ChatTags \| OnPlayerChatObjectResponse`

## onPlayerClick
Called when a player clicks

Don't have important functionality depending on wasAltClick,

as it'll always be false for touchscreen players.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player clicking |
| wasAltClick | `boolean` | Whether the click was an alt click (e.g. right click |
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| block | `BlockName` |  |
| targetEId | `EntityId \| null` |  |

## onPlayerClickUp
Called when a player releases a click (mouse-up on desktop, touch-end on mobile).

Fires for both primary and secondary click releases.

Keep in mind wasAltClick will always be false for touchscreen players.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player releasing click |
| wasAltClick | `boolean` | Whether the released click was an alt click (e.g. right click |
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| block | `BlockName` |  |
| targetEId | `EntityId \| null` |  |

## onPlayerCraft
Called when a player crafts an item

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that crafted the item |
| itemName | `string` | The name of the item that was crafted |
| craftingIdx | `number` | The index of the used recipe in the item's recipe list |
| recipe | `RecipesForItem[number]` | The recipe that was used to craft the item |
| craftTimes | `number` | The number of times the craft recipe is used at once (e.g. shift held while crafting) |

## onPlayerDamagingMeshEntity
Called when a player is damaging a mesh entity

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player damaging the mesh entity |
| damagedId | `EntityId` | The id of the mesh entity being damaged |
| damageDealt | `number` | The amount of damage dealt |
| withItem | `string` | The item used to attack |

## onPlayerDamagingMob
Called when a player is damaging a mob

Return "preventDamage" to prevent damage

Return number to change damage dealt to that amount

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player damaging the mob |
| mobId | `MobId` | The id of the mob being damaged |
| damageDealt | `number` | The amount of damage dealt |
| withItem | `string` | The item used to attack |
| damagerDbId | `PlayerDbId` | The database id of the player attacking |
| damageInfo | `DamageInfo` | What dealt the hit: a melee swing, an explosion, a projectile, etc. |


### Returns:
`number \| void \| "preventDamage"`

## onPlayerDamagingOtherPlayer
Called when a player is damaging another player

Return "preventDamage" to prevent damage

Return number to change damage dealt to that amount

Sometimes the damager will have left the game (e.g. spikes placer);

in this case, attackingPlayer will be the damagedPlayer,

but we pass damagerDbId for use cases where it's important.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| attackingPlayer | `PlayerId` | The id of the player attacking |
| damagedPlayer | `PlayerId` | The id of the player being damaged |
| damageDealt | `number` | The amount of damage dealt |
| withItem | `string` | The item used to attack |
| bodyPartHit | `LifeformBodyPart` | The body part hit |
| damagerDbId | `PlayerDbId` | The database id of the player attacking |
| damageInfo | `DamageInfo` | What dealt the hit: a melee swing, an explosion, a projectile, etc. |


### Returns:
`number \| void \| "preventDamage"`

## onPlayerDropItem
Called when a player drops an item

Return "preventDrop" to prevent the player from dropping the item at all.

Return "allowButNoDroppedItemCreated" to allow discarding items without dropping them.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that dropped the item |
| x | `number` | The x coordinate of the item that was dropped |
| y | `number` | The y coordinate of the item that was dropped |
| z | `number` | The z coordinate of the item that was dropped |
| itemName | `ItemName` | The name of the item that was dropped |
| itemAmount | `number` | The amount of the item that was dropped |
| fromIdx | `number` | The index of the item that was dropped from the player's inventory |


### Returns:
`void \| "preventDrop" \| "allowButNoDroppedItemCreated"`

## onPlayerEnteredVehicle
Called when a player enters a vehicle

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that entered the vehicle |
| vehicleType | `MeshEntityVehicleType` | The type of the vehicle |
| vehicleEId | `EntityId` | The id of the vehicle |

## onPlayerExitedVehicle
Called when a player exits a vehicle

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that exited the vehicle |
| vehicleType | `MeshEntityVehicleType` | The type of the vehicle |
| vehicleEId | `EntityId` | The id of the vehicle |

## onPlayerFailedFishCatch
Called after the fishing QTE fails or its time window expires, after removing the bob/session.

Coordinates are the fishing position captured at water entry. Retracting, switching rods, dying, and leaving cancel silently.

caughtItemName is the item selected for the failed attempt; no reward is given.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| rodName | `string` |  |
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| caughtItemName | `ItemName` |  |

## onPlayerFinishChargingItem
Called when a player finishes charging an item

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player charging the item |
| used | `boolean` | Whether the item was used |
| itemName | `string` | The name of the charged item |
| duration | `number` | The duration of the charge |

## onPlayerFinishQTE


### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| qteId | `QTERequestId` |  |
| result | `boolean` |  |

## onPlayerJoin
Called when a player joins the lobby

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `string` | The id of the player that joined |
| fromGameReset | `boolean` | Whether this call is from a game reset (used by SessionBasedGame) |

## onPlayerJump
Called when a player jumps

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `string` | The id of the player that jumped |

## onPlayerKilledMob
Called when a player kills a mob

Return "preventDrop" to prevent the mob from dropping items

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player killed |
| mobId | `MobId` | The id of the mob that killed the player |
| damageDealt | `number` | The amount of damage dealt |
| withItem | `string` | The item used to attack |


### Returns:
`void \| "preventDrop"`

## onPlayerKilledOtherPlayer
Called when a player kills another player

Return "keepInventory" to not drop the player's inventory

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| attackingPlayer | `string` | The id of the player attacking |
| killedPlayer | `string` | The id of the player killed |
| damageDealt | `number` | The amount of damage dealt |
| withItem | `string` | The item used to attack |


### Returns:
`void \| "keepInventory"`

## onPlayerLeave
Called when a player leaves the lobby

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `string` | The id of the player that left |
| serverIsShuttingDown | `boolean` | Whether the server is shutting down |

## onPlayerMoveInvenItem
Called for all types of inventory item movement.

Certain methods of moving item can result in splitting a stack

into multiple slots. (e.g. shift-click).

toStartIdx and toEndIdx provide the min and max idxs moved into.

Return "preventChange" to prevent item movement.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player moving the item |
| fromIdx | `number` | The index that the item is being moved from |
| toStartIdx | `number` | The start index that the item is being moved into |
| toEndIdx | `number` | The end index that the item is being moved into |
| amt | `number` | The amount of the item being moved |


### Returns:
`void \| "preventChange"`

## onPlayerMoveInvenItemWithAmt
Return "preventChange" to prevent the movement

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player moving the item |
| i | `number` | The index of the first slot |
| j | `number` | The index of the second slot |
| amt | `number` | The amount of the item being moved |


### Returns:
`void \| "preventChange"`