<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Usage guide — lihzahrd documentation</title>
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/lihzahrd.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="API Reference" href="reference.html" />
<link rel="prev" title="lihzahrd" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> lihzahrd
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Usage guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installing">Installing</a></li>
<li class="toctree-l2"><a class="reference internal" href="#opening-a-world">Opening a world</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accessing-the-world-properties">Accessing the world properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accessing-the-tile-data">Accessing the tile data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accessing-extra-data">Accessing extra data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#something-else">Something else</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">API Reference</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">lihzahrd</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Usage guide</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/usage.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="usage-guide">
<h1>Usage guide<a class="headerlink" href="#usage-guide" title="Permalink to this headline">¶</a></h1>
<div class="section" id="prerequisites">
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
<p>To use <code class="docutils literal notranslate"><span class="pre">lihzahrd</span></code>, you need Python 3.6 or higher.</p>
<p>That’s it! No other packages are required!</p>
</div>
<div class="section" id="installing">
<h2>Installing<a class="headerlink" href="#installing" title="Permalink to this headline">¶</a></h2>
<p>You can download (or update) the package with <code class="docutils literal notranslate"><span class="pre">pip</span></code> by entering in your terminal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span><span class="o">.</span><span class="mi">8</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">upgrade</span> <span class="n">lihzahrd</span>
</pre></div>
</div>
</div>
<div class="section" id="opening-a-world">
<h2>Opening a world<a class="headerlink" href="#opening-a-world" title="Permalink to this headline">¶</a></h2>
<p>To open a Terraria world file named <code class="docutils literal notranslate"><span class="pre">terra.wld</span></code> located in the current working directory, you should import the
<code class="xref py py-mod docutils literal notranslate"><span class="pre">lihzahrd</span></code> package and then call the <a class="reference internal" href="world.html#lihzahrd.World.create_from_file" title="lihzahrd.World.create_from_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">World.create_from_file()</span></code></a> function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">lihzahrd</span>
<span class="n">world</span> <span class="o">=</span> <span class="n">lihzahrd</span><span class="o">.</span><span class="n">World</span><span class="o">.</span><span class="n">create_from_file</span><span class="p">(</span><span class="s2">"terra.wld"</span><span class="p">)</span>
</pre></div>
</div>
<p>It should take <strong>a few minutes</strong>, depending on the size of the world, and then return a
<a class="reference internal" href="world.html#lihzahrd.World" title="lihzahrd.World"><code class="xref py py-class docutils literal notranslate"><span class="pre">World</span></code></a> object.</p>
</div>
<div class="section" id="accessing-the-world-properties">
<h2>Accessing the world properties<a class="headerlink" href="#accessing-the-world-properties" title="Permalink to this headline">¶</a></h2>
<p>Most of the world properties are accessible directly as attributes of the <a class="reference internal" href="world.html#lihzahrd.World" title="lihzahrd.World"><code class="xref py py-class docutils literal notranslate"><span class="pre">World</span></code></a> object:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">name</span><span class="p">)</span>
<span class="c1"># "Terra"</span>
<span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">is_hardmode</span><span class="p">)</span>
<span class="c1"># False</span>
<span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">spawn_point</span><span class="p">)</span>
<span class="c1"># Coordinates(2101, 246)</span>
</pre></div>
</div>
<p>Some world properties may be grouped in other objects:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">bosses_defeated</span><span class="p">)</span>
<span class="c1"># <BossesDefeated></span>
<span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">bosses_defeated</span><span class="o">.</span><span class="n">eye_of_cthulhu</span><span class="p">)</span>
<span class="c1"># False</span>
</pre></div>
</div>
<p>You can look at the <a class="reference internal" href="world.html#lihzahrd.World" title="lihzahrd.World"><code class="xref py py-class docutils literal notranslate"><span class="pre">World</span></code></a> class documentation or use an IDE that supports type annotations
(such as <a class="reference external" href="https://www.jetbrains.com/pycharm/">PyCharm</a>) to find all available attributes.</p>
</div>
<div class="section" id="accessing-the-tile-data">
<h2>Accessing the tile data<a class="headerlink" href="#accessing-the-tile-data" title="Permalink to this headline">¶</a></h2>
<p>All <a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile" title="lihzahrd.tiles.Tile"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.Tile</span></code></a> are stored in the <a class="reference internal" href="tiles.html#lihzahrd.tiles.TileMatrix" title="lihzahrd.tiles.TileMatrix"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.TileMatrix</span></code></a> accessible at the <a class="reference internal" href="world.html#lihzahrd.World.tiles" title="lihzahrd.World.tiles"><code class="xref py py-attr docutils literal notranslate"><span class="pre">World.tiles</span></code></a>
attribute.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">)</span>
<span class="c1"># <TileMatrix 4200x1200></span>
</pre></div>
</div>
<p>You can access them by using the <code class="docutils literal notranslate"><span class="pre">tiles</span></code> attribute as a two-dimensional array, where (0, 0) is the top-left block:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">])</span>
<span class="c1"># <Tile></span>
</pre></div>
</div>
<p>You can also use <a class="reference internal" href="fileutils.html#lihzahrd.fileutils.Coordinates" title="lihzahrd.fileutils.Coordinates"><code class="xref py py-class docutils literal notranslate"><span class="pre">fileutils.Coordinates</span></code></a> instead of a <a class="reference external" href="https://docs.python.org/3.6/library/stdtypes.html#tuple" title="(in Python v3.6)"><code class="xref py py-class docutils literal notranslate"><span class="pre">tuple</span></code></a> to fetch a specific tile:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">[</span><span class="n">lihzahrd</span><span class="o">.</span><span class="n">fileutils</span><span class="o">.</span><span class="n">Coordinates</span><span class="p">(</span><span class="mi">2000</span><span class="p">,</span> <span class="mi">1000</span><span class="p">)])</span>
<span class="c1"># <Tile B></span>
<span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">[</span><span class="n">world</span><span class="o">.</span><span class="n">spawn_point</span><span class="p">])</span>
<span class="c1"># <Tile B></span>
</pre></div>
</div>
<p>Counting tiles from the bottom-right is possible too:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">])</span>
<span class="c1"># <Tile></span>
</pre></div>
</div>
<p>A single <a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile" title="lihzahrd.tiles.Tile"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.Tile</span></code></a> has five attributes that you can access:</p>
<ul class="simple">
<li><p><a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.block" title="lihzahrd.tiles.Tile.block"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.block</span></code></a>, the foreground <a class="reference internal" href="tiles.html#lihzahrd.tiles.Block" title="lihzahrd.tiles.Block"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.Block</span></code></a>;</p></li>
<li><p><a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.wall" title="lihzahrd.tiles.Tile.wall"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.wall</span></code></a>, the background <a class="reference internal" href="tiles.html#lihzahrd.tiles.Wall" title="lihzahrd.tiles.Wall"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.Wall</span></code></a>;</p></li>
<li><p><a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.liquid" title="lihzahrd.tiles.Tile.liquid"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.liquid</span></code></a>, the <a class="reference internal" href="tiles.html#lihzahrd.tiles.Liquid" title="lihzahrd.tiles.Liquid"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.Liquid</span></code></a> present in that tile;</p></li>
<li><p><a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.wiring" title="lihzahrd.tiles.Tile.wiring"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.wiring</span></code></a>, the colored wires and actuators (<a class="reference internal" href="tiles.html#lihzahrd.tiles.Wiring" title="lihzahrd.tiles.Wiring"><code class="xref py py-class docutils literal notranslate"><span class="pre">tiles.Wiring</span></code></a>);</p></li>
<li><p><a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.extra" title="lihzahrd.tiles.Tile.extra"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.extra</span></code></a>, additional data about the block present at that tile, such as the contents of a chest.</p></li>
</ul>
<p>All of these attributes may be <code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code> if the property isn’t applicable for the tile:
for example, <a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.block" title="lihzahrd.tiles.Tile.block"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.block</span></code></a> is <code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code> if there is no block (“air”) placed there.</p>
</div>
<div class="section" id="accessing-extra-data">
<h2>Accessing extra data<a class="headerlink" href="#accessing-extra-data" title="Permalink to this headline">¶</a></h2>
<p>Extra data, such as the content of chests or the text of signs, may be accessed in two different ways:</p>
<ul>
<li><p>Through the <a class="reference internal" href="tiles.html#lihzahrd.tiles.Tile.extra" title="lihzahrd.tiles.Tile.extra"><code class="xref py py-attr docutils literal notranslate"><span class="pre">tiles.Tile.extra</span></code></a> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">[</span><span class="mi">2893</span><span class="p">,</span> <span class="mi">1074</span><span class="p">]</span><span class="o">.</span><span class="n">extra</span><span class="p">)</span>
<span class="c1"># <Chest '' at 2893, 1074></span>
</pre></div>
</div>
</li>
<li><p>Through the various lists available in the <a class="reference internal" href="world.html#lihzahrd.World" title="lihzahrd.World"><code class="xref py py-class docutils literal notranslate"><span class="pre">World</span></code></a> class, such as <a class="reference internal" href="world.html#lihzahrd.World.chests" title="lihzahrd.World.chests"><code class="xref py py-attr docutils literal notranslate"><span class="pre">World.chests</span></code></a>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">chests</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
<span class="c1"># <Chest '' at 2893, 1074></span>
</pre></div>
</div>
</li>
</ul>
<p>Both ways return the same object, but one may be faster than the other, depending on your use case:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">world</span><span class="o">.</span><span class="n">tiles</span><span class="p">[</span><span class="mi">2893</span><span class="p">,</span> <span class="mi">1074</span><span class="p">]</span><span class="o">.</span><span class="n">extra</span> <span class="ow">is</span> <span class="n">world</span><span class="o">.</span><span class="n">chests</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
<span class="c1"># True</span>
</pre></div>
</div>
</div>
<div class="section" id="something-else">
<h2>Something else<a class="headerlink" href="#something-else" title="Permalink to this headline">¶</a></h2>
<p>All information included in a Terraria savefile is parsed in this package and made available in the <a class="reference internal" href="world.html#lihzahrd.World" title="lihzahrd.World"><code class="xref py py-class docutils literal notranslate"><span class="pre">World</span></code></a>
object.</p>
<p>If you couldn’t find what you needed in this short usage guide, check the API Reference or have a look at the
<a class="reference external" href="https://github.com/Steffo99/lihzahrd/tree/master/lihzahrd">source code</a> !</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="reference.html" class="btn btn-neutral float-right" title="API Reference" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="index.html" class="btn btn-neutral float-left" title="lihzahrd" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2020, Stefano Pigozzi
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>