Minecraft Scripting API – Complete Reference & Examples

This page documents the complete Minecraft scripting API exposed through the Visualmodder v2.0 library. The API is designed to be used from Python and allows you to create structures, manipulate the cursor, interact with players, spawn entities, and react to game events.

Most functions operate on a cursor position, which represents the current location, direction, and inclination in the world. Shapes and objects are created relative to this cursor.

Location Objects and How to Use Them in Python

Some functions return a Location object. This object comes from the Minecraft server (Java) and exposes its data through getter methods. Direct attribute access is not supported. 


loc = vm.moveTo(Position.AIM)

x = loc.getX()
y = loc.getY()
z = loc.getZ()

yaw = loc.getYaw()
pitch = loc.getPitch()

Movement & Orientation

moveTo(steps: number, direction: Direction)

Moves the cursor a given number of blocks relative to its current orientation. Movement directions include FORWARD, BACKWARD, LEFT, RIGHT, UP, and DOWN.


loc = vm.moveTo(3, Direction.UP)

Returns: Location

moveTo(coordSystem, x: number, y: number, z: number)

Moves the cursor to an absolute position defined using a coordinate system:

  • CARTESIAN → (x, y, z)
  • CYLINDRICAL → (radius, theta, height)
  • SPHERICAL → (radius, theta, phi)

vm.moveTo(Coordinate.CARTESIAN, 0, 64, 0)

Returns: Location

moveTo(position: Position)

Moves the cursor to a predefined position such as the player, the start of the script, or the last marked location.

  • START: Initial script start location
  • NEXT_BLOCK: Next solid block in facing direction
  • PLAYER: Player’s current position
  • AIM: Block the player is looking at
  • MARK: Last marked cursor location

vm.moveTo(Position.PLAYER)

Returns: Location

markPosition()

Saves the current cursor location for later reference.


vm.markPosition()

Returns: void

setDirection(direction: Compass)

Sets the horizontal orientation (yaw) of the cursor.

Compass values are: SAME_AS_PLAYER, NORTH, SOUTH, EAST, WEST


vm.setDirection(Compass.NORTH)

Returns: Location

changeDirection(angle: number)

Rotates the cursor horizontally by the given number of degrees (0 – 360). 


vm.changeDirection(90)

Returns: Location

setInclination(angle: number)

Sets the vertical pitch of the cursor by the given number of degrees (0: horizontal, 90: Vertical). 


vm.setInclination(0)

Returns: Location

changeInclination(angle: number)

Adjusts the vertical pitch relative to the current value. 


vm.changeInclination(45)

Returns: Location

Geometry & Structures

createBlock(block)

Places one block at the cursor location. 


vm.createBlock(Block.STONE)

Returns: void

createRectangle(width: number, height: number, filled: Boolean, blocks…)

Creates a rectangle centered on the cursor in the X/Y plane. 


vm.createRectangle(6, 4, False, Block.STONE)

Returns: void

createSquare(width: number, filled: Boolean, blocks…)

Creates a square centered at the cursor. 


vm.createSquare(4, False, Block.GOLD_BLOCK)

Returns: void

createCircle(radius: number, filled: Boolean, blocks…)

Creates a circular shape centered at the cursor. 


vm.createCircle(5, False, Block.IRON_BLOCK)

Returns: void

createEllipse(radiusX: number, radiusY: number, filled: Boolean, blocks…)

Creates an ellipse centered at the cursor.


vm.createEllipse(10, 5, False, Block.IRON_BLOCK)

Returns: void

createLine(length: number, blocks…)

Creates a straight line. The cursor is in the middle of the line. 


vm.createLine(10, Block.BRICKS)

Returns: void

connectPositions(blocks…)

Connects the previously marked position with the current position


vm.connectPositions(Block.BRICKS)

Returns: void

createPolygon(sides: number, radiusX: number, radiusY: number, arcAngle: number, filled, blocks…)

createPolygon(sides, radiusX, radiusY, arcAngle, filled, blocks…)

  • sides: number of polygon sides
  • radiusX: horizontal radius
  • radiusY: vertical radius (or null for a circle)
  • arcAngle: visible arc angle: it indicates how much of the polygon should be drawn. As example: 90 draws a quarter of the polygon, 180 draws half polygon and 360 the full polygon
  • filled: whether to fill the interior
  • blocks: block definition(s)

vm.createPolygon(3, 5, 5, 225, False, Block.BRICKS)

Returns: void

createStar(points: number, innerRadius: number, outerRadius: number, filled, blocks…)

Creates a star centered at the cursor.

  • points: number of star points
  • innerRadius: inner radius of the inside points of the star
  • outerRadius: outer radius of the tips of the star
  • filled; whether to fill the interior
  • blocks; block definition(s)

vm.createStar(7, 6, 12, False, Block.GLASS)

Returns: void

createArc(length, blocks…)

Creates an arc. The arc is a the curve following the perimeter of an ellipse

  • radiusX: horizontal radius
  • radiusY: vertical radius
  • arcAngle: visible arc angle: it indicates how much of the polygon should be drawn. As example: 90 draws a quarter of the polygon, 180 draws half polygon and 360 the full polygon
  • filled: whether to fill the interior
  • blocks: block definition(s)

vm.createArc(10, Block.BRICKS)

Returns: void

createText(text, fontSize, filled, blocks…)

Renders block-based text and returns the upper-left location.


vm.createText("Hello World", 18, False, Block.GOLD_ORE)

Returns: void

Player Interaction

giveToPlayer(equip Equip, items…)

Gives items or blocks to the player in a specific slot.

  • Equip.INVENTORY
  • Equip.GARMENT
  • Equip.RIGHT_HAND
  • Equip.LEFT_HAND

vm.giveToPlayer(
    Equip.GARMENT,
    Item.DIAMOND_CHESTPLATE,
    Item.NETHERITE_LEGGINGS
)

Returns: void

isCurrentBlock(blocks…)

Checks whether the block at the cursor matches any of the given types.


  if vm.isCurrentBlock(Block.GRASS_BLOCK):
    print('returned true')

Returns: Boolean

isPlayerHolding(blocks…)

Checks what the player is currently holding.


  if vm.isPlayerHolding(Block.GRASS_BLOCK):
    print('returned true')

Returns: Boolean

hasPlayerItem(blocks…)

Checks whether the player has a given item in their inventory.


  if vm.hasPlayerItem(Block.GRASS_BLOCK):
    print('returned true')

Returns: Boolean

isPlayerInteractingWith(blocks…)

Checks whether the player is interacting with a given block.


  if vm.isPlayerInteractingWith(Block.GRASS_BLOCK):
    print('returned true')

Returns: Boolean

Events

onEvent(event, functionName)

Registers a function that is automatically executed when an event occurs. 


vm.onEvent(Event.MOVED, "fireworks")

Returns: void

clearEvents()

Stops all automatic event-triggered function execution.

callFunction(functionName, playerName, param)

Invokes a function defined by another player. It expects to pass one parameter to the function 


vm.callFunction(coolFunction, "myFriend", 7)

Returns: void

waitForBlockCreation()

Makes the program execution wait until all the requested blocks are created. There is a delay between the moment an order to create a block is given and when the blocks effectively appears in the game.

The following code shouws a common mistake that leads to wrong results


#this code will fail
vm.createBlock(Block.GRASS_BLOCK)
if vm.isCurrentBlock(Block.GRASS_BLOCK):
  print('returned true')


#this code will work as expected
vm.createBlock(Block.GRASS_BLOCK)
vm.waitForBlockCreation()
if vm.isCurrentBlock(Block.GRASS_BLOCK):
  print('returned true')

Returns: void

Dictionary-Based Object Customization (Advanced)

Instead of passing a simple block, item, or entity, you can pass a Python dictionary to customize how the object is created. This allows advanced behaviors such as delayed placement, ground alignment, signs with text, baby mobs, talking mobs, and more.

Common Dictionary Attributes

  • TYPE: The Minecraft object to create (block, item, mob, particle).
  • AMOUNT: How many times this object is repeated without writing a long list.
  • DELAY: Seconds before appearing (number or [min, max] for random delay).
  • POTION: Name of the function called when a splash potion is used.
  • SIGN: Text displayed on a sign.
  • TEAM: If true, mobs become friendly to the player.
  • DIRECTION: Orientation (stairs, rails, etc.).
  • LEASH: Leashes mobs to each other or to the player.
  • SIDE: Upper or lower layout (beds, doors, slabs).
  • GROUND: Places the object on the first non-air block below.
  • BABY: Creates a baby mob.
  • TALK: Text spoken by a mob when clicked.
  • IMAGE: Folder containing an image rendered as blocks.
  • VELOCITY: [speed, yaw, pitch] for falling blocks or mobs.

Dictionary Example


  
# Stairs turned left
vm.createBlock(dict(AMOUNT=1, DIRECTION=Direction.LEFT, GROUND=True, TYPE=Block.ANDESITE_STAIRS)) 

# Snow on the ground
 vm.createBlock(dict(GROUND=True, TYPE=Block.SNOW))

# Three signs in a row labeled "hello"
vm.createBlock(dict(AMOUNT=3, GROUND=True, SIGN="hello", TYPE=Block.ACACIA_SIGN))

# The upper side of a door
vm.createBlock(dict(SIDE=Side.UP, TYPE=Block.BIRCH_DOOR))

# Cows around me
vm.createSquare(3, False, Entity.COW);

# A friendly baby zombie
vm.createBlock(dict(TEAM=True, BABY=True, TYPE=Entity.ZOMBIE))

# A talking villager
vm.createBlock(dict(TALK=text, TYPE=Entity.VILLAGER))

# A cat on the leash
vm.createBlock(dict(LEASH=Leash.MYSELF, TYPE=Entity.CAT))

# Sand flying up
vm.createBlock(dict(VELOCITY=[1, 0, 0], TYPE=Block.RED_SAND))

# An image of an animal on the ground
vm.createBlock(dict(GROUND=True, IMAGE="animals/1F401", TYPE=Entity.ITEM_FRAME))

# A sunflower created after a time between 1 and 3 seconds
vm.createBlock(dict(DELAY=[1, 3], TYPE=Block.SUNFLOWER))

In this example, snow blocks are placed on the first solid block found below each position, ensuring the snow correctly follows the terrain.

Powered by  GDPR Cookie Compliance
Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.