Every call and every block on one page. Coordinates come first, always x, y, z, and the block name comes last.
from pyblocks import world, player, noiseImport what you use. world is the world, player is you, noise is smooth random. A position can be three numbers or one position: world.set_block(0, 1, 0, "gold") and world.set_block(player.pos, "gold") both work. A second file of your own beside your program is imported by its name: import mykit.
world.set_block(x, y, z, block) | one block |
world.fill(x1, y1, z1, x2, y2, z2, block) | a box between two corners |
world.clear() | every block to air |
world.generate(seed, preset) | terrain. Presets: "flat", "hills", "mountains", "islands" |
world.hour = 18 | the time of day: 0 midnight, 6 sunrise, 12 noon, 18 sunset. Read it to see the time now |
world.day_length = 2 | how many real minutes a day takes. 0 holds the sun still |
world.size = 256 | how wide the world is, along x and z. Set it before you build |
world.define("sunset", (255, 120, 40)) | a colour of your own: red, green and blue, each 0 to 255. After it, "sunset" is a block name. glows=True makes it a light |
world.sky(latitude, longitude, year, month, day) | the real sky over that place on that date: the real stars, sun, moon and planets. lines=True draws the constellations, names=True names them |
world.sun.altitude world.sun.azimuth | where the sun is now: degrees above the horizon (below 0 it has set), and degrees clockwise from north. Read only |
world.moon.altitude world.moon.azimuth world.moon.lit | the same for the moon, and how much of it is lit, 0.0 new to 1.0 full. Read only |
world.date | the date of the real sky, as (year, month, day). Read only |
world.get_block(x, y, z) | the block name there, "air" if empty |
world.get_height(x, z) | the height of the top block in that column, -1 if empty |
world.in_bounds(x, y, z) | True if that place is inside the world |
world.min_x world.max_x world.min_y world.max_y world.min_z world.max_z | the edges of the world |
world.blocks | a list of every block name |
Reading is free: your program keeps its own copy of the world.
player.x player.y player.z | the block you are standing in. The floor is player.y - 1 |
player.pos | the three together. You can add to it: player.pos + (0, 1, 0) |
player.exact_pos | where you are between blocks, with decimals |
player.facing | "north", "east", "south" or "west" |
player.looking_at | the block under the crosshair, within six blocks, or None. It has .pos, .block, .face and .place, the empty cell in front of that face |
player.yaw player.pitch | the angles in degrees. Yaw: 0 north, 90 east, 180 south, 270 west. Pitch: -90 down, 0 level, 90 up. Set them to turn the view |
player.set_pos(x, y, z) | puts you in that block |
player.set_exact_pos(x, y, z) | puts you anywhere, decimals and all, and slides you there. A loop of these is a camera flight |
player.home = (0, 1, 8) | where H goes |
player.can_fly = False | no flying until the program ends |
player.can_go_home = False | H and the Home button do nothing until the program ends |
player.speed = 10 | how fast you walk, in blocks a second. 4.3 is normal |
player.jump = 3 | how high a jump reaches, in blocks. 1.5 is normal |
player.gravity = 5 | how hard the world pulls down. 28 is normal; the moon is about 5 |
Facts have no parentheses. Actions always do.
world.new_hits() | every block clicked since you last asked. Each hit has .pos, .block, .face and .action, "break" for a left click or "place" for a right click |
world.allow("break", "place") | which clicks count; name the ones you want. world.allow() with nothing locks the world |
world.new_keys() | every letter and number key pressed since you last asked, as "a" to "z" and "0" to "9" |
world.new_messages() | every line typed in chat since you last asked. Each has .text |
world.say(text) | a line to the player |
world.status(text) | one line pinned above the world, for a score. world.status("") takes it down |
world.effect(name, x, y, z) | a bang, a flash or a sound: "boom" "sparks" "smoke" "splash" "ding" "glow". colour="red" tints sparks, smoke and glow |
world.note(note, x, y, z) | a note heard from that place: "c4", "f#5", or a piano key number, 60 is middle C. voice= is "tone", "pluck", "organ" or "bass" |
world.drum(name, x, y, z) | a drum heard from that place: "kick", "snare", "hat" or "clap" |
world.label(x, y, z, text) | writing in that cell, like a sign. One to a cell, and "" takes it down. facing="north" fixes which way it faces |
world.remember() world.restore() | remember the world as it is; put it back |
from PIL import Image | Pillow, for reading a picture beside your program: Image.open("picture.png"), .convert("RGB"), .resize((32, 32)), .getpixel((x, y)) |
noise(x, z, seed=0) | smooth random from 0.0 to 1.0. Divide first: noise(x / 10, z / 10) is wider hills. The same seed gives the same hills |
Clicks, keys and chat wait in a queue until your program asks. Ask inside a loop, with time.sleep(0.1) at the end of it.
Nothing here acts on its own: water does not flow, sand does not fall, and TNT explodes only if your program explodes it. Slime, vine, ladder, web and ice react to you.
| Name | Family | Notes | |
|---|---|---|---|
air | Nothing | the empty cell; fill with it to take blocks away | |
 | grass | Ground | |
 | dirt | Ground | |
 | sand | Ground | |
 | gravel | Ground | |
 | stone | Ground | |
 | snow | Ground | |
 | ice | Ground | slippery: you keep sliding |
 | wood | Building | planks |
 | log | Building | bark on the sides, rings on the ends |
 | leaves | Building | oak or birch foliage |
 | brick | Building | |
 | sandstone | Building | |
 | glass | Building | see-through |
 | iron | Building | |
 | gold | Building | |
 | glowstone | Special | gives light |
 | water | Special | see-through; you walk through it |
 | lava | Special | gives light; you walk through it |
 | tnt | Special | explodes only if your program explodes it |
 | white | Color | |
 | grey | Color | |
 | black | Color | |
 | red | Color | |
 | orange | Color | |
 | yellow | Color | |
 | green | Color | |
 | blue | Color | |
 | purple | Color | |
 | pink | Color | |
 | brown | Color | |
 | poppy | Plant | walked through |
 | daisy | Plant | walked through |
 | dandelion | Plant | walked through |
 | bluebell | Plant | walked through |
 | mushroom | Plant | walked through |
 | fern | Plant | walked through |
 | bush | Plant | walked through |
 | cactus | Plant | solid, a little narrower than its cell |
 | birch | Tree | white bark; a trunk |
 | pine | Tree | dark bark; a trunk |
 | needles | Tree | pine foliage |
 | blossom | Tree | pink foliage |
 | amber | Tree | orange foliage |
 | cobble | Building | |
 | slate | Building | |
 | thatch | Building | |
 | clay | Building | |
 | lantern | Building | gives light; a small cube on the floor of its cell |
 | lamp | Building | looks lit and gives no light; put glowstone there to light it |
 | chest | Game | holds nothing; your program gives it meaning |
 | target | Game | a bullseye, to click |
 | button | Game | presses nothing until your program reads a hit on it |
 | plate | Game | your program can tell when you stand on it |
 | diamond | Game | |
 | slime | Reacts to you | a fall onto it bounces |
 | vine | Reacts to you | climb with W and S; walked through |
 | ladder | Reacts to you | climb with W and S; walked through |
 | tuft | Plant | tall grass; walked through |
 | web | Reacts to you | walked through, slowly |
 | coal | Game | |
 | copper | Game | |
 | emerald | Game |
The console says so in a sentence: a misspelled block name suggests the right one, and an address outside the world says which number is out and what the edges are.
File, Export for 3D printing writes an STL file. Every block that is not a plant becomes a cube. The dialog asks how many millimetres a block is and whether to put a plate underneath, and warns about pieces joined only at an edge or a corner. Water, lava, glass and ice print as solid blocks; the ground does not print.
| click the world | takes the mouse. Look around with the mouse or the arrow keys; Esc gives it back |
| W A S D Space | walk and jump. Ctrl sprints, F flies |
| flying | Space up, Shift down. Tap Space twice to fall; landing puts you back on foot |
| left click, right click | a break hit and a place hit, for your program to read |
| Enter or T | chat, for your program to read |
| F5 F6 | Run, Stop. Ctrl+S saves, and running saves too |
| F2 | a picture of the world, saved beside your program |
| Shift+F2 | a poster of it, big enough to print, with your program's title. # by Ada at the top of your program puts your name on it |
| F7 | steps the camera back: behind you, over your shoulder, then the world drawn flat from above, from the south and from the east. Press it again to come back. Grid paper prints the three flat drawings empty |
| Play a file, Arcade | run someone else's program with its code out of sight. The Arcade lists a folder of them, and a program in that folder will not open in the editor |