Usage guide


To use lihzahrd, you need Python 3.6 or higher.

That’s it! No other packages are required!


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:

# "Terra"

# False

# Coordinates(2101, 246)

Some world properties may be grouped in other objects:

# <BossesDefeated>

# 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.

# <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>

# <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:

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:

    # <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 !