New API

First draft of the new API

---

** DOCUMENT NOT FINAL**

---

During the Monday sprint at PyconUK we decided on a specific API to create. The current API is very Java-like (factories, create functions, instances created without ever being used, etc.) The user should also never have to see any connection object, only human readable functions.

The game world

The Minecraft class describes the world and is instantiated: minecraft = Minecraft([address, port])

The Minecraft class will allow players to set blocks similar to the current api: Minecraft.setBlock(Vector3, Block) This will set a block at a given point in the game (using absolute coordinates within the game) to the given instanciated block

Minecraft.say(String) will send a message to the chat without having any specific owner

All actions changing the game world will be called through the Minecraft calss using this convention

Function names should mirror the in-game minecraft functions where possible, as this will make it easier for players who have played minecraft to understand the API

Blocks

The Blocks class describes a block. A block has an ID which defines what type of block it is. Blocks will only be instantiated when required. At the moment one type of each block is instantiated at runtime.

aside:

It can be argued that we should not have a block class and just deal in block IDs. I agree with this -Jørn Lomax

The Player

The Minecraft world has a player, which is a member of the Minecraft class. Minecraft.player.pos() will give the players position (it's a function, because we don't keep the players pos updated, so we always have to fetch it)

We could make it a property using the @property decorator. -- Miles Gould

Minecraft.player.say(String) will make the player say something Minecraft.player.tell(String, target) will make the player whisper a message to another player

Other important stuff

While we still have the low level "Minecraft.setBlock(Vector3, blockID) we should also define some higher level functions like what @jonathanfine has written. The idea is that you take two points in space and say "fill inn everything within it with a certain block". If they happen to be on one plane, you get a wall, a carpet or a roof. If the space only contains a straight line, a straight line will be drawn, if it defines a cube, a cube will be made, and so on. Since this is done in a loop it allows to manipulate the blocks placed

the example code written: is the following

for pos in area(start, end):

    if pos.x % 2 == 0:
        
         pos.block == blockID.WHITE

    else:

        pos.block == blockID.BLOCK 

The reasoning behind this (for those interested): In minecraft all things are blocks. Some happen to be dirt, some water and some just happen to be air. Therefore it's logical to be able to iterate over every point in space and set the block to be something different.