Skip to content

Latest commit

 

History

History
195 lines (185 loc) · 10.1 KB

API.md

File metadata and controls

195 lines (185 loc) · 10.1 KB
gitea include_toc
none
true

API

In addition to Minecraft: Pi Edition's builtin API, MCPI-Reborn also implements the RaspberryJuice API. This page documents the API.

The API operates over a TCP socket.

It is typically hosted on port 4711, but this can be configured.

Compatibility Mode

By default, MCPI-Reborn runs in a "compatibility mode." This makes it completely compatible with RaspberryJuice, but limits functionality.

  • Bold text only applies to the compatibility mode.
  • Underlined text only applies when it is disabled.
  • Text enclosed in curly braces (for instance {text}) is meant to be Base64-URL-encoded when the compatibility mode is disabled.
  • In the compatibility mode, entity type IDs are automatically translated to/from their MC Java equivalents.

Commands

  • Commands are formatted like <command>(<args>) and may return a response. The response Fail indicates an error.
  • All commands are responses end with a newline.
  • Arguments surrounded by square brackets (for instance [abc]) are optional.
  • Numbers surrounded by colons (for instance :a:) are floating-point, all other numbers are integers.
  • Lists are delimited by pipes (|). For instance: A|B|C.
  • Unless otherwise noted, all player.*(...) commands are equivalent to entity.*(local_player_id,...).

Vanilla

  • world.setBlock(x,y,z,block_id[,data])
    • Description: Set the specified block at the given location.
  • world.getBlock(x,y,z)
    • Description: Retrieve the block ID at the specified location.
    • Output: block_id
  • world.getBlockWithData(x,y,z)
    • Description: Retrieve the block ID and data value at the specified location.
    • Output: block_id,data
  • world.setBlocks(x0,y0,z0,x1,y1,z1,block_id[,data])
    • Description: Fill the given region with the specified block.
  • world.getHeight(x,z)
    • Description: Get the last (from the top-down) non-solid block's Y-coordinate at the given location.
    • Output: max_y
  • world.getPlayerIds()
    • Description: Retrieve the entity IDs of all players.
    • Output: List of entity_id
  • world.checkpoint.save()
    • Description: Save checkpoint.
  • world.checkpoint.restore()
    • Description: Restore saved checkpoint.
  • player/world.setting(option,value)
    • Description: Set the specified setting to the provided integer value (0 is false, all other numbers are true). The possible settings are:
      • autojump
      • nametags_visible
      • world_immutable
  • entity.setTile(entity_id,x,y,z)
    • Description: Move the specified entity to the given position.
  • entity.setPos(entity_id,:x:,:y:,:z:)
    • Description: See above.
  • entity.getTile(entity_id)
    • Description: Retrieve the given entity's position.
    • Output: x,y,z
  • entity.getPos(entity_id)
    • Description: See above.
    • Output: :x:,:y:,:z:
  • chat.post(message)
    • Description: Post the specified message to chat.
  • camera.mode.setFixed()
    • Description: Set the camera to fixed-position mode.
  • camera.mode.setNormal([entity_id])
    • Description: Set the camera to normal mode. The camera will be the specified entity (or the local player if none is provided).
  • camera.mode.setFollow([entity_id])
    • Description: Set the camera to follow mode. The camera will follow the specified entity (or the local player if none is provided).
  • camera.setPos(:x:,:y:,:z:)
    • Description: Move the camera to the given position. The XZ-coordinates are automatically offset by 0.5.
  • events.clear()
    • Description: Clear all queued events.
    • Note: On RaspberryJuice, this does not clear projectile events. This behavior is maintained only in the compatibility mode.
  • events.block.hits()
    • Description: Retrieve all queued block hit events. These events are generated by players using an Iron Sword on blocks.
    • Output: List of x,y,z,face,entity_id

RaspberryJuice

  • world.getBlocks(x0,y0,z0,x1,y1,z1)
    • Description: Retrieve the blocks in the specified region.
    • Output: List of block_id,data
      • In compatibility mode, this list is delimited with commas (,).
  • world.getPlayerId({username})
    • Description: Retrieve the entity ID of the specified player.
    • Note: MCPI usernames are not unique. This command will only return the first player found.
    • Output: entity_id
  • world.getEntities(entity_type_id)
    • Description: Retrieve all entities of the specified type12.
    • Output: List entity_id,entity_type_id,entity_type_name,:x:,:y:,:z:
  • entity.getEntities(entity_id,distance,entity_type_id)
    • Description: Retrieve all entities of the specified type12 within the given distance of the provided entity.
    • Output: See above.
  • world.removeEntity(entity_id)
    • Description: Remove the specified entity1.
    • Output: number_of_entities_removed
  • world.removeEntities(entity_type_id)
    • Description: Remove all entities of the specified type12.
    • Output: See above.
  • entity.removeEntities(entity_id,distance,entity_type_id)
    • Description: Remove all entities of the specified type12 within the given distance of the provided entity.
    • Output: See above.
  • world.spawnEntity(:x:,:y:,:z:,entity_type_id)
    • Description: Spawn the specified entity at the given position.
    • Output: entity_id
  • world.getEntityTypes()
    • Description: Retrieve all spawnable entity types.
    • Output: List of entity_type_id,{entity_type_name}
  • world.setSign(x,y,z,id,data[,{line_1}][,{line_2}][,{line_3}][,{line_4}])
    • Description: Set the specified block at the given location. If the block is a sign, then also set its contents.
    • Note: In the compatibility mode, if a sign already exists, then any lines not included in the command will be left as-is instead of reset.
  • entity.getName(entity_id)
    • Description: Retrieve the name of the specified entity. For players, this will be their username.
    • Output: {entity_name}
  • entity.setDirection(entity_id,:x:,:y:,:z:)
    • Description: Set the specified entity's rotation using a unit vector.
  • entity.getDirection(entity_id)
    • Description: Retrieve the specified entity's rotation as a unit vector.
    • Output: :x:,:y:,:z:
  • entity.setRotation(entity_id,:yaw:)
    • Description: Set the specified entity's yaw.
  • entity.getRotation(entity_id)
    • Description: Retrieve the specified entity's yaw.
    • Output: :yaw:
  • entity.setPitch(entity_id,:pitch:)
    • Description: Set the specified entity's pitch.
  • entity.getPitch(entity_id)
    • Description: Retrieve the specified entity's pitch.
    • Output: :pitch:
  • entity.setAbsPos(entity_id,:x:,:y:,:z:)3
    • Description: Move the specified entity to the given absolute4 position.
  • entity.getAbsPos(entity_id)3
    • Description: Retrieve the given entity's absolute4 position.
    • Output: :x:,:y:,:z:
  • entity.events.block.hits(entity_id)
    • Description: Retrieve all queued block hit events produced by the specified entity.
    • Output: See events.block.hits.
  • events.chat.posts()
    • Description: Retrieve all queued chat events.
    • Output: List of entity_id,{message}
      • When compatibility mode is disabled, this will also include non-chat messages denoted with an entity ID of -1.
  • entity.events.chat.posts(entity_id)
    • Description: Retrieve all queued chat events produced by the specified entity.
    • Output: See above.
  • events.projectile.hits()
    • Description: Retrieve all queued projectile hit events.
    • Output: List of x,y,z,1,shooter_entity_name,[target_entity_name],shooter_entity_id,target_entity_id
      • If the projectile hit a block, target_entity_id will be -1 and target_entity_name will be blank.
  • entity.events.projectile.hits(entity_id)
    • Description: Retrieve all queued projectile hit events produced by the specified entity.
    • Output: See above.
  • entity.events.clear(entity_id)
    • Description: Clear all queued events produced by the specified entity.

Reborn-Specific

  • reborn.disableCompatMode()
    • Description: Disable the compatibility mode.
    • Output: reborn_version
  • reborn.enableCompatMode()
    • Description: Re-enable the compatibility mode.
  • world.getSign(x,y,z)
    • Description: Retrieve the text of the given sign.
    • Output: List of {line}
  • world.getSeed()
    • Description: Retrieve the seed of the loaded world.
    • Output: seed
  • world.getGameMode()
    • Description: Retrieve the game-mode of the loaded world.
    • Output: game_mode
  • world.spawnItem(:x:,:y:,:z:,item_id,count,data)
    • Description: Spawn the specified Dropped Item at the given position.
    • Output: entity_id
  • entity.getType(entity_id)
    • Description: Check the type of the given entity. For special entities like players, this will be 0.
    • Output: entity_type_id
  • entity.setVelocity(entity_id,:veclocity_x:,:veclocity_y:,:veclocity_z:)
    • Description: Set the specified entity's velocity.
  • entity.getVelocity(entity_id)
    • Description: Retrieve the specified entity's velocity.
    • Output: :veclocity_x:,:veclocity_y:,:veclocity_z:
  • entity.getId(entity_id)
    • Description: Retrieve the specified entity's ID.
    • Note: Only the player.getId() version of this command is useful.
    • Output: entity_id
  • entity.getSelectedItem(entity_id)
    • Description: Retrieve the selected item of the specified entity. For humanoid mobs (like players), this will be their current carried item. For Dropped Items, this will be the item itself. This will return an item ID of 0 if the entity is not currently selecting an item.
    • Output: item_id,count,data

Footnotes

  1. These commands will never match players. ↩ ↩2 ↩3 ↩4 ↩5

  2. If the ID is -1, it will match all entities. ↩ ↩2 ↩3 ↩4

  3. RaspberryJuice only implements the player.* versions of these commands. ↩ ↩2

  4. The API normally applies an offset to all coordinates, these commands use the raw data. ↩ ↩2