# Usage guide

## Prerequisites

To use `lihzahrd`, you need Python 3.6 or higher.

That’s it! No other packages are required!

## Installing

You can download (or update) the package with `pip` by entering in your terminal:

    python3.8 -m pip install --upgrade lihzahrd

## Opening a world

To open a Terraria world file named `terra.wld` located in the current working directory, you should import the `lihzahrd` package and then call the `World.create_from_file()` function:

    import lihzahrd
    world = lihzahrd.World.create_from_file("terra.wld")

It should take a few minutes, depending on the size of the world, and then return a `World` object.

## Accessing the world properties

Most of the world properties are accessible directly as attributes of the `World` object:

    print(world.name)
    # "Terra"

    print(world.is_hardmode)
    # False

    print(world.spawn_point)
    # Coordinates(2101, 246)

Some world properties may be grouped in other objects:

    print(world.bosses_defeated)
    # <BossesDefeated>

    print(world.bosses_defeated.eye_of_cthulhu)
    # False

You can look at the `World` class documentation or use an IDE that supports type annotations (such as PyCharm) to find all available attributes.

## Accessing the tile data

All `tiles.Tile` are stored in the `tiles.TileMatrix` accessible at the `World.tiles` attribute.

    print(world.tiles)
    # <TileMatrix 4200x1200>

You can access them by using the `tiles` attribute as a two-dimensional array, where (0, 0) is the top-left block:

    print(world.tiles[0, 0])
    # <Tile>

You can also use `fileutils.Coordinates` instead of a `tuple` to fetch a specific tile:

    print(world.tiles[lihzahrd.fileutils.Coordinates(2000, 1000)])
    # <Tile B>

    print(world.tiles[world.spawn_point])
    # <Tile B>

Counting tiles from the bottom-right is possible too:

    print(world.tiles[-1, -1])
    # <Tile>

A single `tiles.Tile` has five attributes that you can access:

- `tiles.Tile.block`, the foreground `tiles.Block`;

- `tiles.Tile.wall`, the background `tiles.Wall`;

- `tiles.Tile.liquid`, the `tiles.Liquid` present in that tile;

- `tiles.Tile.wiring`, the colored wires and actuators (`tiles.Wiring`);

- `tiles.Tile.extra`, additional data about the block present at that tile, such as the contents of a chest.

All of these attributes may be `None` if the property isn’t applicable for the tile: for example, `tiles.Tile.block` is `None` if there is no block (“air”) placed there.

## Accessing extra data

Extra data, such as the content of chests or the text of signs, may be accessed in two different ways:

- Through the `tiles.Tile.extra` attribute:

      print(world.tiles[2893, 1074].extra)
      # <Chest '' at 2893, 1074>

- Through the various lists available in the `World` class, such as `World.chests`:

      print(world.chests[0])
      # <Chest '' at 2893, 1074>

Both ways return the same object, but one may be faster than the other, depending on your use case:

    print(world.tiles[2893, 1074].extra is world.chests[0])
    # True

## Something else

All information included in a Terraria savefile is parsed in this package and made available in the `World` object.

If you couldn’t find what you needed in this short usage guide, check the API Reference or have a look at the source code !