# Callbacks, part 1 of 3

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

Players can use World Code in custom worlds get functions they've written to run when game events happen. These special functions are called callbacks. The world code can be viewed by pressing F8 by default. Initially the world code will have this comment, which can be removed:

```text
tick onClose onPlayerJoin onPlayerLeave onPlayerJump onRespawnRequest
playerCommand onPlayerChat onPlayerAttemptChangeBlock onPlayerChangeBlock
onPlayerDropItem onPlayerPickedUpItem onPlayerSelectInventorySlot
onBlockStand onBlockStandStart onBlockStandStop onPlayerAttemptCraft
onPlayerCraft onPlayerAttemptOpenChest onPlayerOpenedChest
onPlayerMoveItemOutOfInventory onPlayerMoveInvenItem onPlayerMoveItemIntoIdxs
onPlayerSwapInvenSlots onPlayerMoveInvenItemWithAmt onPlayerAttemptAltAction
onPlayerAltAction onPlayerClick onPlayerClickUp onClientOptionUpdated
onMobSettingUpdated onInventoryUpdated onChestUpdated
onWorldAttemptChangeBlock onWorldChangeBlock onCreateBloxdMeshEntity
onEntityCollision onPlayerAttemptSpawnMob onWorldAttemptSpawnMob
onPlayerSpawnMob onWorldSpawnMob onWorldAttemptDespawnMob onMobDespawned
onPlayerAttemptSpawnVehicle onWorldAttemptSpawnVehicle onPlayerSpawnVehicle
onWorldSpawnVehicle onVehicleDespawned onEntityDeleted onPlayerAttack
onPlayerDamagingOtherPlayer onPlayerDamagingMob onMobDamagingPlayer
onMobDamagingOtherMob onAttemptKillPlayer onPlayerKilledOtherPlayer
onMobKilledPlayer onPlayerKilledMob onMobKilledOtherMob onPlayerPotionEffect
onPlayerDamagingMeshEntity onPlayerBreakMeshEntity onPlayerUsedThrowable
onPlayerThrowableHitTerrain onTouchscreenActionButton onTaskClaimed
onChunkLoaded onPlayerRequestChunk onItemDropCreated
onPlayerStartChargingItem onPlayerFinishChargingItem onPlayerAttemptFish
onPlayerSucceededFishCatch onPlayerFailedFishCatch onPlayerFinishQTE
onPlayerToggledShopMenu onPlayerPlayedEmote onPlayerEnteredVehicle
onPlayerExitedVehicle onPlayerBoughtShopItem onPlayerPressedButton
onPlayerReleasedButton onUiRequestResponded doPeriodicSave

To use a callback, just assign a function to it in the world code!
tick = () => {}			 or			 function tick() {}
```

You can use `api.setCallbackValueFallback("callbackName", defaultValue)` to set a default value to be returned by your callback code if it throws an error.

## doPeriodicSave
Called every so often.

You should save custom db values/s3 objects here.

Persisted items ARE saved on graceful shutdown (e.g. uncaught error, update, etc),

but this helps prevent large data-loss on non-graceful shutdowns.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|

## onAttemptKillPlayer
Called when a player is about to be killed

Return "preventDeath" to prevent the player from being killed

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| killedPlayer | `PlayerId` | The id of the player being killed |
| attackingLifeform | `LifeformId` | The optional id of the lifeform attacking the player |


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

## onBlockStand
Called when a player stands on a block

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that stood on the block |
| x | `number` | The x coordinate of the block that was stood on |
| y | `number` | The y coordinate of the block that was stood on |
| z | `number` | The z coordinate of the block that was stood on |
| blockName | `BlockName` | The name of the block that was stood on |

## onBlockStandStart
Called when a player enters a block. Only called once per block until the player leaves the block.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that entered the block |
| x | `number` | The x coordinate of the block that was entered |
| y | `number` | The y coordinate of the block that was entered |
| z | `number` | The z coordinate of the block that was entered |
| blockName | `BlockName` | The name of the block that was entered |

## onBlockStandStop
Called when a player leaves a block.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player that left the block |
| x | `number` | The x coordinate of the block that was left |
| y | `number` | The y coordinate of the block that was left |
| z | `number` | The z coordinate of the block that was left |
| blockName | `BlockName` | The name of the block that was left |

## onChestUpdated
Called when a chest is updated by a player

x, y, z, will be null if isMoonstoneChest is true

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| initiatorEId | `PlayerId` | The id of the player who updated the chest |
| isMoonstoneChest | `boolean` | Whether the chest is a moonstone chest |
| x | `number \| null` | The x coordinate of the chest |
| y | `number \| null` | The y coordinate of the chest |
| z | `number \| null` | The z coordinate of the chest |

## onChunkLoaded
Called when a chunk is first loaded

API Methods that modify the chunk like setBlock cannot be used here to make

persisted changes, and will introduce client-server desync most cases,

but might have some creative uses if you know what you're doing.

For most use cases, consider using another callback e.g. tick.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| chunkId | `string` | The id of the chunk being loaded |
| chunk | `LoadedChunk` | The chunk being loaded, which can be modified by this callback  * For world code callbacks this value will always be null. |
| wasPersistedChunk | `boolean` | Whether the chunk was persisted |

## onClientOptionUpdated
Called when a client option is updated

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player whose option was updated |
| option | `ClientOption` | The option that was updated |
| value | `any` | The new value of the option, always null for custom code |

## onClose
Called when the lobby is shutting down

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| serverIsShuttingDown | `boolean` | Whether the server is shutting down |

## onCreateBloxdMeshEntity
Called when a mesh entity is created

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| eId | `EntityId` | The id of the mesh entity |
| type | `string` | The type of mesh entity |
| initiatorId | `EntityId \| null` | The id of the entity that created the mesh entity, if any |

## onEntityCollision
Called when a entity collides with another entity

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| eId | `EntityId` | The id of the entity |
| otherEId | `EntityId` | The id of the other entity |

## onEntityDeleted
Called when any non-player entity is deleted, after any type specific callback such as "onMobDespawned".

Not called when an item drop is picked up or expires, or when a throwable expires or hits something.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| eId | `EntityId` | The id of the entity deleted |
| entityType | `EntityType` | The type of the entity deleted |

## onInventoryUpdated
Called when a player's inventory is updated

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player whose inventory was updated |

## onItemDropCreated
Called when an item drop is created

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| itemEId | `EntityId` | The id of the item drop |
| itemName | `string` | The name of the item dropped |
| itemAmount | `number` | The amount dropped |
| x | `number` | The x coordinate of the item drop |
| y | `number` | The y coordinate of the item drop |
| z | `number` | The z coordinate of the item drop |

## onMobDamagingOtherMob
Called when a mob is damaging another mob

Return "preventDamage" to prevent damage

Return number to change damage dealt to that amount

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| attackingMob | `MobId` | the id of the mob attacking |
| damagedMob | `MobId` | the id of the mob being damaged |
| damageDealt | `number` | the amount of damage dealt |
| withItem | `string` | the item used to attack |
| damageInfo | `DamageInfo` | what dealt the hit: a melee swing, an explosion, a projectile, etc. |


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

## onMobDamagingPlayer
Called when a mob is damaging a player

Return "preventDamage" to prevent damage

Return number to change damage dealt to that amount

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| attackingMob | `MobId` | the id of the mob damaging the player |
| damagedPlayer | `PlayerId` | the id of the player being damaged |
| damageDealt | `number` | the amount of damage dealt |
| withItem | `string` | the item used to attack |
| damageInfo | `DamageInfo` | what dealt the hit: a melee swing, an explosion, a projectile, etc. |


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

## onMobDespawned
Called when a mob is despawned

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| mobId | `MobId` | The id of the mob despawned |

## onMobKilledOtherMob
Called when a mob kills another mob

Return "preventDrop" to prevent the mob from dropping items

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| attackingMob | `MobId` | The id of the mob attacking |
| killedMob | `MobId` | The id of the mob killed |
| damageDealt | `number` | The amount of damage dealt |
| withItem | `string` | The item used to attack |


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

## onMobKilledPlayer
Called when a mob kills a player

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

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


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

## onMobSettingUpdated
Called when a mob setting is updated

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| mobId | `MobId` | The id of the mob whose setting was updated |
| setting | `MobSetting` | The setting that was updated |
| value | `any` | The new value of the setting |

## onPlayerAltAction
Called when player completes an alt action. Right click, the interact bind (E by default) and a mobile tap all arrive here; a left click does not, so this is the callback to use for anything a player should have to choose to do rather than trigger by swinging.

Keeps firing while the input is held, roughly every 50-150ms. That is harmless for anything idempotent, but an interaction that grants an item, charges a currency or advances a conversation has to swallow the repeats itself - open shops with toggle off, and debounce the rest per player.

The co-ordinates will be undefined if there is no targeted block (and block will be "Air")

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player completing the alt action |
| x | `number` | The x coordinate of the targeted block |
| y | `number` | The y coordinate of the targeted block |
| z | `number` | The z coordinate of the targeted block |
| block | `BlockName` | The name of the targeted block |
| targetEId | `EntityId \| null` | The id of the targeted entity |

## onPlayerAttack
Called when a player attacks another player

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

## onPlayerAttemptAltAction
Called when player alt actions (right click on pc).

The co-ordinates will be undefined if there is no targeted block (and block will be "Air")

Some actions can be prevented by returning "preventAction",

but this may not work as well for certain actions which the game client predicts to succeed -

test it to see if it works for your use case, feel free to report any broken ones.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The id of the player attempting the alt action |
| x | `number` | The x coordinate of the targeted block |
| y | `number` | The y coordinate of the targeted block |
| z | `number` | The z coordinate of the targeted block |
| block | `BlockName` | The name of the targeted block |
| targetEId | `EntityId \| null` | The id of the targeted entity |


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

## onPlayerAttemptChangeBlock
Called before a player changes a block.

Return "preventChange" to stop it. Then onPlayerChangeBlock will not run.

Growing EZ placements validate at request time and again at completion; keep validation free of rewards or charges.

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

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The player trying to change the block |
| x | `number` | The block's x coordinate |
| y | `number` | The block's y coordinate |
| z | `number` | The block's z coordinate |
| fromBlock | `BlockName` | The current block |
| toBlock | `BlockName` | The proposed block |
| droppedItem | `BlockName \| null` | The item that would drop |
| fromBlockInfo | `MultiBlockInfo` | The current multiblock info |
| toBlockInfo | `MultiBlockInfo` | The proposed multiblock info |


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

## onPlayerAttemptCraft
Called when a player attempts to craft an item

Return "preventCraft" to prevent a craft from happening

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


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

## onPlayerAttemptFish
Called once when a fishing hook first enters water. Coordinates are the bob's position at water entry.

Return "preventFish" to cancel, or { caughtItemName?, biteDelayMs?, qte? } to select the fish and override the rod's bite delay

and nine-second timed-click QTE. Default delays are Rusty 7–9 seconds, Sturdy 5–7, and Carbon/other rods 2–4.

The selected fish is fixed for the attempt; omitting caughtItemName uses the engine's default fish selection.

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


### Returns:
`void \| FishingAttemptOptions \| "preventFish"`