Gdpc

an Interface instance with x, y and z offsets. That is, GDPC 5.0.0 supported
*translations*. This version, however, enhances this with 90-degree rotations
around the Y-axis and flipping/mirroring operations.

At the core of the transformation system lies the `Transform` class, which
essentially acts as a transformation matrix. It stores a translation (a 3D
vector), a rotation around the Y-axis (0, 1, 2 or 3) and a boolean flip vector.
Transforms can be multiplied like matrices, and they can be applied to vectors.

The `Block` class contains functionality that ensures that even *individual
blocks* which have an orientation (such as stairs) are rotated and flipped
correctly.

The `Editor` class now has a `.transform` attribute that defines that editor's
"point of view". It is applied to all block placement and retrieval positions.
You can modify this transform to change the editor's local coordinate system.

See the transformation tutorial for more details about the transformation
system.


Other changes

**Additions:**

- GDPC is now fully type hinted!

- Some important objects are now re-exported from `__init__.py`. That means
you can now use\
`from gdpc import Editor, Block, Transform, Rect, Box`.

- Mostly thanks to a change in GDMC-HTTP, you can now interact with different
dimensions! Simply modify `Editor.dimension`
(e.g. `Editor.dimension = "the_nether"`).

- Mostly thanks to a change in GDMC-HTTP, you can now directly retrieve biomes
using `Editor.getBiome()`.

- `Editor.placeBlock()` can now place multiple of the same block at once, with
improved performance.

- `Editor.runCommand()` can now run the command with a specific execution
position.

- `Editor.runCommand()` can now optionally defer the command until after the
next block buffer flush.

- `Editor` now has a new optional performance feature: it can automatically
multithread buffer flushes. Note however that this feature only rarely
improves performance and may come with some significant downsides. See the
editor performance tutorial for more information.

- You can now change the GDMC HTTP interface host from the default
`"http://localhost:9000"` - simply modify `Editor.host`.

- Block palettes now support "no placement" entries - simply use `Block(None)`.
Contrary to `Block("air")`, these "empty" blocks don't overwrite existing
blocks on placement.

- For most functions in `geometry`, there is now a corresponding function in
`vector_tools` that will yield all points of the shape directly, without
placing any blocks.

- `bookData()` (previously called `writeBook()`) now properly escapes the passed
text, title, author and description strings. You can now freely use characters
like `'` and `\`.

- `lookup.py` has been updated with all Minecraft 1.18 blocks, and most 1.19
blocks.


**Changes:**

- GDPC no longer prints anything directly. Most prints have been removed or
replaced with exceptions, and for those where this was not possible, GDPC now
uses the `logging` module. You can now disable all GDPC console output using
`logging.getLogger("gdpc").setLevel(logging.CRITICAL + 1)`.

- Exception messages are no longer colored.

- GDPC no longer checks the build area - it no longer prints warnings when
placing blocks outside of it. Build area warnings/enforcement may be added
to GDMC-HTTP in a future version.

- Various custom exception types have been added for specific GDPC errors.

- Exception messages for GDMC HTTP interface-related errors are now more
descriptive.

- Various functions that previously silently returned a default value on error
now throw an exception instead.

- All requests to the GDMC HTTP interface now perform some retries before
throwing an exception. The amount of retries is configurable.

- GDPC no longer sends any requests on import, so it will no longer crash on
import when Minecraft is not running.

- Thanks to a change in GDMC-HTTP, you now only need to place one block of a
multi-block object such as a door or a bed to place the entire thing.

- The block buffer of an `Editor` now also acts as a cache, ensuring that the
buffering mode is fully transparent.

- The integration of `Editor` and `WorldSlice` has been improved. See the
editor performance tutorial for more details.

- Some functions have been removed from `geometry`, and various new ones have
been added.

- `bookData()` no longer adds hardcoded pages to the created book.

- Metadata dunders like `__version__` are now only available from `__init__.py`,
but there are now more of them.


**Fixes:**

- Lots of bugs have been fixed, though no doubt many new ones have been
introduced as well. ;)


Older versions

For older versions, see
<https://github.com/nikigawlik/gdmc_http_client_python/releases>

Mostly thanks to work in the GDMC-HTTP mod, GDPC is now compatible with
Minecraft 1.19.2! On the technical side, that means it now supports negative
Y-coordinates and cubic biomes.

Unfortunately, the GDMC-HTTP mod is not backwards compatible with Minecraft

GDPC itself is still compatible with 1.16.5, but its only HTTP backend - the
GDMC-HTTP mod - is not.)


New and renamed modules

All of GDPC's modules have changed substantially, but many have held the same
general purpose. Most of these have been renamed, however:
- `direct_interface` -> `interface`
- `interface` -> `editor`\
(The `Interface` class is now the `Editor` class.)
- `toolbox` -> `minecraft_tools` and `editor_tools`\
The latter contains tools that require an `Editor`, while the former contains
tools that don't.
- `bitarray` and `worldLoader` -> `world_slice`

Lots of new modules have been added:
- `block`: Provides the `Block` class, more on this later.
- `block_state_tools`: Provides tools to work with orientation-related
[block states](https://minecraft.wiki/Block_states).
This is mainly for internal use.
- `exceptions`: Contains exception classes for GDPC.
- `model.py`: Provides the `Model` class, which can be used to store a structure
in memory. Future versions will add features like scanning in models from
Minecraft.
- `nbt_tools`: Provides some low-level tools for the
[NBT format](https://minecraft.wiki/NBT_format). This is mainly for
internal use.
- `transform`: Provides the `Transform` class and related utilities, more on
this later.
- `utils`: Provides various generic utilities that GDPC uses internally, but
may also be useful to others.
- `vector_tools`: Provides lots of vector math utilities, including the helpful
classes `Rect` and `Box`. Vectors are described further below.


Tutorials

The `examples` directory now contains various small tutorial-like scripts that
demonstrate and explain one particular feature of GDPC.


Editor class

The class that was previously called `Interface` is now called `Editor`, and
has received many new features. Most of these are described below. An important
change, however, is that there is no longer a "global" editor: there is no
more free `placeBlock()` function. You have to create an `Editor` instance and
then use `Editor.placeBlock()`.


Block class

This version introduces the `Block` class, which represents a Minecraft block.
The API for placing and retrieving blocks now uses this class instead of
strings: you place and get `Block("stone")` instead of `"stone"`.

Blocks consist of three components:
- A (namespaced) id (e.g. `minecraft:chest`).
- Optional [block states](https://minecraft.wiki/Block_states)
(e.g. `facing=north`).
- Optional [block entity](https://minecraft.wiki/Block_entity)
(S)NBT data (e.g. `{Items: [{Slot: 13b, id: "apple", Count: 1b}]}`).

The `Block` class supports all three of these. In other words, GDPC now fully
supports both placing and retrieving blocks with block states and NBT data!
No longer do you need to send separate commands to modify a block's NBT data
after placing it!
See `Block.py` and the advanced block tutorial for more details.

The `Block` class also plays an important role in enabling GDPC's new
transformation system - more on that further below.


Vectors

All GDPC functions that take position paramaters (i.e. nearly all of them) now
work with *vectors*, rather than separate x, y and z coordinates. GDPC is
however quite flexible in the types of vectors it accepts: any sequence of
numbers will do. That includes things like lists, tuples, numpy arrays and more.

Internally, GDPC now uses vector objects from the `pyGLM` package. Whenever a
GDPC function returns a vector, it will also be from this module. The `pyGLM`
vectors support various vector math operators that make lots of common
operations much easier and faster. They are also the basis of many of the more
advanced additions listed below.

See the the vector tutorial for more details about vectors.


Transformations

The most important addition is probably the transformation system. It allows you
to "transform" your frame of reference for placing and retrieving blocks, so
that you can always build using local coordinates instead of global ones. The
idea is based on the use of transformation matrices in typical 3D graphics
applications.

If you're programming, say, a house function, you could just always build the
house at (0,0,0) with its door pointing north, and then later call the function
with different transformations to place the house at any position and under any
rotation!