### Install GDPC from GitHub

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/installation.md

Installs the latest development version of GDPC directly from its GitHub repository. This is an alternative to installing from PyPI.

```bash
python3 -m pip install git+https://github.com/avdstaaij/gdpc
```

--------------------------------

### Install GDPC using pip

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/installation.md

Installs the GDPC library from PyPI using pip. Ensure Python 3.8 or higher is installed. On Windows, 'python3' might need to be replaced with 'py'.

```bash
python3 -m pip install gdpc
```

--------------------------------

### GDPC Quick Example

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/index.md

Demonstrates basic GDPC usage: initializing the Editor, getting a block at specific coordinates, placing a single block, and building a cuboid using the geometry module.

```python
from gdpc import Editor, Block, geometry

editor = Editor(buffering=True)

# Get a block
block = editor.getBlock((0,48,0))

# Place a block
editor.placeBlock((0,80,0), Block("stone"))

# Build a cube
geometry.placeCuboid(editor, (0,80,2), (2,82,4), Block("oak_planks"))
```

--------------------------------

### Update GDPC using pip

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/installation.md

Updates the GDPC library to the latest version from PyPI using pip. Similar to installation, 'python3' might need to be replaced with 'py' on Windows.

```bash
python3 -m pip install --upgrade gdpc
```

--------------------------------

### GDPC Quick Example

Source: https://github.com/avdstaaij/gdpc/blob/master/README.md

Demonstrates basic GDPC usage, including getting a block, placing a block, and building a cuboid using the geometry module.

```python
from gdpc import Editor, Block, geometry

editor = Editor(buffering=True)

# Get a block
block = editor.getBlock((0,48,0))

# Place a block
editor.placeBlock((0,80,0), Block("stone"))

# Build a cube
geometry.placeCuboid(editor, (0,80,2), (2,82,4), Block("oak_planks"))
```

--------------------------------

### Publish to PyPI

Source: https://github.com/avdstaaij/gdpc/blob/master/release-guide.md

Steps to prepare and publish the GDPC package to the Python Package Index (PyPI) using build and twine.

```bash
# Remove previous build artifacts (optional but recommended):
rm -rf dist

# Install build and twine if not already installed:
python3 -m pip install --upgrade build twine

# Build the package:
python3 -m build

# Upload to PyPI:
python3 -m twine upload dist/*
```

--------------------------------

### Create GitHub Release

Source: https://github.com/avdstaaij/gdpc/blob/master/release-guide.md

Instructions for creating a new release on GitHub, including setting the tag, title, and body content from the changelog.

```APIDOC
GitHub Release Creation:

1. Create Tag:
   - Format: "vX.X.X" (e.g., "v1.2.3")
   - Ensure it's a new, unique tag.

2. Set Release Title:
   - Format: "X.X.X" (e.g., "1.2.3")
   - Do not include the "v".

3. Set Release Body:
   - Content: The changelog section for the specific version being released.
   - Exclude the version header (e.g., "## X.X.X").
```

--------------------------------

### Install Development Dependencies and GDPC

Source: https://github.com/avdstaaij/gdpc/blob/master/CONTRIBUTING.md

Installs development dependencies, installs GDPC in editable mode, and sets up additional packages required for development.

```bash
pip install -r requirements-dev
```

--------------------------------

### Install GDPC in Editable Mode

Source: https://github.com/avdstaaij/gdpc/blob/master/requirements-dev.txt

Installs the GDPC project in editable mode, making it discoverable for tests and examples. This is a common practice for Python package development.

```shell
pip install -e .

```

--------------------------------

### Install GDPC and Documentation Dependencies

Source: https://github.com/avdstaaij/gdpc/blob/master/requirements-docs.txt

This snippet lists the Python packages required for building the GDPC project's documentation. It includes Sphinx and several extensions for theming and parsing, as well as GDPC itself installed in editable mode for API reference generation.

```python
sphinx==7.1.2
sphinx-autobuild==2021.3.14
myst-parser==3.0.1
sphinx-immaterial[keys]==0.11.14
-e .
```

--------------------------------

### Place Floor Blocks

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Places a 5x5 floor of stone bricks at a specified Y-level within the build area. This example demonstrates basic block placement.

```python
from gdpc import Editor, Block

editor = Editor()

buildArea = editor.getBuildArea()

y = 128

for x in range(buildArea.offset.x, buildArea.offset.x + 5):
    for z in range(buildArea.offset.z, buildArea.offset.z + 5):
        editor.placeBlock((x, y, z), Block("stone_bricks"))
```

--------------------------------

### GDPC Editor Building Example

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/transformation.md

Demonstrates building structures using GDPC's Editor, including placing individual blocks and cuboids, and applying transformations like translation and flipping.

```python
from gdpc import Editor, Block, Transform
from gdpc.geometry import placeCuboid, placeCheckeredCuboid

def buildExampleStructure(editor):
    editor.placeBlock((0,0,0), Block("yellow_concrete"))
    placeCuboid(editor, (1,0,0), (3,0,0), Block("red_concrete"))
    placeCuboid(editor, (0,1,0), (0,2,0), Block("lime_concrete"))
    placeCuboid(editor, (0,0,1), (0,0,3), Block("blue_concrete"))

editor = Editor()

with editor.pushTransform((0,99,0)):
    placeCheckeredCuboid(
        editor,
        (-4,0,-2), (4,0,10),
        Block("gray_concrete"), Block("white_concrete")
    )

    with editor.pushTransform(Transform((0,1,0))):
        buildExampleStructure(editor)

    with editor.pushTransform(Transform((0,1,5), flip=(True, False, False))):
        buildExampleStructure(editor)
```

--------------------------------

### Update Version and Commit

Source: https://github.com/avdstaaij/gdpc/blob/master/release-guide.md

This snippet details the steps to update the version number in `__init__.py`, modify the changelog, and commit these changes with a specific message.

```python
# In __init__.py:
__version__ = "X.X.X"

# Commit message:
# Updated version to X.X.X
```

--------------------------------

### Install GDPC in Editable Mode

Source: https://github.com/avdstaaij/gdpc/blob/master/CONTRIBUTING.md

Installs the local version of GDPC in editable mode, allowing for direct testing of local changes. It's recommended to use a virtual environment for this.

```bash
pip install -e .
```

--------------------------------

### Build House on Terrain

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Loads world data, gets heightmap, and places a hollow cuboid house structure adapted to the terrain's Y-level. It also constructs a roof using stairs and planks.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

# Load world slice of the build area
editor.loadWorldSlice(cache=True)

# Get heightmap
heightmap = editor.worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"]

x = buildArea.offset.x + 1
z = buildArea.offset.z + 1

y = heightmap[3,3] - 1

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+4, z+4), Block("oak_planks"))
placeCuboid(editor, (x, y, z), (x+4, y, z+4), Block("stone_bricks"))

# Build roof: loop through distance from the middle
for dx in range(1, 4):
    yy = y + 6 - dx
    leftBlock  = Block("oak_stairs", {"facing": "east"})
    rightBlock = Block("oak_stairs", {"facing": "west"})
    placeCuboid(editor, (x+2-dx, yy, z-1), (x+2-dx, yy, z+5), leftBlock)
    placeCuboid(editor, (x+2+dx, yy, z-1), (x+2+dx, yy, z+5), rightBlock)

# build the top row of the roof
placeCuboid(editor, (x+2, y+5, z-1), (x+2, y+5, z+5), Block("oak_planks"))
```

--------------------------------

### Initialize Editor with Performance Features

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/improving-editor-performance.md

Constructs an Editor instance with performance features like buffering, caching, and a specific cache limit enabled from the start.

```python
editor = Editor(buffering=True, caching=True, cacheLimit=1024)
```

--------------------------------

### Place and Get Blocks

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/basic-world-interaction.md

Demonstrates how to place a block at specific coordinates and retrieve the block at a given position using the Editor class. It also shows how to create a Block object.

```python
from gdpc import Editor, Block

editor = Editor()

editor.placeBlock((0,128,0), Block("red_concrete"))

block = editor.getBlock((0,128,0))
print(block) # e.g. "minecraft:red_concrete"
```

--------------------------------

### Retrieve a Block with GDPC

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Shows how to retrieve a block from the Minecraft world using GDPC's Editor. This example retrieves the previously placed red concrete block and prints its identifier.

```python
from gdpc import Editor, Block

editor = Editor()

editor.placeBlock((0,128,0), Block("red_concrete"))

block = editor.getBlock((0,128,0))
print(block)
```

--------------------------------

### Applying Multiple Transform Components

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/transformation.md

Shows the order of operations when a Transform has multiple components: flip first, then rotate, then translate. This example combines rotation and translation.

```python
transform = Transform(translation=(1,0,1), rotation=1)

vec = (2,0,-1)

result = transform * vec # (2,0,3)
```

--------------------------------

### Building Terrain-Adaptive Walls

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/world-slice.md

Example of using heightmaps to construct a wall that follows the ground's contour. It iterates through the build area's perimeter and places blocks based on heightmap values.

```python
from gdpc import Editor, Block

editor = Editor()
buildArea = editor.getBuildArea()
buildRect = buildArea.toRect()
editor.loadWorldSlice(buildRect, cache=True)
heightmap = editor.worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"]

# Loop through the perimeter of the build area
for point in buildRect.outline:
    localPoint = point - buildRect.offset

    # You can index a numpy array with a pyGLM vector by converting to a tuple
    height = heightmap[tuple(localPoint)]

    for y in range(height, height + 5):
        editor.placeBlock((point[0], y, point[1]), Block("stone_bricks"))
```

--------------------------------

### Access Heightmap Data

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Retrieves heightmap data from the loaded `WorldSlice`. The heightmaps are stored as NumPy arrays indexed by (X,Z) coordinates. This example specifically accesses the 'MOTION_BLOCKING_NO_LEAVES' heightmap to find the ground level.

```python
# (...)

# The heightmaps are available as a dictionary of 2D
# [numpy](https://numpy.org/doc/stable/) arrays indexed with (X,Z)-coordinates,
# with `[0,0]` indicating the height at the start of WorldSlice (in our case, the
# build area). We'll use the "MOTION_BLOCKING_NO_LEAVES" heightmap, which stores
# the heights of the highest blocks that block motion or contain a fluid but which
# are not leaves. That's usually what we consider "the ground" (tree trunks are an
# exception).

# Example of accessing the heightmap (actual usage would involve editor.worldSlice):
# height = editor.worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"][0, 0]
```

--------------------------------

### GDPC Geometry Module Examples

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/building-shapes.md

Demonstrates the usage of various shape-building functions from the GDPC geometry module, including placeCuboid, placeFittingCylinder, placeLine, placeStripedCuboid, and placeRectOutline. These functions simplify the process of creating complex structures in the game world.

```python
import numpy as np
from pyglm.glm import ivec3
from gdpc import Editor, Block, geometry
from gdpc.vector_tools import addY

editor = Editor()

buildArea = editor.getBuildArea()
buildRect = buildArea.toRect()

worldSlice = editor.loadWorldSlice(buildRect)

heightmap = worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"]
meanHeight = int(np.mean(heightmap))
groundCenter = addY(buildRect.center, meanHeight)

# Place a cuboid shape
geometry.placeCuboid(
    editor,
    groundCenter + ivec3(-3, -10, -23), # Corner 1
    groundCenter + ivec3( 4,  20, -16), # Corner 2
    Block("blue_concrete")
)

# Place a cylinder
geometry.placeFittingCylinder(
    editor,
    groundCenter + ivec3(-3, -10, -10), # Corner 1
    groundCenter + ivec3( 4,  20,  -3), # Corner 2
    Block("lime_concrete")
)

# Place a diagonal line
geometry.placeLine(
    editor,
    groundCenter + ivec3(-3, 10,  3), # Endpoint 1
    groundCenter + ivec3( 4, 17, 10), # Endpoint 1
    Block("yellow_concrete"),
    width=1
)

# Place a cuboid that is striped along the Z axis (axis 2)
geometry.placeStripedCuboid(
    editor,
    groundCenter + ivec3(-3, -10, 16), # Corner 1
    groundCenter + ivec3( 4,  20, 23), # Corner 2
    Block("purple_concrete"),
    Block("magenta_concrete"),
    axis=2
)

# Place an outline around the build area
geometry.placeRectOutline(editor, buildRect, 100, Block("red_concrete"))
```

--------------------------------

### Visualize Build Area Outline and Place Cuboid

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Demonstrates using `placeRectOutline` to visualize the build area's (X,Z) rectangle and `placeCuboid` to place a floor. This helps in understanding spatial boundaries.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeRectOutline

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

placeRectOutline(editor, buildArea.toRect(), 140, Block("red_concrete"))

y = 128
x = buildArea.offset.x
z = buildArea.offset.z

placeCuboid(editor, (x, y, z), (x+4, y, z+4), Block("stone_bricks"))
```

--------------------------------

### Place Floor Blocks with Buffering

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Places a 5x5 floor of stone bricks with buffering enabled for improved performance. Buffering batches block changes for more efficient transmission to the GDMC-HTTP interface.

```python
from gdpc import Editor, Block

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

y = 128

for x in range(buildArea.offset.x, buildArea.offset.x + 5):
    for z in range(buildArea.offset.z, buildArea.offset.z + 5):
        editor.placeBlock((x, y, z), Block("stone_bricks"))
```

--------------------------------

### Get Minecraft Version

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/basic-world-interaction.md

Demonstrates how to get the version of the Minecraft client that GDPC is interacting with using the getMinecraftVersion method.

```python
from gdpc import Editor

editor = Editor()
version = editor.getMinecraftVersion()
print(version) # e.g. "1.19.2"
```

--------------------------------

### Add Door and Clear Space

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This snippet demonstrates how to place a door and clear out the interior of the house and the area in front of the door using air blocks. It highlights the use of `Block("air")` for removal.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

# Assuming editor, x, y, z, height are defined
# Example values:
editor = Editor()
x, y, z = 0, 64, 0
height = 5
depth = 5

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+height, z+depth), Block("oak_planks"))
placeCuboid(editor, (x, y, z), (x+4, y, z+depth), Block("stone"))
placeCuboid(editor, (x+1, y+1, z+1), (x+3, y+height-1, z+3), Block("air"))

# Add a door
doorBlock = Block("oak_door", {"facing": "north", "hinge": "left"})
editor.placeBlock((x+2, y+1, z), doorBlock)

# Clear some space in front of the door
placeCuboid(editor, (x+1, y+1, z-1), (x+3, y+3, z-1), Block("air"))
```

--------------------------------

### Place Cuboid using Geometry Helper

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Uses the `placeCuboid` function from `gdpc.geometry` to place a solid box of stone bricks. This simplifies the process compared to manual iteration.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

y = 128
x = buildArea.offset.x
z = buildArea.offset.z

placeCuboid(editor, (x, y, z), (x+4, y, z+4), Block("stone_bricks"))
```

--------------------------------

### Get Biome

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/basic-world-interaction.md

Shows how to retrieve the biome name for a specific set of coordinates using the Editor's getBiome method.

```python
from gdpc import Editor

editor = Editor()
biome = editor.getBiome((0,128,0))
print(biome) # e.g. "minecraft:plains"
```

--------------------------------

### Add Door and Clear Space

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This code adds an oak door to the house and then clears a 3x3 area in front of the door using air blocks. It demonstrates placing a specific block with orientation and clearing space with `placeCuboid`.

```python
# Add a door
doorBlock = Block("oak_door", {"facing": "north", "hinge": "left"})
editor.placeBlock((x+2, y+1, z), doorBlock)

# Clear some space in front of the door
placeCuboid(editor, (x+1, y+1, z-1), (x+3, y+3, z-1), Block("air"))
```

--------------------------------

### Place a Block with GDPC

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Demonstrates how to place a single block in the Minecraft world using the GDPC Editor. Requires the GDMC HTTP Interface mod. Places a red concrete block at specified coordinates.

```python
from gdpc import Editor, Block

editor = Editor()

editor.placeBlock((0,128,0), Block("red_concrete"))
```

--------------------------------

### Complete House Generation Script

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This is a comprehensive script that generates a house with randomized dimensions and materials. It includes building the main structure, adding a floor, clearing the interior, placing a door, and adding roof details.

```python
from random import randint, choice
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

# Load world slice of the build area
editor.loadWorldSlice(cache=True)

# Get heightmap
heightmap = editor.worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"]

x = buildArea.offset.x + 1
z = buildArea.offset.z + 1

y = heightmap[3,1] - 1

height = randint(3, 7)
depth  = randint(3, 10)

# Random floor palette
floorPalette = [
    Block("stone_bricks"),
    Block("cracked_stone_bricks"),
    Block("cobblestone"),
]

# Choose wall material
wallBlock = choice([
    Block("oak_planks"),
    Block("spruce_planks"),
    Block("white_terracotta"),
    Block("green_terracotta"),
])
print(f"Chosen wall block: {wallBlock}")

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+height, z+depth), wallBlock)
placeCuboid(editor, (x, y, z), (x+4, y-5, z+depth), floorPalette)
placeCuboid(editor, (x+1, y+1, z+1), (x+3, y+height-1, z+3), Block("air"))

# Add a door
doorBlock = Block("oak_door", {"facing": "north", "hinge": "left"})
editor.placeBlock((x+2, y+1, z), doorBlock)

# Clear some space in front of the door
placeCuboid(editor, (x+1, y+1, z-1), (x+3, y+3, z-1), Block("air"))

# Build roof: loop through distance from the middle
for dx in range(1, 4):
    yy = y + height + 2 - dx

    # Build row of stairs blocks
    leftBlock  = Block("oak_stairs", {"facing": "east"})
    rightBlock = Block("oak_stairs", {"facing": "west"})
    placeCuboid(editor, (x+2-dx, yy, z-1), (x+2-dx, yy, z+depth+1), leftBlock)
    placeCuboid(editor, (x+2+dx, yy, z-1), (x+2+dx, yy, z+depth+1), rightBlock)

    # Add upside-down accent blocks
    leftBlock  = Block("oak_stairs", {"facing": "west", "half": "top"})
    rightBlock = Block("oak_stairs", {"facing": "east", "half": "top"})
    for zz in [z-1, z+depth+1]:
        editor.placeBlock((x+2-dx+1, yy, zz), leftBlock)
        editor.placeBlock((x+2+dx-1, yy, zz), rightBlock)

# Save changes to the world
editor.flush()
print("House built!")
```

--------------------------------

### Get Build Area

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Retrieves the defined build area from the GDMC interface. The build area is a Box object representing the operational bounds for the program.

```python
from gdpc import Editor, Block

editor = Editor()

buildArea = editor.getBuildArea()
print(buildArea)
```

--------------------------------

### Build Main Shape with Hollow Cuboid and Floor

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Demonstrates building the main structure of a house using `placeCuboidHollow` for the walls and `placeCuboid` to overwrite the floor. This function requires the Editor instance and block coordinates.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

y = 128
x = buildArea.offset.x
z = buildArea.offset.z

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+4, z+4), Block("oak_planks"))
placeCuboid(editor, (x, y, z), (x+4, y, z+4), Block("stone_bricks"))
```

--------------------------------

### Convert PDF to SVG

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/tools/latex-diagrams/notes.md

This snippet demonstrates how to convert a PDF file to an SVG file using the pdf2svg command-line utility. Ensure pdf2svg is installed before running this command.

```bash
pdf2svg input.pdf output.svg
```

--------------------------------

### Randomize House Materials

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Further randomizes the house by selecting wall materials using `random.choice` and applying a random block palette for the floor. This allows for varied appearances and a more 'rugged' look.

```python
from random import randint, choice
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

# Load world slice of the build area
editor.loadWorldSlice(cache=True)

# Get heightmap
heightmap = editor.worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"]

x = buildArea.offset.x + 1
z = buildArea.offset.z + 1

y = heightmap[3,3] - 1

height = randint(3, 7)
depth  = randint(3, 10)

# Random floor palette
floorPalette = [
    Block("stone_bricks"),
    Block("cracked_stone_bricks"),
    Block("cobblestone"),
]

# Choose wall material
wallBlock = choice([
    Block("oak_planks"),
    Block("spruce_planks"),
    Block("white_terracotta"),
    Block("green_terracotta"),
])
print(f"Chosen wall block: {wallBlock}")

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+height, z+depth), wallBlock)
placeCuboid(editor, (x, y, z), (x+4, y, z+depth), floorPalette)
```

--------------------------------

### Transform Class Initialization

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/transformation.md

Demonstrates how to initialize the Transform class with translation, rotation, and flip components.

```python
from gdpc import Transform

transform = Transform((1,2,3), 1, (True, False, False))
```

--------------------------------

### Load World Slice for Heightmap Access

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Loads the world slice for the current build area, enabling access to heightmaps. The `cache=True` argument optimizes block retrieval by using the loaded world slice as a cache.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

# Load world slice of the build area
editor.loadWorldSlice(cache=True)

# (...)
```

--------------------------------

### Getting Blocks and Biomes from WorldSlice

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/world-slice.md

Illustrates how to retrieve block and biome data from a loaded WorldSlice using both local and global coordinate systems. Shows how to handle requests for data outside the slice boundaries.

```python
from gdpc import Editor, Rect

rect = Rect((2,2), (5,5)) # Rect with corners (2,2) and (6,6)

editor = Editor()
worldSlice = editor.loadWorldSlice(rect)

# Get the block and biome at local (X,Z)=(3,64,3) / global (X,Z)=(5,64,5).
block = worldSlice.getBlock((3,64,3))
biome = worldSlice.getBiome((3,64,3))

# Get the block and biome at global (X,Z)=(3,64,3) / local (X,Z)=(1,64,1).
block = worldSlice.getBlockGlobal((3,64,3))
biome = worldSlice.getBiomeGlobal((3,64,3))

# Get Block("minecraft:void_air"), since this position is not in the slice.
block = worldSlice.getBlock((6,64,6))
```

--------------------------------

### Create Stairs Block with Facing and Half States

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Shows how to create a Minecraft `Block` instance for stairs, specifying its orientation ('facing') and whether it's on the bottom or top half ('half'). This is crucial for building roofs and other complex structures.

```python
block = Block("oak_stairs", {"facing": "east", "half": "bottom"})
```

--------------------------------

### General Vector Utilities in GDPC (Python)

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/vectors.md

Provides examples of general vector manipulation functions available in GDPC's `vector_tools` module, such as `addY`, `dropY`, `perpendicular`, and `toAxisVector2D`. These functions operate on vector-likes and return pyGLM vectors.

```python
from pyglm.glm import ivec2, ivec3
from gdpc.vector_tools import addY, dropY, perpendicular, toAxisVector2D

# Example usage (assuming vector definitions)
# vec3 = ivec3(1, 2, 3)
# vec2 = ivec2(4, 5)

# addY_vec = addY(vec3, 10) # Adds 10 to the Y component
# dropY_vec = dropY(vec3)    # Removes the Y component, returns ivec2
# perp_vec = perpendicular(vec2) # Returns a perpendicular vector to vec2
# axis_vec = toAxisVector2D(vec3) # Converts a 3D vector to a 2D axis vector

```

--------------------------------

### Build Roof and Stairs

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This code snippet builds the roof structure of a house by iterating through distances from the center and placing oak stairs for support and accent blocks. It utilizes the `Block` class and `placeCuboid` function for block placement.

```python
for dx in range(1, 4):
    yy = y + height + 2 - dx

    # Build row of stairs blocks
    leftBlock  = Block("oak_stairs", {"facing": "east"})
    rightBlock = Block("oak_stairs", {"facing": "west"})
    placeCuboid(editor, (x+2-dx, yy, z-1), (x+2-dx, yy, z+depth+1), leftBlock)
    placeCuboid(editor, (x+2+dx, yy, z-1), (x+2+dx, yy, z+depth+1), rightBlock)

    # Add upside-down accent blocks
    leftBlock  = Block("oak_stairs", {"facing": "west", "half": "top"})
    rightBlock = Block("oak_stairs", {"facing": "east", "half": "top"})
    for zz in [z-1, z+depth+1]:
        editor.placeBlock((x+2-dx+1, yy, zz), leftBlock)
        editor.placeBlock((x+2+dx-1, yy, zz), rightBlock)
```

--------------------------------

### Run Minecraft Command

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/basic-world-interaction.md

Illustrates how to execute a Minecraft command in the game world using the Editor's runCommand method. The leading '/' should be omitted.

```python
from gdpc import Editor

editor = Editor()
editor.runCommand("say hello world!")
```

--------------------------------

### Build Top Roof Row

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This snippet places a solid row of oak planks to complete the top of the roof structure. It uses the `placeCuboid` function for efficient block placement.

```python
yy = y + height + 1
placeCuboid(editor, (x+2, yy, z-1), (x+2, yy, z+depth+1), Block("oak_planks"))
```

--------------------------------

### Extend Floor

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This snippet shows how to extend the house floor downwards to better integrate with uneven terrain. It uses `placeCuboid` to fill a larger area with the floor material.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

# Assuming editor, x, y, z, height, depth are defined
# Example values:
editor = Editor()
x, y, z = 0, 64, 0
height = 5
depth = 5

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+height, z+depth), Block("oak_planks"))
# Extend floor downwards
placeCuboid(editor, (x, y, z), (x+4, y-5, z+depth), Block("stone"))
```

--------------------------------

### Using pushTransform for Transformation Contexts

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/transformation.md

Demonstrates how to use `Editor.pushTransform` as a context manager to temporarily apply transformations. Changes to `Editor.transform` are reverted upon exiting the `with` block. It also shows how to push a specific transform object or a translation vector directly.

```python
from gdpc import Editor, Transform

editor = Editor()

# Using pushTransform as a context manager
with editor.pushTransform():
    editor.transform @= Transform((1,2,3))
    # ... build some stuff ...
# Editor.transform is now back to its previous state.

# Pushing a specific transform object
with editor.pushTransform(Transform((1,2,3))):
    # ... build some stuff ...

# Pushing a translation vector directly
with editor.pushTransform((1,2,3)):
    # ... build some stuff ...

```

--------------------------------

### Build Roof Details

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

This snippet adds decorative upside-down stairs blocks to the front and back of the roof for improved aesthetics. It iterates through a range to place blocks at different depths.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid

# Assuming editor, x, y, z, height, depth are defined
# Example values:
editor = Editor()
x, y, z = 0, 64, 0
height = 5
depth = 5

# Build roof: loop through distance from the middle
for dx in range(1, 4):
    yy = y + height + 2 - dx

    # Build row of stairs blocks
    leftBlock  = Block("oak_stairs", {"facing": "east"})
    rightBlock = Block("oak_stairs", {"facing": "west"})
    placeCuboid(editor, (x+2-dx, yy, z-1), (x+2-dx, yy, z+depth+1), leftBlock)
    placeCuboid(editor, (x+2+dx, yy, z-1), (x+2+dx, yy, z+depth+1), rightBlock)

    # Add upside-down accent blocks
    leftBlock  = Block("oak_stairs", {"facing": "west", "half": "top"})
    rightBlock = Block("oak_stairs", {"facing": "east", "half": "top"})
    for zz in [z-1, z+depth+1]:
        editor.placeBlock((x+2-dx+1, yy, zz), leftBlock)
        editor.placeBlock((x+2+dx-1, yy, zz), rightBlock)
```

--------------------------------

### Project Dependencies

Source: https://github.com/avdstaaij/gdpc/blob/master/requirements-dev.txt

Lists the core dependencies for the GDPC project, including specific versions for build and twine. These are essential for the project's functionality.

```python
build==1.2.2.post1
twine==6.1.0

```

--------------------------------

### Randomize House Height and Depth

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Enhances the house building script by introducing randomization for the house's height and depth using Python's `random.randint`. Hardcoded dimensions are replaced with these random variables.

```python
from random import randint
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

# Load world slice of the build area
editor.loadWorldSlice(cache=True)

# Get heightmap
heightmap = editor.worldSlice.heightmaps["MOTION_BLOCKING_NO_LEAVES"]

x = buildArea.offset.x + 1
z = buildArea.offset.z + 1

y = heightmap[3,3] - 1

height = randint(3, 7)
depth  = randint(3, 10)

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+height, z+depth), Block("oak_planks"))
placeCuboid(editor, (x, y, z), (x+4, y, z+depth), Block("stone_bricks"))

# Build roof: loop through distance from the middle
for dx in range(1, 4):
    yy = y + height + 2 - dx

    # Build row of stairs blocks
    leftBlock  = Block("oak_stairs", {"facing": "east"})
    rightBlock = Block("oak_stairs", {"facing": "west"})
    placeCuboid(editor, (x+2-dx, yy, z-1), (x+2-dx, yy, z+depth+1), leftBlock)
    placeCuboid(editor, (x+2+dx, yy, z-1), (x+2+dx, yy, z+depth+1), rightBlock)

# build the top row of the roof
yy = y + height + 1
placeCuboid(editor, (x+2, yy, z-1), (x+2, yy, z+depth+1), Block("oak_planks"))
```

--------------------------------

### Set Build Area Command

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

The in-game Minecraft command to set the build area. It takes six coordinates defining two opposing corners of the desired box.

```minecraft
/setbuildarea ~ 0 ~ ~63 255 ~63
```

--------------------------------

### Helper Functions for Block Creation

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/advanced-blocks.md

Showcases helper functions from `gdpc.minecraft_tools` and `gdpc.editor_tools` for simplifying the creation and placement of blocks, such as signs and container blocks.

```python
from gdpc.minecraft_tools import signBlock
from gdpc.editor_tools import placeSign, placeContainerBlock
from gdpc import Editor, Block

# Create the same sign block as in the earlier example using a helper function
sign = signBlock("oak", rotation=9, frontLine2="Lorem ipsum")

editor = Editor()

# Example of placing a sign using a tool (assuming editor is initialized)
# placeSign(editor, (0, 64, 0), "oak", rotation=9, frontLine2="Lorem ipsum")

# Example of placing a container block (e.g., a chest)
# placeContainerBlock(editor, (1, 64, 0), "chest", items=[{"Slot": 0, "id": "apple", "Count": 1}])
```

--------------------------------

### Documentation Requirements

Source: https://github.com/avdstaaij/gdpc/blob/master/requirements-dev.txt

Specifies the requirements file for documentation generation. This file likely contains packages needed for building documentation, such as Sphinx or Read the Docs configurations.

```shell
pip install -r ./requirements-docs.txt

```

--------------------------------

### GDPC Block Class Initialization

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/overview/advanced-blocks.md

Demonstrates creating GDPC Block objects with IDs, states, and NBT data. The `Block` class represents Minecraft blocks, allowing customization of their properties.

```python
from gdpc import Editor, Block

# An oak log on its side (aligned with the z-axis):
log = Block("oak_log", {"axis": "z"})

# A stone brick stairs block that's upside-down and facing west:
stairs = Block("stone_brick_stairs", {"facing": "west", "half": "top"})

# A chest with an apple in the middle slot:
chest = Block("chest", data='{Items: [{Slot: 13b, id: "apple", Count: 1b}]}')

# A sign that's rotated by 9 steps and shows the text "Lorem ipsum":
sign = Block(
    "oak_sign",
    {"rotation": "9"},
    "{front_text: {messages: ['{\"text\": \"\"}', '{\"text\": \"Lorem ipsum\"}', '{\"text\": \"\"}', '{\"text\": \"\"}']}}"
)
```

--------------------------------

### Build Diagonal Roof with Stairs Blocks

Source: https://github.com/avdstaaij/gdpc/blob/master/docs/source/getting-started/tutorial-house.md

Constructs a diagonal roof using `oak_stairs` blocks. It iterates to create rows of stairs facing inwards from both sides and places a final row of planks at the peak. This involves calculating y-coordinates based on distance from the center.

```python
from gdpc import Editor, Block
from gdpc.geometry import placeCuboid, placeCuboidHollow

editor = Editor(buffering=True)

buildArea = editor.getBuildArea()

y = 128
x = buildArea.offset.x + 1
z = buildArea.offset.z + 1

# Build main shape
placeCuboidHollow(editor, (x, y, z), (x+4, y+4, z+4), Block("oak_planks"))
placeCuboid(editor, (x, y, z), (x+4, y, z+4), Block("stone_bricks"))

# Build roof: loop through distance from the middle
for dx in range(1, 4):
    yy = y + 6 - dx

    # Build row of stairs blocks
    leftBlock  = Block("oak_stairs", {"facing": "east"})
    rightBlock = Block("oak_stairs", {"facing": "west"})
    placeCuboid(editor, (x+2-dx, yy, z-1), (x+2-dx, yy, z+5), leftBlock)
    placeCuboid(editor, (x+2+dx, yy, z-1), (x+2+dx, yy, z+5), rightBlock)

# build the top row of the roof
placeCuboid(editor, (x+2, y+5, z-1), (x+2, y+5, z+5), Block("oak_planks"))
```