# API Reference, part 1 of 5

Part 1 of 5 of [API Reference](https://bloxd.io/docs/api-reference.md). It covers addCustomKillfeedMessage to createEnchantmentAttributesForItem. [llms.txt](https://bloxd.io/docs/llms.txt) lists every part.

## addCustomKillfeedMessage
Add a custom killfeed message to the killfeed

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| killer | ` { eId: EntityId } \| { name: string; colour: string } ` | The entity ID or a custom name and colour for the killer |
| victim | ` { eId: EntityId } \| { name: string; colour: string } ` | The entity ID or a custom name and colour for the victim |
| withItem | `string` | The item used |

## addFollowingEntityToPlayer
Add following entity to an entity

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `EntityId` |  |
| eId | `EntityId` |  |
| offset | `number[]` |  |
| followsPlayerRotation | `boolean` |  |

## addQTE
Create and register the UI for the requested quicktime event (QTE) to the screen.

Handle the result via the onPlayerFinishQTE engine callback.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| qteParameters | `QTEClientParameters<T>` | includes type and parameters |



### Returns:
`QTERequestId`

 

an id that can be passed to deleteQTE

## addUiRequest
Add a request for the player to answer in the top right corner. E.g. accepting or denying a tprequest.



Use onUiRequestResponded to handle the response.



Example Usage:

```js
const myRequestId = api.addUiRequest(playerId, {
  type: "standard",
  title: "Do you want to join the game?",
}, 5000)

onUiRequestResponded = (playerId, uiRequestId, response) => {
  if (uiRequestId === myRequestId) {
    api.log(response)
  }
}
```

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The ID of the player to add the request to. |
| parameters | `UiRequestClientParameters` | The parameters of the request. |
| timeoutAfterMs | `number` | The timeout after which the request will be automatically deleted. A response will not be given and onUiRequestResponded will not be called. |



### Returns:
`UiRequestId`

 

The ID of the request. Pass into deleteUiRequest or cross-reference with onUiRequestResponded.

## addUiRequestPopup
Add a request for the player to answer in the form of a popup. This blocks the player from doing anything else until they respond.



Use onUiRequestResponded to handle the response.



Example Usage:

```js
const myRequestId = api.addUiRequestPopup(playerId, "Do you want to join the game?")

onUiRequestResponded = (playerId, uiRequestId, response) => {
  if (uiRequestId === myRequestId) {
    api.log(response)
  }
}
```

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The ID of the player to add the request to. |
| requestText | `string` | The text of the request. |



### Returns:
`PNull<UiRequestId>`

 

The ID of the request, or null if the request was rate limited. Pass into deleteUiRequest or cross-reference with onUiRequestResponded.

## animateEntity
Animates the given entity. Pass `null` for `animationSchema` to stop the entity's current animation (the

`initialTimeFraction` and `animationSpeed` arguments are ignored in that case).

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| entityId | `EntityId` |  |
| animationSchema | `AnimationSchema \| BlockbenchAnimationSchema \| null` |  |
| initialTimeFraction | `number` |  |
| animationSpeed | `number` |  |

## applyAuraChange
Add (or remove if negative) aura to a player. Will not go over max level or under 0

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| auraDiff | `number` |  |



### Returns:
`number`

 

The actual change in aura

## applyEffect
Apply an effect to a lifeform.

Can be an inbuilt effect E.g. "Speed" (speed boost), "Damage" (damage boost).

For inbuilt just pass the name of the effect and the functionality is handled in-engine.

For custom effect, you pass customEffectInfo. The icon can be an InGameIconName or a bloxd item name.

The custom effect onEndCb is an optional helper within which you can undo the effect you applied.

Note that onEndCb will not work for press to code boards, code blocks or world code.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| lifeformId | `LifeformId` |  |
| effectName | `string` |  |
| duration | `number \| null` |  |
| customEffectInfo | ` { icon?: IngameIconName \| ItemName; onEndCb?: () => void; displayName?: string \| TranslatedText } & Partial<InbuiltEffectInfo> ` |  |

## applyHealthChange


### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| lifeformId | `LifeformId` |  |
| changeAmount | `number` | Must be an integer. A positive amount will increase the entity's health. A negative amount will decrease the entity's shield first, then their health. |
| whoDidDamage | ` LifeformId \| { lifeformId: LifeformId; withItem: string } ` | Optional - If damage done by another player |
| broadcastLifeformHurt | `boolean` |  |



### Returns:
`boolean`

## applyImpulse
Apply an impulse to an entity

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| eId | `EntityId` |  |
| xImpulse | `number` |  |
| yImpulse | `number` |  |
| zImpulse | `number` |  |

## applyMeleeHit
Make it as if hittingEId hit hitEId

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| hittingEId | `LifeformId` |  |
| hitEId | `LifeformId` |  |
| dirFacing | `number[]` |  |
| bodyPartHit | `PNull<LifeformBodyPart>` |  |
| overrides | ` { damage?: PNull<number> heldItemName?: PNull<string> horizontalKbMultiplier?: number verticalKbMultiplier?: number } ` |  |



### Returns:
`boolean`

 

whether the attack damaged the lifeform

## attemptApplyDamage
Apply damage to a lifeform.

eId is the player initiating the damage, hitEId is the lifeform being hit.



It is recommended to self-inflict damage when the game code wants to apply damage to a lifeform.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| { eId, hitEId, attemptedDmgAmt, withItem, bodyPartHit = undefined, attackDir = undefined, showCritParticles = false, reduceVerticalKbVelocity = true, horizontalKbMultiplier = 1, verticalKbMultiplier = 1, broadcastEntityHurt = true, attackCooldownSettings = null, hittingSoundOverride = null, ignoreOtherEntitySettingCanAttack = false, isTrueDamage = false, damagerDbId = null, damageCause = null, } | `PlayerAttemptDamageOtherPlayerOpts` |  |



### Returns:
`boolean`

 

whether the attack damaged the lifeform

## attemptCreateAudioEntity
Create an invisible audio entity at a world position that loops a sound to

nearby players (e.g. a waterfall or fireplace).



Audio entities count against the same budget as physics-less mesh entities; returns null

if that budget is exhausted.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| soundName | `string` | The sound to loop. |
| volume | `number` |  |
| options | ` { refDistance?: number maxHearDist?: number rate?: number } ` | : number, maxHearDist: number, rate: number} refDistance: higher means the sound decreases less in volume with distance. Defaults to 3. Hitting is 4. Guns are 10 maxHearDist: sound is not played if player is further than this. Defaults to 30 rate: The speed of playback. Also affects pitch. 0.5-4. Lower playback = lower pitch. Good for varying the sound. E.g. item pickup sound has a random rate between 1 and 1.5. |



### Returns:
`PNull<EntityId>`

 

the audio entity ID, or null if the entity budget is exhausted

## attemptCreateMeshEntity
Try to create a mesh entity. This creates an entity whose mesh position is synced with clients.

Set entity position using setPosition

There is a limit to the number of mesh entities and throwables that can be created, with an even smaller limit for mesh entities with physics.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| type | `MeshType` |  |
| opts | `MeshEntityOpts[MeshType]` |  |
| name | `string` | The default name for the nametag |
| physicsOptions | `MeshEntityPhysicsOpts` | Physics Options |
| initiatorId | `EntityId` | The entity that initiated the creation of the mesh entity. |



### Returns:
`PNull<EntityId>`

 

null if the entity creation failed, otherwise the entity ID.

## attemptCreateThrowable
Try to create a throwable entity.

Similar to creating a mesh entity and uses the same rate limiting.

However, this uses the predefined throwables system and physics used by throwable items with the game

Each throwable item has its own behaviour already, including default velocity, damage and gravity multipliers.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| throwerEId | `EntityId` |  |
| itemName | `ThrowableItem` | Must be an Item that is usually throwable in-engine |
| position | `[number, number, number]` | Starting position |
| direction | `[number, number, number]` |  |
| velocityMult | `number` | Multiplier for the default velocity of the throwable item |
| damageMult | `number` | Multiplier for the default damage of the throwable item |
| gravityMult | `number` | Multiplier for the default gravity of the throwable item |
| attributes | `ItemAttributes` | item attributes (currently used only for the "Boomerag" item) |



### Returns:
`string`

 

null if throwable creation failed, otherwise the entity ID.

## attemptSpawnMob
Try to spawn a mob into the world at a given position. Returns null on failure.

WARNING: Either the "onPlayerAttemptSpawnMob" or the "onWorldAttemptSpawnMob" game callback will be called

depending on whether "spawnerId" is provided. Calling this function inside those callbacks risks infinite recursion.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| mobType | `TMobType` |  |
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| opts | `MobSpawnOpts<TMobType>` | Includes: - mobHerdId The ID of this mob's herd. (A mob herd represents a collection of mobs that move together.) - spawnerId The ID of the player who tried to spawn this mob. - mobDbId A persistent ID for the mob. This can be useful when loading mob data from the database. If the DB ID is already taken, null will be returned. - name If set, gives the mob a name that will be displayed as a nametag above their head. - playSoundOnSpawn - variation - physicsOpts { width: number; height: number; collidesEntities: boolean } |



### Returns:
`PNull<MobId>`

 

null if the mob could not be spawned.
This can happen when there are too many mobs in the world for the current number
of players in the lobby, or if the area is protected e.g. by spawn area protection.

## attemptSpawnVehicle
Try to spawn a rideable vehicle, which players can mount with an alt action.

There is a limit to the number of mesh entities with physics that can be created.

WARNING: Either the "onPlayerAttemptSpawnVehicle" or the "onWorldAttemptSpawnVehicle" game callback will be called

depending on whether "spawnerId" is provided. Calling this function inside those callbacks risks infinite recursion.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| vehicleType | `MeshEntityVehicleType` |  |
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| opts | `VehicleSpawnOpts` | Includes: - spawnerId The ID of the player who spawned the vehicle. The vehicle faces away from them. |



### Returns:
`PNull<EntityId>`

 

null if the vehicle could not be spawned, otherwise the entity ID of the vehicle.

## attemptWorldChangeBlock
Initiate a block change "by the world".

Calls onWorldAttemptChangeBlock, then onWorldChangeBlock if allowed.

initiatorDbId is null if the change was initiated by the game code.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| initiatorDbId | `PNull<PlayerDbId>` |  |
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |
| blockName | `BlockName` |  |
| extraInfo | `WorldBlockChangedInfo` |  |



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

 

"preventChange" if the change was prevented, "preventDrop" if the change was allowed but without dropping any items, and undefined if the change was allowed with an item drop

## blockCoordToChunkId
Get the unique id of the chunk containing pos in the current map

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| pos | `number[]` |  |



### Returns:
`string`

## blockIdToBlockName
Goes from block id to block name. The reverse of blockNameToBlockId

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| blockId | `BlockId` |  |



### Returns:
`BlockName`

## blockNameToBlockId
Get the numeric id of a block used in the ndarrays returned from getChunk

I.e. chunk.blockData.set(x, y, z, api.blockNameToBlockId("Dirt"))

or chunk.blockData.get(x, y, z) === api.blockNameToBlockId("Dirt")

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| blockName | `BlockName` |  |
| allowInvalidBlock | `boolean` | Don't throw an error if the block name is invalid. Defaults false. If true and name is invalid, returns null. |



### Returns:
`PNull<number>`

## broadcastMessage
Send a message to everyone

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| message | `string \| CustomTextStyling` | The text contained within the message. Can use `Custom Text Styling`. |
| style | ` { fontWeight?: number \| string; color?: string; colour?: string } ` | An optional style argument. Can contain values for fontWeight and color of the message. style is ignored if message uses custom text styling (i.e. is not a string). |

## broadcastSound
See documentation for api.playSound

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| soundName | `string` |  |
| volume | `number` |  |
| rate | `number` |  |
| posSettings | ` { playerIdOrPos: EntityId \| number[] maxHearDist?: number refDistance?: number } ` |  |
| exceptPlayerId | `PlayerId` |  |

## calcExplosionForce


### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| eId | `EntityId` |  |
| explosionType | `ExplosionType` |  |
| knockbackFactor | `number` |  |
| explosionRadius | `number` |  |
| explosionPos | `number[]` |  |
| ignoreProjectiles | `boolean` |  |



### Returns:
` { force: [number, number, number]; forceFrac: number; } `

## canOpenStandardChest
Checks if a player is able to open a chest at a given location,

as per the rules laid out by the "onPlayerAttemptOpenChest" game callback.

Returns true if the player can open the chest, false if they cannot, and void if the chest does not exist.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| chestX | `number` |  |
| chestY | `number` |  |
| chestZ | `number` |  |



### Returns:
`PNull<boolean>`

## changePlayerIntoSkin
Change a part of a player's skin.

UGC code is restricted to cosmetics from packs with ugcSelectable; internal code can use any cosmetics.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | Player to change |
| cosmeticType | `CosmeticType` | Type of cosmetic |
| cosmeticName | `CosmeticName` | Chosen cosmetic, will be made lowercase automatically |

## checkValid
Check your game (and, optionally, a entity) is still valid and executing.

Useful if you're using async functions and await within your game.

If you use await/async or promises and do not check this, your game could have closed and then the rest of your

async code executes.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| entityId | `PNull<EntityId>` |  |



### Returns:
`boolean`

## chunkIdToBotLeftCoord
Get the co-ordinates of the block in the chunk with the lowest x, y, and z co-ordinates

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| chunkId | `string` |  |



### Returns:
`[number, number, number]`

## clearDirectionArrow
Clear a directional arrow from the player's screen.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The player to clear the arrow for |
| id | `PNull<string>` | The arrow identifier to clear. If null, clears all arrows for this player. |

## clearInventory
Clear the players inventory

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |

## clearKillstreak
Clears the player's current killstreak

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |

## closeChestForPlayer
Close a chest for a player.

If the player does not have a chest open, do nothing.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |

## configureShopCategory
Set properties of a shop category.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| categoryKey | `ShopCategoryKey` | The key of the category to configure |
| config | `ShopCategoryConfig` | Category configuration properties |

## configureShopCategoryForPlayer
Configure a shop category for a specific player.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The player to configure the category for |
| categoryKey | `ShopCategoryKey` | The key of the category to configure |
| config | `ShopCategoryConfig` | Category configuration properties |

## copyChunk
Copies chunk from one position to another.

A good use case for this is storing 'template' chunks that can be continuously copied to a new position.

In order to reset an area to the template, e.g. resetting a session-based game.



NOTE: Does nothing if the source chunk is not loaded.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| fromPos | `number[]` | A block coordinate within the chunk to copy from. |
| toPos | `number[]` | A block coordinate within the chunk to copy to. |

## createEnchantmentAttributesForItem
Create enchantment attributes for an item at a given enchantment level. Same behaviour as if that level of enchant was selected for the item in an enchanting table.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| itemName | `ItemName` |  |
| enchantmentLevel | `number` |  |



### Returns:
`EnchantmentAttributes`