This page as Markdown: https://bloxd.io/docs/api-reference.md. Every page of these docs, for AI agents: https://bloxd.io/docs/llms.txt

API Reference

addCustomKillfeedMessage

Add a custom killfeed message to the killfeed

Parameters:

addFollowingEntityToPlayer

Add following entity to an entity

Parameters:

addQTE

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

Handle the result via the onPlayerFinishQTE engine callback.

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:

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:

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:

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

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

Parameters:

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:

applyAuraChange

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

Parameters:

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:

applyHealthChange

Parameters:

Returns:

boolean

applyImpulse

Apply an impulse to an entity

Parameters:

applyMeleeHit

Make it as if hittingEId hit hitEId

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

Returns:

string

blockIdToBlockName

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

Parameters:

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:

Returns:

PNull<number>

broadcastMessage

Send a message to everyone

Parameters:

broadcastSound

See documentation for api.playSound

Parameters:

calcExplosionForce

Parameters:

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:

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:

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:

Returns:

boolean

chunkIdToBotLeftCoord

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

Parameters:

Returns:

[number, number, number]

clearDirectionArrow

Clear a directional arrow from the player's screen.

Parameters:

clearInventory

Clear the players inventory

Parameters:

clearKillstreak

Clears the player's current killstreak

Parameters:

closeChestForPlayer

Close a chest for a player.

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

Parameters:

configureShopCategory

Set properties of a shop category.

Parameters:

configureShopCategoryForPlayer

Configure a shop category for a specific player.

Parameters:

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:

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:

Returns:

EnchantmentAttributes

createItemDrop

Create a dropped item.

Parameters:

Returns:

PNull<EntityId>

the id you can pass to setCantPickUpItem, or null if the item drop limit was reached

createMobHerd

Create a mob herd. A mob herd represents a collection of mobs that move together.

Returns:

MobHerdId

createShopItem

Create a new shop item under the given category.

Will create a new category if it does not exist.

If the shop item already exists then it will be replaced.

If any per-player overrides exist under the same categoryKey and itemKey then they will be deleted.

Parameters:

createShopItemForPlayer

Create a new shop item for a specific player.

Will create a new category if it does not exist.

Will replace any overrides this player already has for the same item.

Parameters:

deleteAllItems

Deletes all items dropped in the world

deleteAllLobbyDbValues

Deletes all database values that are saved per lobby.

deleteAllPlayerDbValues

Deletes all database values that are saved per player, including persisted currencies.

Parameters:

deleteAudioEntity

Delete an audio entity by its entity ID (returned by attemptCreateAudioEntity).

Parameters:

deleteCurrency

Delete a currency from a player. This will make the currency unknown to the player.

Parameters:

deleteEntity

Delete any non-player entity (mesh entity, mob, audio entity, item drop, throwable, etc.) and dispose of their state.

Parameters:

Returns:

boolean

whether the entity's replicated state existed and was deleted

deleteItemDrop

Delete an item drop by item drop entity ID

Parameters:

deleteLobbyDbValue

Deletes a database value that is saved per lobby.

Parameters:

deleteMeshEntity

Delete a mesh entity

Parameters:

Returns:

boolean

whether the api successfully deleted the meshEntity

deletePlayerDbValue

Deletes a database value that is saved per player.

Parameters:

deleteQTE

Delete a quicktime event from the screen

Parameters:

deleteShopItem

Delete an existing shop item.

Throws an error if the item does not exist.

Will also delete all per-player overrides for the shop item.

Parameters:

deleteThrowable

Delete a throwable entity before it automatically removes itself.

Parameters:

Returns:

boolean

true if the entity was deleted, false if it was not a throwable entity

deleteUiRequest

Delete a request for a player.

Parameters:

despawnMob

Dispose of a mob's state and remove them from the world without triggering "on death" flows.

Always succeeds.

Parameters:

despawnVehicle

Dispose of a vehicle's state and remove them from the world.

Always succeeds.

Parameters:

editItemCraftingRecipes

Edit the crafting recipes for a player.

Parameters:

exitPlayerVehicle

Take a player off whatever they are riding, dropping them where it is. Does nothing if they are

not riding anything.

Parameters:

findItem

Finds the index of a particular item in a player's inventory.

Parameters:

Returns:

PNull<number>

findStandardChestItem

Find the index of a particular item in a standard chest

Parameters:

Returns:

PNull<number>

forceRespawn

Force respawn a player

Parameters:

getAuraInfo

Get the aura info for a player

Parameters:

Returns:

{ level: number; totalAura: number; auraPerLevel: number }

getBlock

Get the name of a block.

Parameters:

Returns:

BlockName

getBlockCoordinatesPlayerStandingOn

Get the co-ordinates of the blocks the entity is standing on as a list. For example, if the centre of the entity is at 0,0,0

this function will return [[0, -1, 0], [-1, -1, 0], [0, -1, -1], [-1, -1, -1]]

If the entity is just standing on one block, the function would return e.g. [[0, 0, 0]]

If the entity is midair or has no physics body, returns an empty list [].

Parameters:

Returns:

number[][]

getBlockData

Get stored data about a block in a performant manner. Data is cleared when block changes.

E.g. chest

Works well with blocks marked tickable (e.g. wheat)

Parameters:

Returns:

any

getBlockId

Used to get the block id at a specific position.

Intended only for use in hot code paths - default to getBlock for most use cases

Parameters:

Returns:

BlockId

getBlockSolidity

Returns whether a block is solid or not.

E.g. Grass block is solid, while water, ladder and water are not.

Will be true if the block is unloaded.

Parameters:

Returns:

boolean

getBlockTypesPlayerStandingOn

Get the types of block the entity is standing on

For example, if an entity is standing on 4 dirt blocks, this will return ["Dirt", "Dirt", "Dirt", "Dirt"]

Returns an empty list if the entity is midair or has no physics body.

Parameters:

Returns:

any[]

getClientOption

Returns the current value of a client option

Parameters:

Returns:

ClientOptions[PassedOption]

getCraftingRecipesForPlayer

Read a player's current crafting recipe set, keyed by output item name. Includes any

per-player overrides set via editItemCraftingRecipes / removeItemCraftingRecipes.

Parameters:

Returns:

Record<string, RecipesForItem>

getCurrencyAmount

Get the amount of a given currency a player has.

Parameters:

Returns:

PNull<number>

The amount of the currency, or null if the currency is not defined.

getCurrentKillstreak

Gets the player's current killstreak

Parameters:

Returns:

number

getDefaultMobSetting

Returns the current default value for a mob setting.

Parameters:

Returns:

MobSettings<TMobType>[TMobSetting]

getEffectLevel

Get the level of an effect on a lifeform, or 0 if they don't have it.

Parameters:

Returns:

number

getEffects

Get all the effects currently applied to a lifeform.

Parameters:

Returns:

string[]

getEmptyChunk

Use this to get a chunk ndarray you can edit and set in resetChunk.

Only use chunk helpers if you REALLY need the performance (i.e. you are iterating over tens of thousands of blocks)

ReturnedObject.blockData is a 32x32x32 ndarray of air.

(see https://www.npmjs.com/package/ndarray)

Each block id is a 16-bit number

Returns:

GameChunk

getEntitiesInRect

Get the entities in the rect between [minX, minY, minZ] and [maxX, maxY, maxZ]

Parameters:

Returns:

EntityId[]

getEntityHeading

Parameters:

Returns:

number

getEntityName

Get the in game name of an entity.

Parameters:

Returns:

string

getEntityRotation

Get the rotation for a server-auth entity.

Parameters:

Returns:

[number, number, number]

getEntityType

Parameters:

Returns:

EntityType

getHealth

Get the current health of an entity.

Parameters:

Returns:

number

getHeldItem

Get the currently held item of a player

Returns null if no item is being held

If an item is held, return an object of the format {name: itemName, amount: amountOfItem}

Parameters:

Returns:

PNull<InvenItem>

getInitialItemMetadata

Get the metadata about a block or item before stats have been modified by any client options

(i.e. its entry in the initial metadata object)

Parameters:

Returns:

Partial<BlockMetadataItem & NonBlockMetadataItem>

getInventoryFreeSlotCount

Get the amount of free slots in a player's inventory.

Parameters:

Returns:

number

number

getInventoryItemAmount

The amount of an itemName a player has.

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

Parameters:

Returns:

number

number

getItemAmount

Get the amount of an item in an item entity

Parameters:

Returns:

number

number

getItemDropName

Gets the item name of a dropped item

Parameters:

Returns:

PNull<ItemName>

getItemIDsOverlappingWithPlayer

Returns all items overlapping with the given player

Parameters:

Returns:

EntityId[]

the overlapping item entity IDs

getItemSlot

Get the item at a specific index

Returns null if there is no item at that index

If there is an item, return an object of the format { name: string; amount: PNull<number>; attributes: ItemAttributes; }

Parameters:

Returns:

PNull<InvenItem>

getItemStat

Get stat info about a block or item

Either based on a client option for a player: (e.g. DirtTtb)

or its entry in the initial metadata object if no client option is set.

If null is passed for lifeformId, this is simply its entry in blockMetadata etc.

Parameters:

Returns:

AnyMetadataItem[K]

getLifeformScale

Get the scale of a lifeform.

Parameters:

Returns:

number

getLobbyDbValue

Gets a database value that is saved per lobby.

Parameters:

Returns:

PNull<string | number>

getLobbyName

Get the name of the lobby this game is running in.

Returns:

string

getLobbyType

Returns if the current lobby the game is running in is special - e.g. a discord guild or dm, or simply a standard lobby

Returns:

LobbyType

getMetaInfo

Splits the block name by '|'. If no meta info, metaInfo is ''

Parameters:

Returns:

ItemMetaInfo

getMobAiState

Gets the current AI state for the given mob.

Parameters:

Returns:

{ state: MobAiState; params: MobAiStateParams<MobAiState> }

getMobDbId

Gets the persistent database ID for the given mob.

This can be useful for reasoning about mobs that have been loaded from the database, such as owned mobs.

Parameters:

Returns:

PNull<MobDbId>

The persistent database ID for the mob, or null if the mob is not persistent

getMobIds

Get the mob IDs of all mobs in the world.

Returns:

MobId[]

getMobSetting

Get the current value of a mob setting for a specific mob.

Parameters:

Returns:

MobSettings<MobType>[TMobSetting]

getMoonstoneChestItems

Get all the items from a moonstone chest in order. Use this instead of repetitive calls to getMoonstoneChestItemSlot

Moonstone chests are a type of chest where a player accesses the same contents no matter the location of the moonstone chest

Parameters:

Returns:

PNull<InvenItem>[]

getMoonstoneChestItemSlot

Get the item in a player's moonstone chest slot. Null if empty

Moonstone chests are a type of chest where a player accesses the same contents no matter the location of the moonstone chest

Parameters:

Returns:

PNull<InvenItem>

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:

Returns:

OtherEntitySettings[Setting]

getPlayerCosmetic

Get a single equipped cosmetic for a player.

Parameters:

Returns:

CosmeticName

getPlayerDbId

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

Parameters:

Returns:

PlayerDbId

getPlayerDbValue

Gets a database value that is saved per player.

Parameters:

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:

Returns:

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

getPlayerGamemode

Get the gamemode of a player.

Parameters:

Returns:

WorldGamemode

The gamemode of the player.

getPlayerId

Given the name of a player, get their id

Parameters:

Returns:

PNull<PlayerId>

getPlayerIdFromDbId

Returns null if player not in lobby

Parameters:

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:

Returns:

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

getPlayerPhysicsState

Get physics state for player

Parameters:

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:

Returns:

{ position: [number, number, number]; normal: [number, number, number]; adjacent: [number, number, number] }

getPosition

Get position of a player / entity.

Parameters:

Returns:

[number, number, number]

getQueuedStatus

Get the status of a queued command.

Parameters:

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:

Returns:

[number, number, number]

getSelectedInventorySlotI

Get a player's currently selected inventory slot

Parameters:

Returns:

number

getShieldAmount

Get the current shield of an entity.

Parameters:

Returns:

number

getStandardChestFreeSlotCount

Get the amount of free slots in a standard chest

Returns null for non-chests

Parameters:

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:

Returns:

number

number

getStandardChestItems

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

Parameters:

Returns:

PNull<InvenItem>[]

getStandardChestItemSlot

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

Parameters:

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:

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:

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:

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:

Returns:

[number, number, number]

giveCurrencyAmount

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

Parameters:

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:

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:

Returns:

number

hasActiveQTE

Check whether the player has any qteRequests

Parameters:

Returns:

boolean

hasEffect

Check if a lifeform has an effect.

Parameters:

Returns:

boolean

hasItem

Whether a player has an item

Parameters:

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:

inventoryIsFull

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

Parameters:

Returns:

boolean

isAlive

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

Parameters:

Returns:

boolean

isBlockInLoadedChunk

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

Parameters:

Returns:

boolean

isInsideRect

Check if a position is within a cubic rectangle

Parameters:

Returns:

boolean

isMobile

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

Parameters:

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:

// 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:

Returns:

boolean

isPublicLobby

Integer lobby names are public

Returns:

boolean

boolean

kickPlayer

Parameters:

killLifeform

Kill a lifeform.

Parameters:

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:

matchmakeToVariation

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

Pass "default" for the default variation.

Parameters:

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:

openShop

Open the shop UI for a player

Parameters:

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:

playClientPredictedSound

See documentation for api.playSound

Parameters:

playerIsInGame

Whether a player is currently in the game

Parameters:

Returns:

boolean

playerIsLoggedIn

Parameters:

Returns:

boolean

playParticleEffect

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

Parameters:

playSound

Parameters:

preventFallDamageNextGrounding

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

Parameters:

progressBarUpdate

Update the progress bar in the bottom right corner.

Can be queued.

Parameters:

queueCrosshairText

Schedule text to be displayed in the crosshair.

This text will be removed after the duration.

Stacking queued texts will schedule them to be displayed one after the other.

NOTE: Overriding the crosshairText client option may cause queued texts to be displayed incorrectly.

Parameters:

Returns:

QueuedCommandId

The ID of the queued command.

queueMiddleTextLower

Schedule small text to be displayed in the middle of the screen (middleTextLower).

This text will be removed after the duration.

Stacking queued texts will schedule them to be displayed one after the other.

NOTE: Overriding the middleTextLower client option may cause queued texts to be displayed incorrectly.

Parameters:

Returns:

QueuedCommandId

The ID of the queued command.

queueMiddleTextUpper

Schedule large text to be displayed in the middle of the screen (middleTextUpper).

This text will be removed after the duration.

Stacking queued texts will schedule them to be displayed one after the other.

NOTE: Overriding the middleTextUpper client option may cause queued texts to be displayed incorrectly.

Parameters:

Returns:

QueuedCommandId

The ID of the queued command.

raycastForBlock

Raycast for a block in the world.

Given a position and a direction, find the first block that the "ray" hits.

Parameters:

Returns:

BlockRaycastResult

removeAppliedSkin

Remove gamemode-applied skin from a player

Parameters:

removeEffect

Remove an effect from a lifeform.

Parameters:

removeFollowingEntityFromPlayer

Remove following entity from an entity

Parameters:

removeFromQueue

Remove a queued command from the queue.

Parameters:

removeItemCraftingRecipes

Removes crafting recipes

Parameters:

removeItemName

Remove an amount of item from a player's inventory

Parameters:

removeItemNameFromStandardChest

Remove an amount of item from a standardChest inventory

Parameters:

removeMiddleScreenBar

If there is any current middle screen bar running, this will hide it

Parameters:

resetCanChangeBlock

Remove any previous can/cant change block settings for a player at a specific co-ordinate

Parameters:

resetCanChangeBlockRect

Remove any previous can/cant change block rect settings for a player

Parameters:

resetCanChangeBlockType

Remove any previous can/cant change block type settings for a player

Parameters:

resetCanPickUpItem

Reset a player's ability to pick up an item. itemId returned by createItemDrop

Parameters:

resetItemCraftingRecipes

Reset the crafting recipes for a given back to its original bloxd state

Parameters:

resetShopItemForPlayer

Delete a specific player's overrides for a shop item.

Like other methods, it doesn't matter whether the overrides were created

using createShopItemForPlayer or by using updateShopItemForPlayer instead.

This method does nothing if the overrides don't exist or are defined internally by the engine.

Parameters:

scalePlayerMeshNodes

Set an entity's meshScaling setting by 3d vector. Model node scaling is applied to lifeforms;

for mesh entities, this setting affects nametag placement and interaction reach, not the model's nodes.

State from prior calls to this api is lost so if you want to have multiple nodes scaled, pass in all the scales at once.

Parameters:

sendFlyingMiddleMessage

Send a flying middle message to a specific player

Parameters:

sendHitmarker

Show a hitmarker on the player's screen (the X-shaped crosshair flash indicating a successful hit).

Useful for custom weapons or things that need visual hit feedback.

Parameters:

sendMessage

Send a message to a specific player

Parameters:

sendOverShopInfo

Show a message over the shop in the same place that a shop item's onBoughtMessage is shown.

Displays for a couple seconds before disappearing

Use case is to show a dynamic message when player buys an item

Parameters:

sendTopRightHelper

Parameters:

setAuraLevel

Set the aura level for a player - shortcut for setTotalAura(level * auraPerLevel)

Parameters:

setBlock

Set a block. Valid names are any block name, including 'Air'

This function is optimised for setting broad swathes of blocks. For example, if you have a 50x50x50 area you need to turn to air, it will run performantly if you call this in double nested loops.

IF you're only changing a few blocks, you want this to be super snappy for players, AND you're calling this outside of your _tick function, you can use api.setOptimisations(false).

If you want the optimisations for large quantities of blocks later on, then call api.setOptimisations(true) when you're done.

Parameters:

setBlockData

Store data about a block in a performant manner. Data is cleared when block changes.

E.g. chest

Works well with blocks marked tickable (e.g. wheat)

Parameters:

setBlockRect

Helper function that sets all blocks in a rectangle to a specific block.

Parameters:

setBlockWalls

Create walls by providing two opposite corners of the cuboid

Parameters:

setCallbackValueFallback

Set a default value to be returned by your callback code if it throws an error.

Parameters:

setCameraDirection

Set the direction the player is looking.

Parameters:

setCameraZoom

Set camera zoom for a player

Parameters:

setCanChangeBlock

Let a player change a block at a specific co-ordinate. Useful when client option canChange is false.

Overrides blockRect and blockType settings, so also useful when you have disallowed changing of a block type with setCantChangeBlockType.

Using this on 1000s of blocks will cause lag - if that is needed, find a way to use setCanChangeBlockType.

Parameters:

setCanChangeBlockRect

Make it so a player can Change blocks within two points. Coordinates are inclusive. E.g. if [0, 0, 0] is pos1

and [1, 1, 1] is pos2 then the 8 blocks contained within low and high will be able to be broken.

Overrides setCantChangeBlockType

Parameters:

setCanChangeBlockType

Lets a player Change a block type. Valid names are any block name, including 'Air'

Less priority than cant change block pos/can change block rect

Parameters:

setCantChangeBlock

Prevents a player from changing a block at a specific co-ordinate. Useful when client option canChange is true.

Overrides blockRect and blockType settings, so also useful when you have allowed changing of a block type with setCantChangeBlockType.

Using this on 1000s of blocks will cause lag - if that is needed, find a way to use setCantChangeBlockType.

Parameters:

setCantChangeBlockRect

Make it so a player cant Change blocks within two points. Coordinates are inclusive. E.g. if [0, 0, 0] is pos1

and [1, 1, 1] is pos2 then the 8 blocks contained within pos1 and pos2 won't be able to be broken.

Overrides setCanChangeBlockType

Parameters:

setCantChangeBlockType

Stops a player from changing a block type. Valid names are any block name, including 'Air'

Less priority than can change block pos/can change block rect

Parameters:

setCantPickUpItem

Prevent a player from picking up an item. itemId returned by createItemDrop

Parameters:

setChunkAsSchematic

Replace a world chunk with a chunk from a project schematic, including air and block data.

Both positions are block coordinates selecting their containing 32-block chunk.

Add schematics in the Code Editor. Missing paths or source chunks throw an error.

Parameters:

setClientOption

Modify a client option at runtime and send to the client if it changed

Parameters:

setClientOptions

Modify client options at runtime

Parameters:

setClientOptionToDefault

Sets a client option to its default value. This will be the value stored in your game's defaultClientOptions, otherwise Bloxd's default.

Parameters:

setCurrency

Dynamically define a currency for a player and show it on the HUD.

Amounts will persist between sessions if persistent is set to true.

Persistent currencies count towards db length limits.

Example usage:

api.setCurrency(myId, "myCurrency", { amount: 100, icon: "coins", iconColour: "blue", persistent: true })

Parameters:

setCurrencyAmount

Set the amount of a currency a player has. For persistent currencies, amount/subtext count towards db length limits.

Parameters:

setDefaultMobSetting

Set the default value for a mob setting.

Parameters:

setDirectionArrow

Show a directional arrow indicator on the player's screen pointing toward a world position.

When the position is off-screen the indicator is a rotating chevron at the screen edge.

When the position is on-screen it becomes a small marker dot.

The arrow persists until explicitly cleared via clearDirectionArrow.

Calling again with the same id updates the existing arrow in-place.

Parameters:

setEntityHeading

Parameters:

setEntityRotation

Set the rotation for a server-auth entity.

Parameters:

setEveryoneSettingForPlayer

Set a player's other-entity setting for every player, mob and Person mesh in the game.

includeNewJoiners=true means that the player will have the setting applied to new joiners.

Parameters:

setHealth

Set the current health of an entity.

If you want to set their health to more than their current max health, the optional increaseMaxHealthIfNeeded must be true.

Parameters:

Returns:

boolean

setItemAmount

Set the amount of an item in an item entity

Parameters:

setItemSlot

Put an item in a specific index. Default hotbar is indexes 0-9

Parameters:

setItemStat

Set a stat attribute for a block or item

NOTE: Only a subset of stats are customisable this way.

afterEatenItem requires an unstackable food.

minChargeStateToUse must be within the item's chargeStages and set on the base item, applying to all its charging variants.

fishingRodInfo adjusts existing rods; drops names the replacement mining drop.

Example: setItemStat(playerId, "Iron Dagger", "comboInfo", { comboWindowMs: 1000, comboMultipliers: [1, 1.5, 2] })

Parameters:

setLifeformScale

Set the visual + physical scale of a lifeform. A scale of 1 is the default size,

Parameters:

setLobbyDbValue

Sets a database value that is saved per lobby. This persists between sessions.

Parameters:

setMaxPlayers

Update the max players and soft max players matchmaking will use

softMaxPlayers is the number of players that matchmaking will route to using "Quick Play".

Once the softMaxPlayers limit is reached, this lobby can only be joined by requesting the lobby name or joining a friend.

maxPlayers is the absolute maximum: a lobby will not have more players than this.

Tip: softMaxPlayers should be around 90% of maxPlayers

WARNING: This change is not immediate, as it takes a while for matchmaking to find out.

Also, this will not kick players out of the lobby if set to a lower value than the current player count.

Parameters:

setMobAiState

Sets the current AI state for the given mob.

Some AI states will require context such as the ID of the lifeform being chased.

Parameters:

setMobSetting

Set the current value of a mob setting for a specific mob.

Parameters:

setMoonstoneChestItemSlot

Moonstone chests are a type of chest where a player accesses the same contents no matter the location of the moonstone chest

Parameters:

setOtherEntitySetting

Set a player's other-entity setting for a specific entity.

Parameters:

setOtherEntitySettings

Set many of a player's other-entity settings for a specific entity.

Parameters:

setOtherEntitySettingToDefault

Reset a player's other-entity setting for a specific entity to the game's default value.

Parameters:

setPlayerDbValue

Sets a database value that is saved per player. For custom games this persists between sessions and

between lobbies, and is shared across all of the game's variations (e.g. a hub and its sub-modes).

Parameters:

setPlayerGamemode

Set the gamemode of a player. This is persistent across lobbies for custom games.

Parameters:

setPlayerOpacity

Set an entity's opacity

A simple helper that calls setTargetedPlayerSettingForEveryone

Parameters:

setPlayerOpacityForOnePlayer

Set the opacity of an entity for one player

A simple helper that calls setOtherEntitySetting

Parameters:

setPlayerPhysicsState

Set physics state of player (vehicle type and tier).

For types that have tiers (e.g. BOAT, GLIDER, CAR), a tier of null defaults to the first

tier (0). Types without tiers (e.g. DEFAULT) must be given a null tier.

Parameters:

setPlayerPose

Set the pose of the player

Parameters:

setPlayerVehicle

Seat a player in a vehicle. Seat 0 drives; other seats follow the vehicle without movement control.

The player leaves their current vehicle and replaces anyone occupying the requested seat.

Parameters:

setPosition

Set position of a player / entity.

Parameters:

setSelectedInventorySlotI

Force the player to have the ith inventory slot selected. E.g. newI 0 makes the player have the 0th inventory slot selected

Parameters:

setShieldAmount

Set the current shield of a lifeform.

Parameters:

setStandardChestItemSlot

Parameters:

setTargetedPlayerSettingForEveryone

Set every player's other-entity setting to a specific value for a particular entity.

includeNewJoiners=true means that new players joining the game will also have this other player setting applied.

Parameters:

setTotalAura

Sets the total aura for a player. Will not go over max level or under 0

Parameters:

setVehicleSetting

Override a physics setting for a specific vehicle entity, replacing the type/tier default for that

vehicle's rider. The override is stored on the shared Bloxd and, when the vehicle currently has a

rider, replicated to that rider's client. Mirrors setMobSetting.

A setting can also be overridden for one block by naming the block first, e.g.

setVehicleSetting(boatId, "IceCanAutoStep", true). That is stored as an entry of the matching

<setting>ByBlock record, which the physics tick reads as a precomputed block lookup.

Parameters:

setVelocity

Set the velocity of an entity

Parameters:

setWalkThroughRect

Allow a player to walk through (or not walk through) voxels that are located within a given rectangle.

For blocks that are normally solid and not seethrough, the player will experience slight visual glitches while inside the block.

You could set both pos1 and pos2 to [0, 0, 0] to make only 0, 0, 0 walkthrough, for example.

A player standing inside a voxel that turns solid for them is lifted onto it if there is room above, including onto a CANT_WALK_THROUGH rect.

To let them stay where they are, remove the block before removing its exemption.

Parameters:

setWalkThroughType

Allow a player to walk through a type of block. For blocks that are normally solid and not seethrough, the player will experience slight visual glitches while inside the block.

A player standing inside a block that turns solid for them is lifted onto it if there is room above. To let them stay where they are, remove the block before making its type solid again.

Parameters:

shakePlayerCamera

Shake a player's camera.

Parameters:

showShopTutorial

Show the shop tutorial for a player. Will not be shown if they have ever seen the shop tutorial in your game before.

Parameters:

updateAudioEntity

Update an audio entity's config (sound, volume, falloff, rate). Only the provided fields

change.

Parameters:

updateEntityNodeMeshAttachment

Attach/detach mesh instances to/from an entity

Parameters:

updateMeshEntity

Update a mesh entity. If used on a non-mesh entity, will do nothing.

Parameters:

updateMeshParticleSystems

Updates the particle systems of multiple mesh entities at specified nodes

Parameters:

updateShopItem

Update selected properties of an existing shop item.

For example, { canBuy: true } to allow players to purchase the item.

Throws an error if the item does not exist.

Parameters:

updateShopItemForPlayer

Update selected properties of an existing shop item for a specific player.

For example, { canBuy: true } to allow this player to purchase the item.

Throws an error if the item does not exist.

Parameters: