lihzahrd/README.md

<div align="center">

![](.media/icon-128x128_round.png)

# Lihzahrd

Terraria game world parser for Python

</div>

## Links

[![Available on PyPI](https://img.shields.io/pypi/v/lihzahrd)](https://pypi.org/project/lihzahrd/)

[![Full documentation](https://img.shields.io/website?url=https%3A%2F%2Fgh.steffo.eu%2Flihzahrd%2Fhtml%2F&up_message=passing&down_message=failing&label=docs)](https://gh.steffo.eu/lihzahrd/html/)

## Installation

Lihzahrd can be installed from PyPI like any other public Python package.

Using [uv](https://docs.astral.sh/uv/), that means:

```shell
uv add lihzahrd
```

## Usage

You can open a world file and get a `World` object by calling:

```python
import lihzahrd
world = lihzahrd.World.create_from_file("filename.wld")
```

It _will_ take a while to process: a small Terraria world contains more than 5 million tiles!

Once you have a `World` object, you can use all data present in the save file by accessing [its attributes](http://gh.steffo.eu/lihzahrd/html/world.html).

> [!Warning]
> 
> Maliciously designed Terraria worlds can drain system resources, crash the interpreter, or possibly do other evil things!
> 
> **Make sure you trust worlds before parsing them!**

## Documentation

The documentation is available [here](https://gh.steffo.eu/lihzahrd/html/).

If you know something that is missing in the documentation, please let me know [with an issue](https://github.com/Steffo99/lihzahrd/issues/new)!

## PyPy

`lihzahrd` is compatible with [PyPy](https://www.pypy.org), an alternative implementation on Python!

If you think that parsing a world takes too much time, you can use PyPy to reduce the required time by a factor of ~3!

### Benchmarks

Time to parse the same large world:

- CPython took 11.45 s.
- Pypy took 3.57 s!

### Building docs

You can build the docs by entering the `docs_source` folder and running `make html`, then committing the whole `docs` folder.

## References used

- The [TEdit World Parser](https://github.com/TEdit/Terraria-Map-Editor/blob/master/TEditXna/Terraria/World.FileV2.cs), the most accurate source currently available.
- The [tModLoader wiki](https://github.com/tModLoader/tModLoader/wiki), containing lists of all possible IDs.
- The [Terrafirma world documentation](http://seancode.com/terrafirma/world.html), accurate for old worlds (version <69)
- The [1.3.x.x world documentation](http://ludwig.schafer.free.fr/), a bit incomplete, but an useful source nevertheless.
- A [JS World Parser](https://github.com/cokolele/terraria-world-parser/) on GitHub.
- A [Background Guide](https://steamcommunity.com/sharedfiles/filedetails/?id=841032800) on Steam that displays all possible world backgrounds.

## See also

- [flyingsnake](https://github.com/Steffo99/flyingsnake), a map renderer using this package
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`<div align="center">`
1.0b1 2019-08-13 17:56:17 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`![](.media/icon-128x128_round.png)`
1.0b1 2019-08-13 17:56:17 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`# Lihzahrd`
1.0b1 2019-08-13 17:56:17 +00:00
Remove trailing dot 2024-09-04 19:08:15 +00:00			`Terraria game world parser for Python`
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00
			`</div>`

			`## Links`
Update README.md 2023-03-06 14:58:42 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`[![Available on PyPI](https://img.shields.io/pypi/v/lihzahrd)](https://pypi.org/project/lihzahrd/)`
Update README.md 2023-03-06 14:58:42 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`[![Full documentation](https://img.shields.io/website?url=https%3A%2F%2Fgh.steffo.eu%2Flihzahrd%2Fhtml%2F&up_message=passing&down_message=failing&label=docs)](https://gh.steffo.eu/lihzahrd/html/)`
Update README.md 2023-03-06 14:58:42 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`## Installation`

			`Lihzahrd can be installed from PyPI like any other public Python package.`
Update README.md 2023-03-06 14:58:42 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`Using [uv](https://docs.astral.sh/uv/), that means:`
Update README.md 2023-03-06 14:58:42 +00:00
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			```shell
			`uv add lihzahrd`
			```
1.0b1 2019-08-13 17:56:17 +00:00
			`## Usage`

			You can open a world file and get a `World` object by calling:

Update README.md 2023-03-06 14:58:42 +00:00			```python
1.0b1 2019-08-13 17:56:17 +00:00			`import lihzahrd`
			`world = lihzahrd.World.create_from_file("filename.wld")`
			```

			`It _will_ take a while to process: a small Terraria world contains more than 5 million tiles!`

			Once you have a `World` object, you can use all data present in the save file by accessing [its attributes](http://gh.steffo.eu/lihzahrd/html/world.html).

3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`> [!Warning]`
Process unknown data 2023-03-06 01:21:06 +00:00			`>`
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`> Maliciously designed Terraria worlds can drain system resources, crash the interpreter, or possibly do other evil things!`
Process unknown data 2023-03-06 01:21:06 +00:00			`>`
3.1.1: Improve project metadata 2024-09-04 15:05:01 +00:00			`> Make sure you trust worlds before parsing them!`
Process unknown data 2023-03-06 01:21:06 +00:00
1.0b1 2019-08-13 17:56:17 +00:00			`## Documentation`

			`The documentation is available [here](https://gh.steffo.eu/lihzahrd/html/).`

Update README.md 2023-03-06 14:58:42 +00:00			`If you know something that is missing in the documentation, please let me know [with an issue](https://github.com/Steffo99/lihzahrd/issues/new)!`
1.0b1 2019-08-13 17:56:17 +00:00
Add PyPy section to the README 2020-04-17 15:24:48 +00:00			`## PyPy`

Update README.md 2023-03-06 14:58:42 +00:00			`lihzahrd` is compatible with [PyPy](https://www.pypy.org), an alternative implementation on Python!
Add PyPy section to the README 2020-04-17 15:24:48 +00:00
			`If you think that parsing a world takes too much time, you can use PyPy to reduce the required time by a factor of ~3!`

			`### Benchmarks`

			`Time to parse the same large world:`

			`- CPython took 11.45 s.`
			`- Pypy took 3.57 s!`

Optimize some more by using __slots__ 2020-06-10 11:16:43 +00:00			`### Building docs`

			You can build the docs by entering the `docs_source` folder and running `make html`, then committing the whole `docs` folder.

			`## References used`

			`- The [TEdit World Parser](https://github.com/TEdit/Terraria-Map-Editor/blob/master/TEditXna/Terraria/World.FileV2.cs), the most accurate source currently available.`
			`- The [tModLoader wiki](https://github.com/tModLoader/tModLoader/wiki), containing lists of all possible IDs.`
			`- The [Terrafirma world documentation](http://seancode.com/terrafirma/world.html), accurate for old worlds (version <69)`
			`- The [1.3.x.x world documentation](http://ludwig.schafer.free.fr/), a bit incomplete, but an useful source nevertheless.`
			`- A [JS World Parser](https://github.com/cokolele/terraria-world-parser/) on GitHub.`
			`- A [Background Guide](https://steamcommunity.com/sharedfiles/filedetails/?id=841032800) on Steam that displays all possible world backgrounds.`

Update docs 2019-08-20 14:27:02 +00:00			`## See also`

Update README.md 2023-03-07 00:45:48 +00:00			`- [flyingsnake](https://github.com/Steffo99/flyingsnake), a map renderer using this package`