# API Reference, part 3 of 5

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

## getNumMobs
Get the number of mobs in the world.

### Returns:
`number`

## getNumPlayers
Get the number of players in the room

### Returns:
`number`

## getOtherEntitySetting
Get the value of a player's other-entity setting for a specific entity.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| relevantPlayerId | `PlayerId` |  |
| targetedEntityId | `EntityId` |  |
| settingName | `Setting` |  |



### Returns:
`OtherEntitySettings[Setting]`

## getPlayerCosmetic
Get a single equipped cosmetic for a player.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| cosmeticType | `CosmeticType` | Type of cosmetic |



### Returns:
`CosmeticName`

## getPlayerDbId
Given a player, get their permanent identifier that doesn't change when leaving and re-entering

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



### Returns:
`PlayerDbId`

## getPlayerDbValue
Gets a database value that is saved per player.

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



### Returns:
`PNull<string | number>`

## getPlayerFacingInfo
Get the position of a player's camera and the direction (both in Euclidean and spherical coordinates) they are attempting to use an item.

The camPos has the same limitations described in getPlayerTargetInfo

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



### Returns:
` { camPos: [number, number, number]; dir: [number, number, number]; angleDir: AngleDir; moveHeading: number } `

## getPlayerGamemode
Get the gamemode of a player.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The ID of the player to get the gamemode of. |



### Returns:
`WorldGamemode`

 

The gamemode of the player.

## getPlayerId
Given the name of a player, get their id

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



### Returns:
`PNull<PlayerId>`

## getPlayerIdFromDbId
Returns null if player not in lobby

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| dbId | `PlayerDbId` |  |



### Returns:
`PNull<PlayerId>`

## getPlayerIds
Get all the player ids.

### Returns:
`PlayerId[]`

## getPlayerPartyWhenJoined
Returns the party that the player was in when they joined the game. The returned object contains the playerDbIds, as well

as the playerIds if available, of the party leader and members.

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



### Returns:
`PNull<{ partyCode: string; playerDbIds: PlayerDbId[] }>`

## getPlayerPhysicsState
Get physics state for player

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



### Returns:
`PlayerPhysicsState<PhysicsType>`

## getPlayerTargetInfo
Get the position of a player's target block and the block adjacent to it (e.g. where a block would be placed)





Note: This position is a tick ahead of the client's block target info (noa.targetedBlock),

since the client updates the blocktarget before the entities tick (and since it uses the renderposition of the camera)



This normally doesn't matter but if you are client predicting something based on noa.targetedBlock

(currently only applicable to in-engine code), you should not verify using this

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



### Returns:
` { position: [number, number, number]; normal: [number, number, number]; adjacent: [number, number, number] } `

## getPosition
Get position of a player / entity.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| entityId | `EntityId` |  |



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

## getQueuedStatus
Get the status of a queued command.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| id | `QueuedCommandId` | The ID of the queued command to get the status of. |



### Returns:
`QueuedStatusString`

 

NOT_IN_QUEUE, WAITING_TO_RUN, or CURRENTLY_RUNNING.

## getSchematicDimensions
Get a project schematic's stored dimensions as [x, y, z], including selection padding.

Uses the active project snapshot. Missing schematic paths throw an error.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| schematicPath | `string` | Project-relative path, including .bloxdschem. |



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

## getSelectedInventorySlotI
Get a player's currently selected inventory slot

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



### Returns:
`number`

## getShieldAmount
Get the current shield of an entity.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| entityId | `EntityId` |  |



### Returns:
`number`

## getStandardChestFreeSlotCount
Get the amount of free slots in a standard chest

Returns null for non-chests

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



### Returns:
`PNull<number>`

 

number

## getStandardChestItemAmount
The amount of an itemName a standard chest has.

Returns 0 if the standard chest has none, and a negative number if infinite.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| chestPos | `number[]` |  |
| itemName | `ItemName` |  |



### Returns:
`number`

 

number

## getStandardChestItems
Get all the items from a standard chest in order. Use this instead of repetitive calls to getStandardChestItemSlot

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



### Returns:
`PNull<InvenItem>[]`

## getStandardChestItemSlot
Get the item at a chest slot. Null if empty otherwise format {name: itemName, amount: amountOfItem}

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



### Returns:
`PNull<InvenItem>`

## getUnitCoordinatesLifeformWithin
Get the up to 12 unit co-ordinates the entity is located within

(Samples the four horizontal corners at up to three vertical levels)

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| lifeformId | `EntityId` |  |



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

 

List of x, y, z positions e.g. [[-1, 0, 0], [-1, 1, 0], [-1, 2, 0]]

## getVariation
Get the current sub-variation name.

Returns `"default"` when there is no named sub-variation.

### Returns:
`string`

## getVehicleSeats
The seat layout for a vehicle entity - at minimum one driver seat (index 0), optionally more

passenger seats after it. Resolved from the spawned vehicle's def (`VehicleMeshEntityDef.seats`,

falling back to a single driver seat at the physics type/tier's own `riderOffset` default) or a

rideable mob's override (`getMobVehicleSeats`, falling back to its `rideHeight`). Throws if

`vehicleEId` is not a vehicle.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| vehicleEId | `EntityId` |  |



### Returns:
`VehicleSeat[]`

## getVehicleSetting
The current value of a physics setting for a specific vehicle entity: the value set via

`setVehicleSetting` if overridden, otherwise (when `returnDefaultIfNotOverridden`) the type/tier

default from the vehicle's physics state. Mirrors `getMobSetting`.



The one default not read from the type/tier is a mob's `riderOffset`, which comes from its ride height.



A per-block setting (e.g. `"IceCanAutoStep"`) is `undefined` when that block is unlisted, which means

the block does not change the setting rather than that the setting is off.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| vehicleEId | `EntityId` |  |
| setting | `TSetting` |  |
| returnDefaultIfNotOverridden | `boolean` |  |



### Returns:
`SettableVehicleSettingValue<TSetting>`

## getVelocity
Get the velocity of an entity

Will return [0, 0, 0] if the entity doesn't have a physics body

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| eId | `EntityId` |  |



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

## giveCurrencyAmount
Give a player an amount of currency. Can be negative to remove money.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| currencyId | `string` |  |
| amount | `number` |  |

## giveItem
Inventory stuff

Give a player an item and a certain amount of that item.

Returns the amount of item added to the users inventory.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| itemName | `ItemName` |  |
| itemAmount | `number` |  |
| attributes | `ItemAttributes` | An optional object for certain types of item. For guns this can contain the shotsLeft field which is the amount of ammo the gun currently has. |



### Returns:
`number`

## giveStandardChestItem
Give a standard chest an item and a certain amount of that item.

Returns the amount of item added to the chest.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| chestPos | `number[]` |  |
| itemName | `ItemName` |  |
| itemAmount | `number` |  |
| playerId | `PlayerId` | The player who is interacting with the chest. |
| attributes | `ItemAttributes` | An optional object for certain types of item. For guns this can contain the shotsLeft field which is the amount of ammo the gun currently has. |



### Returns:
`number`

## hasActiveQTE
Check whether the player has any qteRequests

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



### Returns:
`boolean`

## hasEffect
Check if a lifeform has an effect.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| lifeformId | `LifeformId` |  |
| name | `string` |  |
| atOrAboveLevel | `number` | Checks whether the effect is at or above the given level |



### Returns:
`boolean`

## hasItem
Whether a player has an item

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



### Returns:
`boolean`

 

bool

## initiateMiddleScreenBar
This will initiate the MiddleScreenBar, starting at empty and filling up to full over the given duration.

Good to represent cooldowns (eg gun reload) or charged items (eg crossbow)

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| duration | `number` | ms over which the MiddleScreenBar fills up |
| chargeExpiresAutomatically | `boolean` | Defaults to true. If true, the bar will disappear upon reaching full. If false, the bar will remain at full until hidden with removeMiddleScreenBar |
| horizontalBarRemOffset | `number` | Offset the bar left or right (in css unit - rem) |

## inventoryIsFull
Whether the player has space in their inventory to get new blocks

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



### Returns:
`boolean`

## isAlive
Whether a lifeform is alive or dead (or on the respawn screen, in a player's case).

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| lifeformId | `LifeformId` |  |



### Returns:
`boolean`

## isBlockInLoadedChunk
Check if the block at a specific position is in a loaded chunk.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| x | `number` |  |
| y | `number` |  |
| z | `number` |  |



### Returns:
`boolean`

## isInsideRect
Check if a position is within a cubic rectangle

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| coordsToCheck | `number[]` |  |
| pos1 | `number[]` | position of one corner |
| pos2 | `number[]` | position of opposite corner |
| addOneToMax | `boolean` |  |



### Returns:
`boolean`

## isMobile
Whether the player is on a mobile device or a computer.

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



### Returns:
`boolean`

## isNearInterrupt
Returns true if your code is about to be interrupted for exceeding its time budget.

Use this to break up long-running code into smaller chunks.





### Example:

```js
// Resume from where we stopped last time (or 0 on the first run)
let savedLoopCounter = 0

// ...

for (let i = savedLoopCounter; i < 1000; i++) {
	if (api.isNearInterrupt()) {
		// Out of time - remember our progress and stop before getting killed
		savedLoopCounter = i
		break
	}

	someExpensiveFunction()
}
```

### Returns:
`boolean`

## isPlayerCrouching
Check whether a player is crouching

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



### Returns:
`boolean`

## isPublicLobby
Integer lobby names are public

### Returns:
`boolean`

 

boolean

## kickPlayer


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

## killLifeform
Kill a lifeform.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| lifeformId | `LifeformId` |  |
| whoKilled | ` LifeformId \| { lifeformId: LifeformId; withItem: string } ` | Optional |

## matchmakePlayer
Tell a player to disconnect from the current lobby and join a new one.



To connect to a specific variation, format is `gamename_variation`.

For Custom Games, this will be `classic_playerSchematic|XXXXXXXXXX` or

`classic_playerSchematic|XXXXXXXXXX|<varname>` for a named sub-variation.



NOTE: Players won't disconnect immediately (they may play an ad before being redirected).

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| game | `string` | Defaults to the current game. |
| lobbyName | `string` | Defaults to "Quick Play" |

## matchmakeToVariation
Matchmake a player into a sub-variation of the current custom game.

Pass `"default"` for the default variation.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | The player to matchmake |
| varname | `string` | Sub-variation name (`[A-Za-z0-9_-]`, 1-32 chars), or `"default"` |

## now
Obtain Date.now() value saved at start of current game tick

### Returns:
`number`

## openChestForPlayer
Open a chest for a player.

If there is no chest, or the player cannot open it, do nothing.

WARNING: This may call "onPlayerAttemptOpenChest" to determine if the player has permission to open it. Using this function inside that callback risks infinite recursion.

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

## openShop
Open the shop UI for a player

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` |  |
| toggle | `boolean` | Whether to close the shop if it's already open. Leave this off when opening from an interaction: holding the interact button re-fires the alt action every ~50-150ms, so a toggle would flicker the shop open and closed until release. |
| forceCategoryKey | `PNull<ShopCategoryKey>` | If set, will change the shop to this category |
| onlyIfNonEmpty | `boolean` | If true, will only open the shop if the category (or shop, if no category is provided) is non-empty |

## passifyHostility
Clears any aggro the mob has towards the given lifeform.

If the mob is currently chasing or running away from it, this also transitions the mob back to idle.

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| mobId | `MobId` |  |
| targetLifeformId | `LifeformId` |  |

## playClientPredictedSound
See documentation for api.playSound

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

## playerIsInGame
Whether a player is currently in the game

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



### Returns:
`boolean`

## playerIsLoggedIn


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



### Returns:
`boolean`

## playParticleEffect
Play particle effect on all clients, or only on some clients if clientPredictedBy is specified

### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| opts | `TempParticleSystemOpts \| ParticlePresetOpts` |  |
| clientPredictedBy | `EntityId` | Play only on clients where the entity clientPredictedBy is visible and not the viewing player |

## playSound


### Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
| playerId | `PlayerId` | hears the sound |
| soundName | `string` | Can also be a prefix. If so, a random sound with that prefix will be played |
| volume | `number` | 0-1. If it's too quiet and volume is 1, normalise your sound in audacity |
| rate | `number` | 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. |
| posSettings | ` { playerIdOrPos: EntityId \| number[] maxHearDist?: number refDistance?: number } ` | : EntityId \| number[], maxHearDist: number, refDistance: number} playerIdOrPos: The entity the sound originates from, or the position of the sound maxHearDist: sound is not played if player is further than this. Default 15 refDistance: higher means the sound decreases less in volume with distance. Default 3. Hitting is 4. Guns are 10 |

## preventFallDamageNextGrounding
Prevents the player from taking fall damage next time they land on the ground

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