diff --git a/pr-preview/pr-346/installation/changelog/index.html b/pr-preview/pr-346/installation/changelog/index.html
index fc88b806..4c1b8f03 100644
--- a/pr-preview/pr-346/installation/changelog/index.html
+++ b/pr-preview/pr-346/installation/changelog/index.html
@@ -560,13 +560,13 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exec-1--version-v050-215-g3077c-2024-10-20" class="md-nav__link">
+  <a href="#exec-1--version-v050-219-g0c674-2024-10-22" class="md-nav__link">
     <span class="md-ellipsis">
-      Version v0.5.0-215-g3077c (2024-10-20)
+      Version v0.5.0-219-g0c674 (2024-10-22)
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Version v0.5.0-215-g3077c (2024-10-20)">
+    <nav class="md-nav" aria-label="Version v0.5.0-219-g0c674 (2024-10-22)">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
@@ -1825,13 +1825,13 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#exec-1--version-v050-215-g3077c-2024-10-20" class="md-nav__link">
+  <a href="#exec-1--version-v050-219-g0c674-2024-10-22" class="md-nav__link">
     <span class="md-ellipsis">
-      Version v0.5.0-215-g3077c (2024-10-20)
+      Version v0.5.0-219-g0c674 (2024-10-22)
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="Version v0.5.0-215-g3077c (2024-10-20)">
+    <nav class="md-nav" aria-label="Version v0.5.0-219-g0c674 (2024-10-22)">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
@@ -2094,7 +2094,7 @@ <h1 id="changelog">Changelog<a class="headerlink" href="#changelog" title="Perma
 </div>
 <p><details class="example" open="open">
 <summary>Unreleased Changes</summary>
-<h2 id="exec-1--version-v050-215-g3077c-2024-10-20">Version v0.5.0-215-g3077c (2024-10-20)<a class="headerlink" href="#exec-1--version-v050-215-g3077c-2024-10-20" title="Permanent link">&para;</a></h2>
+<h2 id="exec-1--version-v050-219-g0c674-2024-10-22">Version v0.5.0-219-g0c674 (2024-10-22)<a class="headerlink" href="#exec-1--version-v050-219-g0c674-2024-10-22" title="Permanent link">&para;</a></h2>
 <h3 id="exec-1--features">Features<a class="headerlink" href="#exec-1--features" title="Permanent link">&para;</a></h3>
 <ul>
 <li><a href="https://github.com/py-mine/mcproto/issues/209">#209</a>: Added <code>InvalidPacketContentError</code> exception, raised when deserializing of a specific packet fails. This error inherits from <code>IOError</code>, making it backwards compatible with the original implementation.</li>
diff --git a/pr-preview/pr-346/objects.inv b/pr-preview/pr-346/objects.inv
index 5b51b1ed..cd32347c 100644
Binary files a/pr-preview/pr-346/objects.inv and b/pr-preview/pr-346/objects.inv differ
diff --git a/pr-preview/pr-346/reference/private/authentication/index.html b/pr-preview/pr-346/reference/private/authentication/index.html
index 1035bdaf..f1495ef1 100644
--- a/pr-preview/pr-346/reference/private/authentication/index.html
+++ b/pr-preview/pr-346/reference/private/authentication/index.html
@@ -1660,8 +1660,28 @@
 
 <h1 id="internal-components-for-authentication">Internal components for authentication<a class="headerlink" href="#internal-components-for-authentication" title="Permanent link">&para;</a></h1>
 <p>These are the utility components related to / used in the authentication module.</p>
-<!-- TODO: https://github.com/mkdocstrings/mkdocstrings/discussions/699
--->
+
+
+<div class="doc doc-object doc-module">
+
+
+
+
+    <div class="doc doc-contents first">
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
+
+
+
+
+
 
 
 
@@ -1676,7 +1696,7 @@ <h2 id="mcproto.auth.msa.MSAAccount" class="doc doc-heading">
 <a href="#mcproto.auth.msa.MSAAccount" class="headerlink" title="Permanent link">&para;</a></h2>
 
 
-    <div class="doc doc-contents first">
+    <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
               Bases: <code><a class="autorefs autorefs-internal" title="mcproto.auth.account.Account" href="../../public/authentication/#mcproto.auth.account.Account">Account</a></code></p>
 
@@ -1736,6 +1756,15 @@ <h3 id="mcproto.auth.msa.MSAAccount._get_access_token_from_xbox" class="doc doc-
 
 
 
+  </div>
+
+    </div>
+
+</div>
+
+
+
+
 
 
 
diff --git a/pr-preview/pr-346/reference/private/protocol/index.html b/pr-preview/pr-346/reference/private/protocol/index.html
index 512078ff..05c3a821 100644
--- a/pr-preview/pr-346/reference/private/protocol/index.html
+++ b/pr-preview/pr-346/reference/private/protocol/index.html
@@ -1540,6 +1540,102 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncWriter" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseAsyncWriter
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseAsyncWriter">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncWriter._write_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_write_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncWriter" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseSyncWriter
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseSyncWriter">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncWriter._write_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_write_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncReader" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseAsyncReader
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseAsyncReader">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncReader._read_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_read_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncReader" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseSyncReader
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseSyncReader">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncReader._read_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_read_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
     </ul>
@@ -1621,6 +1717,102 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncWriter" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseAsyncWriter
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseAsyncWriter">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncWriter._write_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_write_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncWriter" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseSyncWriter
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseSyncWriter">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncWriter._write_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_write_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncReader" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseAsyncReader
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseAsyncReader">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseAsyncReader._read_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_read_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncReader" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;BaseSyncReader
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" BaseSyncReader">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.protocol.base_io.BaseSyncReader._read_varuint" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_read_varuint
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
     </ul>
@@ -1766,6 +1958,330 @@ <h2 id="mcproto.protocol.utils.to_twos_complement" class="doc doc-heading">
 
 </div>
 
+<div class="doc doc-object doc-module">
+
+
+
+
+    <div class="doc doc-contents first">
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
+
+
+
+
+
+
+
+
+<div class="doc doc-object doc-class">
+
+
+
+<h2 id="mcproto.protocol.base_io.BaseAsyncWriter" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.protocol.base_io.BaseAsyncWriter</span>
+
+
+<a href="#mcproto.protocol.base_io.BaseAsyncWriter" class="headerlink" title="Permanent link">&para;</a></h2>
+
+
+    <div class="doc doc-contents ">
+            <p class="doc doc-class-bases">
+              Bases: <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
+
+
+        <p>Base class holding asynchronous write buffer/connection interactions.</p>
+
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
+
+
+
+
+
+
+
+
+
+<div class="doc doc-object doc-function">
+
+
+<h3 id="mcproto.protocol.base_io.BaseAsyncWriter._write_varuint" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mcproto.protocol.base_io.BaseAsyncWriter._write_varuint</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-async"><code>async</code></small>
+  </span>
+
+<a href="#mcproto.protocol.base_io.BaseAsyncWriter._write_varuint" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_write_varuint</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">max_bits</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Write an arbitrarily big unsigned integer in a variable length format.</p>
+<p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p>
+<p>Writing will be limited up to integer values of <code>max_bits</code> bits, and trying to write bigger values will rase
+a :exc:<code>ValueError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes
+will be sent, in this case it would actually take at most 5 bytes, due to the variable encoding overhead.</p>
+<p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation
+flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after
+this one. The least significant group is written first, followed by each of the more significant groups, making
+varints little-endian, however in groups of 7 bits, not 8.</p>
+
+    </div>
+
+</div>
+
+
+
+  </div>
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-class">
+
+
+
+<h2 id="mcproto.protocol.base_io.BaseSyncWriter" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.protocol.base_io.BaseSyncWriter</span>
+
+
+<a href="#mcproto.protocol.base_io.BaseSyncWriter" class="headerlink" title="Permanent link">&para;</a></h2>
+
+
+    <div class="doc doc-contents ">
+            <p class="doc doc-class-bases">
+              Bases: <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
+
+
+        <p>Base class holding synchronous write buffer/connection interactions.</p>
+
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
+
+
+
+
+
+
+
+
+
+<div class="doc doc-object doc-function">
+
+
+<h3 id="mcproto.protocol.base_io.BaseSyncWriter._write_varuint" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mcproto.protocol.base_io.BaseSyncWriter._write_varuint</span>
+
+
+<a href="#mcproto.protocol.base_io.BaseSyncWriter._write_varuint" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_write_varuint</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">max_bits</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Write an arbitrarily big unsigned integer in a variable length format.</p>
+<p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p>
+<p>Writing will be limited up to integer values of <code>max_bits</code> bits, and trying to write bigger values will rase
+a :exc:<code>ValueError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes
+will be sent, in this case it would actually take at most 5 bytes, due to the variable encoding overhead.</p>
+<p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation
+flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after
+this one. The least significant group is written first, followed by each of the more significant groups, making
+varints little-endian, however in groups of 7 bits, not 8.</p>
+
+    </div>
+
+</div>
+
+
+
+  </div>
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-class">
+
+
+
+<h2 id="mcproto.protocol.base_io.BaseAsyncReader" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.protocol.base_io.BaseAsyncReader</span>
+
+
+<a href="#mcproto.protocol.base_io.BaseAsyncReader" class="headerlink" title="Permanent link">&para;</a></h2>
+
+
+    <div class="doc doc-contents ">
+            <p class="doc doc-class-bases">
+              Bases: <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
+
+
+        <p>Base class holding asynchronous read buffer/connection interactions.</p>
+
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
+
+
+
+
+
+
+
+
+
+<div class="doc doc-object doc-function">
+
+
+<h3 id="mcproto.protocol.base_io.BaseAsyncReader._read_varuint" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mcproto.protocol.base_io.BaseAsyncReader._read_varuint</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-async"><code>async</code></small>
+  </span>
+
+<a href="#mcproto.protocol.base_io.BaseAsyncReader._read_varuint" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_read_varuint</span><span class="p">(</span><span class="o">*</span><span class="p">,</span> <span class="n">max_bits</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Read an arbitrarily big unsigned integer in a variable length format.</p>
+<p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p>
+<p>Reading will be limited up to integer values of <code>max_bits</code> bits, and trying to read bigger values will rase
+an :exc:<code>IOError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes
+will be read, in this case we would actually read at most 5 bytes, due to the variable encoding overhead.</p>
+<p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation
+flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after
+this one. The least significant group is written first, followed by each of the more significant groups, making
+varints little-endian, however in groups of 7 bits, not 8.</p>
+
+    </div>
+
+</div>
+
+
+
+  </div>
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-class">
+
+
+
+<h2 id="mcproto.protocol.base_io.BaseSyncReader" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.protocol.base_io.BaseSyncReader</span>
+
+
+<a href="#mcproto.protocol.base_io.BaseSyncReader" class="headerlink" title="Permanent link">&para;</a></h2>
+
+
+    <div class="doc doc-contents ">
+            <p class="doc doc-class-bases">
+              Bases: <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
+
+
+        <p>Base class holding synchronous read buffer/connection interactions.</p>
+
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
+
+
+
+
+
+
+
+
+
+<div class="doc doc-object doc-function">
+
+
+<h3 id="mcproto.protocol.base_io.BaseSyncReader._read_varuint" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mcproto.protocol.base_io.BaseSyncReader._read_varuint</span>
+
+
+<a href="#mcproto.protocol.base_io.BaseSyncReader._read_varuint" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_read_varuint</span><span class="p">(</span><span class="o">*</span><span class="p">,</span> <span class="n">max_bits</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+
+        <p>Read an arbitrarily big unsigned integer in a variable length format.</p>
+<p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p>
+<p>Reading will be limited up to integer values of <code>max_bits</code> bits, and trying to read bigger values will rase
+an :exc:<code>IOError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes
+will be read, in this case we would actually read at most 5 bytes, due to the variable encoding overhead.</p>
+<p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation
+flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after
+this one. The least significant group is written first, followed by each of the more significant groups, making
+varints little-endian, however in groups of 7 bits, not 8.</p>
+
+    </div>
+
+</div>
+
+
+
+  </div>
+
+    </div>
+
+</div>
+
+
+
+
+  </div>
+
+    </div>
+
+</div>
+
 
 
 
diff --git a/pr-preview/pr-346/reference/private/types/index.html b/pr-preview/pr-346/reference/private/types/index.html
index d4eb8cd5..f02840f1 100644
--- a/pr-preview/pr-346/reference/private/types/index.html
+++ b/pr-preview/pr-346/reference/private/types/index.html
@@ -1544,21 +1544,102 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#mcproto.types.nbt._FloatingNBTag" class="md-nav__link">
+  <a href="#mcproto.types.nbt.NBTag" class="md-nav__link">
     <span class="md-ellipsis">
-      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_FloatingNBTag
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;NBTag
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" NBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_read_header
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _read_header">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header(buf)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;buf
     </span>
   </a>
   
 </li>
-      
-        <li class="md-nav__item">
-  <a href="#mcproto.types.nbt._NumberArrayNBTag" class="md-nav__link">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header(read_type)" class="md-nav__link">
     <span class="md-ellipsis">
-      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_NumberArrayNBTag
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;read_type
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header(with_name)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;with_name
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_write_header
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _write_header">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header(buf)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;buf
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header(with_type)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;with_type
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header(with_name)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;with_name
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -1568,15 +1649,69 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label=" _NumberNBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._NumberNBTag.payload" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;payload
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._FloatingNBTag" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_FloatingNBTag
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _FloatingNBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._FloatingNBTag.payload" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;payload
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
-  <a href="#mcproto.types.nbt._get_tag_type" class="md-nav__link">
+  <a href="#mcproto.types.nbt._NumberArrayNBTag" class="md-nav__link">
     <span class="md-ellipsis">
-      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;_get_tag_type
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_NumberArrayNBTag
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _NumberArrayNBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._NumberArrayNBTag.payload" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;payload
     </span>
   </a>
   
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
     </ul>
@@ -1622,21 +1757,102 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#mcproto.types.nbt._FloatingNBTag" class="md-nav__link">
+  <a href="#mcproto.types.nbt.NBTag" class="md-nav__link">
     <span class="md-ellipsis">
-      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_FloatingNBTag
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;NBTag
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" NBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_read_header
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _read_header">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header(buf)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;buf
     </span>
   </a>
   
 </li>
-      
-        <li class="md-nav__item">
-  <a href="#mcproto.types.nbt._NumberArrayNBTag" class="md-nav__link">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header(read_type)" class="md-nav__link">
     <span class="md-ellipsis">
-      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_NumberArrayNBTag
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;read_type
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._read_header(with_name)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;with_name
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-method"></code>&nbsp;_write_header
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _write_header">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header(buf)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;buf
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header(with_type)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;with_type
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt.NBTag._write_header(with_name)" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;with_name
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -1646,15 +1862,69 @@
     </span>
   </a>
   
+    <nav class="md-nav" aria-label=" _NumberNBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._NumberNBTag.payload" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;payload
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
-  <a href="#mcproto.types.nbt._get_tag_type" class="md-nav__link">
+  <a href="#mcproto.types.nbt._FloatingNBTag" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_FloatingNBTag
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _FloatingNBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._FloatingNBTag.payload" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;payload
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._NumberArrayNBTag" class="md-nav__link">
     <span class="md-ellipsis">
-      <code class="doc-symbol doc-symbol-toc doc-symbol-function"></code>&nbsp;_get_tag_type
+      <code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;_NumberArrayNBTag
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label=" _NumberArrayNBTag">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#mcproto.types.nbt._NumberArrayNBTag.payload" class="md-nav__link">
+    <span class="md-ellipsis">
+      <code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;payload
     </span>
   </a>
   
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
     </ul>
@@ -1684,21 +1954,27 @@ <h1 id="internal-components-for-types">Internal components for types<a class="he
 <p>These are the utility components related to / used in the types module.</p>
 
 
-<div class="doc doc-object doc-module">
-
+<div class="doc doc-object doc-class">
 
 
 
-    <div class="doc doc-contents first">
+<h2 id="mcproto.types.nbt.NBTag" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt.NBTag</span>
 
 
+<a href="#mcproto.types.nbt.NBTag" class="headerlink" title="Permanent link">&para;</a></h2>
 
 
+    <div class="doc doc-contents first">
+            <p class="doc doc-class-bases">
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.abc.MCType" href="../../public/types/#mcproto.types.abc.MCType">MCType</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTagConvertible" href="../../public/types/#mcproto.types.nbt.NBTagConvertible">NBTagConvertible</a></code></p>
 
 
+        <p>Base class for NBT tags.</p>
+<p>In MC v1.20.2+ the type and name of the root tag is not written to the buffer, and unless specified,
+the type of the tag is assumed to be TAG_Compound.</p>
 
 
-  <div class="doc doc-children">
 
 
 
@@ -1706,42 +1982,206 @@ <h1 id="internal-components-for-types">Internal components for types<a class="he
 
 
 
+  <div class="doc doc-children">
 
-<div class="doc doc-object doc-class">
 
 
 
-<h2 id="mcproto.types.nbt._FloatingNBTag" class="doc doc-heading">
-<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt._FloatingNBTag</span>
 
 
-<a href="#mcproto.types.nbt._FloatingNBTag" class="headerlink" title="Permanent link">&para;</a></h2>
 
 
-    <div class="doc doc-contents ">
-            <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../public/types/#mcproto.types.nbt.NBTag">NBTag</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.utils.abc.RequiredParamsABCMixin" href="../abc/#mcproto.utils.abc.RequiredParamsABCMixin">RequiredParamsABCMixin</a></code></p>
 
+<div class="doc doc-object doc-function">
 
-        <p>Base class for NBT tags representing a floating-point number.</p>
 
+<h3 id="mcproto.types.nbt.NBTag._read_header" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mcproto.types.nbt.NBTag._read_header</span>
 
 
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-classmethod"><code>classmethod</code></small>
+  </span>
 
+<a href="#mcproto.types.nbt.NBTag._read_header" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_read_header</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag._read_header(buf)">buf</a></span><span class="p">:</span> <span class="n"><span title="mcproto.buffer.Buffer">Buffer</span></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag._read_header(read_type)">read_type</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag._read_header(with_name)">with_name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#tuple">tuple</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTagType" href="../../public/types/#mcproto.types.nbt.NBTagType">NBTagType</a></span><span class="p">]</span>
+</code></pre></div>
 
+    <div class="doc doc-contents ">
 
+        <p>Read the header of the NBT tag.</p>
+
+
+<p><span class="doc-section-title">Parameters:</span></p>
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Type</th>
+          <th>Description</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+          <tr class="doc-section-item">
+            <td>
+<h4 id="mcproto.types.nbt.NBTag._read_header(buf)" class="doc doc-heading doc-heading-parameter">                  <code>buf</code>
+<a href="#mcproto.types.nbt.NBTag._read_header(buf)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
+            <td>
+                  <code><span title="mcproto.buffer.Buffer">Buffer</span></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>The buffer to read from.</p>
+              </div>
+            </td>
+            <td>
+                <em>required</em>
+            </td>
+          </tr>
+          <tr class="doc-section-item">
+            <td>
+<h4 id="mcproto.types.nbt.NBTag._read_header(read_type)" class="doc doc-heading doc-heading-parameter">                  <code>read_type</code>
+<a href="#mcproto.types.nbt.NBTag._read_header(read_type)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>Whether to read the type of the tag from the buffer. * If <code>True</code>, the tag type will be read from the buffer * If <code>False</code> and called from a subclass, the tag type will be inferred from the subclass. * If <code>False</code> and called from the base class, the tag type will be TAG_Compound.</p>
+              </div>
+            </td>
+            <td>
+                  <code>True</code>
+            </td>
+          </tr>
+          <tr class="doc-section-item">
+            <td>
+<h4 id="mcproto.types.nbt.NBTag._read_header(with_name)" class="doc doc-heading doc-heading-parameter">                  <code>with_name</code>
+<a href="#mcproto.types.nbt.NBTag._read_header(with_name)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>Whether to read the name of the tag. If set to <code>False</code>, the tag will have the name <code>""</code>.</p>
+              </div>
+            </td>
+            <td>
+                  <code>True</code>
+            </td>
+          </tr>
+      </tbody>
+    </table>
+
+
+    <p><span class="doc-section-title">Returns:</span></p>
+    <table>
+      <thead>
+        <tr>
+          <th>Type</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+          <tr class="doc-section-item">
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#tuple">tuple</a>[<a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a>, <a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTagType" href="../../public/types/#mcproto.types.nbt.NBTagType">NBTagType</a>]</code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>A tuple containing the name and the tag type.  .. note:: It is possible that this function reads nothing from the buffer if both <code>with_name</code> and <code>read_type</code> are set to <code>False</code>.</p>
+              </div>
+            </td>
+          </tr>
+      </tbody>
+    </table>
 
+    </div>
 
+</div>
 
-  <div class="doc doc-children">
+<div class="doc doc-object doc-function">
 
 
+<h3 id="mcproto.types.nbt.NBTag._write_header" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-method"></code>            <span class="doc doc-object-name doc-function-name">mcproto.types.nbt.NBTag._write_header</span>
 
 
+<a href="#mcproto.types.nbt.NBTag._write_header" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_write_header</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag._write_header(buf)">buf</a></span><span class="p">:</span> <span class="n"><span title="mcproto.buffer.Buffer">Buffer</span></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag._write_header(with_type)">with_type</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag._write_header(with_name)">with_name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+</code></pre></div>
 
+    <div class="doc doc-contents ">
 
+        <p>Write the header of the NBT tag to the buffer.</p>
+
+
+<p><span class="doc-section-title">Parameters:</span></p>
+    <table>
+      <thead>
+        <tr>
+          <th>Name</th>
+          <th>Type</th>
+          <th>Description</th>
+          <th>Default</th>
+        </tr>
+      </thead>
+      <tbody>
+          <tr class="doc-section-item">
+            <td>
+<h4 id="mcproto.types.nbt.NBTag._write_header(buf)" class="doc doc-heading doc-heading-parameter">                  <code>buf</code>
+<a href="#mcproto.types.nbt.NBTag._write_header(buf)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
+            <td>
+                  <code><span title="mcproto.buffer.Buffer">Buffer</span></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>The buffer to write to.</p>
+              </div>
+            </td>
+            <td>
+                <em>required</em>
+            </td>
+          </tr>
+          <tr class="doc-section-item">
+            <td>
+<h4 id="mcproto.types.nbt.NBTag._write_header(with_type)" class="doc doc-heading doc-heading-parameter">                  <code>with_type</code>
+<a href="#mcproto.types.nbt.NBTag._write_header(with_type)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>Whether to include the type of the tag in the serialization.</p>
+              </div>
+            </td>
+            <td>
+                  <code>True</code>
+            </td>
+          </tr>
+          <tr class="doc-section-item">
+            <td>
+<h4 id="mcproto.types.nbt.NBTag._write_header(with_name)" class="doc doc-heading doc-heading-parameter">                  <code>with_name</code>
+<a href="#mcproto.types.nbt.NBTag._write_header(with_name)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>Whether to include the name of the tag in the serialization.</p>
+              </div>
+            </td>
+            <td>
+                  <code>True</code>
+            </td>
+          </tr>
+      </tbody>
+    </table>
 
+    </div>
 
+</div>
 
 
 
@@ -1755,19 +2195,20 @@ <h2 id="mcproto.types.nbt._FloatingNBTag" class="doc doc-heading">
 
 
 
-<h2 id="mcproto.types.nbt._NumberArrayNBTag" class="doc doc-heading">
-<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt._NumberArrayNBTag</span>
+<h2 id="mcproto.types.nbt._NumberNBTag" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt._NumberNBTag</span>
 
 
-<a href="#mcproto.types.nbt._NumberArrayNBTag" class="headerlink" title="Permanent link">&para;</a></h2>
+<a href="#mcproto.types.nbt._NumberNBTag" class="headerlink" title="Permanent link">&para;</a></h2>
 
 
-    <div class="doc doc-contents ">
+    <div class="doc doc-contents first">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../public/types/#mcproto.types.nbt.NBTag">NBTag</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.utils.abc.RequiredParamsABCMixin" href="../abc/#mcproto.utils.abc.RequiredParamsABCMixin">RequiredParamsABCMixin</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.utils.abc.RequiredParamsABCMixin" href="../abc/#mcproto.utils.abc.RequiredParamsABCMixin">RequiredParamsABCMixin</a></code></p>
 
 
-        <p>Base class for NBT tags representing an array of numbers.</p>
+        <p>Base class for NBT tags representing a number.</p>
+<p>This class is not meant to be used directly, but rather through its subclasses.</p>
 
 
 
@@ -1785,6 +2226,27 @@ <h2 id="mcproto.types.nbt._NumberArrayNBTag" class="doc doc-heading">
 
 
 
+<div class="doc doc-object doc-attribute">
+
+
+
+<h3 id="mcproto.types.nbt._NumberNBTag.payload" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">mcproto.types.nbt._NumberNBTag.payload</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
+  </span>
+
+<a href="#mcproto.types.nbt._NumberNBTag.payload" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">payload</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+    </div>
+
+</div>
+
 
 
 
@@ -1799,20 +2261,19 @@ <h2 id="mcproto.types.nbt._NumberArrayNBTag" class="doc doc-heading">
 
 
 
-<h2 id="mcproto.types.nbt._NumberNBTag" class="doc doc-heading">
-<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt._NumberNBTag</span>
+<h2 id="mcproto.types.nbt._FloatingNBTag" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt._FloatingNBTag</span>
 
 
-<a href="#mcproto.types.nbt._NumberNBTag" class="headerlink" title="Permanent link">&para;</a></h2>
+<a href="#mcproto.types.nbt._FloatingNBTag" class="headerlink" title="Permanent link">&para;</a></h2>
 
 
-    <div class="doc doc-contents ">
+    <div class="doc doc-contents first">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../public/types/#mcproto.types.nbt.NBTag">NBTag</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.utils.abc.RequiredParamsABCMixin" href="../abc/#mcproto.utils.abc.RequiredParamsABCMixin">RequiredParamsABCMixin</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.utils.abc.RequiredParamsABCMixin" href="../abc/#mcproto.utils.abc.RequiredParamsABCMixin">RequiredParamsABCMixin</a></code></p>
 
 
-        <p>Base class for NBT tags representing a number.</p>
-<p>This class is not meant to be used directly, but rather through its subclasses.</p>
+        <p>Base class for NBT tags representing a floating-point number.</p>
 
 
 
@@ -1830,6 +2291,27 @@ <h2 id="mcproto.types.nbt._NumberNBTag" class="doc doc-heading">
 
 
 
+<div class="doc doc-object doc-attribute">
+
+
+
+<h3 id="mcproto.types.nbt._FloatingNBTag.payload" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">mcproto.types.nbt._FloatingNBTag.payload</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
+  </span>
+
+<a href="#mcproto.types.nbt._FloatingNBTag.payload" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">payload</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#float">float</a></span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
+    </div>
+
+</div>
+
 
 
 
@@ -1840,28 +2322,65 @@ <h2 id="mcproto.types.nbt._NumberNBTag" class="doc doc-heading">
 
 </div>
 
+<div class="doc doc-object doc-class">
 
-<div class="doc doc-object doc-function">
 
 
-<h2 id="mcproto.types.nbt._get_tag_type" class="doc doc-heading">
-<code class="doc-symbol doc-symbol-heading doc-symbol-function"></code>            <span class="doc doc-object-name doc-function-name">mcproto.types.nbt._get_tag_type</span>
+<h2 id="mcproto.types.nbt._NumberArrayNBTag" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-class"></code>            <span class="doc doc-object-name doc-class-name">mcproto.types.nbt._NumberArrayNBTag</span>
 
 
-<a href="#mcproto.types.nbt._get_tag_type" class="headerlink" title="Permanent link">&para;</a></h2>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">_get_tag_type</span><span class="p">(</span><span class="n">tag</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../public/types/#mcproto.types.nbt.NBTag">NBTag</a></span> <span class="o">|</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/glossary.html#term-type">type</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../public/types/#mcproto.types.nbt.NBTag">NBTag</a></span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTagType" href="../../public/types/#mcproto.types.nbt.NBTagType">NBTagType</a></span>
-</code></pre></div>
+<a href="#mcproto.types.nbt._NumberArrayNBTag" class="headerlink" title="Permanent link">&para;</a></h2>
 
-    <div class="doc doc-contents ">
 
-        <p>Get the tag type of an NBTag object or class.</p>
+    <div class="doc doc-contents first">
+            <p class="doc doc-class-bases">
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.utils.abc.RequiredParamsABCMixin" href="../abc/#mcproto.utils.abc.RequiredParamsABCMixin">RequiredParamsABCMixin</a></code></p>
+
+
+        <p>Base class for NBT tags representing an array of numbers.</p>
+
+
+
+
+
+
+
+
+
+  <div class="doc doc-children">
 
+
+
+
+
+
+
+<div class="doc doc-object doc-attribute">
+
+
+
+<h3 id="mcproto.types.nbt._NumberArrayNBTag.payload" class="doc doc-heading">
+<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>            <span class="doc doc-object-name doc-attribute-name">mcproto.types.nbt._NumberArrayNBTag.payload</span>
+
+
+  <span class="doc doc-labels">
+      <small class="doc doc-label doc-label-instance-attribute"><code>instance-attribute</code></small>
+  </span>
+
+<a href="#mcproto.types.nbt._NumberArrayNBTag.payload" class="headerlink" title="Permanent link">&para;</a></h3>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">payload</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/glossary.html#term-list">list</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">]</span>
+</code></pre></div>
+
+    <div class="doc doc-contents ">
     </div>
 
 </div>
 
 
 
+
+
   </div>
 
     </div>
diff --git a/pr-preview/pr-346/reference/public/packets/index.html b/pr-preview/pr-346/reference/public/packets/index.html
index 893e0739..633bca10 100644
--- a/pr-preview/pr-346/reference/public/packets/index.html
+++ b/pr-preview/pr-346/reference/public/packets/index.html
@@ -3250,7 +3250,7 @@ <h3 id="mcproto.packets.async_read_packet" class="doc doc-heading">
   </span>
 
 <a href="#mcproto.packets.async_read_packet" class="headerlink" title="Permanent link">&para;</a></h3>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">async_read_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_read_packet(reader)">reader</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncReader" href="../protocol/#mcproto.protocol.base_io.BaseAsyncReader">BaseAsyncReader</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_read_packet(packet_map)">packet_map</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Mapping" href="https://docs.python.org/3.13/library/collections.abc.html#collections.abc.Mapping">Mapping</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/glossary.html#term-type">type</a></span><span class="p">[</span><span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span><span class="p">]],</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_read_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">async_read_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_read_packet(reader)">reader</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseAsyncReader">BaseAsyncReader</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_read_packet(packet_map)">packet_map</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Mapping" href="https://docs.python.org/3.13/library/collections.abc.html#collections.abc.Mapping">Mapping</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/glossary.html#term-type">type</a></span><span class="p">[</span><span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span><span class="p">]],</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_read_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -3274,7 +3274,7 @@ <h3 id="mcproto.packets.async_read_packet" class="doc doc-heading">
 <h4 id="mcproto.packets.async_read_packet(reader)" class="doc doc-heading doc-heading-parameter">                  <code>reader</code>
 <a href="#mcproto.packets.async_read_packet(reader)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncReader" href="../protocol/#mcproto.protocol.base_io.BaseAsyncReader">BaseAsyncReader</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseAsyncReader">BaseAsyncReader</a></code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -3336,7 +3336,7 @@ <h3 id="mcproto.packets.async_write_packet" class="doc doc-heading">
   </span>
 
 <a href="#mcproto.packets.async_write_packet" class="headerlink" title="Permanent link">&para;</a></h3>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">async_write_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_write_packet(writer)">writer</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncWriter" href="../protocol/#mcproto.protocol.base_io.BaseAsyncWriter">BaseAsyncWriter</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_write_packet(packet)">packet</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.packets.packet.Packet" href="#mcproto.packets.Packet">Packet</a></span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_write_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">async_write_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_write_packet(writer)">writer</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseAsyncWriter">BaseAsyncWriter</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_write_packet(packet)">packet</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.packets.packet.Packet" href="#mcproto.packets.Packet">Packet</a></span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.async_write_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -3360,7 +3360,7 @@ <h3 id="mcproto.packets.async_write_packet" class="doc doc-heading">
 <h4 id="mcproto.packets.async_write_packet(writer)" class="doc doc-heading doc-heading-parameter">                  <code>writer</code>
 <a href="#mcproto.packets.async_write_packet(writer)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncWriter" href="../protocol/#mcproto.protocol.base_io.BaseAsyncWriter">BaseAsyncWriter</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseAsyncWriter">BaseAsyncWriter</a></code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -3451,7 +3451,7 @@ <h3 id="mcproto.packets.sync_read_packet" class="doc doc-heading">
 
 
 <a href="#mcproto.packets.sync_read_packet" class="headerlink" title="Permanent link">&para;</a></h3>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">sync_read_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_read_packet(reader)">reader</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="../protocol/#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_read_packet(packet_map)">packet_map</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Mapping" href="https://docs.python.org/3.13/library/collections.abc.html#collections.abc.Mapping">Mapping</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/glossary.html#term-type">type</a></span><span class="p">[</span><span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span><span class="p">]],</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_read_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">sync_read_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_read_packet(reader)">reader</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_read_packet(packet_map)">packet_map</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" title="collections.abc.Mapping" href="https://docs.python.org/3.13/library/collections.abc.html#collections.abc.Mapping">Mapping</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/glossary.html#term-type">type</a></span><span class="p">[</span><span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span><span class="p">]],</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_read_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="mcproto.packets.interactions.T_Packet">T_Packet</span></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -3475,7 +3475,7 @@ <h3 id="mcproto.packets.sync_read_packet" class="doc doc-heading">
 <h4 id="mcproto.packets.sync_read_packet(reader)" class="doc doc-heading doc-heading-parameter">                  <code>reader</code>
 <a href="#mcproto.packets.sync_read_packet(reader)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="../protocol/#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -3533,7 +3533,7 @@ <h3 id="mcproto.packets.sync_write_packet" class="doc doc-heading">
 
 
 <a href="#mcproto.packets.sync_write_packet" class="headerlink" title="Permanent link">&para;</a></h3>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">sync_write_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_write_packet(writer)">writer</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="../protocol/#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_write_packet(packet)">packet</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.packets.packet.Packet" href="#mcproto.packets.Packet">Packet</a></span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_write_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">sync_write_packet</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_write_packet(writer)">writer</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_write_packet(packet)">packet</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.packets.packet.Packet" href="#mcproto.packets.Packet">Packet</a></span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.packets.sync_write_packet(compression_threshold)">compression_threshold</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#int">int</a></span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -3557,7 +3557,7 @@ <h3 id="mcproto.packets.sync_write_packet" class="doc doc-heading">
 <h4 id="mcproto.packets.sync_write_packet(writer)" class="doc doc-heading doc-heading-parameter">                  <code>writer</code>
 <a href="#mcproto.packets.sync_write_packet(writer)" class="headerlink" title="Permanent link">&para;</a></h4>            </td>
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="../protocol/#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></code>
             </td>
             <td>
               <div class="doc-md-description">
diff --git a/pr-preview/pr-346/reference/public/protocol/index.html b/pr-preview/pr-346/reference/public/protocol/index.html
index 93f0a0d5..2f193007 100644
--- a/pr-preview/pr-346/reference/public/protocol/index.html
+++ b/pr-preview/pr-346/reference/public/protocol/index.html
@@ -4165,7 +4165,7 @@ <h2 id="mcproto.protocol.base_io.StructFormat" class="doc doc-heading">
 
     <div class="doc doc-contents first">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></code>, <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#bytearray">bytearray</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></code>, <code><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#bytearray">bytearray</a></code></p>
 
 
         <p>In-memory bytearray-like buffer supporting the common read/write operations.</p>
@@ -4417,7 +4417,7 @@ <h2 id="mcproto.connection.AsyncConnection" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncReader" href="#mcproto.protocol.base_io.BaseAsyncReader">BaseAsyncReader</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncWriter" href="#mcproto.protocol.base_io.BaseAsyncWriter">BaseAsyncWriter</a></code>, <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseAsyncReader">BaseAsyncReader</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseAsyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseAsyncWriter">BaseAsyncWriter</a></code>, <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
 
 
         <p>Base class for all classes handling asynchronous connections.</p>
@@ -4691,7 +4691,7 @@ <h2 id="mcproto.connection.SyncConnection" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></code>, <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncReader" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncReader">BaseSyncReader</a></code>, <code><a class="autorefs autorefs-internal" title="mcproto.protocol.base_io.BaseSyncWriter" href="../../private/protocol/#mcproto.protocol.base_io.BaseSyncWriter">BaseSyncWriter</a></code>, <code><a class="autorefs autorefs-external" title="abc.ABC" href="https://docs.python.org/3.13/library/abc.html#abc.ABC">ABC</a></code></p>
 
 
         <p>Base class for all classes handling synchronous connections.</p>
diff --git a/pr-preview/pr-346/reference/public/types/index.html b/pr-preview/pr-346/reference/public/types/index.html
index 96c1f314..5b6e66e6 100644
--- a/pr-preview/pr-346/reference/public/types/index.html
+++ b/pr-preview/pr-346/reference/public/types/index.html
@@ -3532,7 +3532,7 @@ <h3 id="mcproto.types.nbt.ByteArrayNBT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code></p>
 
 
         <p>NBT tag representing an array of bytes. The length of the array is stored as a signed 32-bit integer.</p>
@@ -3639,7 +3639,7 @@ <h3 id="mcproto.types.nbt.CompoundNBT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code></p>
 
 
         <p>NBT tag representing a compound of named tags.</p>
@@ -3819,7 +3819,7 @@ <h3 id="mcproto.types.nbt.EndNBT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code></p>
 
 
         <p>Sentinel tag used to mark the end of a TAG_Compound.</p>
@@ -3995,7 +3995,7 @@ <h3 id="mcproto.types.nbt.ListNBT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code></p>
 
 
         <p>NBT tag representing a list of tags. All tags in the list must be of the same type.</p>
@@ -4026,7 +4026,7 @@ <h4 id="mcproto.types.nbt.ListNBT.__iter__" class="doc doc-heading">
 
 
 <a href="#mcproto.types.nbt.ListNBT.__iter__" class="headerlink" title="Permanent link">&para;</a></h4>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="fm">__iter__</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nf"><a class="autorefs autorefs-external" title="collections.abc.Iterator" href="https://docs.python.org/3.13/library/collections.abc.html#collections.abc.Iterator">Iterator</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></span><span class="p">]</span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="fm">__iter__</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="nf"><a class="autorefs autorefs-external" title="collections.abc.Iterator" href="https://docs.python.org/3.13/library/collections.abc.html#collections.abc.Iterator">Iterator</a></span><span class="p">[</span><span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></span><span class="p">]</span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -4207,7 +4207,7 @@ <h4 id="mcproto.types.nbt.NBTag.deserialize" class="doc doc-heading">
   </span>
 
 <a href="#mcproto.types.nbt.NBTag.deserialize" class="headerlink" title="Permanent link">&para;</a></h4>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">deserialize</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.deserialize(buf)">buf</a></span><span class="p">:</span> <span class="n"><span title="mcproto.buffer.Buffer">Buffer</span></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.deserialize(with_name)">with_name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.deserialize(with_type)">with_type</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">deserialize</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.deserialize(buf)">buf</a></span><span class="p">:</span> <span class="n"><span title="mcproto.buffer.Buffer">Buffer</span></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.deserialize(with_name)">with_name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.deserialize(with_type)">with_type</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -4289,7 +4289,7 @@ <h5 id="mcproto.types.nbt.NBTag.deserialize(with_type)" class="doc doc-heading d
       <tbody>
           <tr class="doc-section-item">
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -4316,7 +4316,7 @@ <h4 id="mcproto.types.nbt.NBTag.from_object" class="doc doc-heading">
   </span>
 
 <a href="#mcproto.types.nbt.NBTag.from_object" class="headerlink" title="Permanent link">&para;</a></h4>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">from_object</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.from_object(data)">data</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.FromObjectType" href="#mcproto.types.nbt.FromObjectType">FromObjectType</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.from_object(schema)">schema</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.FromObjectSchema" href="#mcproto.types.nbt.FromObjectSchema">FromObjectSchema</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.from_object(name)">name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">from_object</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.from_object(data)">data</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.FromObjectType" href="#mcproto.types.nbt.FromObjectType">FromObjectType</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.from_object(schema)">schema</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.FromObjectSchema" href="#mcproto.types.nbt.FromObjectSchema">FromObjectSchema</a></span><span class="p">,</span> <span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTag.from_object(name)">name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -4398,7 +4398,7 @@ <h5 id="mcproto.types.nbt.NBTag.from_object(name)" class="doc doc-heading doc-he
       <tbody>
           <tr class="doc-section-item">
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -4426,7 +4426,7 @@ <h4 id="mcproto.types.nbt.NBTag.read_from" class="doc doc-heading">
   </span>
 
 <a href="#mcproto.types.nbt.NBTag.read_from" class="headerlink" title="Permanent link">&para;</a></h4>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">read_from</span><span class="p">(</span><span class="n">buf</span><span class="p">:</span> <span class="n"><span title="mcproto.buffer.Buffer">Buffer</span></span><span class="p">,</span> <span class="n">with_type</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n">with_name</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">read_from</span><span class="p">(</span><span class="n">buf</span><span class="p">:</span> <span class="n"><span title="mcproto.buffer.Buffer">Buffer</span></span><span class="p">,</span> <span class="n">with_type</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span> <span class="n">with_name</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/functions.html#bool">bool</a></span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -4622,7 +4622,7 @@ <h4 id="mcproto.types.nbt.NBTag.to_nbt" class="doc doc-heading">
 
 
 <a href="#mcproto.types.nbt.NBTag.to_nbt" class="headerlink" title="Permanent link">&para;</a></h4>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">to_nbt</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">to_nbt</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -4775,7 +4775,7 @@ <h4 id="mcproto.types.nbt.NBTagConvertible.to_nbt" class="doc doc-heading">
 
 
 <a href="#mcproto.types.nbt.NBTagConvertible.to_nbt" class="headerlink" title="Permanent link">&para;</a></h4>
-<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">to_nbt</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTagConvertible.to_nbt(name)">name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></span>
+<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">to_nbt</span><span class="p">(</span><span class="n"><a class="autorefs autorefs-internal" href="#mcproto.types.nbt.NBTagConvertible.to_nbt(name)">name</a></span><span class="p">:</span> <span class="n"><a class="autorefs autorefs-external" href="https://docs.python.org/3.13/library/stdtypes.html#str">str</a></span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></span>
 </code></pre></div>
 
     <div class="doc doc-contents ">
@@ -4825,7 +4825,7 @@ <h5 id="mcproto.types.nbt.NBTagConvertible.to_nbt(name)" class="doc doc-heading
       <tbody>
           <tr class="doc-section-item">
             <td>
-                  <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code>
+                  <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code>
             </td>
             <td>
               <div class="doc-md-description">
@@ -5274,7 +5274,7 @@ <h3 id="mcproto.types.nbt.StringNBT" class="doc doc-heading">
 
     <div class="doc doc-contents ">
             <p class="doc doc-class-bases">
-              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="#mcproto.types.nbt.NBTag">NBTag</a></code></p>
+              Bases: <code><a class="autorefs autorefs-internal" title="mcproto.types.nbt.NBTag" href="../../private/types/#mcproto.types.nbt.NBTag">NBTag</a></code></p>
 
 
         <p>NBT tag representing an UTF-8 string value. The length of the string is stored as a signed 16-bit integer.</p>
diff --git a/pr-preview/pr-346/search/search_index.json b/pr-preview/pr-346/search/search_index.json
index fff067ce..c066482a 100644
--- a/pr-preview/pr-346/search/search_index.json
+++ b/pr-preview/pr-346/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"MCPROTO"},{"location":"#what-is-mcproto","title":"What is Mcproto","text":"<p>Mcproto is a python library that provides various low level interactions with the Minecraft protocol. It attempts to be a full wrapper around the Minecraft protocol, which means it could be used as a basis for Minecraft bots written in python, or even full python server implementations.</p> <p>Warning</p> <p>This library is still heavily Work-In-Progress, which means a lot of things can still change and some features may be missing or incomplete. Using the library for production applications at it's current state isn't recommended.</p>"},{"location":"community/attribution/","title":"Attribution","text":"<p>This document serves as a way to explicitly give credit to projects which made mcproto possible.</p> <p>Note that as with any other project, if there was some code that was directly utilized from these projects, it will be mentioned in <code>LICENSE-THIRD-PARTY.txt</code>, not in here. This file isn't meant to serve as a place to disclose used code and it's licenses, but rather to give proper credit where it is due, and to shout out a few amazing projects that allowed mcproto to exist in the first place.</p> <ul> <li>wiki.vg (https://wiki.vg): An absolutely amazing community driven wiki that documents how the minecraft protocol is   structured and the changes that occur between the protocol versions.</li> <li>PyMine-Net: The project that was the main inspiration to this project, being a separation of the minecraft   networking tooling used in PyMine-Server, which is an attempt at implementing a fully working minecraft server purely   in python. However, this project is no longer maintained, and so mcproto was created to be it's replacement.</li> <li>Mcstatus: A library that allows for easy fetching of status/query data from minecraft servers, including parsers and   structures that meaningfully represent the obtained data, but also the logic on how it's actually obtained, some of   which this project took heavy inspiration from.</li> <li>pyCraft: A long abandoned project similar to mcproto, which served as an inspiration for various functionalities in   the library.</li> <li>quarry: A library providing support for basic interactions with the minecraft protocol, though only up to packet reading.   Implementation for reading data from specific packets is not included.</li> </ul> <p>To all of these projects, they deserve a massive thank you, for keeping their code/information open-sourced and available as a source of information, and inspiration freely to anyone.</p>"},{"location":"community/code-of-conduct/","title":"Code of Conduct","text":"<p>This code of conduct outlines our expectations for the people involved with this project. We, as members, contributors and leaders are committed to providing a welcoming and inspiring project that anyone can easily join, expecting a harassment-free experience, as described in this code of conduct.</p> <p>This code of conduct is here to ensure we provide a welcoming and inspiring project that anyone can easily join, expecting a harassment-free experience, as described in this code of conduct.</p> <p>The goal of this document is to set the overall tone for our community. It is here to outline some of the things you can and can't do if you wish to participate in our community. However it is not here to serve as a rule-book with a complete set of things you can't do, social conduct differs from situation to situation, and person to person, but we should do our best to try and provide a good experience to everyone, in every situation.</p> <p>We value many things beyond just technical expertise, including collaboration and supporting others within our community. Providing a positive experience for others can have a much more significant impact than simply providing the correct answer.</p>"},{"location":"community/code-of-conduct/#harassment","title":"Harassment","text":"<p>We share a common understanding of what constitutes harassment as it applies to a professional setting. Although this list cannot be exhaustive, we explicitly honor the following \"protected attributes\": diversity in age, gender, culture, ethnicity, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, disability and personal appearance. We will not tolerate discrimination based on any of the protected characteristics above, including some that may not have been explicitly mentioned here. We consider discrimination of any kind to be unacceptable and immoral.</p> <p>Harassment includes, but is not limited to:</p> <ul> <li>Offensive comments (or \"jokes\") related to any of the above mentioned attributes.</li> <li>Deliberate \"outing\"/\"doxing\" of any aspect of a person's identity, such as physical or electronic address, without   their explicit consent, except as necessary means to protect others from intentional abuse.</li> <li>Unwelcome comments regarding a person's lifestyle choices and practices, including those related to food, health,   parenting, drugs and employment.</li> <li>Deliberate misgendering. This includes deadnaming or persistently using a pronoun that does not correctly reflect a   person's gender identity. You must address people by the name they give you when not addressing them by their   username or handle.</li> <li>Threats of violence, both physical and psychological.</li> <li>Incitement of violence towards any individual, including encouraging a person to engage in self-harm.</li> <li>Publication of non-harassing private communication.</li> <li>Pattern of inappropriate social conduct, such as requesting/assuming inappropriate levels of intimacy with others, or   excessive teasing after a request to stop.</li> <li>Continued one-on-one communication after requests to cease.</li> <li>Sabotage of someone else's work or intentionally hindering someone else's performance.</li> </ul>"},{"location":"community/code-of-conduct/#plagiarism","title":"Plagiarism","text":"<p>Plagiarism is the re-use of someone else's work (eg: binary content such as images, textual content such as an article, but also source code, or any other copyrightable resources) without the permission or a license right from the author. Claiming someone else's work as your own is not just immoral and disrespectful to the author, but also illegal in most countries. You should always follow the authors wishes, and give credit where credit is due.</p> <p>If we found that you've intentionally attempted to add plagiarized content to our code-base, you will likely end up being permanently banned from any future contributions to this project's repository. We will of course also do our best to remove, or properly attribute this plagiarized content as quickly as possible.</p> <p>An unintentional attempt at plagiarism will not be punished as harshly, but nevertheless, it is your responsibility as a contributor to check where the code you're submitting comes from, and so repeated submission of such content, even after you were warned might still get you banned.</p> <p>Please note that an online repository that has no license is presumed to only be source-available, NOT open-source. Meaning that this work is protected by author's copyright, automatically imposed over it, and without any license extending that copyright, you have no rights to use such code. So know that you can't simply take some source-code, even though it's published publicly. This code may be available to be seen by anyone, but that does not mean it's also available to be used by anyone in other projects.</p> <p>Another important note to keep in mind is that even if some project has an open-source license, that license may have conditions which are incompatible with our codebase (such as requiring all of the code that links to this new part to also be licensed under the same license, which our code-base is not currently under). That is why it's necessary to understand a license before using code available under it. Simple attribution often isn't everything that the license requires.</p> Learn more about software licensing <p>If you are new to software licensing, you can check out this article, which does a good job at explaining the basics.</p>"},{"location":"community/code-of-conduct/#generally-inappropriate-behavior","title":"Generally inappropriate behavior","text":"<p>Outside of just harassment and plagiarism, there are countless other behaviors which we consider unacceptable, as they may be offensive, and discourage people from engaging with our community.</p> <p>Examples of generally inappropriate behavior:</p> <ul> <li>The use of sexualized language or imagery of any kind</li> <li>The use of inappropriate images, including in an account's avatar</li> <li>The use of inappropriate language, including in an account's nickname</li> <li>Any spamming, flamming, baiting or other attention-stealing behavior</li> <li>Discussing topics that are overly polarizing, sensitive, or incite arguments.</li> <li>Responding with \"RTFM\", \"just google it\" or similar response to help requests</li> <li>Other conduct which could be reasonably considered inappropriate</li> </ul> <p>Examples of generally appropriate behavior:</p> <ul> <li>Being kind and courteous to others</li> <li>Collaborating with other community members</li> <li>Gracefully accepting constructive criticism</li> <li>Using welcoming and inclusive language</li> <li>Showing empathy towards other community members</li> </ul>"},{"location":"community/code-of-conduct/#scope","title":"Scope","text":"<p>This Code of Conduct applies within all community spaces, including this repository itself, conversations on any platforms officially connected to this project (such as in GitHub issues, emails or platforms like discord). It also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official social media account, or acting as an appointed representative at an online or offline event.</p> <p>All members involved with the project are expected to follow this Code of Conduct, no matter their position in the project's hierarchy, this Code of Conduct applies equally to contributors, maintainers and people seeking help/reporting bugs, etc.</p>"},{"location":"community/code-of-conduct/#enforcement-responsibilities","title":"Enforcement Responsibilities","text":"<p>Whenever a participant has made a mistake, we expect them to take responsibility for their actions. If someone has been harmed or offended, it is our responsibility to listen carefully and respectfully, and to do our best to right the wrong.</p> <p>Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, harmful, or otherwise undesirable.</p> <p>Community leaders have the right and responsibility to remove, edit or reject comments, commits, code, wiki edits, issues and other contributions within the enforcement scope that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.</p> <p>If you have experienced or witnessed unacceptable behavior constituting a code of conduct violation or have any other code of conduct concerns, please let us know and we will do our best to resolve this issue.</p>"},{"location":"community/code-of-conduct/#reporting-a-code-of-conduct-violation","title":"Reporting a Code of Conduct violation","text":"<p>If you think that someone is violating the Code of Conduct, you can report it to any repository maintainer, either by email or through a Discord DM. You should avoid using public channels for reporting these violations, and instead do so in private discussion with a maintainer.</p>"},{"location":"community/code-of-conduct/#sources","title":"Sources","text":"<p>The open-source community has an incredible amount of resources that people have freely provided to others and we all depend on these projects in many ways. This code of conduct article is no exception and there were many open source projects that has helped bring this code of conduct to existence. For that reason, we'd like to thank all of these communities and projects for keeping their content open and available to everyone, but most notably we'd like to thank the projects with established codes of conduct and diversity statements that we used as our inspiration. Below is the list these projects:</p> <ul> <li>Python: https://www.python.org/community/diversity/</li> <li>Contributor Covenant: https://www.contributor-covenant.org/</li> <li>Rust-lang: https://www.rust-lang.org/policies/code-of-conduct</li> <li>Code Fellows: https://github.com/codefellows/code-of-conduct</li> <li>Python Discord: https://www.pythondiscord.com/pages/code-of-conduct/</li> </ul>"},{"location":"community/license/","title":"License","text":"<p>This project's source code is licensed under the GNU Lesser General Public License (LGPL) version 3.</p> <p>The LGPL license allows you to use mcproto as a library pretty much in any code-base, including in proprietary code-bases. However, if you wish to make a derivative project to mcproto itself, such a project will need to be licensed under LGPL as well.</p> Full LICENSE text LICENSE.txt<pre><code>                   GNU LESSER GENERAL PUBLIC LICENSE\n                       Version 3, 29 June 2007\n\n Copyright (C) 2007 Free Software Foundation, Inc. &lt;http://fsf.org/&gt;\n Everyone is permitted to copy and distribute verbatim copies\n of this license document, but changing it is not allowed.\n\n\n  This version of the GNU Lesser General Public License incorporates\nthe terms and conditions of version 3 of the GNU General Public\nLicense, supplemented by the additional permissions listed below.\n\n  0. Additional Definitions.\n\n  As used herein, \"this License\" refers to version 3 of the GNU Lesser\nGeneral Public License, and the \"GNU GPL\" refers to version 3 of the GNU\nGeneral Public License.\n\n  \"The Library\" refers to a covered work governed by this License,\nother than an Application or a Combined Work as defined below.\n\n  An \"Application\" is any work that makes use of an interface provided\nby the Library, but which is not otherwise based on the Library.\nDefining a subclass of a class defined by the Library is deemed a mode\nof using an interface provided by the Library.\n\n  A \"Combined Work\" is a work produced by combining or linking an\nApplication with the Library.  The particular version of the Library\nwith which the Combined Work was made is also called the \"Linked\nVersion\".\n\n  The \"Minimal Corresponding Source\" for a Combined Work means the\nCorresponding Source for the Combined Work, excluding any source code\nfor portions of the Combined Work that, considered in isolation, are\nbased on the Application, and not on the Linked Version.\n\n  The \"Corresponding Application Code\" for a Combined Work means the\nobject code and/or source code for the Application, including any data\nand utility programs needed for reproducing the Combined Work from the\nApplication, but excluding the System Libraries of the Combined Work.\n\n  1. Exception to Section 3 of the GNU GPL.\n\n  You may convey a covered work under sections 3 and 4 of this License\nwithout being bound by section 3 of the GNU GPL.\n\n  2. Conveying Modified Versions.\n\n  If you modify a copy of the Library, and, in your modifications, a\nfacility refers to a function or data to be supplied by an Application\nthat uses the facility (other than as an argument passed when the\nfacility is invoked), then you may convey a copy of the modified\nversion:\n\n   a) under this License, provided that you make a good faith effort to\n   ensure that, in the event an Application does not supply the\n   function or data, the facility still operates, and performs\n   whatever part of its purpose remains meaningful, or\n\n   b) under the GNU GPL, with none of the additional permissions of\n   this License applicable to that copy.\n\n  3. Object Code Incorporating Material from Library Header Files.\n\n  The object code form of an Application may incorporate material from\na header file that is part of the Library.  You may convey such object\ncode under terms of your choice, provided that, if the incorporated\nmaterial is not limited to numerical parameters, data structure\nlayouts and accessors, or small macros, inline functions and templates\n(ten or fewer lines in length), you do both of the following:\n\n   a) Give prominent notice with each copy of the object code that the\n   Library is used in it and that the Library and its use are\n   covered by this License.\n\n   b) Accompany the object code with a copy of the GNU GPL and this license\n   document.\n\n  4. Combined Works.\n\n  You may convey a Combined Work under terms of your choice that,\ntaken together, effectively do not restrict modification of the\nportions of the Library contained in the Combined Work and reverse\nengineering for debugging such modifications, if you also do each of\nthe following:\n\n   a) Give prominent notice with each copy of the Combined Work that\n   the Library is used in it and that the Library and its use are\n   covered by this License.\n\n   b) Accompany the Combined Work with a copy of the GNU GPL and this license\n   document.\n\n   c) For a Combined Work that displays copyright notices during\n   execution, include the copyright notice for the Library among\n   these notices, as well as a reference directing the user to the\n   copies of the GNU GPL and this license document.\n\n   d) Do one of the following:\n\n       0) Convey the Minimal Corresponding Source under the terms of this\n       License, and the Corresponding Application Code in a form\n       suitable for, and under terms that permit, the user to\n       recombine or relink the Application with a modified version of\n       the Linked Version to produce a modified Combined Work, in the\n       manner specified by section 6 of the GNU GPL for conveying\n       Corresponding Source.\n\n       1) Use a suitable shared library mechanism for linking with the\n       Library.  A suitable mechanism is one that (a) uses at run time\n       a copy of the Library already present on the user's computer\n       system, and (b) will operate properly with a modified version\n       of the Library that is interface-compatible with the Linked\n       Version.\n\n   e) Provide Installation Information, but only if you would otherwise\n   be required to provide such information under section 6 of the\n   GNU GPL, and only to the extent that such information is\n   necessary to install and execute a modified version of the\n   Combined Work produced by recombining or relinking the\n   Application with a modified version of the Linked Version. (If\n   you use option 4d0, the Installation Information must accompany\n   the Minimal Corresponding Source and Corresponding Application\n   Code. If you use option 4d1, you must provide the Installation\n   Information in the manner specified by section 6 of the GNU GPL\n   for conveying Corresponding Source.)\n\n  5. Combined Libraries.\n\n  You may place library facilities that are a work based on the\nLibrary side by side in a single library together with other library\nfacilities that are not Applications and are not covered by this\nLicense, and convey such a combined library under terms of your\nchoice, if you do both of the following:\n\n   a) Accompany the combined library with a copy of the same work based\n   on the Library, uncombined with any other library facilities,\n   conveyed under the terms of this License.\n\n   b) Give prominent notice with the combined library that part of it\n   is a work based on the Library, and explaining where to find the\n   accompanying uncombined form of the same work.\n\n  6. Revised Versions of the GNU Lesser General Public License.\n\n  The Free Software Foundation may publish revised and/or new versions\nof the GNU Lesser General Public License from time to time. Such new\nversions will be similar in spirit to the present version, but may\ndiffer in detail to address new problems or concerns.\n\n  Each version is given a distinguishing version number. If the\nLibrary as you received it specifies that a certain numbered version\nof the GNU Lesser General Public License \"or any later version\"\napplies to it, you have the option of following the terms and\nconditions either of that published version or of any later version\npublished by the Free Software Foundation. If the Library as you\nreceived it does not specify a version number of the GNU Lesser\nGeneral Public License, you may choose any version of the GNU Lesser\nGeneral Public License ever published by the Free Software Foundation.\n\n  If the Library as you received it specifies that a proxy can decide\nwhether future versions of the GNU Lesser General Public License shall\napply, that proxy's public statement of acceptance of any version is\npermanent authorization for you to choose that version for the\nLibrary.\n</code></pre>"},{"location":"community/license/#this-documentation","title":"This documentation","text":"<p>This documentation itself follows a Creative Commons license: CC BY-NC-SA 4.0 </p> <p>Tip</p> <p>If you need a copyright header for proper attribution, you can use:</p> RenderedHTML <p>Mcproto Documentation \u00a9 2024 by ItsDrike</p> <pre><code>&lt;a href=\"https://py-mine.github.io/mcproto\"&gt;Mcproto Documentation&lt;/a&gt; &amp;copy; 2024 by &lt;a href=\"mailto:itsdrike@protonmail.com\"&gt;ItsDrike&lt;/a&gt;\n</code></pre> <p>If you also need the license identifier, use the following:</p> <pre><code>&lt;a href=\"https://creativecommons.org/licenses/by-nc-sa/4.0/\"&gt;CC BY-NC-SA 4.0&lt;/a&gt; &lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1\" alt=\"\"&gt;&lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1\" alt=\"\"&gt;&lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1\" alt=\"\"&gt;&lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/sa.svg?ref=chooser-v1\" alt=\"\"&gt;\n</code></pre>"},{"location":"community/license/#differently-licensed-parts","title":"Differently licensed parts","text":"<p>Some parts of the project follow a different license. See the <code>LICENSE-THIRD-PARTY.txt</code> file, which lists all of these parts and their respective licenses.</p> Full LICENSE-THIRD-PARTY text LICENSE-THIRD-PARTY.txt<pre><code>---------------------------------------------------------------------------------------------------\n                                            MIT License\nApplies to:\n    - Copyright (c) 2021 Python Discord\n      Copyright (C) 2022 Hassan Abouelela &lt;hassan@hassanamr.com&gt;\n      Copyright (C) 2022 Chris Lovering &lt;chris.lovering.95@gmail.com&gt;\n      Copyright (C) 2022 mbaruh &lt;mbaruh@hotmail.com&gt;\n      All rights reserved.\n        - mcproto/utils/version_map.py: portions of VersionMap._walk_submodules function\n    - Copyright (c) 2020 Nekokatt\n      Copyright (c) 2021-present davfsa\n      All rights reserved.\n        - .github/ISSUE_TEMPLATE/bug_report.yml: Template heavily inspired by original\n        - .github/ISSUE_TEMPLATE/feature_request.yml: Template heavily inspired by original\n        - .github/workflows/fragment-check.yml: Entire file\n        - .github/workflows/prepare-release.yml: Workflow heavily inspired by original\n        - .github/scripts/normalize_coverage.py: Entire file\n    - Copyright (c) 2015-present Rapptz\n      All rights reserved.\n        - docs/installation/version-guarantees.rst: Entire file\n    - Copyright (c) 2016-2024 Martin Donath\n      All rights reserved\n         - docs/contributing/reporting-a-bug.md: Majority of the file\n---------------------------------------------------------------------------------------------------\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n---------------------------------------------------------------------------------------------------\n                                 GNU LESSER GENERAL PUBLIC LICENSE\nApplies to:\n    - Copyright (c) 2022, Milo Weinberg &lt;iapetus011@gmail.com&gt;\n      All rights reserved.\n        - mcproto/packets/packet.py: GameState and PacketDirection enum classes\n---------------------------------------------------------------------------------------------------\nFulltext of the license can be seen in the LICENSE.txt file, as it matches the current license of\nthis project, this file just disclaims the copyrighted sections used in our codebase.\n\n---------------------------------------------------------------------------------------------------\n                                    Apache License version 2.0\nApplies to:\n    - Copyright (c) 2012 Ammar Askar\n      All rights reserved.\n        - mcproto/connection.py: write, read methods in all classes (not _write and _read though)\n        - mcproto/encryption.py: encrypt_token_and_secret, generate_shared_secret functions\n---------------------------------------------------------------------------------------------------\n\n\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright [yyyy] [name of copyright owner]\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n</code></pre>"},{"location":"contributing/making-a-pr/","title":"Making a pull request","text":"<p>Work In Progress</p> <p>This page is missing a guide on writing a good PR body</p>"},{"location":"contributing/making-a-pr/#pull-requests","title":"Pull Requests","text":"<p>Welcome! If you're interested in contributing to mcproto, you've come to the right place. Mcproto is an open-source project, and we welcome contributions from anyone eager to help out.</p> <p>To contribute, you can create a pull request on our GitHub repository. Your pull request will then be reviewed by our maintainers, and once approved, it will be merged into the main repository. Contributions can include bug fixes, documentation updates, or new features.</p> <p>Code quality requirements</p> <p>While we encourage and appreciate contributions, maintaining high code quality is crucial to us. That means you will need to adhere to our code quality standards. Contributions may be rejected if they do not meet these guidelines.</p>"},{"location":"contributing/making-a-pr/#get-assigned-to-the-issue","title":"Get assigned to the issue","text":"<p>The very first thing you will need to do is deciding what you actually want to work on. In all likelihood, you already have something in mind if you're reading this, however, if you don't, you're always free to check the opened GitHub issues. If you find anything interesting there that you'd wish to work on, leave a comment on that issue with something like: \"I'd like to work on this\".</p> <p>Even if you do have an idea already, we heavily recommend (though not require) that you first make an issue, this can be a bug report, but also a feature request, or something else. Once you made the issue, leave a: \"I'd like to work on this\" comment on it.</p> <p>Eventually, a maintainer will get back to you and you will be assigned to the issue. By getting assigned, you reserve the right to work on that given issue and it also prevents us (or someone else) from potentially working on the same thing that you're already addressing. This is also the reason why we recommend creating an issue first. Being assigned is a soft approval from us, giving you the green light to start coding.</p> <p>Of course, you are welcome to start working on the issue even before being officially assigned. However, please be aware that sometimes, we may choose not to pursue a certain feature / bugfix. In such cases, your work might not end up being used, which would be a shame.</p> <p>Minor tasks don't need an issue</p> <p>While we generally do encourage contributors to first create an issue and get assigned to it first. If you're just fixing a typo, improving the wording, or making some minor optimizations to the code, you can safely skip this step.</p> <p>The point of encouraging issues is to prevent needlessly wasting people's time. However, with these minor tasks, it might actually take you longer to create a full issue about the problem than it would to just submit a fix.</p> <p>There's therefore no point in cluttering the issue tracker with a bunch of small issues that can often be changed in just a few minutes.</p>"},{"location":"contributing/making-a-pr/#pull-request-body","title":"Pull Request Body","text":"<p>TODO</p>"},{"location":"contributing/making-a-pr/#work-in-progress-prs","title":"Work in Progress PRs","text":"<p>Whenever you open a pull request that isn't yet ready to be reviewed and merged, you can mark it as a draft. This provides both visual and functional indicator that the PR isn't yet ready to be merged.</p> <p>Methods of marking PR as a draft:</p> When creating it After creation <p>Once your work is done and you think the PR is ready to be merged, mark it as Ready for review</p> <p></p>"},{"location":"contributing/making-a-pr/#contributing-guidelines","title":"Contributing guidelines","text":"<p>In order to make a successful contribution, it is required that you get familiar with our contributing guidelines.</p>"},{"location":"contributing/making-a-pr/#automated-checks","title":"Automated checks","text":"<p>The project includes various CI workflows that will run automatically for your pull request after every push and check your changed with various tools. These tools are here to ensure that our contributing guidelines are met and ensure good code quality of your PR.</p> <p>That said, you shouldn't rely on these CI workflows to let you know if you made a mistake, instead, you should run these tools on your own machine during the development. Many of these tools can fix the violations for you automatically and it will generally be a better experience for you. Running these tools locally will also prevent a bunch of \"Fix the CI\" commits, which just clutter the git history.</p> <p>Make sure to read our contributing guidelines thoroughly, as they describe how to use these tools and even how to have them run automatically before each commit, so you won't forget.</p> <p>Passing the CI workflows is a requirement in order to get your pull request merged. If a maintainer sees a PR that's marked as ready for review, but isn't passing the CI, we'll often refrain from even reviewing it, as we consider it incomplete. If you have a technical reason why your PR can't pass the CI, let us know in the PR description or a comment.</p>"},{"location":"contributing/making-a-pr/#code-review","title":"Code Review","text":"<p>All pull requests will need to be reviewed by at least one team member before merging. The reviewer will provide feedback and suggestions for improvement.</p> <p>Once a reviewer approves your pull request, it can be merged into the <code>main</code> branch.</p> How do I request a review? <p>Request a review from a team member by assigning them as a reviewer to your pull request.</p> <p>However, you can also just wait until we get to your PR, you don't need to assign a reviewer unless you want someone specific to review. Just make sure that your PR is marked as ready for review and not draft.</p>"},{"location":"contributing/making-a-pr/#giving-feedback","title":"Giving Feedback","text":"<p>If you wish, you can also provide some feedback on other PRs. Doing so is a great way to fill the time while you're waiting for your PR to be reviewed by us and you're also speeding up the process, as it reduces the amount of time we'd have to spend reviewing those other PRs before getting to yours.</p> <p>When reviewing a pull request, aim to be constructive and specific. Highlight areas that need improvement and suggest potential solutions. If you have any questions on concerns about something in the code, don't hesitate to ask the author for clarification.</p> <p>Focus on the following aspects during a code review:</p> <ul> <li>Correctness and functionality</li> <li>Code quality and readability</li> <li>Adherence to the project guidelines</li> </ul> Good Code Review Feedback <p>Here are some examples of a good code review feedback:</p> <pre><code>- Great work on the new function! The implementation looks good overall.\n- The tests cover most of the functionality, but it's are missing a test case for edge case X. Could you add a test for that?\n- The logic in the new function is somewhat complex. Consider breaking it into smaller functions for better clarity.\n- The new feature is well-implemented, but it would be great to add more inline comments to explain the logic, as\n  it isn't trivial to understand.\n- There's a small typo in the docstring. Could you correct it?\n- The configuration settings are hard-coded. Can you move them to a configuration file to make it easier to manage?\n</code></pre> <p>Always be respectful and considerate when giving feedback. Remember that the goal is to improve the code and help the author grow as a developer.</p> <p>Be Positive</p> <p>Don't forget to acknowledge the positive aspects of the contribution as well!</p>"},{"location":"contributing/reporting-a-bug/","title":"Bug reports","text":"<p>Mcproto is an actively maintained project that we constantly strive to improve. With a project of this size and complexity, bugs may occur. If you think you have discovered a bug, you can help us by submitting an issue to our public issue tracker, following this guide.</p>"},{"location":"contributing/reporting-a-bug/#before-creating-an-issue","title":"Before creating an issue","text":"<p>Before opening a new issue with your bug report, please do the following things:</p>"},{"location":"contributing/reporting-a-bug/#upgrade-to-latest-version","title":"Upgrade to latest version","text":"<p>Chances are that the bug you discovered was already fixed in a subsequent version. Thus, before reporting an issue, ensure that you're running the latest version of mcproto.</p> <p>Bug fixes are not backported</p> <p>Please understand that only bugs that occur in the latest version of mcproto will be addressed. Also, to reduce duplicate efforts, fixes cannot be backported to earlier versions.</p>"},{"location":"contributing/reporting-a-bug/#search-for-existing-issues","title":"Search for existing issues","text":"<p>It's possible that the issue you're having was already reported. Please take some time and search the existing issues in the GitHub repository for your problem. If you do find an existing issue that matches the problem you're having, simply leave a  reaction instead (avoid commenting \"I have this issue too\" or similar, as that ultimately just clutters the discussion in that issue, but if you do think that you have something meaningful to add, please do).</p> <p>Note</p> <p>Make sure to also check the closed issues. By default, github issue search will start with: <code>is:issue is:open</code>, remove the <code>is:open</code> part to search all issues, not just the opened ones. It's possible that we seen this issue before, but closed the issue as something that we're unable to fix.</p>"},{"location":"contributing/reporting-a-bug/#creating-a-new-issue","title":"Creating a new issue","text":"<p>At this point, when you still haven't found a solution to your problem, we encourage you to create an issue. To do so, you can click here.</p>"},{"location":"contributing/reporting-a-bug/#writing-good-bug-reports","title":"Writing good bug reports","text":"<p>We have a GitHub issue template set up, which will guide you towards telling us everything that we need to know. However, for the best results, keep reading through this section. In here, we'll explain how a well formatted issue should look like in general and what it should contain.</p>"},{"location":"contributing/reporting-a-bug/#issue-title","title":"Issue Title","text":"<p>A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug you want to report can be inferred right from the title.</p> Example Clear Ping packet has incorrect ID Wordy The Ping packet has an incorrect packet ID of 0, when it should be 1 Unclear Ping packet is incorrect Non-english El paquete ping tiene una identificaci\u00f3n incorrecta Useless Help"},{"location":"contributing/reporting-a-bug/#bug-description","title":"Bug description","text":"<p>Now, to the bug you want to report. Provide a clear, focused, specific and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported to us. Adhere to the following principles:</p> <ol> <li>Explain the what, not the how \u2013 don't explain how to reproduce the bug here,    we're getting there. Focus on articulating the problem and its impact as clearly as possible.</li> <li>Keep it short and concise - if the bug can be precisely explained in one or two sentences, perfect. Don't    inflate it - maintainers and future users will be grateful for having to read less.</li> <li>Don't under-explain - don't leave out important details just to keep things short. While keeping things short is    important, if something is relevant, mention it. It is more important for us to have enough information to be able    to understand the bug, even if it means slightly longer bug report.</li> <li>One bug at a time - if you encounter several unrelated bugs, please create separate issues for them. Don't    report them in the same issue, as this makes it difficult for others when they're searching for existing issues and    also for us, since we can't mark such an issue as complete if only one of the bugs was fixed.</li> </ol> <p> Stretch goal \u2013 if you have a link to an existing page that describes the issue, or otherwise explains some of your claims, include it. Usually, this will be a https://wiki.vg link leading to the Minecraft protocol documentation for something.</p> <p> Stretch goal #2 \u2013 if you found a workaround or a way to fix the bug, you can help other users temporarily mitigate the problem before we maintainers can fix the bug in our code base.</p>"},{"location":"contributing/reporting-a-bug/#reproduction","title":"Reproduction","text":"<p>A minimal reproducible example is at the heart of every well-written bug report, as it allows us maintainers to instantly recreate the necessary conditions to inspect the bug and quickly find its root cause from there. It's a proven fact that issues with concise and small reproductions can be fixed much faster.</p> <p>Focus on creating a simple and small code snippet that we can run to see the bug. Do your best to avoid giving us large snippets or whole files just for the purpose of the reproducible example, do your best to reduce the amount of code as much as you can and try to avoid using external dependencies in the snippet (except for mcproto of course).</p> <p>Sometimes, the bug can't be described in terms of code snippets, such as when reporting a mistake in the documentation, in that case, provide a link to the documentation or whatever other relevant that will allows us to see the bug with minimal effort.</p>"},{"location":"contributing/reporting-a-bug/#next-steps","title":"Next steps","text":"<p>Once you submit the issue, the main part of reporting a bug is done, but things aren't completely over yet. You now have 2 choices:</p>"},{"location":"contributing/reporting-a-bug/#wait-for-us-to-get-to-the-problem","title":"Wait for us to get to the problem","text":"<p>If you don't wish to solve the bug yourself, all that remains is waiting for us to handle it.</p> <p>Please understand that we are all volunteers here and we work on the project simply the fun of it. This means that we may sometimes have other priorities in life or we just want to work on some more interesting tasks first. It might therefore take a while for us to get to your bug (don't worry though, in most cases, we're pretty quick). Even if things are slower, we kindly ask you to avoid posting comments like \"Any progress on this?\" as they are not helpful and create unnecessary clutter in the discussion.</p> <p>When we do address your issue, we might need further information from you. GitHub has a notification system, so once we respond, you will be notified there. Note that, by default, these notifications might not be forwarded to your email or elsewhere, so please check GitHub periodically for updates.</p> <p>Finally, when we fix your bug, we will mark the issue as closed (GitHub will notify you of this too). Once that happens, your bug should be fixed, but we appreciate it if you take the time to verify that everything is working correctly. If the issue persists, you can reopen the issue and let us know.</p> <p>Issues are fixed on the main branch</p> <p>Do note that when we close an issue, it means that we have fixed your bug in the <code>main</code> branch of the repository.   That doesn't necessarily mean the fix has been released on PyPI yet, so you might still need to wait for the next   release. Alternatively, you can also try the git installation to   get the project right from that latest <code>main</code> branch.</p>"},{"location":"contributing/reporting-a-bug/#attempt-to-solve-it-yourself","title":"Attempt to solve it yourself","text":"<p>Quote</p> <p>The fastest way to get something done is to avoid waiting on others.</p> <p>If you wish to try and tackle the bug yourself, let us know by commenting on the issue with something like \"I'd like to work on this\". This helps us avoid duplicate efforts and ensures that we don't work on something you're already addressing.</p> <p>Once a maintainer sees your comment, they will assign the issue to you. Being assigned is a soft approval from us, giving you the green light to start working.</p> <p>Of course, you are welcome to start working on the issue even before being officially assigned. However, please be aware that sometimes we choose not to fix certain bugs for specific reasons. In such cases, your work might not end up being used.</p> <p>Before starting your work though, make sure to also read our pull request guide.</p>"},{"location":"contributing/guides/","title":"Contributing guides &amp; guidelines","text":"<p>Welcome to the contributing guides &amp; guidelines for mcproto. This documentation is intended for our contributors, interested in writing or modifying mcproto itself. If you just wish to use mcproto in your project, you can safely skip this section.</p> <p>Mcproto is a relatively large project and maintaining it is no easy task. With a project like that, consistency and good code quality becomes very important to keep the code-base readable and bug-free. To achieve this, we have put together these guidelines that will explain the code style and coding practices that we expect our contributors to follow.</p> <p>This documentation will also include various guides that tell you how to set up our project for development and explain the automated tools that we use to improve our coding experience and enforce a bunch of the code style rules quickly and without the need for human review.</p>"},{"location":"contributing/guides/#the-golden-rules-of-contributing","title":"The Golden Rules of Contributing","text":"<p>These are the general rules which you should follow when contributing. You can glance over these and then go over the individual guides one by one, or use the references in these rules to get to the specific guide page explaining the rule.</p> <p>Note</p> <p>This list serves as a quick-reference rather than a full guide. Some of our guidelines aren't directly linked in these references at all and we heavily encourage you to go over each of the guide pages in the order they're listed in the docs.</p> <ol> <li>Lint before you push. We have multiple code linting rules, which define our general style of the code-base.    These are often enforced through certain tools, which you are expected to run before every push and ideally even    before every commit. The specifics of our linting rules are mentioned in our style guide.    Running all of these tools manually before every commit would however be quite annoying, so we use    pre-commit.</li> <li>Make great commits. Great commits should be atomic (do one thing only and do it well), with a commit message    that explaining what was done, and why. More on this here.</li> <li>Make an issue before the PR. Before you start working on your PR, open an issue and let us know what you're    planning. We described this further in our making a PR guide.</li> <li>Use assets licensed for public use. Whenever you're adding a static asset (e.g. images/video files/audio or    even code) that isn't owned/written by you, make sure it has a compatible license with our projects.</li> <li>Follow our Code of Conduct</li> </ol>"},{"location":"contributing/guides/#changes-to-these-guidelines","title":"Changes to these guidelines","text":"<p>While we're confident and happy with the current code style and tooling, we acknowledge that change is inevitable. New tools are constantly being developed, and we have already made significant updates to our code style in the past.</p> <p>Every project evolves over time, and these guidelines are no exception. This documentation is open to pull requests and changes from contributors. Just ensure that any updates to this document are in sync with the codebase. If you propose a code style change, you must apply that change throughout the codebase to maintain internal consistency.</p> <p>If you believe you have something valuable to add or change, please submit a pull request. For major style changes, we strongly encourage you to open an issue first, as we may not always agree with significant alterations. For minor clarity improvements or typo fixes, opening an issue isn't necessary.</p> <p>We tried to design our specifications to be straightforward and comprehensive, but we might not always succeed, as we're doing so from our perspective of already having extensive background knowledge. Therefore, we welcome any clarity improvements to the documentation. If you think you can explain something better, please contribute.</p>"},{"location":"contributing/guides/#footnotes","title":"Footnotes","text":"<p>We understand that going through all of these guidelines can be time-consuming and a lot to remember. However, we strongly encourage you to review them, especially if you haven't worked with these tools or followed such best practices before.</p> <p>Every page in this contributing guides category has an abstract at the top, summarizing its content. This allows you to quickly determine if you are already familiar with the topic or, if you're re-reading, to quickly recall what the page covers. Feel free to skip any guide pages if you're already familiar with what they cover.</p> <p>We believe these guides will be beneficial to you beyond our codebase, as they promote good coding practices and help make your code cleaner. You will likely be able to apply much of the knowledge you gain here to your own projects.</p>"},{"location":"contributing/guides/#disclaimer","title":"Disclaimer","text":"<p>These documents were inspired by Python Discord's CONTRIBUTING agreement.</p>"},{"location":"contributing/guides/changelog/","title":"Changelog fragments","text":"Abstract <p>This page describes our use of <code>towncrier</code> for the project's changelog. It explains the different changelog categories, the process of creating changelog fragment files and generating a changelog preview. Additionally, the page contains a guide on writing good changelog fragments.</p> <p>Our project contains a changelog which tracks all notable changes for easy and quick reference to both users and our contributors.</p> <p>To maintain our changelog, we're using <code>towncrier</code>, which allows us to create fragment files, which each contains a single changelog entry. Once a new release is created, all of these fragments will be used to create a changelog for that new release.</p> <p>We generally require every pull request to to include a new changelog fragment, summarizing what it does.</p> <p>Note</p> <p>If you think your change shouldn't require a changelog entry (it's a small / simple change that isn't worth noting), ask us to add the <code>skip-fragment-check</code> label to your PR, which will disable the automated check that enforces a presence of the changelog fragment.</p>"},{"location":"contributing/guides/changelog/#structure-of-a-fragment-file","title":"Structure of a fragment file","text":"<p>The fragment files are stored in the <code>changes/</code> directory in our project. These files follow the following naming format: <code>{pull_request_number}.{type}.md</code>.</p> <p>Possible fragment types are:</p> <ul> <li><code>feature</code>: New feature that affects the public API.</li> <li><code>bugfix</code>: A bugfix, which was affecting the public API.</li> <li><code>docs</code>: Change to the documentation, or updates to public facing docstrings</li> <li><code>breaking</code>: Signifying a breaking change of some part of the project's public API, which could cause issues for     end-users updating to this version. (Includes deprecation removals.)</li> <li><code>deprecation</code>: Signifying a newly deprecated feature, scheduled for eventual removal.</li> <li><code>internal</code> Fully internal change that doesn't affect the public API, but is significant enough to be mentioned,     likely because it affects project contributors. (Such as a new linter rule, change in code style, significant change     in internal API, ...)</li> </ul>"},{"location":"contributing/guides/changelog/#create-fragments-with-commands","title":"Create fragments with commands","text":"<p>While you can absolutely create these files manually, it's often a lot more convenient to use the <code>towncrier</code> CLI, which can create the file for you in the proper place automatically. With it, you can simply run:</p> <pre><code>towncrier create {pull_request_number}.{type}.md\n</code></pre> <p>After you ran the command, a new file will appear in the <code>changes/</code> directory. You can now open it and describe your change inside of it.</p> <p>If the change is simple enough, you can even use the <code>-c</code> / <code>--content</code> flag to specify it directly, like:</p> <pre><code>towncrier create 12.feature.md -c \"Add dinosaurs!\"\n</code></pre> <p>Terminal editors</p> <p>If you're used to terminal editors, there's also an <code>--edit</code> flag, which will open the file with your <code>$EDITOR</code>. (I would recommend <code>neovim</code>, but if you find it too complex, <code>nano</code> also works well)</p>"},{"location":"contributing/guides/changelog/#multiple-fragments-in-a-single-pr","title":"Multiple fragments in a single PR","text":"<p>If necessary, multiple fragment files can be created per pull-request, with different change types, if the PR covers multiple areas. For example for PR #13 that both introduces a feature, and changes the documentation, can add 2 fragment files: <code>13.feature.md</code> and <code>13.docs.md</code>.</p> <p>Additionally, if a single PR is addressing multiple unrelated topics in the same category, and needs to make multiple distinct changelog entries, an optional counter value can be added at the end of the file name (needs to be an integer). So for example PR #25 which makes 2 distinct internal changes can add these fragment files: <code>25.internal.1.md</code> and <code>25.internal.2.md</code>. (The numbers in this counter position will not be shown in the final changelog and are merely here for separation of the individual fragments.)</p> <p>However if the changes are related to some bigger overarching goal, you can also just use a single fragment file with the following format:</p> changes/25.internal.md<pre><code>Update towncrier categories\n\n    - Rename `documentation` category to shorter: `docs`\n    - Add `internal` category for changes unrelated to public API, but potentially relevant to contributors\n    - Add github workflow enforcing presence of a new changelog fragment file for each PR\n        - For insignificant PRs which don't require any changelog entry, a maintainer can add `skip-fragment-check` label.\n</code></pre> <p>Warning</p> <p>While possible, if you end up making multiple distinct changelog fragments like this, it's a sign that your PR might be too big, and you should split it up into multiple PRs instead. Making huge PRs that address several unrelated topics at once is generally a bad practice, and should be avoided. If you go overboard, your PR might even end up getting closed for being too big, and you'll be required to split it up.</p>"},{"location":"contributing/guides/changelog/#preview-changelog","title":"Preview changelog","text":"<p>To preview the latest changelog, run <code>towncrier build --draft --version latest</code>.</p> Meaning of the version value <p>The <code>--version</code> attribute usually takes the version number of the project, to which these changes apply. However, since we just want to preview the changes, it doesn't really matter for us, so we can just pass <code>latest</code> or whatever else you wish.</p> <p>For actual builds, the version is automatically obtained and this command is executed in our release CI workflow.</p> <p>This version will be used in the first line of the changelog (the header).</p> Meaning of --draft flag <p>The <code>--draft</code> flag will make sure that towncrier will only show you the contents of the next changelog version entry, but won't actually add that generated content to our <code>CHANGELOG.md</code> file, while consuming (removing) the changelog fragments.</p> <p>You will never need to run <code>towncrier</code> without the <code>--draft</code> flag, as our CI workflows for project releasing handle that automatically.</p> <p>To make this a bit easier, there is a taskipy task running the command above, so you can just use <code>poetry run task changelog-preview</code> to see the changelog, if you don't like remembering new commands.</p>"},{"location":"contributing/guides/changelog/#writing-good-changelog-fragments","title":"Writing good changelog fragments","text":"<p>Fragment files follow the same markdown syntax as our documentation.</p> <p>The contents of a fragment file should describe the change that you've made in a quick and general way. That said, the change descriptions can be a bit more verbose than just the PR title, but only if it's necessary. Keep in mind that these changes will be shown to the end users of the library, so try to explain your change in a way that a non-contributor would understand.</p> <p>Tip</p> <p>If your change needs some more in-depth explanations, perhaps with code examples and reasoning for why such a change was made, use the PR body (description) for this purpose. Each changelog entry will contain a link to the corresponding pull request, so if someone is interested in any additional details about a change, they can always look there.</p>"},{"location":"contributing/guides/changelog/#examples-of-good-changlog-fragment-files","title":"Examples of good changlog fragment files","text":"<p> Clear and descriptive</p> changes/171.feature.md<pre><code>Add `Account.check` function, to verify that the access token in use is valid, and the data the Account instance has matches the data minecraft API has.\n</code></pre> changes/179.docs.md<pre><code>Enforce presence of docstrings everywhere with pydocstyle. This also adds docstring to all functions and classes that didn't already have one. Minor improvements for consistency were also made to some existing docstrings.\n</code></pre> <p> Slightly on the longer side, but it's justified (Sometimes, it's important to explain the issue that this fixes, so that users know that it was there)</p> changes/330.bugfix.md<pre><code>Fix behavior of the `mcproto.utils.deprecation` module, which was incorrectly always using a fallback version, assuming mcproto is at version 0.0.0. This then could've meant that using a deprecated feature that is past the specified deprecation (removal) version still only resulted in a deprecation warning, as opposed to a full runtime error.\n</code></pre> <p> With an extra note about the breaking change (Adding some extra description isn't always bad, especially for explaining how a breaking change affects existing code)</p> changes/130.breaking.md<pre><code>Renamed \"shared_key\" field to \"shared_secret\" in `LoginEncryptionPacket`, following the official terminology.\n\n    This is a breaking change as `LoginEncryptionPacket`'s `__init__` method now uses \"shared_secret\" keyword only\n    argument, not \"shared_key\". Every initialization call to this packet needs to be updated.\n</code></pre> <p> With a list of subchanges that were made (Be careful with this one though, make sure you don't over-do it)</p> changes/129.feature.md<pre><code>Added a system for handling Minecraft authentication\n\n    - Yggdrasil system for unmigrated i.e. non-Microsoft accounts (supportng Minecraft accounts, and the really old\n      Mojang accounts)\n    - Microsoft OAuth2 system (Xbox live) for migrated i.e. Microsoft accounts\n</code></pre>"},{"location":"contributing/guides/changelog/#examples-of-bad-changelog-fragment-files","title":"Examples of bad changelog fragment files","text":"<p> Unclear (But what does this class do?)</p> changes/123.feature.md<pre><code>Update `Buffer` class.\n</code></pre> <p> Bad category (This is a feature, not a bugfix)</p> changes/161.bugfix.md<pre><code>Add support for encryption. Connection classes now have `enable_encryption` method, and some encryption related functions were added into a new mcproto.encryption module.\n</code></pre> <p> Starts with dash (Sometimes, it can feel natural to start your changelog entry with a <code>-</code>, as it is a list item in the final changelog, however, this dash will already be added automatically)</p> changes/171.feature.md<pre><code>-   Add `Account.check` function, to verify that the access token in use is valid, and the data the Account instance has matches the data minecraft API has.\n</code></pre> <p> Wrapped first line (Splitting up the first line into multiple lines is something we often do in markdown, because it should still be rendered as a single line, however, because of how towncrier merges these fragments, using multiple lines will cause issues and the changelog won't be formatter correctly! Further blocks can have wrapped lines.)</p> changes/330.bugfix.md<pre><code>Fix behavior of the `mcproto.utils.deprecation` module, which was incorrectly always using a fallback version, assuming\nmcproto is at version 0.0.0. This then could've meant that using a deprecated feature that is past the specified\ndeprecation (removal) version still only resulted in a deprecation warning, as opposed to a full runtime error.\n</code></pre> <p> No indent in description (Sometimes, we want to add additional description to our changelog entry. When doing so, we need to make sure that the description block is indented with 4 spaces and there is a blank line after the first / title line.)</p> changes/330.breaking.md<pre><code>Renamed \"shared_key\" field to \"shared_secret\" in `LoginEncryptionPacket`, following the official terminology.\n\nThis is a breaking change as `LoginEncryptionPacket`'s `__init__` method now uses \"shared_secret\" keyword only\nargument, not \"shared_key\". Every initialization call to this packet needs to be updated.\n</code></pre> <p> Way too long (This should've been the PR description)</p> changes/161.feature.md<pre><code>Introduce support for encryption handling.\n\n    Most servers (even offline ones) usually send an EncryptionRequest packet during the LOGIN state, with a public\n    (RSA) key that the client is expected to use to encrypt a randomly generated shared secret, to send back to the\n    server in EncryptionResponse packet. After that, all further communication is encrypted with this shared secret.\n\n    The encryption used is a AES/CFB8 stream cipher. That means the encrypted ciphertext will have the same amount\n    of bytes as the original plaintext, allowing us to still trust our reader/writer methods that rely on reading\n    specific amounts of bytes, even if their content don't make sense.\n\n    This directly uses the base connection classes and adds enable_encryption method to them, which after getting\n    called will automatically encrypt/decrypt any incomming/outcomming data.\n\n    This additionally also changes the LoginEncryptionRequest packet class, and makes the public key attribute\n    actually hold an RSA public key (from the cryptography library), instead of just the received bytes. This is\n    then much more useful to work with later on. This is a breaking change.\n</code></pre> <p>Verify if your changelog works</p> <p>Our CI will automatically build the documentation for your PR and post a link to it as a comment in the pull request. This documentation will include a preview of the changelog with all unreleased changes in the changelog page. You can take a look there to make sure that your change fragment(s) resulted in the proper output.</p> <p>Internal changes</p> <p>We're a bit more forgiving when it comes to describing your change if your change is in the <code>internal</code> category, as end users don't need to read those. Changes in this category can be a bit less descriptive.</p>"},{"location":"contributing/guides/changelog/#footnotes","title":"Footnotes","text":"<ul> <li>See https://keepachangelog.com for more info about why and how to properly maintain a changelog</li> <li>For more info about <code>towncrier</code>, check out it's documentation</li> </ul>"},{"location":"contributing/guides/deprecations/","title":"Deprecations","text":"<p>Work In Progress</p> <p>This page is still being written. The content below (if any) may change.</p>"},{"location":"contributing/guides/docstrings/","title":"Docstring formatting","text":"<p>Work In Progress</p> <p>This page is still being written. The content below (if any) may change.</p>"},{"location":"contributing/guides/docstrings/#docstring-formatting-directive","title":"Docstring formatting directive","text":""},{"location":"contributing/guides/great-commits/","title":"Great Commits","text":"Abstract <p>This guide describes how to make good commits that are helpful to maintainers, debuggable and readable when going over the <code>git log</code>, or <code>git blame</code>.</p> <p>It explains the purpose of a commit message and it's structure, goes over the importance of making commits \"atomic\" and the practice of partial staging, mentions why and how to avoid making a lot of fixing commits, describes force pushing after modifying the git history, alongside it's downsides and finally, it explains why these practices are worth following and how they make the developer's life easier.</p> <p>A well-structured git log is crucial for a project's maintainability, providing insight into changes as a reference for future maintainers (or old forgetful ones, like me). Here, we outline the best practices for making good commits in our project.</p>"},{"location":"contributing/guides/great-commits/#commit-message-guidelines","title":"Commit Message Guidelines","text":""},{"location":"contributing/guides/great-commits/#purpose","title":"Purpose","text":"<p>Every commit should represent a change in the source code. The commit message should not only describe what was changed but also why it was necessary and what it achieves.</p>"},{"location":"contributing/guides/great-commits/#more-than-just-the-first-line","title":"More than just the first line","text":"<p>Many developers are uesd to commiting changes with a simple <code>git commit -m \"My message\"</code>, and while this is enough and it's perfectly fine in many cases, sometimes you just need more space to describe what a change truly achieves.</p> <p>Surprisingly, many people don't even know that they can make a commit that has more in it's message than just the title/first line. That then leads to poorly documented changes, because single line sometimes just isn't enough.</p> <p>To create a commit with a bigger commit message, you can simply run the <code>git commit</code> command without the <code>-m</code> argument. This should open a temporary file in your text editor (<code>$EDITOR</code>), in which you can write out your commit message in full.</p> Use git commit by default <p>I\u2019d actually recommend making the simple <code>git commit</code> the default way you make new commits, since it invites you to write more about it, by just seeing that you have that space available. We usually don\u2019t even know what exactly we\u2019ll write in our new commit message before getting to typing it out, and knowing you have that extra space if you need it will naturally lead to using it, even if you didn\u2019t know you needed it ahead of time.</p> <p>Note</p> <p>That said, not every commit requires both a subject and a body. Sometimes, a change may be so simple, that no further context is necessary. With those changes, including a body would just be a waste of the readers time. For example:</p> <pre><code>Fix typo in README\n</code></pre> <p>This message doesn't need anything extra. Some people like to include what the typo was, but if you want to know that, you can just look at the actual changes that commit made. There's a whole bunch of ways to do that with git, like <code>git show</code>, <code>git diff</code> or <code>git log --patch</code>. So while in some cases, having extra context can be very valuable, you also shouldn't overdo it.</p>"},{"location":"contributing/guides/great-commits/#structure","title":"Structure","text":"<p>Git commits should be written in a very specific way. There\u2019s a few rules to follow:</p> <ol> <li>Subject Line:<ul> <li>Limit to 50 characters (This isn't a hard limit, but try not to go much longer. This limit ensures   readability and forces the author to thing about the most concise way to explain what's going on. Hint: If you're   having trouble summarizing, you might be committing too much at once)</li> <li>A single sentence (The summary should be a single sentence, multiple probably wouldn't fit into the character   limit anyways)</li> <li>Capitalize the first letter</li> <li>Don't end with a period (A period will only waste one of your precious 50 characters for the summary and   it's not very useful context wise)</li> <li>Use imperative mood (Imperative mood means \u201cwritten as if giving a command/instruction\u201d i.e.: \u201cAdd support   for X\u201d, not \u201cI added support for X\u201d or \u201cSupport for X was added\u201d, as a rule of thumb, a subject message should be   able to complete the sentence: \u201cIf implemented, this commit will \u2026\u201d)</li> </ul> </li> <li>Body:<ul> <li>Separate the body from the subject line with a blank line (Not doing so would make git think your summary   spans across multiple lines, rather than it being a body)</li> <li>Wrap at 72 characters (Commits are often printed into the terminal with the <code>git log</code> command. If the output   isn't wrapped, going over the terminals width can cause a pretty messy output. The recommended maximum width for terminal text output is 80 characters, but git tools can often add indents, so 72 characters is a sensible maximum)</li> <li>Avoid implementation details (The diff shows the \"how\", focus on the \"what\" and \"why\")</li> </ul> </li> </ol> <p>Git commits can use markdown, most other programs will understand it and it's a great way to bring in some more style, improving the readability. In fact, if you view the commit from a site like GitHub, it will automatically render any markdown in the commit for you.</p> Example commit <pre><code>Summarize changes in around 50 characters or less\n\nMore detailed explanatory text, if necessary. Wrap it to about 72\ncharacters or so. In some contexts, the first line is treated as the\nsubject of the commit and the rest of the text as the body. The\nblank line separating the summary from the body is critical (unless\nyou omit the body entirely); various tools like `log`, `shortlog`\nand `rebase` can get confused if you run the two together.\n\nExplain the problem that this commit is solving. Focus on why you\nare making this change as opposed to how (the code explains that).\nAre there side effects or other unintuitive consequences of this\nchange? Here's the place to explain them.\n\nFurther paragraphs come after blank lines.\n\n- Bullet points are okay too\n- They're very useful for listing something\n</code></pre> <p> Stretch goal \u2013 Include relevant keywords to make your commits easily searchable (e.g. the name of the class/function you modified).</p> <p> Stretch goal #2 \u2013 Keep it engaging! Provide some interesting context or debug processes to make the commit history both more informative and fun to read.</p>"},{"location":"contributing/guides/great-commits/#make-atomic-commits","title":"Make \"atomic\" commits","text":"<p>Definition</p> <p>Atomic: of or forming a single irreducible unit or component in a larger system.</p> <p>The term \u201catomic commit\u201d means that the commit is only representing a single change, that can\u2019t be further reduced into multiple commits, i.e. this commit only handles a single change. Ideally, it should be possible to sum up the changes that a good commit makes in a single sentence.</p> <p>That said, the irreducibility should only apply to the change itself, obviously, making a commit for every line of code wouldn\u2019t be very clean. Having a commit only change a small amount of code isn\u2019t what makes it atomic. While the commit certainly can be small, it can just as well be a commit that\u2019s changing thousands of lines. (That said, you should have some really good justification for it if you\u2019re actually making commits that big.)</p> <p>The important thing is that the commit is only responsible for addressing a single change. A counter-example would be a commit that adds a new feature, but also fixes a bug you found while implementing this feature, and also improves the formatting of some other function, that you encountered along the way. With atomic commits, all of these actions would get their own standalone commits, as they\u2019re unrelated to each other, and describe several different changes.</p> <p>Note that making atomic commits isn't just about splitting thins up to only represent single changes, indeed, while they should only represent the smallest possible change, it should also be a \u201ccomplete\u201d change. This means that a commit responsible for changing how some function works in order to improve performance should ideally also update the documentation, make the necessary adjustments to unit-tests so they still pass, and update all of the references to this updated function to work properly after this change.</p> <p>Summary</p> <p>So, an atomic commit is a commit representing a single (ideally an irreducible) change, that\u2019s fully implemented and integrates well with the rest of the codebase.</p>"},{"location":"contributing/guides/great-commits/#partial-adds","title":"Partial adds","text":"<p>Many people tend to always simply use <code>git add -A</code> (or <code>git add .</code>), to stage all of the changes they made, and then create a commit with it all. Sometimes, you might not even stage the changes and choose to use <code>git commit -a</code>, to quickly commit everything.</p> <p>In an ideal world, where you only made the changes you needed to make for this single atomic commit, this would work pretty well, and while sometimes this is the case, in many cases, you might've also fixed a bug or a typo that you noticed while working on your changes, or already implemented something else, that doesn't fit into your single atomic commit that you now wish to make.</p> <p>In this case, it can be very useful to know that you can instead make a \"partial\" add, and only stage those changes that belong to the commit. In some cases, all that you'll need is to only stage some specific files, which you can do with:</p> <pre><code>git add path/to/some/file path/to/other/file\n</code></pre> <p>That said, in most cases, you're left with a single file that contains multiple changes. When this happens, you can use the <code>-p</code>/<code>--patch</code> flag:</p> <pre><code>git add -p path/to/file\n</code></pre> <p>Git will then let you interactively go over every \"hunk\" (a chunk of code, with changes close to each other) and let you decide whether to accept it (hence staging that single hunk), split it into more chunks, skip it (avoids staging this hunk) or even modify it in your editor, allowing you to remove the intertwined code from multiple changes, so that your commit will really only perform a single change.</p> <p>Use --patch more often</p> <p>This git feature has slowly became one of my favorite tools, and I use it almost every time I need to commit something, even if I don't need to change or skip things, since it also allows me to quickly review the changes I'm making, before they make it into a commit.</p>"},{"location":"contributing/guides/great-commits/#avoid-fixing-commits","title":"Avoid fixing commits","text":"<p>A very common occurrence I see in a ton of different projects is people making sequences of commits that go like:</p> <ul> <li>Fix bug X</li> <li>Actually fix bug X</li> <li>Fix typo in variable name</li> <li>Sort imports</li> <li>Follow lint rules</li> <li>Run auto-formatter</li> </ul> <p>While people can obviously mess up sometimes, and just not get something right on the first try, a fixing commit is rarely a good way to solve that.</p> <p>Instead of making a new commit, you can actually just amend the original. To do this, we can use the <code>git commit --amned</code>, which will add your staged changes into the previous commit, even allowing you to change the message of that old commit.</p> <p>Not only that, if you've already made another commit, but now found something that needs changing in the commit before that, you can use interactive rebase with <code>git rebase -i HEAD~3</code>, allowing you to change the last 3 commits, or even completely remove some of those commits.</p> <p>For more on history rewriting, I'd recommend checking the official git documentation.</p>"},{"location":"contributing/guides/great-commits/#force-pushing","title":"Force pushing","text":"<p>Changing history is a great tool to clean up after yourself, but it works best with local changes, i.e. with changes you haven't yet pushed.</p> <p>If you're changing git history after you've already pushed, you will find that pushing again will not work, giving you a message like \"updates were rejected because the remote contains work that you do not have locally\".</p> <p>To resolve this issue, it is possible to make a \"force push\" with <code>git push --force</code> command. Running this will push your branch to the remote (to GitHub) regardless of what was in the remote already, hence overriding it.</p> <p>Warning</p> <p>Force pushing becomes risky if others have already pulled the branch you are working on. If you overwrite the branch with a force push, it can lead to several issues:</p> <ul> <li>Lost Work: Collaborators may have pushed to your branch already, following it's existing git history.   However, after your force-push, their changes would be ereased from the remote. Make sure you pull / rebase   from the remote before you make a force-push.</li> <li>Complex conflicts: If someone else has pulled your branch and did some changes that they didn't yet push   before you force-pushed, suddenly, their git history is now no longer in sync. Resolving conflicts like that is   possible, but it can be very annoying.</li> <li>Harder reviews: When reviewing your code, we sometimes like going over the individual commits to understand   your individual (atomic) changes better. It's often a lot easier to look at and review 10 different atomic   changes individually, that together form a PR than it would be to look at all of them at once. By force-pushing,   you're changing the commit history, making the changes to the code that we already reviewed. This is partially   GitHub's fault though, for not providing an easier way of showing these changes across force-pushes.</li> </ul>"},{"location":"contributing/guides/great-commits/#force-pushing-on-pr-feature-branches","title":"Force pushing on PR feature branches","text":"<p>In our project, we do allow force pushing on your individual feature branches that you use for your PR. This flexibility enables you to clean up your commit history and refine your changes before they are merged into the main branch. However, it's important to note that many other projects may not permit force pushing due to the risks involved. Always check the contributing guidelines of the project you are working on.</p> <p>Best practices</p> <p>To mitigate the risks associated with force pushing, consider following these best practices:</p> <ul> <li>Push less often: Try to limit of othen you push changes to the remote repository in general. Aim to push only   when you are satisfied with the set of changes you have. This reduces the likelihood of needing to force-push a   lot.</li> <li>Force push quickly: If you do need to force-push, try to do so as quickly as possible. The more time that has   passed since your normal push, the more likely it is that someone have already clonned/pulled your changes. If a   force push was made within just a few seconds of the original push (and it only overwrites the changes from that   last push), it's not very likely that someone will have those changes pulled already, so you probably won't break   anyone's local version.</li> <li>Pull before changing history: Make absolutely certain that you don't override anyone's changes with your   force-push. Sometimes, maintainers can create new commits in your branch, other times, that can even be you by   modifying something from GitHub, or clicking on the apply suggestion button from a code-review. By pulling before   you start changing history, you can make sure that you won't erease these changes and they'll remain a part of   your modified history.</li> </ul>"},{"location":"contributing/guides/great-commits/#benefits","title":"Benefits","text":"<p>Now that you've seen some of the best practices to follow when making new commits, let's talk a bit about why we follow these practices and what benefits we can gain from them.</p>"},{"location":"contributing/guides/great-commits/#a-generally-improved-development-workflow","title":"A generally improved development workflow","text":"<p>Speaking from my personal experience, I can confidently say that learning how to make good git commits, specifically the practice of making atomic commits will make you a better programmer overall. That might sound surprising, but it's really true.</p> <p>The reason is that it forces you to only tackle one issue at a time. This naturally helps you to think about how to split your problem into several smaller (atomic) subproblems and make commits addressing those single parts. This is actually one of very well known approaches to problem-solving, called the \"divide and conquer\" method, where you split your problem into really small, trivially simple chunks that you solve one by one.</p>"},{"location":"contributing/guides/great-commits/#easier-bug-hunting","title":"Easier bug hunting","text":"<p>Bugs in code are pretty much inevitable, even for the most experienced of developers. Sometimes, we just don't realise how certain part of the code-base will interact with another part, or we're just careless as we try and build something fast.</p> <p>The most annoying bugs are those that aren't discovered immediately during development. These bugs can require a lot of work to track down. With a good git log, filled with a lot of small commits, where each commit leaves the code-base in a usable state, you can make this process a lot simpler!</p> <p>Git has a command specifically for this: <code>git bisect</code>. It will first make you mark 2 commits, a good one and a bad one, after which it will perform a binary search, checking out the commits in between these two as you try and replicate the bug on each. This will quickly lead you to the specific commit that introduced this bug, without having to do any code debugging at all.</p> <p>The great advantage here is that users reporting bugs can often perform git bisects too, even without having to know much about development and the structure of our code-base and if the identified commit is small enough, the issue is often apparent just from looking at the diff. Even for bigger commits though, they can be often reverted to quickly fix the issue and give developers time to focus on actually resolving it, while using it's diff as a reference.</p>"},{"location":"contributing/guides/great-commits/#enhanced-git-blame","title":"Enhanced git blame","text":"<p>Clear commit messages can be very useful for understanding certain parts of the code. Git provides a tool called <code>git blame</code>, which can show you which commit is responsible for adding a specific line into the code-base. From there, you can then take a look at that commit specifically and see it's title &amp; description to further understand that change, along with the rest of the diff to give you proper context for how that line worked with the rest of the code.</p> <p>This can often be a great tool when refactoring, as sometimes it can be quite unclear why something is done the way it is and commits can sometimes help explain that.</p>"},{"location":"contributing/guides/great-commits/#efficient-cherry-picking","title":"Efficient cherry picking","text":"<p>In some cases, it can be useful to carry over certain change (commit) from one place to another. This process is called cherry-picking (<code>git cherry-pick</code>), which will copy a commit and apply it's diff elsewhere. With atomic commits, this will often work without any further adjustments, since each commit should itself leave you with a functioning project.</p>"},{"location":"contributing/guides/great-commits/#streamlined-pull-request-reviews","title":"Streamlined pull request reviews","text":"<p>Reviewers can often better understand and verify changes by examining your well-structured commits, improving the review process.</p>"},{"location":"contributing/guides/great-commits/#footnotes","title":"Footnotes","text":"<p>This guide took heavy inspiration from this article: https://itsdrike.com/posts/great-commits/.</p> <p>Quote</p> <p>P.S. It's not plagiarism if the original was written by me :P</p> <p>See the original article's sources for proper attributions.</p>"},{"location":"contributing/guides/precommit/","title":"Pre-commit","text":"Abstract <p>This guide explains what is pre-commit and how to set it up as a git hook that will run automatically before your commits. It also describes how to run pre-commit manually from the CLI, how to skip some or all of the individual checks it performs, what happens when hooks edit files and where it's configuration file is.</p> <p>Now that you've seen the linters, formatters, type-checkers and other tools that we use in the project, you might be wondering whether you're really expected to run all of those commands manually, after each change. And of course, no, you're not, that would be really annoying, and you'd probably also often just forget to do that.</p> <p>So, instead of that, we use a tool called <code>pre-commit</code>, which creates a git hook, that will automatically run before each commit you make. That means each time when you make a commit, all of these tools will run over the code you updated, and if any of these linters detects an issue, the commit will be aborted, and you will see which linter failed, and it's output telling you why.</p>"},{"location":"contributing/guides/precommit/#installing-pre-commit","title":"Installing pre-commit","text":"<p>To install pre-commit as a git hook all you need to do is to run:</p> <pre><code>pre-commit install\n</code></pre> <p>This will install pre-commit as a git hook into your git repository, which will mean it will run automatically before every new commit you make.</p> <p>Warning</p> <p>Pre-commit itself will be installed via poetry, which means you will need to have an activated poetry environment whenever you make a new commit, otherwise, the pre-commit git hook will fail with command not found.</p>"},{"location":"contributing/guides/precommit/#hooks-that-modify-files","title":"Hooks that modify files","text":"<p>Sometimes, hooks can end up modifying your files, for example the ruff format hook may do so if your file wasn't already formatted by ruff. When this happens, the hook itself will fail, which will make git abort the commit. At this point, you will be left with the original changes still staged, but some files may have been modified, which means you'll want to <code>git add</code> those again, staging these automatic modifications and then make the commit again.</p> <p>Note that in case you were only committing a partial change, which means you still had some parts of the file unstaged, pre-commit will not modify the files for you. Instead, the hook will just fail, leaving the rest up to you. You should now run the formatter yourself and perform another partial add, updating the staged changes to be compliant.</p>"},{"location":"contributing/guides/precommit/#running-manually","title":"Running manually","text":"<p>Even though in most cases, it will be more than enough to have pre-commit run automatically as a git hook, sometimes, you may want to run it manually without making a commit.</p> <p>Tip</p> <p>You can run this command without having pre-commit installed as a git hook at all. This makes it possible to avoid installing pre-commit and instead running all checks manually each time. That said, we heavily recommend that you instead install pre-commit properly, as it's very easy to forget to run these checks.</p> <p>To run pre-commit manually you can use the following command:</p> <pre><code>pre-commit run --all-files\n</code></pre> <p>Using this command will make pre-commit run on all files within the project, rather than just running against the git staged ones, which is the behavior of the automatically ran hook.</p>"},{"location":"contributing/guides/precommit/#skipping-pre-commit","title":"Skipping pre-commit","text":"<p>Automatic skipping</p> <p>Pre-commit is pretty smart and will skip running certain tools depending on which files you modified. For example some hooks only check the validity of Python code, so if you haven't modified any Python files, there is no need to run those hooks.</p> <p>Even though in most cases enforcing linting before each commit is what we want, there are some situations where we need to commit some code which doesn't pass these checks. This can happen for example after a merge, or as a result of making a single purpose small commit without yet worrying about linters. In these cases, you can use the <code>--no-verify</code> flag when making a commit, telling git to skip the pre-commit hooks and commit normally. When making a commit, this would look like:</p> <pre><code>git commit -m \"My unchecked commit\" --no-verify\n</code></pre> <p>You can also only skip a specific hook, by setting <code>SKIP</code> environmental variable (e.g. <code>SKIP=basedpyright</code>) or even multiple hooks (<code>SKIP=ruff-linter,ruff-formatter,slotscheck</code>). When making a commit, this would look like:</p> <pre><code>SKIP=\"check-toml,slotscheck,basedpyright\" git commit -m \"My partially checked commit\"\n</code></pre> <p>The names of the individual hooks are their ids, you can find those in the configuration file for pre-commit.</p> <p>Warning</p> <p>This kind of verification skipping should be used sparingly. We value a clean history which consistently follows our linting guidelines, and making commits with linting issues only leads to more commits, fixing those issues later.</p>"},{"location":"contributing/guides/precommit/#configuration","title":"Configuration","text":"<p>You can find pre-commit's configuration the <code>.pre-commit-config.yaml</code> file, where we define which tools should be ran and how. Currently, pre-commit runs ruff linter, ruff formatter, slotscheck and basedpyright, but also a checker for some issues in TOML/YAML files.</p>"},{"location":"contributing/guides/setup/","title":"Setting things up","text":"<p>Work In Progress</p> <p>This page is missing a guide on configuring vscode to pick up poetry environment.</p>"},{"location":"contributing/guides/setup/#setting-up-the-project","title":"Setting up the project","text":"Abstract <p>This guide describes the very basics of setting up our project.</p> <p>It explains how to use <code>poetry</code> to install the python dependencies for the project. After which it goes over using poetry (activating the virtual environment, keeping the dependencies up to date as we update them, adding / removing dependencies and poetry dependency group).</p>"},{"location":"contributing/guides/setup/#pre-requisites","title":"Pre-requisites","text":"<p>A basic knowledge of git and GitHub, alongside working within the terminal and running commands is a requirement to work on this project.</p> <p>This guide assumes you have already forked our repository, clonned it to your computer and created your own git branch to work on.</p> <p>If you wish to work from an already forked repository, make sure to check out the main branch and do a <code>git pull</code> to get your fork up to date. Now create your new branch.</p>"},{"location":"contributing/guides/setup/#poetry","title":"Poetry","text":"<p>This project uses <code>poetry</code>. Poetry is a tool for managing python dependencies in a reproducible way, ensuring that everyone is using the same versions. It creates virtual environments for each project, which ensures that your global dependencies won't clash with the project.</p> More about virtual environments <p>A python virtual environment is essentially a separate mini installation of python used purely for the project you're working on (as opposed to using your system-wide python installation for everything).</p> <p>The reason we do this is to avoid dependency conflicts. Consder this: Our project needs library \"foo\" at version 2.5.2, however, you also have another unrelated project, that also needs the \"foo\" library, but this project didn't yet update this dependency, and requires an older version of this library: 1.2.0. This is a problem, because our project won't work with a version that old, we're using some of the new features of that library, similarly, your project won't work with a newer version though.</p> <p>With a virtual environment, both projects will have their own isolated python installation, that only contains the dependencies listed for that project, avoiding any conflicts completely.</p> <p>You can create virtual environments manually, with the built-in <code>venv</code> python module, but poetry makes this much simpler. If you want to find out more about virutal environments, check the official python documentation.</p> <p>This means you will need to have poetry installed on your system to run our project. To do so, just follow their official documentation.</p>"},{"location":"contributing/guides/setup/#dependency-installation","title":"Dependency installation","text":"<p>Once installed, you will want to create a new environment for our project, with all of our dependencies installed. Open a terminal in the project's directory and run the following command:</p> <pre><code>poetry install\n</code></pre> <p>After running this command, the virtual environment will be populated with all of the dependencies that you will need for running &amp; developing the project.</p>"},{"location":"contributing/guides/setup/#activating-the-environment","title":"Activating the environment","text":"<p>The virtual environment that you just created will contain a bunch of executable programs, such as <code>ruff</code> (our linter). One of those executable programs is also <code>python</code>, which is the python interpreter for this environment, capable of using all of those dependencies installed in that environment.</p> <p>By default, when you run the <code>python</code> command, your machine will use the system-wide python installation though and the executables present in this environment will not be runnable at all. In order to make your terminal use the programs from this environment, instead of the global ones, you will need to \"activate\" the environment.</p> <p>Some IDEs/editors are capable of doing this automatically when you open the project, if your editor supports that, you should configure it to do so.</p> Configuring VSCode to use the poetry environment <p>TODO</p> <p>If your IDE doesn't have that option, or you just wish to work from the terminal, you can instead run:</p> <pre><code>poetry shell\n</code></pre> <p>Now you can start the IDE from your terminal, which should make it work within the poetry python environment.</p> <p>Execute a single command inside the virtual environment</p> <p>If you just want to urn a single command from the venv, without necessarily having to activate the environment (often useful in scripts), poetry provides a quick and simple way to do so. All you need to do is prefix any such command with <code>poetry run</code> (e.g. <code>poetry run ruff</code>).</p>"},{"location":"contributing/guides/setup/#keeping-your-dependencies-up-to-date","title":"Keeping your dependencies up to date","text":"<p>We often update the dependencies of mcproto to keep them up to date. Whenever we make such an update, you will need to update your virtual environment to prevent it from going out of date. An out of date environment could mean that you're using older versions of some libraries and what will run on your machine might not match what will run on other machines with the dependencies updated.</p> <p>Thankfully, poetry makes updating the dependencies very easy as all you have to do is re-run the installation command:</p> <pre><code>poetry install\n</code></pre> <p>It can sometimes be hard to know when you need to run the install command, in most cases, even if we did update something and you're still on an older version, nothing significant will actually happen, however, the moment you start seeing some errors when you try to run the project, or inconsistencies with the continuous integration workflows from your local runs, it's a good indication that your dependencies are probably out of date.</p> <p>Ideally, you should run this command as often as possible, if there aren't any new changes, it will simply exit instantly. You should be especially careful when switching git branches, as dependencies might have been changed (most likely a new dependency was introduced, or an old one got removed), so consider running this command whenever you switch to another branch, unless you know that branch didn't make any changes to the project dependencies.</p>"},{"location":"contributing/guides/setup/#poetry-dependency-groups","title":"Poetry dependency groups","text":"<p>Poetry has a really cool way of splitting up the dependencies that projects need into multiple groups. For example, you can have a group of dependencies for linting &amp; autoformatting, another group for documentation support, unit-testing, for releasing the project, etc.</p> <p>To see which dependencies belong to which group, you can check the <code>pyproject.toml</code> file for the <code>[tool.poetry.group.GROUP_NAME.dependencies]</code> sections.</p> <p>By default, <code>poetry install</code> will install all non-optional dependency groups. That means all development dependencies you should need will get installed.</p> <p>The reason why we use groups is because in some of our automated workflows, we don't always need all of the project dependencies and we can save time by only installing the group(s) that we need. It also provides a clean way to quickly see which dependencies are being used for what.</p> <p>The most important group is the <code>main</code> group. This group contains all runtime dependencies, which means without these dependencies, the project wouldn't be runnable at all. It is these libraries that will become the dependencies of our library when we make a release on PyPI.</p>"},{"location":"contributing/guides/setup/#installing-dependencies","title":"Installing dependencies","text":"<p>During the development, you may sometimes want to introduce a new library to the project, to do this, you will first need to decide which dependency group it should belong to. To do this, identify whether this new dependency will be required to run the project, or if it's just some tool / utility that's necessary only during the development.</p> <p>If it's a runtime dependency, all you need to do is run:</p> <pre><code>poetry add [name-of-your-dependency]\n</code></pre> <p>This will add the dependency to the <code>main</code> group.</p> <p>However, if you're working with a development dependency, you will want to go over the dependency groups we have (from <code>pyproject.toml</code>) and decide where it should belong. Once you figured that out, you can run:</p> <pre><code>poetry add --group [group-name] [name-of-your-dependency]\n</code></pre> <p>Note</p> <p>Sometimes, it might make sense to include the same dependency in multiple groups. (Though this is usually quite rare.)</p>"},{"location":"contributing/guides/setup/#uninstalling-dependencies","title":"Uninstalling dependencies","text":"<p>Similarly, we sometimes stop needing a certain dependency. Uninstalling is a very similar process to installation. First, find which group you want to remove this dependency from and then run:</p> <pre><code>poetry remove --group [group-name] [name-of-your-dependency]\n</code></pre>"},{"location":"contributing/guides/slotscheck/","title":"Slotscheck","text":"Abstract <p>This page explains how we enforce the proper use of <code>__slots__</code> on our classes with <code>slotscheck</code> tool. We go over what slotted classes, what slotscheck enforces, how to run slotscheck and how to configure it.</p> <p>On top of the tools you already saw (ruff &amp; basedpyright), we also have one more tool that performs static analysis on our code: slotscheck.</p>"},{"location":"contributing/guides/slotscheck/#what-is-slotscheck","title":"What is slotscheck","text":"<p>Slotscheck is a tool that focuses on enforcing proper use of <code>__slots__</code> on classes.</p> What are slotted classes <p>If you aren't familiar with slotted classes, you should check the official documentation. That said, if you just want a quick overview:</p> <ul> <li>Slots allow you to explicitly declare all member attributes of a class (e.g. declaring <code>__slots__ = (\"a\", \"b\")</code>   will make the class instances only contain variables <code>a</code> and <code>b</code>, trying to set any other attribute will result   in an <code>AttributeError</code>).</li> <li>The reason we like using slots is the efficiency they come with. Slotted classes use up less RAM and offer   a faster attribute access.</li> </ul> <p>Example of a slotted class:</p> <pre><code>class FooBar:\n    __slots__ = (\"foo\", \"bar\")\n\n    def __init__(self, foo: str, bar: str) -&gt; None:\n        self.foo = foo\n        self.bar = bar\n\nx = FooBar(\"a\", \"b\")\nprint(x.a, x.b)\nx.c = 5  # AttributeError\n</code></pre> <p>With a low level project like mcproto, efficiency is important and <code>__slots__</code> offer such efficiency at a very low cost (of simply defining them).</p> <p>The purpose of <code>slotscheck</code> is to check that our slotted classes are using <code>__slots__</code> properly, as sometimes, it is easy to make mistakes, which result in losing a lot of the efficiency that slots provide. Issues that slotscheck detects:</p> <ul> <li>Detect broken slots inheritance</li> <li>Detect overlapping slots</li> <li>Detect duplicate slots</li> </ul>"},{"location":"contributing/guides/slotscheck/#how-to-use-slotscheck","title":"How to use slotscheck","text":"<p>To run slotscheck on the codebase, you can use the following command:</p> <pre><code>slotscheck -m mcproto\n</code></pre> <p>Make you have an activated poetry virtual environment and you're in the project's root directory.</p>"},{"location":"contributing/guides/slotscheck/#configuring-slotscheck","title":"Configuring slotscheck","text":"<p>Sometimes, you may want to ignore certain files from being checked. To do so, you can modify the slotscheck configuration in <code>pyproject.toml</code>, under the <code>[tool.slotscheck]</code> option. That said, doing so should be very rare and you should have a very good reason to ignore your file instead of fixing the underlying issue.</p>"},{"location":"contributing/guides/style-guide/","title":"Style Guide","text":"<p>Work In Progress</p> <p>This page is missing a guide on ruff editor integration</p>"},{"location":"contributing/guides/style-guide/#style-guide","title":"Style Guide","text":"Abstract <p>This page describes how we use <code>ruff</code> to enforce a consistent code style in our project.</p> <p>For clarity and readability, adhering to a consistent code style across the whole project is very important. It is not unusual that style adjustments will be requested in pull requests.</p> <p>It is always a good practice to review the style of the existing code-base before and to adhere to that established style before adding something new. That applies even if it isn't the code style you generally prefer. (That said, if you think a code style change of some kind would be justified, feel free to open an issue about it and tell us why.)</p> <p>Quote</p> <p>A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.</p> <p>However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!</p> <p>\u2014 PEP 8, the general Style Guide for Python Code</p> Check out the PEP8 song <p>The Python Discord community have made an amazing song about PEP8, check it out here!</p>"},{"location":"contributing/guides/style-guide/#automatic-linting","title":"Automatic linting","text":"<p>As there is a lot of various code style rules we adhere to in our code base, describing all of them here would take way too long and it would be impossible to remember anyway. For that reason, we use automated tools to help us catch any code style violations automatically.</p> <p>Currently, we use <code>ruff</code> to enforce most of our code style requirements. That said, we do have some other tools that check the correctness of the code, we will describe those later.</p>"},{"location":"contributing/guides/style-guide/#ruff-linter-formatter","title":"Ruff linter &amp; formatter","text":"<p>Ruff is an all-in-one linter &amp; formatter solution, which aims to replace three previously very popular tools into a single package:</p> <ul> <li><code>flake8</code> linter</li> <li><code>isort</code> import sorter</li> <li><code>black</code> auto-formatter</li> </ul> Why pick ruff over the combination of these tools? <p>There were multiple reasons why we chose ruff instead of using the above tools individually, here's just some of them:</p> <ul> <li>Ruff is faster (written in rust! )</li> <li>A single tool is more convenient than 3 separate ones</li> <li>Ruff includes a lot of flake8 plugins with some great lint rules</li> <li>Ruff has a great community and is slowly managing to overtake these individual projects</li> <li>If you're already used to flake8, you'll feel right at home with ruff, it even has the same error codes (mostly)!</li> </ul> <p>You can check the ruff configuration we're using in <code>pyproject.toml</code> file, under the <code>[tool.ruff]</code> category (and it's subcategories). You can find which linter rules are enabled and which we choose to exclude, some file-specific overrides where the rules apply differently and a bunch of other configuration options.</p>"},{"location":"contributing/guides/style-guide/#linter","title":"Linter","text":"<p>To run ruff linter on the code, open the terminal in the project's root directory and run:</p> <pre><code>ruff check .\n</code></pre> <p>Don't forget to activate the poetry virtual environment before running ruff.</p> <p>Ruff is really smart and it can often automatically fix some of the style violations it found. To make ruff do that, you can add the <code>--fix</code> flag to the command:</p> <pre><code>ruff check --fix .\n</code></pre> <p>If you got a rule violation in your code and you don't understand what the rule's purpose is supposed to be / why we enforce it, you can use Ruff to show you some details about that rule. The explanation that ruff will give you will often even contain code examples. To achieve this, simply run:</p> <pre><code>ruff rule [rule-id]\n</code></pre> <p>With the <code>[rule-id]</code> being the rule you're interested in, for example <code>UP038</code>.</p> Use glow to render the markdown syntax from ruff rule command <p>The <code>ruff rule</code> command will output the rule explanation in markdown, however, since you're running this comand in a terminal, there won't be any helpful syntax highlighting for that by default.</p> <p>That's why I'd recommend using a markdown render such as <code>glow</code>. With it, you can pipe the output from ruff into it and have it produce a fancy colored output, that's much easier to read: <code>ruff rule UP038 | glow</code>.</p> <p>Alternatively, you can also find the rules and their description in the ruff documentation.</p>"},{"location":"contributing/guides/style-guide/#formatter","title":"Formatter","text":"<p>On top of being an amazing linter, ruff is also an automatic code formatter. That means ruff can actually make your code follow a proper and style automatically! It will just take your original unformatted (but valid) python code and edit it to meet our configured code style for you.</p> <p>To make ruff format your code, simply run:</p> <pre><code>ruff format .\n</code></pre>"},{"location":"contributing/guides/style-guide/#editor-integration","title":"Editor integration","text":"<p>TODO</p>"},{"location":"contributing/guides/style-guide/#other-style-guidelines","title":"Other style guidelines","text":"<p>While <code>ruff</code> can do a lot, it can't do everything. There are still some guidelines that you will need to read over and apply manually. You will find these guides on the next pages of this documentation.</p>"},{"location":"contributing/guides/type-hints/","title":"Type Hints","text":"Abstract <p>This article explains what python type-hints are, how they can be enforced with the use of type checkers and the type checker of our choice: basedpyright and it's editor integration.</p> <p>Most people only know python as a dynamically typed language, that doesn't offer any kind of type safety. In the very days of python, this was true, however today, things are a bit different. Even though Python on it's own is still a dynamically typed language, it does actually support specifying \"type hints\" which can even be enforced by external tools called \"type checkers\". With those, we can achieve a (mostly) type safe experience while using Python.</p>"},{"location":"contributing/guides/type-hints/#regular-python","title":"Regular python","text":"<p>In regular python, as most people know it, you might end up writing a function like this:</p> <pre><code>def add(x, y):\n  return x + y\n</code></pre> <p>In this code, you have no idea what the type of <code>x</code> and <code>y</code> arguments should be. So, even though you may have intended for this function to only work with numbers (ints), it's actually entirely possible to use it with something else. For example, running <code>add(\"hello\", \"world)</code> will return <code>\"helloworld\"</code> because the <code>+</code> operator works on strings too.</p> <p>The point is, there's nothing telling you what the type of these parameters should be, and that could lead to misunderstandings. Even though in some cases, you can figure out what the type should these variables have purely based on their name alongside the name of the function, in most cases, it's not that easy. It often requires looking through the docs, or going over the actual source code of such function.</p> <p>Annoyingly, python won't even prevent you from passing in types that are definitely incorrect, like: <code>add(1, \"hi\")</code>. Running this would cause a <code>TypeError</code>, but unless you have unit-tests that actually run that code, you won't find out about this bug until it actually causes an issue and at that point, it might already be too late, since your code has crashed a production app.</p> <p>Clearly then, this isn't ideal.</p>"},{"location":"contributing/guides/type-hints/#type-hints_1","title":"Type-Hints","text":"<p>While python doesn't require it, there is in fact a way to add a \"hint\" that indicates what type should a given variable have. So, when we take the function from above, adding type-hints to it would result in something like this:</p> <pre><code>def add(x: int, y: int) -&gt; int:\n  return x + y\n</code></pre> <p>We've now made the types very explicit to the programmer, which means they'll no longer need to spend a bunch of time looking through the implementation of that function, or going through the documentation just to know how to use this function. Instead, the type hints will tell just you.</p> <p>This is incredibly useful, because most editors will be able to pick up these type hints, and show them to you while calling the function, so you know what to pass right away, without even having to look at the function definition where the type-hints are defined.</p> <p>Not only that, specifying a type-hint will greatly improve the development experience in your editor / IDE, because you'll get much better auto-completion. The thing is, if you have a parameter like <code>x</code>, but your editor doesn't know what type it should have, it can't really help you if you start typing <code>x.remove</code>, looking for the <code>removeprefix</code> function. However, if you tell your editor that <code>x</code> is a string (<code>x: str</code>), it will now be able to go through all of the methods that strings have, and show you those that start with <code>remove</code> (being <code>removeprefix</code> and <code>removesuffix</code>).</p> <p>This makes type-hints great at saving you time while developing, even though you have to do some additional work when specifying them.</p>"},{"location":"contributing/guides/type-hints/#runtime-behavior","title":"Runtime behavior","text":"<p>Even though type-hints are a part of the Python language, the interpreter doesn't actually care about them. That means that the interpreter doesn't do any optimizations or checking when you're running your code, even if you have a function like <code>add</code> that we have added type-hints to, code like <code>add(1, \"hi\")</code> will not cause any immediate errors.</p> <p>Most editors are configured very loosely when it comes to type-hints. That means they will show you these hints when you're working with the function, but they won't produce warnings when you pass in the wrong thing. That's why they're called \"type hints\", they're only hints that can help you out, but they aren't actually enforced.</p>"},{"location":"contributing/guides/type-hints/#enforcing-type-hints-type-checkers","title":"Enforcing type hints - Type Checkers","text":"<p>Even though python on it's own indeed doesn't enforce the type-hints you specify, there are tools that can run \"static\" checks against your code. A static check is a check that works with your code in it's textual form. It will read the contents of your python files without actually running that file and analyze it purely based on that text content.</p> <p>Using these tools will allow you to analyze your code for typing mistakes before you ever even run your program. That means having a function call like <code>add(1, \"hi\")</code> anywhere in your code would be detected and reported as an issue.</p> <p>There is a bunch of these tools available for python, but the most common ones are <code>pyright</code> and <code>mypy</code>.</p>"},{"location":"contributing/guides/type-hints/#basedpyright","title":"BasedPyright","text":"<p>The type checker that we use in our code-base is basedpyright. It's a fork of pyright which adds some extra checks and features and focuses more on the open-source community, than the official Microsoft owned Pyright.</p>"},{"location":"contributing/guides/type-hints/#running-basedpyright","title":"Running BasedPyright","text":"<p>To run BasedPyright on the code-base, you can use the following command:</p> <pre><code>basedpyright .\n</code></pre> <p>You will need to run this from an activated poetry environment while in the project's root directory.</p>"},{"location":"contributing/guides/type-hints/#editor-integration","title":"Editor Integration","text":"VSCodeNeovim <p>On vscode, you can simply install the BasedPyright extension from the marketplace.</p> <p>Note that this extension does collide with the commonly used Pylance extension, which is installed automatically alongside the Python extension and provide intellisense for Python. The reason BasedPyright collides with this extension is that Pylance actually uses pyright as a language server in the background, and as we mentioned, basedpyright is an alternative, so using both would cause duplicate errors. This means that you will need to disable Pylance, at least within our codebase.</p> <p>If you're using Neovim, I would recommend setting up LSP (Language Server Protocol) and installing basedpyright, as it has language server support built into it. You can achieve this with the <code>lspconfig</code> plugin. You can then use <code>mason-lspconfig</code> to install <code>basedpyright</code>, or manually configure <code>lspconfig</code> and use your system-wide <code>basedpyright</code> executable.</p>"},{"location":"contributing/guides/type-hints/#great-resources","title":"Great resources","text":"<p>While type hinting might seem very simple from the examples shown above, there is actually a fair bit to it, and if you never worked within a type checked code-base, you should definitely check out some of these resources, which go over the basics.</p> <ul> <li>Getting started with type hints in Python - a   blog post / tutorial by decorator-factory.</li> <li>Basics of static typing - part of the BasedPyright documentation</li> <li>Mypy documentation - very extensive documentation on various typing   concepts. (Some things are mypy focused, but most things will cary over to basedpyright too)</li> <li>Python documentation for the <code>typing</code> module - Python's standard   library contains a <code>typing</code> module, which holds a bunch of useful structures that we often use while working with   type-hints.</li> <li>PEP 484 - formal specification of type hints for the Python langauge</li> </ul>"},{"location":"contributing/guides/unit-tests/","title":"Unit Tests","text":"<p>Work In Progress</p> <p>This page is still being written. The content below (if any) may change.</p>"},{"location":"installation/","title":"Installation","text":""},{"location":"installation/#pypi-stable-version","title":"PyPI (stable) version","text":"<p>Mcproto is available on PyPI and can be installed like any other python library with:</p>  pip poetry rye uv pdm <pre><code>pip install mcproto\n</code></pre> <p>pip is the main package installer for Python.</p> <pre><code>poetry add mcproto\n</code></pre> <p>Poetry is an all-in-one solution for Python project management.</p> <pre><code>rye add mcproto\n</code></pre> <p>Rye is an all-in-one solution for Python project management, written in Rust.</p> <pre><code>uv pip install mcproto\n</code></pre> <p>uv is an ultra fast dependency resolver and package installer, written in Rust.</p> <pre><code>pdm add mcproto\n</code></pre> <p>PDM is an all-in-one solution for Python project management.</p>"},{"location":"installation/#latest-git-version","title":"Latest (git) version","text":"<p>Alternatively, you may want to install the latest available version, which is what you currently see in the <code>main</code> git branch. Although this method will actually work for any branch with a pretty straightforward change.</p> <p>This kind of installation should only be done if you wish to test some new unreleased features and it's likely that you will encounter bugs.</p> <p>That said, since mcproto is still in development, changes can often be made quickly and it can sometimes take a while for these changes to carry over to PyPI. So if you really want to try out that latest feature, this is the method you'll want.</p> <p>To install the latest mcproto version directly from the <code>main</code> git branch, use:</p>  pip poetry rye uv pdm <pre><code>pip install 'mcproto@git+https://github.com/py-mine/mcproto@main'\n</code></pre> <p>pip is the main package installer for Python.</p> <pre><code>poetry add 'git+https://github.com/py-mine/mcproto#main'\n</code></pre> <p>Poetry is an all-in-one solution for Python project management.</p> <pre><code>rye add mcproto --git='https://github.com/py-mine/mcproto' --branch main\n</code></pre> <p>Rye is an all-in-one solution for Python project management, written in Rust.</p> <pre><code>uv pip install 'mcproto@git+https://github.com/py-mine/mcproto@main'\n</code></pre> <p>uv is an ultra fast dependency resolver and package installer, written in Rust.</p> <pre><code>pdm add \"git+https://github.com/py-mine/mcproto@main\"\n</code></pre> <p>PDM is an all-in-one solution for Python project management.</p>"},{"location":"installation/changelog/","title":"Changelog","text":"<p>Major and minor releases also include the changes specified in prior development releases.</p> <p>Tip</p> <p>Feel free to skip the Internal Changes category if you aren't a contributor / core developer of mcproto.</p> <p> Unreleased Changes </p>"},{"location":"installation/changelog/#exec-1--version-v050-215-g3077c-2024-10-20","title":"Version v0.5.0-215-g3077c (2024-10-20)","text":""},{"location":"installation/changelog/#exec-1--features","title":"Features","text":"<ul> <li>#209: Added <code>InvalidPacketContentError</code> exception, raised when deserializing of a specific packet fails. This error inherits from <code>IOError</code>, making it backwards compatible with the original implementation.</li> <li> <p>#257: Added the <code>NBTag</code> to deal with NBT data</p> <ul> <li>The <code>NBTag</code> class is the base class for all NBT tags and provides the basic functionality to serialize and deserialize NBT data from and to a <code>Buffer</code> object.</li> <li>The classes <code>EndNBT</code>, <code>ByteNBT</code>, <code>ShortNBT</code>, <code>IntNBT</code>, <code>LongNBT</code>, <code>FloatNBT</code>, <code>DoubleNBT</code>, <code>ByteArrayNBT</code>, <code>StringNBT</code>, <code>ListNBT</code>, <code>CompoundNBT</code>, <code>IntArrayNBT</code>and <code>LongArrayNBT</code> were added and correspond to the NBT types described in the NBT specification.</li> <li>NBT tags can be created using the <code>NBTag.from_object()</code> method and a schema that describes the NBT tag structure.     Compound tags are represented as dictionaries, list tags as lists, and primitive tags as their respective Python types.     The implementation allows to add custom classes to the schema to handle custom NBT tags if they inherit the <code>:class: NBTagConvertible</code> class.</li> <li>The <code>NBTag.to_object()</code> method can be used to convert an NBT tag back to a Python object. Use include_schema=True to include the schema in the output, and <code>include_name=True</code> to include the name of the tag in the output. In that case the output will be a dictionary with a single key that is the name of the tag and the value is the object representation of the tag.</li> <li>The <code>NBTag.serialize()</code> can be used to serialize an NBT tag to a new <code>Buffer</code> object.</li> <li>The <code>NBTag.deserialize(buffer)</code> can be used to deserialize an NBT tag from a <code>Buffer</code> object.</li> <li>If the buffer already exists, the <code>NBTag.write_to(buffer, with_type=True, with_name=True)</code> method can be used to write the NBT tag to the buffer (and in that case with the type and name in the right format).</li> <li>The <code>NBTag.read_from(buffer, with_type=True, with_name=True)</code> method can be used to read an NBT tag from the buffer (and in that case with the type and name in the right format).</li> <li>The <code>NBTag.value</code> property can be used to get the value of the NBT tag as a Python object.</li> </ul> </li> <li> <p>Added further encryption related fucntions used by servers.</p> </li> <li>Update <code>LoginStart</code> packet to latest protocol version (<code>uuid</code> no longer optional)</li> </ul>"},{"location":"installation/changelog/#exec-1--bugfixes","title":"Bugfixes","text":"<ul> <li>#330: Fix behavior of the <code>mcproto.utils.deprecation</code> module, which was incorrectly always using a fallback version, assuming mcproto is at version 0.0.0. This then could've meant that using a deprecated feature that is past the specified deprecation (removal) version still only resulted in a deprecation warning, as opposed to a full runtime error.</li> </ul>"},{"location":"installation/changelog/#exec-1--documentation-improvements","title":"Documentation Improvements","text":"<ul> <li>#179: Enforce presence of docstrings everywhere with pydocstyle. This also adds docstring to all functions and classes that didn't already have one. Minor improvements for consistency were also made to some existing docstrings.</li> <li>#346: Complete documentation rewrite</li> <li>Add protocol and protocol pages (API reference docs)</li> </ul>"},{"location":"installation/changelog/#exec-1--internal-changes","title":"Internal Changes","text":"<ul> <li>#131: Any overridden methods in any classes now have to explicitly use the <code>typing.override</code> decorator (see PEP 698)</li> <li>#258: Fix readthedocs CI</li> <li>#259: Merge dependabot PRs automatically, if they pass all CI checks.</li> <li>#274: Update ruff<ul> <li>Update ruff version (the version we used was very outdated)</li> <li>Drop isort in favor of ruff's built-in isort module in the linter</li> <li>Drop black in favor of ruff's new built-in formatter</li> <li>Update ruff settings, including adding/enabling some new rule-sets</li> </ul> </li> <li>#285: Add <code>gen_serializable_test</code> function to generate tests for serializable classes, covering serialization, deserialization, validation, and error handling.</li> <li>#285: Rework the <code>Serializable</code> class</li> <li>#286: Update the docstring formatting directive in CONTRIBUTING.md to reflect the formatting practices currently in place.</li> <li> <p>#300: Update CI</p> <ul> <li>Fix CI not running unit tests on python 3.8 (only 3.11)</li> <li>Update to use python 3.12 (in validation and as one of the matrix versions in unit-tests workflow)</li> <li>Trigger and run lint and unit-tests workflows form a single main CI workflow.</li> <li>Only send status embed after the main CI workflow finishes (not for both unit-tests and validation)</li> <li>Use <code>--output-format=github</code> for <code>ruff check</code> in the validation workflow</li> <li>Fix the status-embed workflow</li> </ul> </li> <li> <p>#323: Enable various other ruff rules as a part of switching to blacklist model, where we explicitly disable the rules we don't want, rather than enabling dozens of rule groups individually.</p> </li> <li>#329: - Change the type-checker from <code>pyright</code> to <code>basedpyright</code><ul> <li>BasedPyright is a fork of pyright, which provides some additional typing features and re-implements various proprietary features from the closed-source Pylance vscode extension.</li> <li>Overall, it is very similar to pyright with some bonus stuff on top. However, it does mean all contributors who want proper editor support for the project will need to update their editor settings and add basedpyright. The instructions on how to do this are described in the updated <code>CONTRIBUTING.md</code>.</li> </ul> </li> <li>#347: Fix towncrier after an update (template file isn't ignored by default, so ignore it manually)</li> <li>#379: Remove codeclimate</li> </ul>"},{"location":"installation/changelog/#version-050-2023-08-10","title":"Version 0.5.0 (2023-08-10)","text":""},{"location":"installation/changelog/#breaking-changes","title":"Breaking Changes","text":"<ul> <li> <p>#130: Renamed \"shared_key\" field to \"shared_secret\" in <code>LoginEncryptionPacket</code>, following the official terminology.</p> <ul> <li>This is a breaking change, <code>LoginEncryptionPacket</code>'s <code>__init__</code> method now uses \"shared_secret\" keyword only argument, not \"shared_key\".</li> </ul> </li> <li> <p>#130: The <code>LoginStart</code> packet now contains a (required) UUID field (which can be explicitly set to <code>None</code>).</p> <ul> <li>For some reason, this field was not added when the login packets were introduced initially, and while the UUID field can indeed be omitted in some cases (it is an optional filed), in vast majority of cases, it will be present, and we should absolutely support it.</li> <li>As this is a new required field, the <code>__init__</code> function of <code>LoginStart</code> now also expects this <code>uuid</code> keyword argument to be present, making this a breaking change.</li> </ul> </li> <li> <p>#159: Fix packet compression handling in the interaction methods.</p> <p>This fixes a bug that didn't allow for specifying an exact compression threshold that the server specified in <code>LoginSetCompression</code> packet, and instead only allowing to toggle between compression on/off, which doesn't really work as server doesn't expect compression for packets below that threshold.</p> <ul> <li><code>sync_write_packet</code>, <code>async_write_pakcet</code>, <code>sync_read_packet</code> and <code>async_read_packet</code> functions now take <code>compression_threshold</code> instead of <code>compressed</code> bool flag</li> </ul> </li> <li> <p>#161: <code>LoginEncryptionRequest</code> now uses <code>cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey</code> to hold the public key, instead of just pure <code>bytes</code>. Encoding and decoding of this key happens automatically during serialize/deserialize. This is a breaking change for anyone relying on the <code>public_key</code> field from this packet being <code>bytes</code>, and for anyone initializing this packet directly with <code>__init__</code>, which now expects <code>RSAPublicKey</code> instance instead.</p> </li> </ul>"},{"location":"installation/changelog/#features","title":"Features","text":"<ul> <li>#129: Added a system for handling Minecraft authentication<ul> <li>Yggdrasil system for unmigrated i.e. non-Microsoft accounts (supportng Minecraft accounts, and the really old Mojang accounts)</li> <li>Microsoft OAuth2 system (Xbox live) for migrated i.e. Microsoft accounts</li> </ul> </li> <li>#160: Re-export the packet classes (or any other objects) from the gamestate modules (<code>mcproto.packets.handshaking</code>/<code>mcproto.packets.login</code>/...) directly. Allowing simpler imports (<code>from mcproto.packets.login import LoginStart</code> instead of <code>from mcproto.packets.login.login import LoginStart</code>)</li> <li>#161: Add support for encryption. Connection classes now have <code>enable_encryption</code> method, and some encryption related functions were added into a new <code>mcproto.encryption</code> module.</li> <li>#168: Add multiplayer related functionalities for requesting and checking joins for original (bought) minecraft accounts. This allows us to join online servers.</li> <li>#171: Add <code>Account.check</code> function, to verify that the access token in use is valid, and the data the Account instance has matches the data minecraft API has.</li> </ul>"},{"location":"installation/changelog/#bugfixes","title":"Bugfixes","text":"<ul> <li>#130: <code>LoginEncryptionResponse</code> now includes the <code>server_id</code> field. This field was previously hard-coded to 20 spaces (blank value), which is what all minecraft clients on minecraft 1.7.x or higher do, however with older versions, this field is set to 20 random characters, which we should respect.<ul> <li>This is not a breaking change, as <code>server_id</code> will default to <code>None</code> in <code>LoginEncryptionResponse</code>'s <code>__init__</code>, meaning any existing code utilizing this packet will still work. It is purely an additional option.</li> </ul> </li> <li>#167: Fix packet reading/writing when compression is enabled (use zlib as expected, instead of gzip which we were using before)</li> <li>#170: Preserve the call parameters and overloads in the typing signature of <code>mcproto.packets.packet_map.generate_packet_map</code> function. (This wasn't the case before, since <code>functools.lru_cache</code> doesn't preserve this data). Note that this loses on the typing information about the cache itself, as now it will appear to be a regular uncached function to the type-checker. We deemed this approach better to the alternative of no typing info for call arguments or overloads, but preserving cache info.</li> </ul>"},{"location":"installation/changelog/#documentation-improvements","title":"Documentation Improvements","text":"<ul> <li>#129: Mention lack of synchronous alternatives for certain functions (see issue #128)</li> <li>#139: Add a warning in version guarantees page, explaining pre-release guarantees (breaking changes in minor versions allowed)</li> <li>#141: Move installation instructions from README to Installation docs page</li> <li> <p>#144: Add attributetable internal sphinx extension for showing all attributes and methods for specified classes.</p> <ul> <li>This adds <code>attributetable</code> sphinx directive, which can be used before autodoc directive. This will create the attribute table, which will get dynamically moved right below the class definition from autodoc (using javascript).</li> <li>This extension was implemented by discord.py, this is just re-using that code, with some modifications to fit our code style and to fit the documentation design (furo theme).</li> </ul> </li> <li> <p>Updated contributing guidelines (restructure and rewrite some categories, to make it more readable)</p> </li> </ul>"},{"location":"installation/changelog/#internal-changes","title":"Internal Changes","text":"<ul> <li>#133: Enable enforcement of some optional pyright rules</li> <li>#153: Replace flake8 linter with ruff (mostly equivalent, but much faster and configurable from pyproject.toml)</li> <li> <p>#154: Enforce various new ruff linter rules:</p> <ul> <li>PGH: pygrep-hooks (replaces pre-commit version)</li> <li>PL: pylint (bunch of typing related linter rules)</li> <li>UP: pyupgrade (forces use of the newest possible standards, depending on target version)</li> <li>RET: flake8-return (various linter rules related to function returns)</li> <li>Q: flake8-quotes (always use double quotes)</li> <li>ASYNC: flake8-async (report blocking operations in async functions)</li> <li>INT: flake-gettext (gettext related linting rules)</li> <li>PTH: flake8-use-pathlib (always prefer pathlib alternatives to the os ones)</li> <li>RUF: ruff custom rules (various additional rules created by the ruff linter team)</li> </ul> </li> </ul>"},{"location":"installation/changelog/#version-040-2023-06-11","title":"Version 0.4.0 (2023-06-11)","text":""},{"location":"installation/changelog/#breaking-changes_1","title":"Breaking Changes","text":"<ul> <li>#41: Rename <code>mcproto.packets.abc</code> to <code>mcproto.packets.packet</code></li> <li>#116: Restructure the project, moving to a single protocol version model<ul> <li>This change does NOT have a deprecation period, and will very likely break most existing code-bases. However this change is necessary, as multi-version support was unsustainable (see issue #45 for more details)</li> <li>Any packets and types will no longer be present in versioned folders (mcproto.packets.v757.xxx), but rather be directly in the parent directory (mcproto.packets.xxx).</li> <li>This change doesn't affect manual communication with the server, connection, and basic IO writers/readers remain the same.</li> </ul> </li> </ul>"},{"location":"installation/changelog/#version-030-2023-06-08","title":"Version 0.3.0 (2023-06-08)","text":""},{"location":"installation/changelog/#features_1","title":"Features","text":"<ul> <li>#54: Add support for LOGIN state packets<ul> <li><code>LoginStart</code></li> <li><code>LoginEncryptionRequest</code></li> <li><code>LoginEncryptionResponse</code></li> <li><code>LoginSuccess</code></li> <li><code>LoginDisconnect</code></li> <li><code>LoginPluginRequest</code></li> <li><code>LoginPluginResponse</code></li> <li><code>LoginSetCompression</code></li> </ul> </li> </ul>"},{"location":"installation/changelog/#bugfixes_1","title":"Bugfixes","text":"<ul> <li>#75: Increase the stack level of warnings shown on protocol version fallbacks</li> <li>#113: TCP connections now properly shut down the connection gracefully (TCP FIN)</li> </ul>"},{"location":"installation/changelog/#documentation-improvements_1","title":"Documentation Improvements","text":"<ul> <li>#2: Add Sphinx and basic docs layout</li> <li>#18: Rewrite all docstrings into proper Sphinx format, instead of using markdown.</li> <li>#27: Add changelog page to docs, linking <code>CHANGELOG.md</code>, including unreleased changes from fragments.</li> <li>#28: Use furo theme for the documentation</li> <li>#34: Add version guarantees page</li> <li>#40: Move code of conduct to the docs.</li> <li>Improve readability of the changelog readme (changes/README.md)<ul> <li>Mention taskipy <code>changelog-preview</code> shorthand command</li> <li>Add category headers splitting things up, for better readability</li> <li>Explain how to express multiple changes related to a single goal in a changelog fragment.</li> </ul> </li> <li>Include <code>CHANGELOG.md</code> file in project's distribution files.</li> </ul>"},{"location":"installation/changelog/#internal-changes_1","title":"Internal Changes","text":"<ul> <li>#12: Replace HassanAbouelela setup-python action with ItsDrike/setup-python in CI workflows</li> <li>#17: Start using codeclimate to monitor code coverage and it's changes</li> <li>#35: Add more tests</li> <li>#38: Replace our implementation of <code>SemanticVersion</code> with a community-maintained <code>semantic-version</code> package.</li> <li>#53: Mark all packet classes as <code>typing.final</code>, making the type-checker enforce existence of concrete implementations for all abstract methods.</li> <li>#112: Removed <code>codespell</code> linter. This proved too annoying, especially when we already have a lot of linters here. Spelling mistakes can simply be caught in the review process.</li> <li>#114: Use latest poetry version in CI workflows (remove version lock - at 1.3.1)</li> <li>The <code>documentation</code> category of changelog was renamed to shorter <code>docs</code></li> </ul>"},{"location":"installation/changelog/#version-020-2022-12-30","title":"Version 0.2.0 (2022-12-30)","text":""},{"location":"installation/changelog/#features_2","title":"Features","text":"<ul> <li>#14: Add <code>__slots__</code> to most classes in the project<ul> <li>All connection classes are now slotted</li> <li>Classes in <code>mcproto.utils.abc</code> are now slotted</li> </ul> </li> <li>Separate packet interaction functions into <code>mcproto.packets.interactions</code>, (though they're reexported in   <code>mcproto.packets</code>, so no breaking changes)</li> </ul>"},{"location":"installation/changelog/#bugfixes_2","title":"Bugfixes","text":"<ul> <li>#14: Add missing <code>__slots__</code> to <code>ServerBoundPacket</code> and <code>ClientBoundPacket</code> subclasses, which inherited from slotted   <code>Packet</code>, but didn't themselves define <code>__slots__</code>, causing <code>__dict__</code> to be needlessly created.</li> <li>The error message produced by <code>RequiredParamsABCMixin</code> class when a required no MRO class variable isn't present now   includes a previously missing space, making it more readable.</li> </ul>"},{"location":"installation/changelog/#documentation-improvements_2","title":"Documentation Improvements","text":"<ul> <li>#7: Add and start keeping a changelog, managed by towncrier.</li> <li>#13: Add a security policy.</li> </ul>"},{"location":"installation/changelog/#internal-changes_2","title":"Internal Changes","text":"<ul> <li>#6: Rework deprecation system<ul> <li>Drop support for date-based deprecations, versions work better</li> <li>Provide <code>deprecation_warn</code> function, which emits warnings directly, no need for a decorator</li> <li>Add a <code>SemanticVersion</code> class, supporting version comparisons</li> <li>If the project's version is already higher than the specified deprecation removal version, raise a DeprecationWarning   as a full exception (rather than just a warning).</li> </ul> </li> <li>#7: Add towncrier for managing changelog</li> <li>#14: Add slotscheck, ensuring <code>__slots__</code> are defined properly everywhere.</li> <li>#14: Make <code>typing-extensions</code> a runtime dependency and use it directly, don't rely on <code>if typing.TYPE_CHECKING</code> blocks.</li> <li>#15: Add codespell tool, to automatically find spelling mistakes.</li> <li>Add README file into the <code>tests/</code> folder, explaining how we use unit-tests and some basics of testing.</li> <li>Add <code>CustomMockMixin</code> internal class, inheriting from <code>UnpropagatingMockMixin</code>, but also allowing to use <code>spec_set</code> as   class variable, as it will automatically pass it into <code>__init__</code> of the mock class.</li> <li>Add several new flake8 extensions, and rework flake8 config file</li> <li>Add support for specifying what child mock type to propagate in <code>UnpropagatingMockMixin</code> class (for unit-tests).</li> </ul> <p>The changelog was added during development of 0.2.0, so nothing prior is documented here. Try checking the GitHub releases, or git commit history directly.</p>"},{"location":"installation/version-guarantees/","title":"Version Guarantees","text":"<p>Pre-release phase</p> <p>Mcproto is currently in the pre-release phase (pre v1.0.0). During this phase, these guarantees will NOT be followed! This means that breaking changes can occur in minor version bumps. That said, micro version bumps are still strictly for bugfixes, and will not include any features or breaking changes.</p> <p>This library follows semantic versioning model, which means the major version is updated every time there is an incompatible (breaking) change made to the public API. However due to the fairly dynamic nature of Python, it can be hard to discern what can be considered a breaking change, and what isn't.</p> <p>First thing to keep in mind is that breaking changes only apply to publicly documented functions and classes. If it's not listed in the documentation here, it's an internal feature, that isn't considered a part of the public API, and thus is bound to change. This includes documented attributes that start with an underscore and documented API that is explicitly marked as internal.</p> <p>Note</p> <p>The examples below are non-exhaustive.</p>"},{"location":"installation/version-guarantees/#examples-of-breaking-changes","title":"Examples of Breaking Changes","text":"<ul> <li>Changing the default parameter value of a function to something else.</li> <li>Renaming (or removing) a function without an alias to the old function.</li> <li>Adding or removing parameters of a function.</li> <li>Removing deprecated alias to a renamed function.</li> </ul>"},{"location":"installation/version-guarantees/#examples-of-non-breaking-changes","title":"Examples of Non-Breaking Changes","text":"<ul> <li>Changing function's name, while providing a deprecated alias.</li> <li>Renaming (or removing) private underscored attributes.</li> <li>Adding an element into <code>__slots__</code> of a data class.</li> <li>Changing the behavior of a function to fix a bug.</li> <li>Changes in the typing definitions of the public API.</li> <li>Changes in the documentation.</li> <li>Modifying the internal protocol connection handling.</li> <li>Updating the dependencies to a newer version, major or otherwise.</li> </ul>"},{"location":"reference/private/","title":"Private API Reference","text":"<p>This is the reference documentation page for private mcproto API.</p> <p>Warning</p> <p>Private here means that the functions/classes documented here are only meant to be used internally by the library, you shouldn't use these in your code if you're just a user of this library. This page is here mainly as a reference for contributors and for providing proper linkable references. The backwards compatibility of these components will not be guarranteed, which means breaking changes may be introduced between patch versinos without any warnings.</p>"},{"location":"reference/private/abc/","title":"Utility Abstract Base Classes","text":"<p>These are some internal ABC classes that we utilize in various places.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.RequiredParamsABCMixin","title":"mcproto.utils.abc.RequiredParamsABCMixin","text":"<p>Mixin class to ABCs that require certain attributes to be set in order to allow initialization.</p> <p>This class performs a similar check to what :class:<code>~abc.ABC</code> already does with abstractmethods, but for class variables. The required class variable names are set with :attr:<code>._REQUIRED_CLASS_VARS</code> class variable, which itself is automatically required.</p> <p>Just like with ABCs, this doesn't prevent creation of classes without these required class vars defined, only initialization is prevented. This is done to allow creation of a more specific, but still abstract class.</p> <p>Additionally, you can also define :attr:<code>._REQUIRED_CLASS_VARS_NO_MRO</code> class var, holding names of class vars which should be defined on given class directly. That means inheritance will be ignored so even if a subclass defines the required class var, unless the latest class also defines it, this check will fail.</p> <p>This is often useful for classes that are expected to be slotted, as each subclass will need to define <code>__slots__</code>, otherwise a <code>__dict__</code> will automatically be made for it. However this is entirely optional, and if :attr:<code>._REQUIRED_CLASS_VARS_NO_MRO</code> isn't set, this check is skipped.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.RequiredParamsABCMixin.__new__","title":"mcproto.utils.abc.RequiredParamsABCMixin.__new__","text":"<pre><code>__new__(*a: Any, **kw: Any) -&gt; Self\n</code></pre> <p>Enforce required parameters being set for each instance of the concrete classes.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable","title":"mcproto.utils.abc.Serializable","text":"<p>               Bases: <code>ABC</code></p> <p>Base class for any type that should be (de)serializable into/from :class:<code>~mcproto.Buffer</code> data.</p> <p>Any class that inherits from this class and adds parameters should use the :func:<code>~mcproto.utils.abc.define</code> decorator.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.__attrs_post_init__","title":"mcproto.utils.abc.Serializable.__attrs_post_init__","text":"<pre><code>__attrs_post_init__() -&gt; None\n</code></pre> <p>Run the validation method after the object is initialized.</p> <p>This function is responsible for conversion/transformation of given values right after initialization (often for example to convert an int initialization param into a specific enum variant)</p> <p>.. note::     If you override this method, make sure to call the superclass method at some point to ensure that the     validation is run.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.deserialize","title":"mcproto.utils.abc.Serializable.deserialize  <code>abstractmethod</code> <code>classmethod</code>","text":"<pre><code>deserialize(buf: Buffer) -&gt; Self\n</code></pre> <p>Construct the object from a :class:<code>~mcproto.Buffer</code> (transmittable sequence of bytes).</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.serialize","title":"mcproto.utils.abc.Serializable.serialize","text":"<pre><code>serialize() -&gt; Buffer\n</code></pre> <p>Represent the object as a :class:<code>~mcproto.Buffer</code> (transmittable sequence of bytes).</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.serialize_to","title":"mcproto.utils.abc.Serializable.serialize_to  <code>abstractmethod</code>","text":"<pre><code>serialize_to(buf: Buffer) -&gt; None\n</code></pre> <p>Write the object to a :class:<code>~mcproto.Buffer</code>.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.validate","title":"mcproto.utils.abc.Serializable.validate","text":"<pre><code>validate() -&gt; None\n</code></pre> <p>Validate the object's attributes, raising an exception if they are invalid.</p> <p>By default, this method does nothing. Override it in your subclass to add validation logic.</p> <p>.. note::     This method is called by :meth:<code>~mcproto.utils.abc.Serializable.__attrs_post_init__</code></p>"},{"location":"reference/private/authentication/","title":"Internal components for authentication","text":"<p>These are the utility components related to / used in the authentication module.</p>"},{"location":"reference/private/authentication/#mcproto.auth.msa.MSAAccount","title":"mcproto.auth.msa.MSAAccount","text":"<p>               Bases: <code>Account</code></p> <p>Minecraft account logged into using Microsoft OAUth2 auth system.</p>"},{"location":"reference/private/authentication/#mcproto.auth.msa.MSAAccount._get_access_token_from_xbox","title":"mcproto.auth.msa.MSAAccount._get_access_token_from_xbox  <code>async</code> <code>staticmethod</code>","text":"<pre><code>_get_access_token_from_xbox(client: AsyncClient, user_hash: str, xsts_token: str) -&gt; str\n</code></pre> <p>Obtain access token from an XSTS token from Xbox Live auth (for Microsoft accounts).</p>"},{"location":"reference/private/deprecation/","title":"Deprecation utilities","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated","title":"mcproto.utils.deprecation.deprecated","text":"<pre><code>deprecated(removal_version: str | Version, display_name: str | None = None, replacement: str | None = None, extra_msg: str | None = None) -&gt; DecoratorFunction\n</code></pre> <p>Mark an object as deprecated.</p> <p>Decorator version of :func:<code>.deprecation_warn</code> function.</p> <p>If the currently installed project version is already past the specified deprecation version, a :exc:<code>DeprecationWarning</code> will be raised as a full exception. Otherwise it will just get emitted as a warning.</p> <p>The deprecation message used will be constructed based on the input parameters.</p> <p>Parameters:</p> Name Type Description Default <code>str | None</code> <p>Name of the object that got deprecated (such as <code>my_function</code>).  By default, the object name is obtained automatically from <code>__qualname__</code> (falling back to <code>__name__</code>) of the decorated object. Setting this explicitly will override this obtained name and the <code>display_name</code> will be used instead.</p> <code>None</code> <code>str | Version</code> <p>Version at which this object should be considered as deprecated and should no longer be used.</p> required <code>str | None</code> <p>A new alternative to this (now deprecated) object.</p> <code>None</code> <code>str | None</code> <p>Additional message included in the deprecation warning/exception at the end.</p> <code>None</code>"},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(display_name)","title":"<code>display_name</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(removal_version)","title":"<code>removal_version</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(replacement)","title":"<code>replacement</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(extra_msg)","title":"<code>extra_msg</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn","title":"mcproto.utils.deprecation.deprecation_warn","text":"<pre><code>deprecation_warn(*, obj_name: str, removal_version: str | Version, replacement: str | None = None, extra_msg: str | None = None, stack_level: int = 3) -&gt; None\n</code></pre> <p>Produce an appropriate deprecation warning given the parameters.</p> <p>If the currently installed project version is already past the specified deprecation version, a :exc:<code>DeprecationWarning</code> will be raised as a full exception. Otherwise it will just get emitted as a warning.</p> <p>The deprecation message used will be constructed based on the input parameters.</p> <p>Parameters:</p> Name Type Description Default <code>str</code> <p>Name of the object that got deprecated (such as <code>my_function</code>).</p> required <code>str | Version</code> <p>Version at which this object should be considered as deprecated and should no longer be used.</p> required <code>str | None</code> <p>A new alternative to this (now deprecated) object.</p> <code>None</code> <code>str | None</code> <p>Additional message included in the deprecation warning/exception at the end.</p> <code>None</code> <code>int</code> <p>Stack level at which the warning is emitted.</p> <code>3</code>"},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(obj_name)","title":"<code>obj_name</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(removal_version)","title":"<code>removal_version</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(replacement)","title":"<code>replacement</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(extra_msg)","title":"<code>extra_msg</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(stack_level)","title":"<code>stack_level</code>","text":""},{"location":"reference/private/protocol/","title":"Internal components for protocol","text":"<p>These are the utility components related to / used in the protocol module.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.utils.from_twos_complement","title":"mcproto.protocol.utils.from_twos_complement","text":"<pre><code>from_twos_complement(number: int, bits: int) -&gt; int\n</code></pre> <p>Convert a given <code>number</code> from twos complement format of given amount of <code>bits</code>.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>Given <code>number</code> doesn't fit into given amount of <code>bits</code>. This likely means that you're using the wrong number, or that the number was converted into twos complement with higher amount of <code>bits</code>.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.utils.to_twos_complement","title":"mcproto.protocol.utils.to_twos_complement","text":"<pre><code>to_twos_complement(number: int, bits: int) -&gt; int\n</code></pre> <p>Convert a given <code>number</code> into twos complement format of given amount of <code>bits</code>.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>Given <code>number</code> is out of range, and can't be converted into twos complement format, since it wouldn't fit into the given amount of <code>bits</code>.</p>"},{"location":"reference/private/types/","title":"Internal components for types","text":"<p>These are the utility components related to / used in the types module.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._FloatingNBTag","title":"mcproto.types.nbt._FloatingNBTag","text":"<p>               Bases: <code>NBTag</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for NBT tags representing a floating-point number.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._NumberArrayNBTag","title":"mcproto.types.nbt._NumberArrayNBTag","text":"<p>               Bases: <code>NBTag</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for NBT tags representing an array of numbers.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._NumberNBTag","title":"mcproto.types.nbt._NumberNBTag","text":"<p>               Bases: <code>NBTag</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for NBT tags representing a number.</p> <p>This class is not meant to be used directly, but rather through its subclasses.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._get_tag_type","title":"mcproto.types.nbt._get_tag_type","text":"<pre><code>_get_tag_type(tag: NBTag | type[NBTag]) -&gt; NBTagType\n</code></pre> <p>Get the tag type of an NBTag object or class.</p>"},{"location":"reference/public/authentication/","title":"Authentication","text":""},{"location":"reference/public/authentication/#mcproto.auth.account.Account","title":"mcproto.auth.account.Account","text":"<p>Base class for an authenticated Minecraft account.</p>"},{"location":"reference/public/authentication/#mcproto.auth.account.Account.check","title":"mcproto.auth.account.Account.check  <code>async</code>","text":"<pre><code>check(client: AsyncClient) -&gt; None\n</code></pre> <p>Check with minecraft API whether the account information stored is valid.</p> <p>Raises:</p> Type Description <code>MismatchedAccountInfoError</code> <p>If the information received from the minecraft API didn't match the information currently stored in the account instance.</p> <code>InvalidAccountAccessTokenError</code> <p>If the access token is not valid.</p>"},{"location":"reference/public/authentication/#mcproto.auth.account.InvalidAccountAccessTokenError","title":"mcproto.auth.account.InvalidAccountAccessTokenError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when the access token of the account was reported as invalid.</p>"},{"location":"reference/public/authentication/#mcproto.auth.account.MismatchedAccountInfoError","title":"mcproto.auth.account.MismatchedAccountInfoError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when info stored in the account instance doesn't match one from API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiError","title":"mcproto.auth.yggdrasil.AuthServerApiError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the authserver API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiError.msg","title":"mcproto.auth.yggdrasil.AuthServerApiError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiErrorType","title":"mcproto.auth.yggdrasil.AuthServerApiErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the authserver API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiErrorType.from_status_error","title":"mcproto.auth.yggdrasil.AuthServerApiErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(code: int, short_msg: str, full_msg: str, cause_msg: str | None) -&gt; AuthServerApiErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount","title":"mcproto.auth.yggdrasil.YggdrasilAccount","text":"<p>               Bases: <code>Account</code></p> <p>Minecraft account logged into using Yggdrasil (legacy/unmigrated) auth system.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.authenticate","title":"mcproto.auth.yggdrasil.YggdrasilAccount.authenticate  <code>async</code> <code>classmethod</code>","text":"<pre><code>authenticate(client: AsyncClient, login: str, password: str) -&gt; Self\n</code></pre> <p>Authenticate using the Yggdrasil system (for non-Microsoft accounts).</p> <p>Parameters:</p> Name Type Description Default <code>str</code> <p>E-Mail of your Minecraft account, or username for (really old) Mojang accounts.</p> required <code>str</code> <p>Plaintext account password.</p> required"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.authenticate(login)","title":"<code>login</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.authenticate(password)","title":"<code>password</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.refresh","title":"mcproto.auth.yggdrasil.YggdrasilAccount.refresh  <code>async</code>","text":"<pre><code>refresh(client: AsyncClient) -&gt; None\n</code></pre> <p>Refresh the Yggdrasil access token.</p> <p>This method can be called when the access token expires, to obtain a new one without having to go through a complete re-login. This can happen after some time period, or for example when someone else logs in to this minecraft account elsewhere.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.signout","title":"mcproto.auth.yggdrasil.YggdrasilAccount.signout  <code>async</code>","text":"<pre><code>signout(client: AsyncClient, username: str, password: str) -&gt; None\n</code></pre> <p>Sign out using the Yggdrasil system (for non-Microsoft accounts).</p> <p>Parameters:</p> Name Type Description Default <p>E-Mail of your Minecraft account, or username for (really old) Mojang accounts.</p> required <code>str</code> <p>Plaintext account password.</p> required"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.signout(login)","title":"<code>login</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.signout(password)","title":"<code>password</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.validate","title":"mcproto.auth.yggdrasil.YggdrasilAccount.validate  <code>async</code>","text":"<pre><code>validate(client: AsyncClient) -&gt; bool\n</code></pre> <p>Check if the access token is (still) usable for authentication with a Minecraft server.</p> <p>If this method fails, the stored access token is no longer usable for for authentcation with a Minecraft server, but should still be good enough for :meth:<code>refresh</code>.</p> <p>This mainly happens when one has used another client (e.g. another launcher).</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.MSAAccount","title":"mcproto.auth.msa.MSAAccount","text":"<p>               Bases: <code>Account</code></p> <p>Minecraft account logged into using Microsoft OAUth2 auth system.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.MSAAccount.from_xbox_access_token","title":"mcproto.auth.msa.MSAAccount.from_xbox_access_token  <code>async</code> <code>classmethod</code>","text":"<pre><code>from_xbox_access_token(client: AsyncClient, access_token: str) -&gt; Self\n</code></pre> <p>Construct the account from the xbox access token, using it to get the rest of the profile information.</p> <p>See :meth:<code>_get_access_token_from_xbox</code> for how to obtain the <code>access_token</code>. Note that in most cases, you'll want to use :meth:<code>xbox_auth</code> rather than this method directly.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.MSAAccount.xbox_auth","title":"mcproto.auth.msa.MSAAccount.xbox_auth  <code>async</code> <code>classmethod</code>","text":"<pre><code>xbox_auth(client: AsyncClient, user_hash: str, xsts_token: str) -&gt; Self\n</code></pre> <p>Authenticate using an XSTS token from Xbox Live auth (for Microsoft accounts).</p> <p>See :func:<code>mcproto.auth.microsoft.xbox.xbox_auth</code> for how to obtain the <code>user_hash</code> and <code>xsts_token</code>.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIError","title":"mcproto.auth.msa.ServicesAPIError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the Minecraft services API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIError.msg","title":"mcproto.auth.msa.ServicesAPIError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIErrorType","title":"mcproto.auth.msa.ServicesAPIErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the Minecraft services API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIErrorType.from_status_error","title":"mcproto.auth.msa.ServicesAPIErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(code: int, err_msg: str | None) -&gt; ServicesAPIErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthRequestData","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthRequestData","text":"<p>               Bases: <code>TypedDict</code></p> <p>Data obtained from Microsoft OAuth2 API after making a new authentication request.</p> <p>This data specifies where (URL) we can check with the Microsoft OAuth2 servers for a client confirmation of this authentication request, how often we should check with this server, and when this request expires.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseData","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseData","text":"<p>               Bases: <code>TypedDict</code></p> <p>Data obtained from Microsoft OAuth2 API after a successful authentication.</p> <p>This data contains the access and refresh tokens, giving us the requested account access and the expiry information.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the Microsoft OAuth2 API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError.msg","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the Microsoft OAuth2 API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType.from_status_error","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(error: str) -&gt; MicrosoftOauthResponseErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.full_microsoft_oauth","title":"mcproto.auth.microsoft.oauth.full_microsoft_oauth  <code>async</code>","text":"<pre><code>full_microsoft_oauth(client: AsyncClient, client_id: str) -&gt; MicrosoftOauthResponseData\n</code></pre> <p>Perform full Microsoft Oauth2 sequence, waiting for user to authenticated (from the browser).</p> <p>See :func:<code>microsoft_oauth_request</code> (OAuth2 start) and :func:<code>microsoft_oauth_authenticate</code> (OAuth2 end).</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.microsoft_oauth_authenticate","title":"mcproto.auth.microsoft.oauth.microsoft_oauth_authenticate  <code>async</code>","text":"<pre><code>microsoft_oauth_authenticate(client: AsyncClient, client_id: str, device_code: str) -&gt; MicrosoftOauthResponseData\n</code></pre> <p>Complete Microsoft Oauth2 flow and authenticate.</p> <p>This functon should be called after :func:<code>microsoft_oauth_request</code>. If the user has authorized the request, we will get an access token back, allowing us to perform certain actions on behaf of the microsoft user that has authorized this request. Alternatively, this function will fal with :exc:<code>MicrosoftOauthResponseError</code>.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.microsoft_oauth_request","title":"mcproto.auth.microsoft.oauth.microsoft_oauth_request  <code>async</code>","text":"<pre><code>microsoft_oauth_request(client: AsyncClient, client_id: str) -&gt; MicrosoftOauthRequestData\n</code></pre> <p>Initiate Microsoft Oauth2 flow.</p> <p>This requires a <code>client_id</code>, which can be obtained by creating an application on <code>Microsoft Azure &lt;https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app&gt;</code>_, with 'Allow public client flows' set to 'Yes' (can be set from the 'Authentication' tab).</p> <p>This will create a device id, used to identify our request and a user code, which the user can manually enter to https://www.microsoft.com/link and confirm, after that, :func:<code>microsoft_oauth_authenticate</code> should be called, with the returend device id as an argument.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSErrorType","title":"mcproto.auth.microsoft.xbox.XSTSErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the Xbox Secure Token Server (XSTS) API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSErrorType.from_status_error","title":"mcproto.auth.microsoft.xbox.XSTSErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(xerr_no: int) -&gt; XSTSErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSRequestError","title":"mcproto.auth.microsoft.xbox.XSTSRequestError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the Xbox Secure Token Server (XSTS) API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSRequestError.msg","title":"mcproto.auth.microsoft.xbox.XSTSRequestError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XboxData","title":"mcproto.auth.microsoft.xbox.XboxData","text":"<p>               Bases: <code>NamedTuple</code></p> <p>Xbox authentication data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.xbox_auth","title":"mcproto.auth.microsoft.xbox.xbox_auth  <code>async</code>","text":"<pre><code>xbox_auth(client: AsyncClient, microsoft_access_token: str, bedrock: bool = False) -&gt; XboxData\n</code></pre> <p>Authenticate into Xbox Live account and obtain user hash and XSTS token.</p> <p>See :func:<code>~mcproto.auth.microsoft.oauth.full_microsoft_oauth</code> for info on <code>microsoft_access_token</code>.</p>"},{"location":"reference/public/encryption/","title":"Encryption utilities","text":"<p>The following components are used for encryption related interacions (generally needed during the communication with the server, after an encryption request during the login process)</p>"},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret","title":"mcproto.encryption.decrypt_token_and_secret","text":"<pre><code>decrypt_token_and_secret(private_key: RSAPrivateKey, verification_token: bytes, shared_secret: bytes) -&gt; tuple[bytes, bytes]\n</code></pre> <p>Decrypts the verification token and shared secret with the server's private key.</p> <p>Parameters:</p> Name Type Description Default <code>RSAPrivateKey</code> <p>The RSA private key generated by the server</p> required <code>bytes</code> <p>The verification token encrypted and sent by the client</p> required <code>bytes</code> <p>The shared secret encrypted and sent by the client</p> required <p>Returns:</p> Type Description <code>tuple[bytes, bytes]</code> <p>A tuple containing (decrypted token, decrypted secret)</p>"},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret(private_key)","title":"<code>private_key</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret(verification_token)","title":"<code>verification_token</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret","title":"mcproto.encryption.encrypt_token_and_secret","text":"<pre><code>encrypt_token_and_secret(public_key: RSAPublicKey, verification_token: bytes, shared_secret: bytes) -&gt; tuple[bytes, bytes]\n</code></pre> <p>Encrypts the verification token and shared secret with the server's public key.</p> <p>Parameters:</p> Name Type Description Default <code>RSAPublicKey</code> <p>The RSA public key provided by the server</p> required <code>bytes</code> <p>The verification token provided by the server</p> required <code>bytes</code> <p>The generated shared secret</p> required <p>Returns:</p> Type Description <code>tuple[bytes, bytes]</code> <p>A tuple containing (encrypted token, encrypted secret)</p>"},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret(public_key)","title":"<code>public_key</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret(verification_token)","title":"<code>verification_token</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.generate_rsa_key","title":"mcproto.encryption.generate_rsa_key","text":"<pre><code>generate_rsa_key() -&gt; RSAPrivateKey\n</code></pre> <p>Generate a random RSA key pair for server.</p> <p>This key pair will be used for :class:<code>~mcproto.packets.login.login.LoginEncryptionRequest</code> packet, where the client will be sent the public part of this key pair, which will be used to encrypt the shared secret (and verification token) sent in :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet. The server will then use the private part of this key pair to decrypt that.</p> <p>This will be a 1024-bit RSA key pair.</p>"},{"location":"reference/public/encryption/#mcproto.encryption.generate_shared_secret","title":"mcproto.encryption.generate_shared_secret","text":"<pre><code>generate_shared_secret() -&gt; bytes\n</code></pre> <p>Generate a random shared secret for client.</p> <p>This secret will be sent to the server in :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet, and used to encrypt all future communication afterwards.</p> <p>This will be symetric encryption using AES/CFB8 stream cipher. And this shared secret will be 16-bytes long.</p>"},{"location":"reference/public/encryption/#mcproto.encryption.generate_verify_token","title":"mcproto.encryption.generate_verify_token","text":"<pre><code>generate_verify_token() -&gt; bytes\n</code></pre> <p>Generate a random verify token.</p> <p>This token will be sent by the server in :class:<code>~mcproto.packets.login.login.LoginEncryptionRequest</code>, to be encrypted by the client as a form of verification.</p> <p>This token doesn't need to be cryptographically secure, it's just a sanity check that the client has encrypted the data correctly.</p>"},{"location":"reference/public/multiplayer/","title":"Multiplayer utilities","text":"<p>The following components are used for various multiplayer interacions (generally needed during the server joining process).</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.JoinAcknowledgeData","title":"mcproto.multiplayer.JoinAcknowledgeData","text":"<p>               Bases: <code>TypedDict</code></p> <p>Response from :func:<code>join_check</code> (hasJoined minecraft API endpoint).</p> <p>This response contains information on the user has submitted the :func:<code>join_request</code>. (uuid, name, and player skin properties)</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.JoinAcknowledgeProperty","title":"mcproto.multiplayer.JoinAcknowledgeProperty","text":"<p>               Bases: <code>TypedDict</code></p> <p>Skin blob data from :class:<code>JoinAcknowledgeData</code>.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinCheckFailedError","title":"mcproto.multiplayer.UserJoinCheckFailedError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when :func:<code>join_check</code> fails.</p> <p>This signifies that the Minecraft session API server didn't contain a join request for the <code>server_hash</code> and <code>client_username</code>, and it therefore didn't acknowledge the join.</p> <p>This means the user didn't confirm this join with Minecraft API (didn't call :func:<code>join_request</code>), hence the validity of this account can't be verified. The server should kick the user and end the join flow.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestErrorKind","title":"mcproto.multiplayer.UserJoinRequestErrorKind","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that can occur during :func:<code>join_request</code>.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestErrorKind.from_status_error","title":"mcproto.multiplayer.UserJoinRequestErrorKind.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(code: int, err_msg: str | None) -&gt; UserJoinRequestErrorKind\n</code></pre> <p>Determine the error kind based on the status code and error message.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestFailedError","title":"mcproto.multiplayer.UserJoinRequestFailedError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when :func:<code>join_request</code> fails.</p> <p>This can be caused by various reasons. See: :class:<code>UserJoinRequestErrorKind</code> enum class. The most likely case for this error is invalid authentication token, or the user being banned from multiplayer.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestFailedError.msg","title":"mcproto.multiplayer.UserJoinRequestFailedError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.compute_server_hash","title":"mcproto.multiplayer.compute_server_hash","text":"<pre><code>compute_server_hash(server_id: str, shared_secret: bytes, server_public_key: RSAPublicKey) -&gt; str\n</code></pre> <p>Compute a hash to be sent as 'serverId' field to Mojang session server.</p> <p>This function is used for :func:<code>join_request</code> and :func:<code>join_check</code> functions, which require this hash value.</p> <p>This SHA1 hash is computed based on the <code>server_id</code>, <code>server_public_key</code> and <code>shared_secret</code>. Together, these values ensure that there can't be any middle-man listening in after encryption is established.</p> <p>This is because a middle man/proxy who would want to listed into the encrypted communication would need to know the encryption key (<code>shared_secret</code>). A proxy can capture this key, as the client sends it over to the server in :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet, however it is sent encrypted. The client performs this encryption with a public key, which it got from the server, in :class:<code>mcproto.packets.login.login.LoginEncryptionRequest</code> packet.</p> <p>That mans that for a proxy to be able to actually obtain this shared secret value, it would need to be able to capture the encryption response, and decrypt the shared secret value. That means it would need to send a spoofed version of the encryption request packet, with the server's public key replaced by one that the proxy owns a private key for. This will work, and the proxy could indeed decrypt the sent shared secret now. All it would need to do now is send this shared secret to the server. That's easy, just re-encrypt it with the server's original public key, and send it in a custom encryption request!</p> <p>So then it seems that it's possible to intercept the client-server communication and spy in, and indeed, this will work with offline mode (warez) servers, however with online mode servers, that's where this function comes in!</p> <p>Online mode servers rely on an API server from Mojang's (session server), which the client informs of the join. The server then queries this server for an acknowledgement of this join, and only if this session server confirms that the client did indeed inform it of this join will the server allow this client to join.</p> <p>The trick is, this request to inform the session server of the join can only be performed by the client directly, a proxy can't simulate it, because this request requires a token for the minecraft account, which only the launcher has. The client never sends this token to the server, only to the Mojang's session server, so a proxy wouldn't have it.</p> <p>This join request then contains those 3 variables, one of which being the public key itself, so if the proxy sent a different key, the server would no longer arrive at the same server hash, and the check would fail, so the server wouldn't allow this client to join.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check","title":"mcproto.multiplayer.join_check  <code>async</code>","text":"<pre><code>join_check(client: AsyncClient, client_username: str, server_hash: str, client_ip: str | None = None) -&gt; JoinAcknowledgeData\n</code></pre> <p>Check with the Mojang session server if a join request was made.</p> <p>This function is called by the server in online mode (non-warez), to verify that the joining client really does have an official minecraft account. The client will first inform the server about this join request (:func:<code>join_request</code>), server then runs this check confirming the client is who they say they are.</p> <p>This request should be performed after receiving the after receiving the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet.</p> <p>This request uses a <code>server_hash</code>, this is the value under which the client has submitted their join request, and we'll now be checking for that submission with that same value. This is a hash composed of various values, which together serve as a way to prevent any MITMA (man in the middle attacks). To obtain this hash, see :func:<code>compute_server_hash</code>. This function's docstring also includes description for why and how this prevents a MITMA.</p> <p>Parameters:</p> Name Type Description Default <code>AsyncClient</code> <p>HTTPX async client to make the HTTP request with.</p> required <code>str</code> <p>Must match joining the username of the joining client (case sensitive).  Note: This is the in-game nickname of the selected profile, not Mojang account name (which is never sent to the server). Servers should use the name in \"name\" field which was received in the :class:<code>~mcproto.packets.login.login.LoginStart</code> packet.</p> required <code>str</code> <p>SHA1 hash of the server (see :func:<code>compute_server_hash</code>)</p> required <code>str | None</code> <p>IP address of the connecting player (optional)  Servers only include this when 'prevent-proxy-connections' is set to true in server.properties</p> <code>None</code>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(client)","title":"<code>client</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(client_username)","title":"<code>client_username</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(server_hash)","title":"<code>server_hash</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(client_ip)","title":"<code>client_ip</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request","title":"mcproto.multiplayer.join_request  <code>async</code>","text":"<pre><code>join_request(client: AsyncClient, account: Account, server_hash: str) -&gt; None\n</code></pre> <p>Inform the Mojang session server about this new user join.</p> <p>This function is called by the client, when joining an online mode (non-warez) server. This is required and the server will check that this request was indeed made (:func:<code>join_check</code>).</p> <p>This request should be performed after receiving the :class:<code>~mcproto.packets.login.login.LoginEncryptionRequest</code> packet, but before sending the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code>.</p> <p>Performing this request requires an :class:<code>~mcproto.auth.account.Account</code> instance, as this request is here to ensure that only original Minceraft accounts (officially bought accounts) can join.</p> <p>This request uses a <code>server_hash</code> to identify which server is the client attempting to join. This hash is composed of various values, which together serve as a way to prevent any MITMA (man in the middle attacks). To obtain this hash, see :func:<code>compute_server_hash</code>. This function's docstring also includes description for why and how this prevents a MITMA.</p> <p>Parameters:</p> Name Type Description Default <code>AsyncClient</code> <p>HTTPX async client to make the HTTP request with.</p> required <code>Account</code> <p>Instance of an account containing the minecraft token necessary for this request.</p> required <code>str</code> <p>SHA1 hash of the server (see :func:<code>compute_server_hash</code>)</p> required"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request(client)","title":"<code>client</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request(account)","title":"<code>account</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request(server_hash)","title":"<code>server_hash</code>","text":""},{"location":"reference/public/packets/","title":"Packets","text":""},{"location":"reference/public/packets/#base-classes-and-interaction-functions","title":"Base classes and interaction functions","text":""},{"location":"reference/public/packets/#mcproto.packets.ClientBoundPacket","title":"mcproto.packets.ClientBoundPacket","text":"<p>               Bases: <code>Packet</code></p> <p>Packet bound to a client (Server -&gt; Client).</p>"},{"location":"reference/public/packets/#mcproto.packets.GameState","title":"mcproto.packets.GameState","text":"<p>               Bases: <code>IntEnum</code></p> <p>All possible game states in minecraft.</p>"},{"location":"reference/public/packets/#mcproto.packets.Packet","title":"mcproto.packets.Packet","text":"<p>               Bases: <code>Serializable</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for all packets.</p>"},{"location":"reference/public/packets/#mcproto.packets.PacketDirection","title":"mcproto.packets.PacketDirection","text":"<p>               Bases: <code>IntEnum</code></p> <p>Represents whether a packet targets (is bound to) a client or server.</p>"},{"location":"reference/public/packets/#mcproto.packets.ServerBoundPacket","title":"mcproto.packets.ServerBoundPacket","text":"<p>               Bases: <code>Packet</code></p> <p>Packet bound to a server (Client -&gt; Server).</p>"},{"location":"reference/public/packets/#mcproto.packets.async_read_packet","title":"mcproto.packets.async_read_packet  <code>async</code>","text":"<pre><code>async_read_packet(reader: BaseAsyncReader, packet_map: Mapping[int, type[T_Packet]], *, compression_threshold: int = -1) -&gt; T_Packet\n</code></pre> <p>Read a packet.</p> <p>Parameters:</p> Name Type Description Default <code>BaseAsyncReader</code> <p>The connection/reader to receive this packet from.</p> required <code>Mapping[int, type[T_Packet]]</code> <p>A mapping of packet id (number) -&gt; Packet (class).  This mapping should contain all of the packets for the current gamestate and direction. See :func:<code>~mcproto.packets.packet_map.generate_packet_map</code></p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).  Note that during reading, we don't actually need to know the specific threshold, just whether or not is is non-negative (whether compression is enabled), as the packet format fundamentally changes when it is. That means you can pass any positive number here to enable compresison, regardess of what it actually is.</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.async_read_packet(reader)","title":"<code>reader</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_read_packet(packet_map)","title":"<code>packet_map</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_read_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_write_packet","title":"mcproto.packets.async_write_packet  <code>async</code>","text":"<pre><code>async_write_packet(writer: BaseAsyncWriter, packet: Packet, *, compression_threshold: int = -1) -&gt; None\n</code></pre> <p>Write given <code>packet</code>.</p> <p>Parameters:</p> Name Type Description Default <code>BaseAsyncWriter</code> <p>The connection/writer to send this packet to.</p> required <code>Packet</code> <p>The packet to be sent.</p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.async_write_packet(writer)","title":"<code>writer</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_write_packet(packet)","title":"<code>packet</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_write_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.generate_packet_map","title":"mcproto.packets.generate_packet_map  <code>cached</code>","text":"<pre><code>generate_packet_map(direction: Literal[SERVERBOUND], state: GameState) -&gt; Mapping[int, type[ServerBoundPacket]]\n</code></pre><pre><code>generate_packet_map(direction: Literal[CLIENTBOUND], state: GameState) -&gt; Mapping[int, type[ClientBoundPacket]]\n</code></pre> <pre><code>generate_packet_map(direction: PacketDirection, state: GameState) -&gt; Mapping[int, type[Packet]]\n</code></pre> <p>Dynamically generated a packet map for given <code>direction</code> and <code>state</code>.</p> <p>This generation is done by dynamically importing all of the modules containing these packets, filtering them to only contain those pacekts with the specified parameters, and storing those into a dictionary, using the packet id as key, and the packet class itself being the value.</p> <p>As this fucntion is likely to be called quite often, and it uses dynamic importing to obtain the packet classes, this function is cached, which means the logic only actually runs once, after which, for the same arguments, the same dict will be returned.</p>"},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet","title":"mcproto.packets.sync_read_packet","text":"<pre><code>sync_read_packet(reader: BaseSyncReader, packet_map: Mapping[int, type[T_Packet]], *, compression_threshold: int = -1) -&gt; T_Packet\n</code></pre> <p>Read a packet.</p> <p>Parameters:</p> Name Type Description Default <code>BaseSyncReader</code> <p>The connection/reader to receive this packet from.</p> required <code>Mapping[int, type[T_Packet]]</code> <p>A mapping of packet id (number) -&gt; Packet (class).  This mapping should contain all of the packets for the current gamestate and direction. See :func:<code>~mcproto.packets.packet_map.generate_packet_map</code></p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).  Note that during reading, we don't actually need to know the specific threshold, just whether or not is is non-negative (whether compression is enabled), as the packet format fundamentally changes when it is. That means you can pass any positive number here to enable compresison, regardess of what it actually is.</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet(reader)","title":"<code>reader</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet(packet_map)","title":"<code>packet_map</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet","title":"mcproto.packets.sync_write_packet","text":"<pre><code>sync_write_packet(writer: BaseSyncWriter, packet: Packet, *, compression_threshold: int = -1) -&gt; None\n</code></pre> <p>Write given <code>packet</code>.</p> <p>Parameters:</p> Name Type Description Default <code>BaseSyncWriter</code> <p>The connection/writer to send this packet to.</p> required <code>Packet</code> <p>The packet to be sent.</p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet(writer)","title":"<code>writer</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet(packet)","title":"<code>packet</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#handshaking-gamestate","title":"Handshaking gamestate","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake","title":"mcproto.packets.handshaking.handshake.Handshake","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Initializes connection between server and client. (Client -&gt; Server).</p> <p>Initialize the Handshake packet.</p> <p>Parameters:</p> Name Type Description Default <p>Protocol version number to be used.</p> required <p>The host/address the client is connecting to.</p> required <p>The port the client is connecting to.</p> required <p>The next state for the server to move into.</p> required"},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(protocol_version)","title":"<code>protocol_version</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(server_address)","title":"<code>server_address</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(server_port)","title":"<code>server_port</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(next_state)","title":"<code>next_state</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake.serialize_to","title":"mcproto.packets.handshaking.handshake.Handshake.serialize_to","text":"<pre><code>serialize_to(buf: Buffer) -&gt; None\n</code></pre> <p>Serialize the packet.</p>"},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.NextState","title":"mcproto.packets.handshaking.handshake.NextState","text":"<p>               Bases: <code>IntEnum</code></p> <p>Enum of all possible next game states we can transition to from the :class:<code>Handshake</code> packet.</p>"},{"location":"reference/public/packets/#status-gamestate","title":"Status gamestate","text":""},{"location":"reference/public/packets/#mcproto.packets.status.ping.PingPong","title":"mcproto.packets.status.ping.PingPong","text":"<p>               Bases: <code>ClientBoundPacket</code>, <code>ServerBoundPacket</code></p> <p>Ping request/Pong response (Server &lt;-&gt; Client).</p> <p>Initialize the PingPong packet.</p> <p>Parameters:</p> Name Type Description Default <p>Random number to test out the connection. Ideally, this number should be quite big, however it does need to fit within the limit of a signed long long (-2 ** 63 to 2 ** 63 - 1).</p> required"},{"location":"reference/public/packets/#mcproto.packets.status.ping.PingPong(payload)","title":"<code>payload</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.status.status.StatusRequest","title":"mcproto.packets.status.status.StatusRequest","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Request from the client to get information on the server. (Client -&gt; Server).</p>"},{"location":"reference/public/packets/#mcproto.packets.status.status.StatusResponse","title":"mcproto.packets.status.status.StatusResponse","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Response from the server to requesting client with status data information. (Server -&gt; Client).</p> <p>Initialize the StatusResponse packet.</p> <p>Parameters:</p> Name Type Description Default <p>JSON response data sent back to the client.</p> required"},{"location":"reference/public/packets/#mcproto.packets.status.status.StatusResponse(data)","title":"<code>data</code>","text":""},{"location":"reference/public/packets/#login-gamestate","title":"Login gamestate","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginDisconnect","title":"mcproto.packets.login.login.LoginDisconnect","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to kick a player while in the login state. (Server -&gt; Client).</p> <p>Initialize the LoginDisconnect packet.</p> <p>Parameters:</p> Name Type Description Default <p>The reason for disconnection (kick).</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginDisconnect(reason)","title":"<code>reason</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest","title":"mcproto.packets.login.login.LoginEncryptionRequest","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Used by the server to ask the client to encrypt the login process. (Server -&gt; Client).</p> <p>Initialize the LoginEncryptionRequest packet.</p> <p>Parameters:</p> Name Type Description Default <p>Server's public key.</p> required <p>Sequence of random bytes generated by server for verification.</p> required <p>Empty on minecraft versions 1.7.X and higher (20 random chars pre 1.7).</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest(public_key)","title":"<code>public_key</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest(verify_token)","title":"<code>verify_token</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest(server_id)","title":"<code>server_id</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse","title":"mcproto.packets.login.login.LoginEncryptionResponse","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Response from the client to :class:<code>LoginEncryptionRequest</code> packet. (Client -&gt; Server).</p> <p>Initialize the LoginEncryptionResponse packet.</p> <p>Parameters:</p> Name Type Description Default <p>Shared secret value, encrypted with server's public key.</p> required <p>Verify token value, encrypted with same public key.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse(verify_token)","title":"<code>verify_token</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse.serialize_to","title":"mcproto.packets.login.login.LoginEncryptionResponse.serialize_to","text":"<pre><code>serialize_to(buf: Buffer) -&gt; None\n</code></pre> <p>Serialize the packet.</p>"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest","title":"mcproto.packets.login.login.LoginPluginRequest","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to implement a custom handshaking flow. (Server -&gt; Client).</p> <p>Initialize the LoginPluginRequest.</p> <p>Parameters:</p> Name Type Description Default <p>Message id, generated by the server, should be unique to the connection.</p> required <p>Channel identifier, name of the plugin channel used to send data.</p> required <p>Data that is to be sent.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest(message_id)","title":"<code>message_id</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest(channel)","title":"<code>channel</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest(data)","title":"<code>data</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginResponse","title":"mcproto.packets.login.login.LoginPluginResponse","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Response to LoginPluginRequest from client. (Client -&gt; Server).</p> <p>Initialize the LoginPluginRequest packet.</p> <p>Parameters:</p> Name Type Description Default <p>Message id, generated by the server, should be unique to the connection.</p> required <p>Optional response data, present if client understood request.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginResponse(message_id)","title":"<code>message_id</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginResponse(data)","title":"<code>data</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSetCompression","title":"mcproto.packets.login.login.LoginSetCompression","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to specify whether to use compression on future packets or not (Server -&gt; Client).</p> <p>Initialize the LoginSetCompression packet.</p> <p>Parameters:</p> Name Type Description Default <p>Maximum size of a packet before it is compressed. All packets smaller than this will remain uncompressed. To disable compression completely, threshold can be set to -1.  .. note:: This packet is optional, and if not set, the compression will not be enabled at all.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSetCompression(threshold)","title":"<code>threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginStart","title":"mcproto.packets.login.login.LoginStart","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Packet from client asking to start login process. (Client -&gt; Server).</p> <p>Initialize the LoginStart packet.</p> <p>Parameters:</p> Name Type Description Default <p>Username of the client who sent the request.</p> required <p>UUID of the player logging in (if the player doesn't have a UUID, this can be <code>None</code>)</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginStart(username)","title":"<code>username</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginStart(uuid)","title":"<code>uuid</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSuccess","title":"mcproto.packets.login.login.LoginSuccess","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to denote a successful login. (Server -&gt; Client).</p> <p>Initialize the LoginSuccess packet.</p> <p>Parameters:</p> Name Type Description Default <p>The UUID of the connecting player/client.</p> required <p>The username of the connecting player/client.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSuccess(uuid)","title":"<code>uuid</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSuccess(username)","title":"<code>username</code>","text":""},{"location":"reference/public/packets/#play-gamestate","title":"Play gamestate","text":"<p>Work In Progress</p> <p>Packets for the Play gamestate aren't yet implemented.</p>"},{"location":"reference/public/protocol/","title":"Protocol documentation","text":"<p>This is the documentation for components related to interactions with the minecraft protocol and connection establishing.</p> <p>               Bases: <code>BaseSyncWriter</code>, <code>BaseSyncReader</code>, <code>bytearray</code></p> <p>In-memory bytearray-like buffer supporting the common read/write operations.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader","title":"mcproto.protocol.base_io.BaseAsyncReader","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding asynchronous read buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read","title":"mcproto.protocol.base_io.BaseAsyncReader.read  <code>abstractmethod</code> <code>async</code>","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Underlying read method, obtaining the raw data.</p> <p>All of the reader functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_ascii","title":"mcproto.protocol.base_io.BaseAsyncReader.read_ascii  <code>async</code>","text":"<pre><code>read_ascii() -&gt; str\n</code></pre> <p>Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_bytearray","title":"mcproto.protocol.base_io.BaseAsyncReader.read_bytearray  <code>async</code>","text":"<pre><code>read_bytearray() -&gt; bytearray\n</code></pre> <p>Read an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_optional","title":"mcproto.protocol.base_io.BaseAsyncReader.read_optional  <code>async</code>","text":"<pre><code>read_optional(reader: Callable[[], Awaitable[R]]) -&gt; R | None\n</code></pre> <p>Read a bool showing if a value is present, if so, also reads this value with <code>reader</code> function.</p> <ul> <li>When <code>False</code> is read, the function will not read anything and <code>None</code> is returned.</li> <li>When <code>True</code> is read, the <code>reader</code> function is called, and it's return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_utf","title":"mcproto.protocol.base_io.BaseAsyncReader.read_utf  <code>async</code>","text":"<pre><code>read_utf() -&gt; str\n</code></pre> <p>Read a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be read + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>IOError</code> <ul> <li>If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all, and :exc:<code>IOError</code> will be raised immediately. * If the received string has more than the maximum amount of characters (32767). Note that in this case, the string will still get read in it's entirety, since it fits into the maximum bytes limit (131068), which was simply read at once. This limitation is here only to replicate the behavior of minecraft's implementation.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_value","title":"mcproto.protocol.base_io.BaseAsyncReader.read_value  <code>async</code>","text":"<pre><code>read_value(fmt: INT_FORMATS_TYPE) -&gt; int\n</code></pre><pre><code>read_value(fmt: FLOAT_FORMATS_TYPE) -&gt; float\n</code></pre><pre><code>read_value(fmt: Literal[BOOL]) -&gt; bool\n</code></pre><pre><code>read_value(fmt: Literal[CHAR]) -&gt; str\n</code></pre> <pre><code>read_value(fmt: StructFormat) -&gt; object\n</code></pre> <p>Read a value as given struct format (<code>fmt</code>) in big-endian mode.</p> <p>The amount of bytes to read will be determined based on the struct format automatically.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_varint","title":"mcproto.protocol.base_io.BaseAsyncReader.read_varint  <code>async</code>","text":"<pre><code>read_varint() -&gt; int\n</code></pre> <p>Read a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_varlong","title":"mcproto.protocol.base_io.BaseAsyncReader.read_varlong  <code>async</code>","text":"<pre><code>read_varlong() -&gt; int\n</code></pre> <p>Read a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter","title":"mcproto.protocol.base_io.BaseAsyncWriter","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding asynchronous write buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write","title":"mcproto.protocol.base_io.BaseAsyncWriter.write  <code>abstractmethod</code> <code>async</code>","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Underlying write method, sending/storing the data.</p> <p>All of the writer functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_ascii","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_ascii  <code>async</code>","text":"<pre><code>write_ascii(value: str) -&gt; None\n</code></pre> <p>Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_bytearray","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_bytearray  <code>async</code>","text":"<pre><code>write_bytearray(data: bytes) -&gt; None\n</code></pre> <p>Write an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_optional","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_optional  <code>async</code>","text":"<pre><code>write_optional(value: T | None, /, writer: Callable[[T], Awaitable[R]]) -&gt; R | None\n</code></pre> <p>Write a bool showing if a <code>value</code> is present, if so, also writes this value with <code>writer</code> function.</p> <ul> <li>When <code>value</code> is <code>None</code>, a bool of <code>False</code> will be written, and <code>None</code> is returned.</li> <li>When <code>value</code> is not <code>None</code>, a bool of <code>True</code> is written, after which the <code>writer</code> function is called,   and the return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_utf","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_utf  <code>async</code>","text":"<pre><code>write_utf(value: str) -&gt; None\n</code></pre> <p>Write a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be written + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the given string <code>value</code> has more characters than the allowed maximum (32767).</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_value","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_value  <code>async</code>","text":"<pre><code>write_value(fmt: INT_FORMATS_TYPE, value: int) -&gt; None\n</code></pre><pre><code>write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[BOOL], value: bool) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[CHAR], value: str) -&gt; None\n</code></pre> <pre><code>write_value(fmt: StructFormat, value: object) -&gt; None\n</code></pre> <p>Write a given <code>value</code> as given struct format (<code>fmt</code>) in big-endian mode.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_varint","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_varint  <code>async</code>","text":"<pre><code>write_varint(value: int) -&gt; None\n</code></pre> <p>Write a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_varlong","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_varlong  <code>async</code>","text":"<pre><code>write_varlong(value: int) -&gt; None\n</code></pre> <p>Write a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader","title":"mcproto.protocol.base_io.BaseSyncReader","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding synchronous read buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read","title":"mcproto.protocol.base_io.BaseSyncReader.read  <code>abstractmethod</code>","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Underlying read method, obtaining the raw data.</p> <p>All of the reader functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_ascii","title":"mcproto.protocol.base_io.BaseSyncReader.read_ascii","text":"<pre><code>read_ascii() -&gt; str\n</code></pre> <p>Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_bytearray","title":"mcproto.protocol.base_io.BaseSyncReader.read_bytearray","text":"<pre><code>read_bytearray() -&gt; bytearray\n</code></pre> <p>Read an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_optional","title":"mcproto.protocol.base_io.BaseSyncReader.read_optional","text":"<pre><code>read_optional(reader: Callable[[], R]) -&gt; R | None\n</code></pre> <p>Read a bool showing if a value is present, if so, also reads this value with <code>reader</code> function.</p> <ul> <li>When <code>False</code> is read, the function will not read anything and <code>None</code> is returned.</li> <li>When <code>True</code> is read, the <code>reader</code> function is called, and it's return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_utf","title":"mcproto.protocol.base_io.BaseSyncReader.read_utf","text":"<pre><code>read_utf() -&gt; str\n</code></pre> <p>Read a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be read + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>IOError</code> <ul> <li>If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all, and :exc:<code>IOError</code> will be raised immediately. * If the received string has more than the maximum amount of characters (32767). Note that in this case, the string will still get read in it's entirety, since it fits into the maximum bytes limit (131068), which was simply read at once. This limitation is here only to replicate the behavior of minecraft's implementation.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_value","title":"mcproto.protocol.base_io.BaseSyncReader.read_value","text":"<pre><code>read_value(fmt: INT_FORMATS_TYPE) -&gt; int\n</code></pre><pre><code>read_value(fmt: FLOAT_FORMATS_TYPE) -&gt; float\n</code></pre><pre><code>read_value(fmt: Literal[BOOL]) -&gt; bool\n</code></pre><pre><code>read_value(fmt: Literal[CHAR]) -&gt; str\n</code></pre> <pre><code>read_value(fmt: StructFormat) -&gt; object\n</code></pre> <p>Read a value into given struct format in big-endian mode.</p> <p>The amount of bytes to read will be determined based on the struct format automatically.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_varint","title":"mcproto.protocol.base_io.BaseSyncReader.read_varint","text":"<pre><code>read_varint() -&gt; int\n</code></pre> <p>Read a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_varlong","title":"mcproto.protocol.base_io.BaseSyncReader.read_varlong","text":"<pre><code>read_varlong() -&gt; int\n</code></pre> <p>Read a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter","title":"mcproto.protocol.base_io.BaseSyncWriter","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding synchronous write buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write","title":"mcproto.protocol.base_io.BaseSyncWriter.write  <code>abstractmethod</code>","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Underlying write method, sending/storing the data.</p> <p>All of the writer functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_ascii","title":"mcproto.protocol.base_io.BaseSyncWriter.write_ascii","text":"<pre><code>write_ascii(value: str) -&gt; None\n</code></pre> <p>Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_bytearray","title":"mcproto.protocol.base_io.BaseSyncWriter.write_bytearray","text":"<pre><code>write_bytearray(data: bytes) -&gt; None\n</code></pre> <p>Write an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_optional","title":"mcproto.protocol.base_io.BaseSyncWriter.write_optional","text":"<pre><code>write_optional(value: T | None, /, writer: Callable[[T], R]) -&gt; R | None\n</code></pre> <p>Write a bool showing if a <code>value</code> is present, if so, also writes this value with <code>writer</code> function.</p> <ul> <li>When <code>value</code> is <code>None</code>, a bool of <code>False</code> will be written, and <code>None</code> is returned.</li> <li>When <code>value</code> is not <code>None</code>, a bool of <code>True</code> is written, after which the <code>writer</code> function is called,   and the return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_utf","title":"mcproto.protocol.base_io.BaseSyncWriter.write_utf","text":"<pre><code>write_utf(value: str) -&gt; None\n</code></pre> <p>Write a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be written + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the given string <code>value</code> has more characters than the allowed maximum (32767).</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_value","title":"mcproto.protocol.base_io.BaseSyncWriter.write_value","text":"<pre><code>write_value(fmt: INT_FORMATS_TYPE, value: int) -&gt; None\n</code></pre><pre><code>write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[BOOL], value: bool) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[CHAR], value: str) -&gt; None\n</code></pre> <pre><code>write_value(fmt: StructFormat, value: object) -&gt; None\n</code></pre> <p>Write a given <code>value</code> as given struct format (<code>fmt</code>) in big-endian mode.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_varint","title":"mcproto.protocol.base_io.BaseSyncWriter.write_varint","text":"<pre><code>write_varint(value: int) -&gt; None\n</code></pre> <p>Write a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_varlong","title":"mcproto.protocol.base_io.BaseSyncWriter.write_varlong","text":"<pre><code>write_varlong(value: int) -&gt; None\n</code></pre> <p>Write a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code> docstring.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.StructFormat","title":"mcproto.protocol.base_io.StructFormat","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>All possible write/read struct types.</p> <p>.. seealso:     :module:<code>struct</code> module documentation.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.remaining","title":"mcproto.buffer.Buffer.remaining  <code>property</code>","text":"<pre><code>remaining: int\n</code></pre> <p>Get the amount of bytes that's still remaining in the buffer to be read.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.clear","title":"mcproto.buffer.Buffer.clear","text":"<pre><code>clear(only_already_read: bool = False) -&gt; None\n</code></pre> <p>Clear out the stored data and reset position.</p> <p>Parameters:</p> Name Type Description Default <code>bool</code> <p>When set to <code>True</code>, only the data that was already marked as read will be cleared, and the position will be reset (to start at the remaining data). This can be useful for avoiding needlessly storing large amounts of data in memory, if this data is no longer useful.  Otherwise, if set to <code>False</code>, all of the data is cleared, and the position is reset, essentially resulting in a blank buffer.</p> <code>False</code>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.clear(only_already_read)","title":"<code>only_already_read</code>","text":""},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.flush","title":"mcproto.buffer.Buffer.flush","text":"<pre><code>flush() -&gt; bytearray\n</code></pre> <p>Read all of the remaining data in the buffer and clear it out.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.read","title":"mcproto.buffer.Buffer.read","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Read data stored in the buffer.</p> <p>Reading data doesn't remove that data, rather that data is treated as already read, and next read will start from the first unread byte. If freeing the data is necessary, check the :meth:<code>.clear</code> function.</p> <p>Parameters:</p> Name Type Description Default <code>int</code> <p>Amount of bytes to be read.  If the requested amount can't be read (buffer doesn't contain that much data/buffer doesn't contain any data), an :exc:<code>IOError</code> will be reaised.  If there were some data in the buffer, but it was less than requested, this remaining data will still be depleted and the partial data that was read will be a part of the error message in the :exc:<code>IOError</code>. This behavior is here to mimic reading from a real socket connection.</p> required"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.read(length)","title":"<code>length</code>","text":""},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.reset","title":"mcproto.buffer.Buffer.reset","text":"<pre><code>reset() -&gt; None\n</code></pre> <p>Reset the position in the buffer.</p> <p>Since the buffer doesn't automatically clear the already read data, it is possible to simply reset the position and read the data it contains again.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.write","title":"mcproto.buffer.Buffer.write","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Write/Store given <code>data</code> into the buffer.</p>"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection","title":"mcproto.connection.AsyncConnection","text":"<p>               Bases: <code>BaseAsyncReader</code>, <code>BaseAsyncWriter</code>, <code>ABC</code></p> <p>Base class for all classes handling asynchronous connections.</p>"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.close","title":"mcproto.connection.AsyncConnection.close  <code>async</code>","text":"<pre><code>close() -&gt; None\n</code></pre> <p>Close the connection (it cannot be used after this).</p>"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.enable_encryption","title":"mcproto.connection.AsyncConnection.enable_encryption","text":"<pre><code>enable_encryption(shared_secret: bytes) -&gt; None\n</code></pre> <p>Enable encryption for this connection, using the <code>shared_secret</code>.</p> <p>After calling this method, the reading and writing process for this connection will be altered, and any future communication will be encrypted/decrypted there.</p> <p>You will need to call this method after sending the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet.</p> <p>Parameters:</p> Name Type Description Default <code>bytes</code> <p>This is the cipher key for the AES symetric cipher used for the encryption.  See :func:<code>mcproto.encryption.generate_shared_secret</code>.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.enable_encryption(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.make_client","title":"mcproto.connection.AsyncConnection.make_client  <code>abstractmethod</code> <code>async</code> <code>classmethod</code>","text":"<pre><code>make_client(address: tuple[str, int], timeout: float) -&gt; Self\n</code></pre> <p>Construct a client connection (Client -&gt; Server) to given server <code>address</code>.</p> <p>Parameters:</p> Name Type Description Default <code>tuple[str, int]</code> <p>Address of the server to connection to.</p> required <code>float</code> <p>Amount of seconds to wait for the connection to be established. If connection can't be established within this time, :exc:<code>TimeoutError</code> will be raised. This timeout is then also used for any further data receiving.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.make_client(address)","title":"<code>address</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.make_client(timeout)","title":"<code>timeout</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.read","title":"mcproto.connection.AsyncConnection.read  <code>async</code>","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Receive data sent through the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform a decryption of the received data.</p> <p>Parameters:</p> Name Type Description Default <code>int</code> <p>Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an :exc:<code>IOError</code> will be raised.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.read(length)","title":"<code>length</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.write","title":"mcproto.connection.AsyncConnection.write  <code>async</code>","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Send given <code>data</code> over the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform an encryption of the input data.</p>"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection","title":"mcproto.connection.SyncConnection","text":"<p>               Bases: <code>BaseSyncReader</code>, <code>BaseSyncWriter</code>, <code>ABC</code></p> <p>Base class for all classes handling synchronous connections.</p>"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.close","title":"mcproto.connection.SyncConnection.close","text":"<pre><code>close() -&gt; None\n</code></pre> <p>Close the connection (it cannot be used after this).</p>"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.enable_encryption","title":"mcproto.connection.SyncConnection.enable_encryption","text":"<pre><code>enable_encryption(shared_secret: bytes) -&gt; None\n</code></pre> <p>Enable encryption for this connection, using the <code>shared_secret</code>.</p> <p>After calling this method, the reading and writing process for this connection will be altered, and any future communication will be encrypted/decrypted there.</p> <p>You will need to call this method after sending the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet.</p> <p>Parameters:</p> Name Type Description Default <code>bytes</code> <p>This is the cipher key for the AES symetric cipher used for the encryption.  See :func:<code>mcproto.encryption.generate_shared_secret</code>.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.enable_encryption(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.make_client","title":"mcproto.connection.SyncConnection.make_client  <code>abstractmethod</code> <code>classmethod</code>","text":"<pre><code>make_client(address: tuple[str, int], timeout: float) -&gt; Self\n</code></pre> <p>Construct a client connection (Client -&gt; Server) to given server <code>address</code>.</p> <p>Parameters:</p> Name Type Description Default <code>tuple[str, int]</code> <p>Address of the server to connection to.</p> required <code>float</code> <p>Amount of seconds to wait for the connection to be established. If connection can't be established within this time, :exc:<code>TimeoutError</code> will be raised. This timeout is then also used for any further data receiving.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.make_client(address)","title":"<code>address</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.make_client(timeout)","title":"<code>timeout</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.read","title":"mcproto.connection.SyncConnection.read","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Receive data sent through the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform a decryption of the received data.</p> <p>Parameters:</p> Name Type Description Default <code>int</code> <p>Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an :exc:<code>IOError</code> will be raised.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.read(length)","title":"<code>length</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.write","title":"mcproto.connection.SyncConnection.write","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Send given <code>data</code> over the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform an encryption of the input data.</p>"},{"location":"reference/public/protocol/#mcproto.connection.TCPAsyncConnection","title":"mcproto.connection.TCPAsyncConnection","text":"<p>               Bases: <code>AsyncConnection</code>, <code>Generic[T_STREAMREADER, T_STREAMWRITER]</code></p> <p>Asynchronous TCP connection using :class:<code>~asyncio.StreamWriter</code> and :class:<code>~asyncio.StreamReader</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.TCPAsyncConnection.socket","title":"mcproto.connection.TCPAsyncConnection.socket  <code>property</code>","text":"<pre><code>socket: socket\n</code></pre> <p>Obtain the underlying socket behind the :class:<code>~asyncio.Transport</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.TCPSyncConnection","title":"mcproto.connection.TCPSyncConnection","text":"<p>               Bases: <code>SyncConnection</code>, <code>Generic[T_SOCK]</code></p> <p>Synchronous connection using a TCP :class:<code>~socket.socket</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.UDPAsyncConnection","title":"mcproto.connection.UDPAsyncConnection","text":"<p>               Bases: <code>AsyncConnection</code>, <code>Generic[T_DATAGRAM_CLIENT]</code></p> <p>Asynchronous UDP connection using :class:<code>~asyncio_dgram.DatagramClient</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.UDPSyncConnection","title":"mcproto.connection.UDPSyncConnection","text":"<p>               Bases: <code>SyncConnection</code>, <code>Generic[T_SOCK]</code></p> <p>Synchronous connection using a UDP :class:<code>~socket.socket</code>.</p>"},{"location":"reference/public/types/","title":"Types","text":""},{"location":"reference/public/types/#mcproto.types.abc","title":"mcproto.types.abc","text":""},{"location":"reference/public/types/#mcproto.types.abc.MCType","title":"mcproto.types.abc.MCType","text":"<p>               Bases: <code>Serializable</code></p> <p>Base class for a minecraft type structure.</p>"},{"location":"reference/public/types/#mcproto.types.chat","title":"mcproto.types.chat","text":""},{"location":"reference/public/types/#mcproto.types.chat.ChatMessage","title":"mcproto.types.chat.ChatMessage","text":"<p>               Bases: <code>MCType</code></p> <p>Minecraft chat message representation.</p>"},{"location":"reference/public/types/#mcproto.types.chat.ChatMessage.__eq__","title":"mcproto.types.chat.ChatMessage.__eq__","text":"<pre><code>__eq__(other: object) -&gt; bool\n</code></pre> <p>Check equality between two chat messages.</p> <p>..warning: This is purely using the <code>raw</code> field, which means it's possible that a chat message that appears the same, but was representing in a different way will fail this equality check.</p>"},{"location":"reference/public/types/#mcproto.types.chat.ChatMessage.as_dict","title":"mcproto.types.chat.ChatMessage.as_dict","text":"<pre><code>as_dict() -&gt; RawChatMessageDict\n</code></pre> <p>Convert received <code>raw</code> into a stadard :class:<code>dict</code> form.</p>"},{"location":"reference/public/types/#mcproto.types.chat.RawChatMessageDict","title":"mcproto.types.chat.RawChatMessageDict","text":"<p>               Bases: <code>TypedDict</code></p> <p>Dictionary structure of JSON chat messages when serialized.</p>"},{"location":"reference/public/types/#mcproto.types.nbt","title":"mcproto.types.nbt","text":""},{"location":"reference/public/types/#mcproto.types.nbt.FromObjectSchema","title":"mcproto.types.nbt.FromObjectSchema  <code>module-attribute</code>","text":"<pre><code>FromObjectSchema: TypeAlias = Union['type[NBTag]', 'type[NBTagConvertible]', 'Sequence[FromObjectSchema]', 'Mapping[str, FromObjectSchema]']\n</code></pre> <p>Represents the type of a schema, used to define how an object should be converted to an NBT tag(s).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.FromObjectType","title":"mcproto.types.nbt.FromObjectType  <code>module-attribute</code>","text":"<pre><code>FromObjectType: TypeAlias = Union[int, float, bytes, str, 'NBTagConvertible', 'Sequence[FromObjectType]', 'Mapping[str, FromObjectType]']\n</code></pre> <p>Represents any object holding some data that can be converted to an NBT tag(s).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.PayloadType","title":"mcproto.types.nbt.PayloadType  <code>module-attribute</code>","text":"<pre><code>PayloadType: TypeAlias = Union[int, float, bytes, str, 'NBTag', 'Sequence[PayloadType]', 'Mapping[str, PayloadType]']\n</code></pre> <p>Represents the type of a payload that can be stored in an NBT tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.__all__","title":"mcproto.types.nbt.__all__  <code>module-attribute</code>","text":"<pre><code>__all__ = ['ByteArrayNBT', 'ByteNBT', 'CompoundNBT', 'DoubleNBT', 'EndNBT', 'FloatNBT', 'IntArrayNBT', 'IntNBT', 'ListNBT', 'LongArrayNBT', 'LongNBT', 'NBTag', 'NBTagConvertible', 'NBTagType', 'ShortNBT', 'StringNBT']\n</code></pre> <p>Implementation of the NBT (Named Binary Tag) format used in Minecraft as described in the NBT specification</p> <p>Source : <code>Minecraft NBT Spec &lt;https://web.archive.org/web/20110723210920/http://www.minecraft.net/docs/NBT.txt&gt;</code>_</p> <p>Named Binary Tag specification</p> <p>NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data. An NBT file consists of a single GZIPped Named Tag of type TAG_Compound.</p> <p>A Named Tag has the following format:</p> <pre><code>byte tagType\nTAG_String name\n[payload]\n</code></pre> <ul> <li>The tagType is a single byte defining the contents of the payload of the tag.</li> <li>The name is a descriptive name, and can be anything (eg \"cat\", \"banana\", \"Hello World!\").   The purpose for this name is to name tags so parsing is easier and can be made to only look for certain recognized   tag names. Exception: If tagType is TAG_End, the name is skipped and assumed to be \"\".</li> <li>The [payload] varies by tagType.</li> </ul> <p>Note that ONLY Named Tags carry the name and tagType data. Explicitly identified Tags (such as TAG_String) only contains the payload.</p> <p>.. seealso:: :class:<code>NBTagType</code></p>"},{"location":"reference/public/types/#mcproto.types.nbt.ByteArrayNBT","title":"mcproto.types.nbt.ByteArrayNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing an array of bytes. The length of the array is stored as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ByteArrayNBT.__bytes__","title":"mcproto.types.nbt.ByteArrayNBT.__bytes__","text":"<pre><code>__bytes__() -&gt; bytes\n</code></pre> <p>Get the bytes value of the ByteArrayNBT tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ByteNBT","title":"mcproto.types.nbt.ByteNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing a single byte value, represented as a signed 8-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT","title":"mcproto.types.nbt.CompoundNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing a compound of named tags.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT.__eq__","title":"mcproto.types.nbt.CompoundNBT.__eq__","text":"<pre><code>__eq__(other: object) -&gt; bool\n</code></pre> <p>Check equality between two CompoundNBT tags.</p> <p>Parameters:</p> Name Type Description Default <code>object</code> <p>The other CompoundNBT tag to compare to.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the tags are equal, False otherwise.  .. note:: The order of the tags is not guaranteed, but the names of the tags must match. This function assumes that there are no duplicate tags in the compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT.__eq__(other)","title":"<code>other</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT.__iter__","title":"mcproto.types.nbt.CompoundNBT.__iter__","text":"<pre><code>__iter__()\n</code></pre> <p>Iterate over the tags in the compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.DoubleNBT","title":"mcproto.types.nbt.DoubleNBT","text":"<p>               Bases: <code>_FloatingNBTag</code></p> <p>NBT tag representing a double-precision floating-point value, represented as a 64-bit IEEE 754-2008 binary64.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.EndNBT","title":"mcproto.types.nbt.EndNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>Sentinel tag used to mark the end of a TAG_Compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.FloatNBT","title":"mcproto.types.nbt.FloatNBT","text":"<p>               Bases: <code>_FloatingNBTag</code></p> <p>NBT tag representing a floating-point value, represented as a 32-bit IEEE 754-2008 binary32 value.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.IntArrayNBT","title":"mcproto.types.nbt.IntArrayNBT","text":"<p>               Bases: <code>_NumberArrayNBTag</code></p> <p>NBT tag representing an array of integers. The length of the array is stored as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.IntNBT","title":"mcproto.types.nbt.IntNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing an integer value, represented as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ListNBT","title":"mcproto.types.nbt.ListNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing a list of tags. All tags in the list must be of the same type.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ListNBT.__iter__","title":"mcproto.types.nbt.ListNBT.__iter__","text":"<pre><code>__iter__() -&gt; Iterator[NBTag]\n</code></pre> <p>Iterate over the tags in the list.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.LongArrayNBT","title":"mcproto.types.nbt.LongArrayNBT","text":"<p>               Bases: <code>_NumberArrayNBTag</code></p> <p>NBT tag representing an array of longs. The length of the array is stored as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.LongNBT","title":"mcproto.types.nbt.LongNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing a long value, represented as a signed 64-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag","title":"mcproto.types.nbt.NBTag","text":"<p>               Bases: <code>MCType</code>, <code>NBTagConvertible</code></p> <p>Base class for NBT tags.</p> <p>In MC v1.20.2+ the type and name of the root tag is not written to the buffer, and unless specified, the type of the tag is assumed to be TAG_Compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.value","title":"mcproto.types.nbt.NBTag.value  <code>abstractmethod</code> <code>property</code>","text":"<pre><code>value: PayloadType\n</code></pre> <p>Get the payload of the NBT tag in a python-friendly format.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize","title":"mcproto.types.nbt.NBTag.deserialize  <code>classmethod</code>","text":"<pre><code>deserialize(buf: Buffer, with_name: bool = True, with_type: bool = True) -&gt; NBTag\n</code></pre> <p>Deserialize the NBT tag.</p> <p>Parameters:</p> Name Type Description Default <code>Buffer</code> <p>The buffer to read from.</p> required <code>bool</code> <p>Whether to read the name of the tag. (Passed to :meth:<code>_read_header</code>)</p> <code>True</code> <code>bool</code> <p>Whether to read the type of the tag. (Passed to :meth:<code>_read_header</code>)</p> <code>True</code> <p>Returns:</p> Type Description <code>NBTag</code> <p>The deserialized NBT tag.  This tag will be an instance of the class, that is associated with the tag type obtained from :meth:<code>_read_header</code> (see: :const:<code>ASSOCIATED_TYPES</code>).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize(buf)","title":"<code>buf</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object","title":"mcproto.types.nbt.NBTag.from_object  <code>staticmethod</code>","text":"<pre><code>from_object(data: FromObjectType, schema: FromObjectSchema, name: str = '') -&gt; NBTag\n</code></pre> <p>Create an NBT tag from a python object and a schema.</p> <p>Parameters:</p> Name Type Description Default <code>FromObjectType</code> <p>The python object to create the NBT tag from.</p> required <code>FromObjectSchema</code> <p>The schema used to create the NBT tags.  This is a description of the types of the <code>data</code> in the python object. It can be a subclass of :class:<code>NBTag</code> (e.g. :class:<code>IntNBT</code>, :class:<code>StringNBT</code>, :class:<code>CompoundNBT</code>, etc.), a :class:<code>dict</code>, a :class:<code>list</code>, a :class:<code>tuple</code>, or a class that has a <code>to_nbt</code> method.  Example of schema:  .. code-block:: python  schema = { \"string\": StringNBT, \"list_of_floats\": [FloatNBT], \"list_of_compounds\": [{ \"key\": StringNBT, \"value\": IntNBT, }], \"list_of_lists\": [[IntNBT], [StringNBT]], }  This would be translated into a :class:<code>CompoundNBT</code>.</p> required <code>str</code> <p>The name of the NBT tag.</p> <code>''</code> <p>Returns:</p> Type Description <code>NBTag</code> <p>The NBT tag created from the python object.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object(data)","title":"<code>data</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object(schema)","title":"<code>schema</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object(name)","title":"<code>name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.read_from","title":"mcproto.types.nbt.NBTag.read_from  <code>abstractmethod</code> <code>classmethod</code>","text":"<pre><code>read_from(buf: Buffer, with_type: bool = True, with_name: bool = True) -&gt; NBTag\n</code></pre> <p>Read the NBT tag from the buffer.</p> <p>Implementation shortcut used in :meth:<code>deserialize</code>. (Subclasses can override this, avoiding some repetition when compared to overriding <code>deserialize</code> directly.)</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize","title":"mcproto.types.nbt.NBTag.serialize","text":"<pre><code>serialize(with_type: bool = True, with_name: bool = True) -&gt; Buffer\n</code></pre> <p>Serialize the NBT tag to a new buffer.</p> <p>Parameters:</p> Name Type Description Default <code>bool</code> <p>Whether to include the type of the tag in the serialization. (Passed to :meth:<code>_write_header</code>)</p> <code>True</code> <code>bool</code> <p>Whether to include the name of the tag in the serialization. (Passed to :meth:<code>_write_header</code>)</p> <code>True</code> <p>Returns:</p> Type Description <code>Buffer</code> <p>The buffer containing the serialized NBT tag.  .. note:: The <code>with_type</code> and <code>with_name</code> parameters only control the first level of serialization.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to","title":"mcproto.types.nbt.NBTag.serialize_to  <code>abstractmethod</code>","text":"<pre><code>serialize_to(buf: Buffer, with_type: bool = True, with_name: bool = True) -&gt; None\n</code></pre> <p>Serialize the NBT tag to a buffer.</p> <p>Parameters:</p> Name Type Description Default <code>Buffer</code> <p>The buffer to write to.</p> required <code>bool</code> <p>Whether to include the type of the tag in the serialization.</p> <code>True</code> <code>bool</code> <p>Whether to include the name of the tag in the serialization.  .. seealso:: :meth:<code>serialize</code></p> <code>True</code>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to(buf)","title":"<code>buf</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_nbt","title":"mcproto.types.nbt.NBTag.to_nbt","text":"<pre><code>to_nbt(name: str = '') -&gt; NBTag\n</code></pre> <p>Convert the object to an NBT tag.</p> <p>.. warning:: This is already an NBT tag, so it will modify the name of the tag and return itself.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_object","title":"mcproto.types.nbt.NBTag.to_object","text":"<pre><code>to_object(include_schema: bool = False, include_name: bool = False) -&gt; PayloadType | Mapping[str, PayloadType] | tuple[PayloadType | Mapping[str, PayloadType], FromObjectSchema]\n</code></pre> <p>Convert the NBT tag to a python object.</p> <p>Parameters:</p> Name Type Description Default <code>bool</code> <p>Whether to return a schema describing the types of the original tag.</p> <code>False</code> <code>bool</code> <p>Whether to include the name of the tag in the output. If the tag has no name, the name will be set to \"\".</p> <code>False</code> <p>Returns:</p> Type Description <code>PayloadType | Mapping[str, PayloadType] | tuple[PayloadType | Mapping[str, PayloadType], FromObjectSchema]</code> <p>Either of: * A python object representing the payload of the tag. (default) * A dictionary containing the name associated with a python object representing the payload of the tag. * A tuple which includes one of the above and a schema describing the types of the original tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_object(include_schema)","title":"<code>include_schema</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_object(include_name)","title":"<code>include_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTagConvertible","title":"mcproto.types.nbt.NBTagConvertible","text":"<p>               Bases: <code>Protocol</code></p> <p>Protocol for objects that can be converted to an NBT tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagConvertible.to_nbt","title":"mcproto.types.nbt.NBTagConvertible.to_nbt","text":"<pre><code>to_nbt(name: str = '') -&gt; NBTag\n</code></pre> <p>Convert the object to an NBT tag.</p> <p>Parameters:</p> Name Type Description Default <code>str</code> <p>The name of the tag.</p> <code>''</code> <p>Returns:</p> Type Description <code>NBTag</code> <p>The NBT tag created from the object.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagConvertible.to_nbt(name)","title":"<code>name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType","title":"mcproto.types.nbt.NBTagType","text":"<p>               Bases: <code>IntEnum</code></p> <p>Enumeration of the different types of NBT tags.</p> <p>See the documentation of the individual variants for more information.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.BYTE","title":"mcproto.types.nbt.NBTagType.BYTE  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>BYTE = 1\n</code></pre> <p>A single signed byte (8 bits).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.BYTE_ARRAY","title":"mcproto.types.nbt.NBTagType.BYTE_ARRAY  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>BYTE_ARRAY = 7\n</code></pre> <p>The payload is a TAG_Int representing the length, followed by an array of  bytes."},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.COMPOUND","title":"mcproto.types.nbt.NBTagType.COMPOUND  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>COMPOUND = 10\n</code></pre> <p>A sequential list of Named Tags. This array keeps going until a TAG_End is found.</p> <ul> <li>If there's a nested TAG_Compound within this tag, that one will also have a TAG_End,   so simply reading until the next TAG_End will not work.</li> <li>The names of the named tags have to be unique within each TAG_Compound.</li> <li>The order of the tags is not guaranteed.</li> </ul>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.DOUBLE","title":"mcproto.types.nbt.NBTagType.DOUBLE  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>DOUBLE = 6\n</code></pre> <p>A floating point value (64 bits, big endian, IEEE 754-2008, binary64).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.END","title":"mcproto.types.nbt.NBTagType.END  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>END = 0\n</code></pre> <p>This tag is used to mark the end of a list. It doesn't carry any payload, and it cannot be named!</p> <p>If this type appears where a Named Tag is expected, the name is assumed to be <code>\"\"</code>. (In other words, this Tag is always just a single <code>0x00</code> byte when named, and nothing in all other cases)</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.FLOAT","title":"mcproto.types.nbt.NBTagType.FLOAT  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>FLOAT = 5\n</code></pre> <p>A floating point value (32 bits, big endian, IEEE 754-2008, binary32).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.INT","title":"mcproto.types.nbt.NBTagType.INT  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>INT = 3\n</code></pre> <p>A signed integer (32 bits, big endian).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.INT_ARRAY","title":"mcproto.types.nbt.NBTagType.INT_ARRAY  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>INT_ARRAY = 11\n</code></pre> <p>The payload is a TAG_Int representing the length, followed by an array of  TAG_Int elements."},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.LIST","title":"mcproto.types.nbt.NBTagType.LIST  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>LIST = 9\n</code></pre> <p>The payload is a TAG_Byte representing the type of the items in the list, followed by a TAG_Int representing the length of the list, followed by an array of  NBTags. <p>All the tags in the list must be of the same type.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.LONG","title":"mcproto.types.nbt.NBTagType.LONG  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>LONG = 4\n</code></pre> <p>A signed long (64 bits, big endian).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.LONG_ARRAY","title":"mcproto.types.nbt.NBTagType.LONG_ARRAY  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>LONG_ARRAY = 12\n</code></pre> <p>The payload is a TAG_Int representing the length, followed by an array of  TAG_Long elements."},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.SHORT","title":"mcproto.types.nbt.NBTagType.SHORT  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>SHORT = 2\n</code></pre> <p>A signed short (16 bits, big endian).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.STRING","title":"mcproto.types.nbt.NBTagType.STRING  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>STRING = 8\n</code></pre> <p>The payload is a TAG_Short representing the length, followed by an array of  bytes, holding a string in UTF-8 format."},{"location":"reference/public/types/#mcproto.types.nbt.ShortNBT","title":"mcproto.types.nbt.ShortNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing a short value, represented as a signed 16-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.StringNBT","title":"mcproto.types.nbt.StringNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing an UTF-8 string value. The length of the string is stored as a signed 16-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.uuid","title":"mcproto.types.uuid","text":""},{"location":"reference/public/types/#mcproto.types.uuid.UUID","title":"mcproto.types.uuid.UUID","text":"<p>               Bases: <code>UUID</code>, <code>MCType</code></p> <p>Minecraft UUID type.</p> <p>In order to support potential future changes in protocol version, and implement McType, this is a custom subclass, however it is currently compatible with the stdlib's <code>uuid.UUID</code>.</p>"},{"location":"usage/","title":"Usage","text":"<p>This part of the documentation contains various guides and explanations on how to use the different parts of mcproto.</p> <p>Work In Progress</p> <p>This category is still being written. Many pages are missing.</p> <p>Didn't find what you were looking for?</p> <p>If you were looking for a guide on something, but you didn't find it documented here and you feel like it's something that others would benefit from seeing too, you can create a github issue and ask us to write one.</p>"},{"location":"usage/authentication/","title":"Minecraft account authentication","text":"<p>Mcproto has first party support to handle authentication, allowing you to use your own minecraft account. This is needed if you wish to login to \"online mode\" (non-warez) servers as a client (player).</p>"},{"location":"usage/authentication/#microsoft-migrated-accounts","title":"Microsoft (migrated) accounts","text":"<p>This is how authentication works for already migrated minecraft accounts, using Microsoft accounts for authentication. (This will be most accounts. Any newly created minecraft accounts - after 2021 will always be Microsoft linked accounts.)</p>"},{"location":"usage/authentication/#creating-azure-application","title":"Creating Azure application","text":"<p>To authenticate with a microsoft account, you will need to go through the entire OAuth2 flow. Mcproto has functions to hide pretty much all of this away, however you will need to create a new Microsoft Azure application, that mcproto will use to obtain an access token.</p> <p>We know this is annoying, but it's a necessary step, as Microsoft only allows these applications to request OAuth2 authentication, and to avoid potential abuse, we can't really just use our registered application (like with say MultiMC), as this token would have to be embedded into our source-code, and since this is python, that would mean just including it here in plain text, and because mcproto is a low level library that can be used for any kind of interactions, we can't trust that you won't abuse this token.</p> <p>Instead, everyone using mcproto should register a new application, and get their own MSA token for your application that uses mcproto in the back.</p> <p>To create a new application, follow these steps (this is a simplified guide, for a full guide, feel free to check the Microsoft documentation):</p> <ol> <li>Go to the Azure portal and log in (create an account if you need to).</li> <li>Search for and select Azure Active Directory.</li> <li>On the left navbar, under Manage section, click on App registrations.</li> <li>Click on New registration on top navbar.</li> <li>Pick a name for the application. Anyone using your app to authenticate will see this name.</li> <li>Choose Personal Microsoft accounts only from the Supported account types.</li> <li>Leave the Redirect URI (optional) empty.</li> <li>Click on Register.</li> </ol> <p>From there, you will need to enable this application to be used for OAuth2 flows. To do that, follow these steps:</p> <ol> <li>On the left navbar, under Manage section, click on Authentication.</li> <li>Set Allow public content flows to Yes.</li> <li>Click Save.</li> </ol> <p>After that, you can go back to the app (click Overview from the left navbar), and you'll want to copy the Application (client) ID. This is the ID you will need to pass to mcproto. (You will also need the Display name, and the Directory (Tenant) ID for [Registering the application with Minecraft] - first time only)</p> <p>If you ever need to access this application again, follow these steps (as Microsoft Azure is pretty unintuitive, we document this too):</p> <ol> <li>Go to the Azure portal and log in.</li> <li>Click on Azure Active Directory (if you can't find it on the main page, you can use the search).</li> <li>On the left navbar, under Manage section, click on App registrations.</li> <li>Click on View all applications from personal account (assuming you registered the app from a personal account).</li> <li>Click on your app.</li> </ol>"},{"location":"usage/authentication/#registering-the-application-with-minecraft","title":"Registering the application with Minecraft","text":"<p>Previously, this step wasn't required, however due to people maliciously creating these applications to steal accounts, Mojang have recently started to limit access to the https://api.minecraftservices.com, and only allow explicitly white listed Client IDs to use this API.</p> <p>This API is absolutely crucial step in getting the final minecraft token, and so you will need to register your Client ID to be white listed by Mojang. Thankfully, it looks like Mojang is generally pretty lenient and at least for me, they didn't cause any unnecessary hassles when I asked for my application to be registered, for development purposes and work on mcproto.</p> <p>That said, you will need to wait a while (about a week, though it could be more), until Mojang reviews your application and approves it. There isn't much we can do about this.</p> <p>To get your Azure application registered, you will need to fill out a simple form, where you accept the EULA, provide your E-Mail, Application name, Application Client ID and Tennant ID.</p> <p>More annoyingly you will additionally also need to provide an associated website or domain for your project/brand. (This application is generally designed for more user-facing programs, such as full launchers. When registering mcproto, I just used the GitHub URL). Lastly, you'll want to describe why you need access to this API in the Justification section.</p> <p>Visit the Mojang article describing this process. There is also a link to the form to fill out.</p>"},{"location":"usage/authentication/#the-code","title":"The code","text":"<p>Finally, after you've managed to register your application and get it approved by Mojang, you can use it with mcproto, go through the Microsoft OAuth2 flow and authorize this application to access your Microsoft account, which mcproto will then use to get the minecraft token you'll then need to login to online servers.</p> <pre><code>import httpx\nfrom mcproto.auth.microsoft.oauth import full_microsoft_oauth\nfrom mcproto.auth.microsoft.xbox import xbox_auth\nfrom mcproto.auth.msa import MSAAccount\n\nMY_MSA_CLIENT_ID = \"[REDACTED]\"  # Paste your own Client ID here\n\nasync def authenticate() -&gt; MSAAccount:\n    async with httpx.AsyncClient() as client:\n        microsoft_token = await full_microsoft_oauth(client, MY_MSA_CLIENT_ID)\n        user_hash, xsts_token = xbox_auth(client, microsoft_token)\n        return MSAAccount.xbox_auth(cilent, user_hash, xsts_token)\n</code></pre> <p>Note that the <code>full_microsoft_oauth</code> function will print a message containing the URL you should visit in your browser, and a one time code to type in once you reach this URL. That will then prompt you to log in to your Microsoft account, and then allow you to authorize the application to use your account.</p>"},{"location":"usage/authentication/#caching","title":"Caching","text":"<p>You will very likely want to set up caching here, and store at least the <code>microsoft_token</code> somewhere, so you don't have to log in each time your code will run. Here's some example code that caches every step of the way, always resorting to the \"closest\" functional token. Note that this is using <code>pickle</code> to store the tokens, you may want to use JSON or other format instead, as it would be safer. Also, be aware that these are sensitive and if compromised, someone could gain access to your minecraft account (though only for playing, they shouldn't be able to change your password or anything like that), so you might want to consider encrypting these cache files before storing:</p> <pre><code>from __future__ import annotations\n\nimport logging\nimport pickle\nfrom pathlib import Path\n\nimport httpx\n\nfrom mcproto.auth.microsoft.oauth import full_microsoft_oauth\nfrom mcproto.auth.microsoft.xbox import XSTSRequestError, xbox_auth\nfrom mcproto.auth.msa import MSAAccount, ServicesAPIError\n\nlog = logging.getLogger(__name__)\n\nMY_MSA_CLIENT_ID = \"[REDACTED]\"  # Paste your own Client ID here\nCACHE_DIR = Path(\".cache/\")\n\n\nasync def microsoft_login(client: httpx.AsyncClient) -&gt; MSAAccount:  # noqa: PLR0912,PLR0915\n    \"\"\"Obtain minecraft account using Microsoft authentication.\n\n    This function performs full caching of every step along the way, allowing for recovery\n    without manual intervention for as long as at least the root token (from Microsoft OAuth2)\n    is valid. Any later tokens will be refreshed and re-cached once invalid.\n\n    If all tokens are invalid, or this function was ran for the first time (without any cached\n    data), you will be shown a URL and a code. You have to go to this URL with your browser and\n    enter the code, completing the OAuth2 flow, obtaining the root token.\n    \"\"\"\n    CACHE_DIR.mkdir(parents=True, exist_ok=True)\n\n    access_token_cache = CACHE_DIR.joinpath(\"xbox_access_token.pickle\")\n    if access_token_cache.exists():\n        with access_token_cache.open(\"rb\") as f:\n            access_token: str = pickle.load(f)  # noqa: S301\n\n        try:\n            account = await MSAAccount.from_xbox_access_token(client, access_token)\n            log.info(\"Logged in with cached xbox minecraft access token\")\n            return account\n        except httpx.HTTPStatusError as exc:\n            log.warning(f\"Cached xbox minecraft access token is invalid: {exc!r}\")\n    else:\n        log.warning(\"No cached access token available, trying Xbox Secure Token Service (XSTS) token\")\n\n    # Access token either doesn't exist, or isn't valid, try XSTS (Xbox) token\n    xbox_token_cache = CACHE_DIR.joinpath(\"xbox_xsts_token.pickle\")\n    if xbox_token_cache.exists():\n        with xbox_token_cache.open(\"rb\") as f:\n            user_hash, xsts_token = pickle.load(f)  # noqa: S301\n\n        try:\n            access_token = await MSAAccount._get_access_token_from_xbox(client, user_hash, xsts_token)\n        except ServicesAPIError as exc:\n            log.warning(f\"Invalid cached Xbox Secure Token Service (XSTS) token: {exc!r}\")\n        else:\n            log.info(\"Obtained xbox access token from cached Xbox Secure Token Service (XSTS) token\")\n            log.info(\"Storing xbox minecraft access token to cache and restarting auth\")\n            with access_token_cache.open(\"wb\") as f:\n                pickle.dump(access_token, f)\n            return await microsoft_login(client)\n    else:\n        log.warning(\"No cached Xbox Secure Token Service (XSTS) token available, trying Microsoft OAuth2 token\")\n\n    # XSTS token either doesn't exist, or isn't valid, try Microsoft OAuth2 token\n    microsoft_token_cache = CACHE_DIR.joinpath(\"microsoft_token.pickle\")\n    if microsoft_token_cache.exists():\n        with microsoft_token_cache.open(\"rb\") as f:\n            microsoft_token = pickle.load(f)  # noqa: S301\n\n        try:\n            user_hash, xsts_token = await xbox_auth(client, microsoft_token)\n        except (httpx.HTTPStatusError, XSTSRequestError) as exc:\n            log.warning(f\"Invalid cached Microsoft OAuth2 token {exc!r}\")\n        else:\n            log.info(\"Obtained Xbox Secure Token Service (XSTS) token from cached Microsoft OAuth2 token\")\n            log.info(\"Storing Xbox Secure Token Service (XSTS) token to cache and restarting auth\")\n            with xbox_token_cache.open(\"wb\") as f:\n                pickle.dump((user_hash, xsts_token), f)\n            return await microsoft_login(client)\n    else:\n        log.warning(\"No cached microsoft token\")\n\n    # Microsoft OAuth2 token either doesn't exist, or isn't valid, request user auth\n    log.info(\"Running Microsoft OAuth2 flow, requesting user authentication\")\n    microsoft_token = await full_microsoft_oauth(client, MY_MSA_CLIENT_ID)\n    log.info(\"Obtained Microsoft OAuth2 token from user authentication\")\n    log.info(\"Storing Microsoft OAuth2 token and restarting auth\")\n    with microsoft_token_cache.open(\"wb\") as f:\n        pickle.dump(microsoft_token[\"access_token\"], f)\n    return await microsoft_login(client)\n</code></pre>"},{"location":"usage/authentication/#minecraft-non-migrated-accounts","title":"Minecraft (non-migrated) accounts","text":"<p>If you haven't migrated your account into a Microsoft account, follow this guide for authentication. (Any newly created Minecraft accounts will be using Microsoft accounts already.) This method of authentication is called \"yggdrasil\".</p> <p>Warning</p> <p>The account migration process has been concluded in  September 19, 2023. See: https://www.minecraft.net/en-us/article/account-migration-last-call</p> <p>That means that it's no longer possible to migrate this old account into a microsoft account and it's only a matter of time until the authentication servers handling these accounts are turned off entirely.</p> <p>Mcproto will remove support for this old authentication methods once this happens.</p> <p>This method of authentication doesn't require any special app registrations, however it is significantly less secure, as you need to enter your login and password directly.</p> <pre><code>  import httpx\n  from mcproto.auth.yggdrasil import YggdrasilAccount\n\n  LOGIN = \"mail@example.com\"\n  PASSWORD = \"my_password\"\n\n  async def authenticate() -&gt; YggdrasilAccount:\n      async with httpx.AsyncClient() as client:\n          return YggdrasilAccount.authenticate(client, login=LOGIN, password=PASSWORD)\n</code></pre> <p>The Account instance you will obtain here will contain a refresh token, and a shorter lived access token, received from Mojang APIs from the credentials you entered. Just like with Microsoft accounts, you may want to cache these tokens to avoid needless calls to request new ones and go through authentication again. That said, since doing so doesn't necessarily require user interaction, if you make the credentials accessible from your code directly, this is a lot less annoying.</p> <p>If you will decide to use caching, or if you plan on using these credentials in a long running program, you may see the access token expire. You can check whether the token is expired with the <code>YggdrasilAccount.validate</code> method, and if it is (call returned <code>False</code>), you can call <code>YggdrasilAccount.refresh</code> to use the refresh token to obtain a new access token. The refresh token is much more long lived than the access token, so this should generally be enough for you, although if you login from elsewhere, or after a really long time, the refresh token might be invalidated, in that case, you'll need to go through the full login again.</p>"},{"location":"usage/authentication/#legacy-mojang-accounts","title":"Legacy Mojang accounts","text":"<p>If your minecraft account is still using the (really old) Mojang authentication, you can simply follow the non-migrated guide, as it will work with these legacy accounts too, the only change you will need to make is to use your username, instead of an email.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"MCPROTO"},{"location":"#what-is-mcproto","title":"What is Mcproto","text":"<p>Mcproto is a python library that provides various low level interactions with the Minecraft protocol. It attempts to be a full wrapper around the Minecraft protocol, which means it could be used as a basis for Minecraft bots written in python, or even full python server implementations.</p> <p>Warning</p> <p>This library is still heavily Work-In-Progress, which means a lot of things can still change and some features may be missing or incomplete. Using the library for production applications at it's current state isn't recommended.</p>"},{"location":"community/attribution/","title":"Attribution","text":"<p>This document serves as a way to explicitly give credit to projects which made mcproto possible.</p> <p>Note that as with any other project, if there was some code that was directly utilized from these projects, it will be mentioned in <code>LICENSE-THIRD-PARTY.txt</code>, not in here. This file isn't meant to serve as a place to disclose used code and it's licenses, but rather to give proper credit where it is due, and to shout out a few amazing projects that allowed mcproto to exist in the first place.</p> <ul> <li>wiki.vg (https://wiki.vg): An absolutely amazing community driven wiki that documents how the minecraft protocol is   structured and the changes that occur between the protocol versions.</li> <li>PyMine-Net: The project that was the main inspiration to this project, being a separation of the minecraft   networking tooling used in PyMine-Server, which is an attempt at implementing a fully working minecraft server purely   in python. However, this project is no longer maintained, and so mcproto was created to be it's replacement.</li> <li>Mcstatus: A library that allows for easy fetching of status/query data from minecraft servers, including parsers and   structures that meaningfully represent the obtained data, but also the logic on how it's actually obtained, some of   which this project took heavy inspiration from.</li> <li>pyCraft: A long abandoned project similar to mcproto, which served as an inspiration for various functionalities in   the library.</li> <li>quarry: A library providing support for basic interactions with the minecraft protocol, though only up to packet reading.   Implementation for reading data from specific packets is not included.</li> </ul> <p>To all of these projects, they deserve a massive thank you, for keeping their code/information open-sourced and available as a source of information, and inspiration freely to anyone.</p>"},{"location":"community/code-of-conduct/","title":"Code of Conduct","text":"<p>This code of conduct outlines our expectations for the people involved with this project. We, as members, contributors and leaders are committed to providing a welcoming and inspiring project that anyone can easily join, expecting a harassment-free experience, as described in this code of conduct.</p> <p>This code of conduct is here to ensure we provide a welcoming and inspiring project that anyone can easily join, expecting a harassment-free experience, as described in this code of conduct.</p> <p>The goal of this document is to set the overall tone for our community. It is here to outline some of the things you can and can't do if you wish to participate in our community. However it is not here to serve as a rule-book with a complete set of things you can't do, social conduct differs from situation to situation, and person to person, but we should do our best to try and provide a good experience to everyone, in every situation.</p> <p>We value many things beyond just technical expertise, including collaboration and supporting others within our community. Providing a positive experience for others can have a much more significant impact than simply providing the correct answer.</p>"},{"location":"community/code-of-conduct/#harassment","title":"Harassment","text":"<p>We share a common understanding of what constitutes harassment as it applies to a professional setting. Although this list cannot be exhaustive, we explicitly honor the following \"protected attributes\": diversity in age, gender, culture, ethnicity, language, national origin, political beliefs, profession, race, religion, sexual orientation, socioeconomic status, disability and personal appearance. We will not tolerate discrimination based on any of the protected characteristics above, including some that may not have been explicitly mentioned here. We consider discrimination of any kind to be unacceptable and immoral.</p> <p>Harassment includes, but is not limited to:</p> <ul> <li>Offensive comments (or \"jokes\") related to any of the above mentioned attributes.</li> <li>Deliberate \"outing\"/\"doxing\" of any aspect of a person's identity, such as physical or electronic address, without   their explicit consent, except as necessary means to protect others from intentional abuse.</li> <li>Unwelcome comments regarding a person's lifestyle choices and practices, including those related to food, health,   parenting, drugs and employment.</li> <li>Deliberate misgendering. This includes deadnaming or persistently using a pronoun that does not correctly reflect a   person's gender identity. You must address people by the name they give you when not addressing them by their   username or handle.</li> <li>Threats of violence, both physical and psychological.</li> <li>Incitement of violence towards any individual, including encouraging a person to engage in self-harm.</li> <li>Publication of non-harassing private communication.</li> <li>Pattern of inappropriate social conduct, such as requesting/assuming inappropriate levels of intimacy with others, or   excessive teasing after a request to stop.</li> <li>Continued one-on-one communication after requests to cease.</li> <li>Sabotage of someone else's work or intentionally hindering someone else's performance.</li> </ul>"},{"location":"community/code-of-conduct/#plagiarism","title":"Plagiarism","text":"<p>Plagiarism is the re-use of someone else's work (eg: binary content such as images, textual content such as an article, but also source code, or any other copyrightable resources) without the permission or a license right from the author. Claiming someone else's work as your own is not just immoral and disrespectful to the author, but also illegal in most countries. You should always follow the authors wishes, and give credit where credit is due.</p> <p>If we found that you've intentionally attempted to add plagiarized content to our code-base, you will likely end up being permanently banned from any future contributions to this project's repository. We will of course also do our best to remove, or properly attribute this plagiarized content as quickly as possible.</p> <p>An unintentional attempt at plagiarism will not be punished as harshly, but nevertheless, it is your responsibility as a contributor to check where the code you're submitting comes from, and so repeated submission of such content, even after you were warned might still get you banned.</p> <p>Please note that an online repository that has no license is presumed to only be source-available, NOT open-source. Meaning that this work is protected by author's copyright, automatically imposed over it, and without any license extending that copyright, you have no rights to use such code. So know that you can't simply take some source-code, even though it's published publicly. This code may be available to be seen by anyone, but that does not mean it's also available to be used by anyone in other projects.</p> <p>Another important note to keep in mind is that even if some project has an open-source license, that license may have conditions which are incompatible with our codebase (such as requiring all of the code that links to this new part to also be licensed under the same license, which our code-base is not currently under). That is why it's necessary to understand a license before using code available under it. Simple attribution often isn't everything that the license requires.</p> Learn more about software licensing <p>If you are new to software licensing, you can check out this article, which does a good job at explaining the basics.</p>"},{"location":"community/code-of-conduct/#generally-inappropriate-behavior","title":"Generally inappropriate behavior","text":"<p>Outside of just harassment and plagiarism, there are countless other behaviors which we consider unacceptable, as they may be offensive, and discourage people from engaging with our community.</p> <p>Examples of generally inappropriate behavior:</p> <ul> <li>The use of sexualized language or imagery of any kind</li> <li>The use of inappropriate images, including in an account's avatar</li> <li>The use of inappropriate language, including in an account's nickname</li> <li>Any spamming, flamming, baiting or other attention-stealing behavior</li> <li>Discussing topics that are overly polarizing, sensitive, or incite arguments.</li> <li>Responding with \"RTFM\", \"just google it\" or similar response to help requests</li> <li>Other conduct which could be reasonably considered inappropriate</li> </ul> <p>Examples of generally appropriate behavior:</p> <ul> <li>Being kind and courteous to others</li> <li>Collaborating with other community members</li> <li>Gracefully accepting constructive criticism</li> <li>Using welcoming and inclusive language</li> <li>Showing empathy towards other community members</li> </ul>"},{"location":"community/code-of-conduct/#scope","title":"Scope","text":"<p>This Code of Conduct applies within all community spaces, including this repository itself, conversations on any platforms officially connected to this project (such as in GitHub issues, emails or platforms like discord). It also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official social media account, or acting as an appointed representative at an online or offline event.</p> <p>All members involved with the project are expected to follow this Code of Conduct, no matter their position in the project's hierarchy, this Code of Conduct applies equally to contributors, maintainers and people seeking help/reporting bugs, etc.</p>"},{"location":"community/code-of-conduct/#enforcement-responsibilities","title":"Enforcement Responsibilities","text":"<p>Whenever a participant has made a mistake, we expect them to take responsibility for their actions. If someone has been harmed or offended, it is our responsibility to listen carefully and respectfully, and to do our best to right the wrong.</p> <p>Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, harmful, or otherwise undesirable.</p> <p>Community leaders have the right and responsibility to remove, edit or reject comments, commits, code, wiki edits, issues and other contributions within the enforcement scope that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.</p> <p>If you have experienced or witnessed unacceptable behavior constituting a code of conduct violation or have any other code of conduct concerns, please let us know and we will do our best to resolve this issue.</p>"},{"location":"community/code-of-conduct/#reporting-a-code-of-conduct-violation","title":"Reporting a Code of Conduct violation","text":"<p>If you think that someone is violating the Code of Conduct, you can report it to any repository maintainer, either by email or through a Discord DM. You should avoid using public channels for reporting these violations, and instead do so in private discussion with a maintainer.</p>"},{"location":"community/code-of-conduct/#sources","title":"Sources","text":"<p>The open-source community has an incredible amount of resources that people have freely provided to others and we all depend on these projects in many ways. This code of conduct article is no exception and there were many open source projects that has helped bring this code of conduct to existence. For that reason, we'd like to thank all of these communities and projects for keeping their content open and available to everyone, but most notably we'd like to thank the projects with established codes of conduct and diversity statements that we used as our inspiration. Below is the list these projects:</p> <ul> <li>Python: https://www.python.org/community/diversity/</li> <li>Contributor Covenant: https://www.contributor-covenant.org/</li> <li>Rust-lang: https://www.rust-lang.org/policies/code-of-conduct</li> <li>Code Fellows: https://github.com/codefellows/code-of-conduct</li> <li>Python Discord: https://www.pythondiscord.com/pages/code-of-conduct/</li> </ul>"},{"location":"community/license/","title":"License","text":"<p>This project's source code is licensed under the GNU Lesser General Public License (LGPL) version 3.</p> <p>The LGPL license allows you to use mcproto as a library pretty much in any code-base, including in proprietary code-bases. However, if you wish to make a derivative project to mcproto itself, such a project will need to be licensed under LGPL as well.</p> Full LICENSE text LICENSE.txt<pre><code>                   GNU LESSER GENERAL PUBLIC LICENSE\n                       Version 3, 29 June 2007\n\n Copyright (C) 2007 Free Software Foundation, Inc. &lt;http://fsf.org/&gt;\n Everyone is permitted to copy and distribute verbatim copies\n of this license document, but changing it is not allowed.\n\n\n  This version of the GNU Lesser General Public License incorporates\nthe terms and conditions of version 3 of the GNU General Public\nLicense, supplemented by the additional permissions listed below.\n\n  0. Additional Definitions.\n\n  As used herein, \"this License\" refers to version 3 of the GNU Lesser\nGeneral Public License, and the \"GNU GPL\" refers to version 3 of the GNU\nGeneral Public License.\n\n  \"The Library\" refers to a covered work governed by this License,\nother than an Application or a Combined Work as defined below.\n\n  An \"Application\" is any work that makes use of an interface provided\nby the Library, but which is not otherwise based on the Library.\nDefining a subclass of a class defined by the Library is deemed a mode\nof using an interface provided by the Library.\n\n  A \"Combined Work\" is a work produced by combining or linking an\nApplication with the Library.  The particular version of the Library\nwith which the Combined Work was made is also called the \"Linked\nVersion\".\n\n  The \"Minimal Corresponding Source\" for a Combined Work means the\nCorresponding Source for the Combined Work, excluding any source code\nfor portions of the Combined Work that, considered in isolation, are\nbased on the Application, and not on the Linked Version.\n\n  The \"Corresponding Application Code\" for a Combined Work means the\nobject code and/or source code for the Application, including any data\nand utility programs needed for reproducing the Combined Work from the\nApplication, but excluding the System Libraries of the Combined Work.\n\n  1. Exception to Section 3 of the GNU GPL.\n\n  You may convey a covered work under sections 3 and 4 of this License\nwithout being bound by section 3 of the GNU GPL.\n\n  2. Conveying Modified Versions.\n\n  If you modify a copy of the Library, and, in your modifications, a\nfacility refers to a function or data to be supplied by an Application\nthat uses the facility (other than as an argument passed when the\nfacility is invoked), then you may convey a copy of the modified\nversion:\n\n   a) under this License, provided that you make a good faith effort to\n   ensure that, in the event an Application does not supply the\n   function or data, the facility still operates, and performs\n   whatever part of its purpose remains meaningful, or\n\n   b) under the GNU GPL, with none of the additional permissions of\n   this License applicable to that copy.\n\n  3. Object Code Incorporating Material from Library Header Files.\n\n  The object code form of an Application may incorporate material from\na header file that is part of the Library.  You may convey such object\ncode under terms of your choice, provided that, if the incorporated\nmaterial is not limited to numerical parameters, data structure\nlayouts and accessors, or small macros, inline functions and templates\n(ten or fewer lines in length), you do both of the following:\n\n   a) Give prominent notice with each copy of the object code that the\n   Library is used in it and that the Library and its use are\n   covered by this License.\n\n   b) Accompany the object code with a copy of the GNU GPL and this license\n   document.\n\n  4. Combined Works.\n\n  You may convey a Combined Work under terms of your choice that,\ntaken together, effectively do not restrict modification of the\nportions of the Library contained in the Combined Work and reverse\nengineering for debugging such modifications, if you also do each of\nthe following:\n\n   a) Give prominent notice with each copy of the Combined Work that\n   the Library is used in it and that the Library and its use are\n   covered by this License.\n\n   b) Accompany the Combined Work with a copy of the GNU GPL and this license\n   document.\n\n   c) For a Combined Work that displays copyright notices during\n   execution, include the copyright notice for the Library among\n   these notices, as well as a reference directing the user to the\n   copies of the GNU GPL and this license document.\n\n   d) Do one of the following:\n\n       0) Convey the Minimal Corresponding Source under the terms of this\n       License, and the Corresponding Application Code in a form\n       suitable for, and under terms that permit, the user to\n       recombine or relink the Application with a modified version of\n       the Linked Version to produce a modified Combined Work, in the\n       manner specified by section 6 of the GNU GPL for conveying\n       Corresponding Source.\n\n       1) Use a suitable shared library mechanism for linking with the\n       Library.  A suitable mechanism is one that (a) uses at run time\n       a copy of the Library already present on the user's computer\n       system, and (b) will operate properly with a modified version\n       of the Library that is interface-compatible with the Linked\n       Version.\n\n   e) Provide Installation Information, but only if you would otherwise\n   be required to provide such information under section 6 of the\n   GNU GPL, and only to the extent that such information is\n   necessary to install and execute a modified version of the\n   Combined Work produced by recombining or relinking the\n   Application with a modified version of the Linked Version. (If\n   you use option 4d0, the Installation Information must accompany\n   the Minimal Corresponding Source and Corresponding Application\n   Code. If you use option 4d1, you must provide the Installation\n   Information in the manner specified by section 6 of the GNU GPL\n   for conveying Corresponding Source.)\n\n  5. Combined Libraries.\n\n  You may place library facilities that are a work based on the\nLibrary side by side in a single library together with other library\nfacilities that are not Applications and are not covered by this\nLicense, and convey such a combined library under terms of your\nchoice, if you do both of the following:\n\n   a) Accompany the combined library with a copy of the same work based\n   on the Library, uncombined with any other library facilities,\n   conveyed under the terms of this License.\n\n   b) Give prominent notice with the combined library that part of it\n   is a work based on the Library, and explaining where to find the\n   accompanying uncombined form of the same work.\n\n  6. Revised Versions of the GNU Lesser General Public License.\n\n  The Free Software Foundation may publish revised and/or new versions\nof the GNU Lesser General Public License from time to time. Such new\nversions will be similar in spirit to the present version, but may\ndiffer in detail to address new problems or concerns.\n\n  Each version is given a distinguishing version number. If the\nLibrary as you received it specifies that a certain numbered version\nof the GNU Lesser General Public License \"or any later version\"\napplies to it, you have the option of following the terms and\nconditions either of that published version or of any later version\npublished by the Free Software Foundation. If the Library as you\nreceived it does not specify a version number of the GNU Lesser\nGeneral Public License, you may choose any version of the GNU Lesser\nGeneral Public License ever published by the Free Software Foundation.\n\n  If the Library as you received it specifies that a proxy can decide\nwhether future versions of the GNU Lesser General Public License shall\napply, that proxy's public statement of acceptance of any version is\npermanent authorization for you to choose that version for the\nLibrary.\n</code></pre>"},{"location":"community/license/#this-documentation","title":"This documentation","text":"<p>This documentation itself follows a Creative Commons license: CC BY-NC-SA 4.0 </p> <p>Tip</p> <p>If you need a copyright header for proper attribution, you can use:</p> RenderedHTML <p>Mcproto Documentation \u00a9 2024 by ItsDrike</p> <pre><code>&lt;a href=\"https://py-mine.github.io/mcproto\"&gt;Mcproto Documentation&lt;/a&gt; &amp;copy; 2024 by &lt;a href=\"mailto:itsdrike@protonmail.com\"&gt;ItsDrike&lt;/a&gt;\n</code></pre> <p>If you also need the license identifier, use the following:</p> <pre><code>&lt;a href=\"https://creativecommons.org/licenses/by-nc-sa/4.0/\"&gt;CC BY-NC-SA 4.0&lt;/a&gt; &lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1\" alt=\"\"&gt;&lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1\" alt=\"\"&gt;&lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1\" alt=\"\"&gt;&lt;img style=\"height:22px!important;margin-left:3px;vertical-align:text-bottom;\" src=\"https://mirrors.creativecommons.org/presskit/icons/sa.svg?ref=chooser-v1\" alt=\"\"&gt;\n</code></pre>"},{"location":"community/license/#differently-licensed-parts","title":"Differently licensed parts","text":"<p>Some parts of the project follow a different license. See the <code>LICENSE-THIRD-PARTY.txt</code> file, which lists all of these parts and their respective licenses.</p> Full LICENSE-THIRD-PARTY text LICENSE-THIRD-PARTY.txt<pre><code>---------------------------------------------------------------------------------------------------\n                                            MIT License\nApplies to:\n    - Copyright (c) 2021 Python Discord\n      Copyright (C) 2022 Hassan Abouelela &lt;hassan@hassanamr.com&gt;\n      Copyright (C) 2022 Chris Lovering &lt;chris.lovering.95@gmail.com&gt;\n      Copyright (C) 2022 mbaruh &lt;mbaruh@hotmail.com&gt;\n      All rights reserved.\n        - mcproto/utils/version_map.py: portions of VersionMap._walk_submodules function\n    - Copyright (c) 2020 Nekokatt\n      Copyright (c) 2021-present davfsa\n      All rights reserved.\n        - .github/ISSUE_TEMPLATE/bug_report.yml: Template heavily inspired by original\n        - .github/ISSUE_TEMPLATE/feature_request.yml: Template heavily inspired by original\n        - .github/workflows/fragment-check.yml: Entire file\n        - .github/workflows/prepare-release.yml: Workflow heavily inspired by original\n        - .github/scripts/normalize_coverage.py: Entire file\n    - Copyright (c) 2015-present Rapptz\n      All rights reserved.\n        - docs/installation/version-guarantees.rst: Entire file\n    - Copyright (c) 2016-2024 Martin Donath\n      All rights reserved\n         - docs/contributing/reporting-a-bug.md: Majority of the file\n---------------------------------------------------------------------------------------------------\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n---------------------------------------------------------------------------------------------------\n                                 GNU LESSER GENERAL PUBLIC LICENSE\nApplies to:\n    - Copyright (c) 2022, Milo Weinberg &lt;iapetus011@gmail.com&gt;\n      All rights reserved.\n        - mcproto/packets/packet.py: GameState and PacketDirection enum classes\n---------------------------------------------------------------------------------------------------\nFulltext of the license can be seen in the LICENSE.txt file, as it matches the current license of\nthis project, this file just disclaims the copyrighted sections used in our codebase.\n\n---------------------------------------------------------------------------------------------------\n                                    Apache License version 2.0\nApplies to:\n    - Copyright (c) 2012 Ammar Askar\n      All rights reserved.\n        - mcproto/connection.py: write, read methods in all classes (not _write and _read though)\n        - mcproto/encryption.py: encrypt_token_and_secret, generate_shared_secret functions\n---------------------------------------------------------------------------------------------------\n\n\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright [yyyy] [name of copyright owner]\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n</code></pre>"},{"location":"contributing/making-a-pr/","title":"Making a pull request","text":"<p>Work In Progress</p> <p>This page is missing a guide on writing a good PR body</p>"},{"location":"contributing/making-a-pr/#pull-requests","title":"Pull Requests","text":"<p>Welcome! If you're interested in contributing to mcproto, you've come to the right place. Mcproto is an open-source project, and we welcome contributions from anyone eager to help out.</p> <p>To contribute, you can create a pull request on our GitHub repository. Your pull request will then be reviewed by our maintainers, and once approved, it will be merged into the main repository. Contributions can include bug fixes, documentation updates, or new features.</p> <p>Code quality requirements</p> <p>While we encourage and appreciate contributions, maintaining high code quality is crucial to us. That means you will need to adhere to our code quality standards. Contributions may be rejected if they do not meet these guidelines.</p>"},{"location":"contributing/making-a-pr/#get-assigned-to-the-issue","title":"Get assigned to the issue","text":"<p>The very first thing you will need to do is deciding what you actually want to work on. In all likelihood, you already have something in mind if you're reading this, however, if you don't, you're always free to check the opened GitHub issues. If you find anything interesting there that you'd wish to work on, leave a comment on that issue with something like: \"I'd like to work on this\".</p> <p>Even if you do have an idea already, we heavily recommend (though not require) that you first make an issue, this can be a bug report, but also a feature request, or something else. Once you made the issue, leave a: \"I'd like to work on this\" comment on it.</p> <p>Eventually, a maintainer will get back to you and you will be assigned to the issue. By getting assigned, you reserve the right to work on that given issue and it also prevents us (or someone else) from potentially working on the same thing that you're already addressing. This is also the reason why we recommend creating an issue first. Being assigned is a soft approval from us, giving you the green light to start coding.</p> <p>Of course, you are welcome to start working on the issue even before being officially assigned. However, please be aware that sometimes, we may choose not to pursue a certain feature / bugfix. In such cases, your work might not end up being used, which would be a shame.</p> <p>Minor tasks don't need an issue</p> <p>While we generally do encourage contributors to first create an issue and get assigned to it first. If you're just fixing a typo, improving the wording, or making some minor optimizations to the code, you can safely skip this step.</p> <p>The point of encouraging issues is to prevent needlessly wasting people's time. However, with these minor tasks, it might actually take you longer to create a full issue about the problem than it would to just submit a fix.</p> <p>There's therefore no point in cluttering the issue tracker with a bunch of small issues that can often be changed in just a few minutes.</p>"},{"location":"contributing/making-a-pr/#pull-request-body","title":"Pull Request Body","text":"<p>TODO</p>"},{"location":"contributing/making-a-pr/#work-in-progress-prs","title":"Work in Progress PRs","text":"<p>Whenever you open a pull request that isn't yet ready to be reviewed and merged, you can mark it as a draft. This provides both visual and functional indicator that the PR isn't yet ready to be merged.</p> <p>Methods of marking PR as a draft:</p> When creating it After creation <p>Once your work is done and you think the PR is ready to be merged, mark it as Ready for review</p> <p></p>"},{"location":"contributing/making-a-pr/#contributing-guidelines","title":"Contributing guidelines","text":"<p>In order to make a successful contribution, it is required that you get familiar with our contributing guidelines.</p>"},{"location":"contributing/making-a-pr/#automated-checks","title":"Automated checks","text":"<p>The project includes various CI workflows that will run automatically for your pull request after every push and check your changed with various tools. These tools are here to ensure that our contributing guidelines are met and ensure good code quality of your PR.</p> <p>That said, you shouldn't rely on these CI workflows to let you know if you made a mistake, instead, you should run these tools on your own machine during the development. Many of these tools can fix the violations for you automatically and it will generally be a better experience for you. Running these tools locally will also prevent a bunch of \"Fix the CI\" commits, which just clutter the git history.</p> <p>Make sure to read our contributing guidelines thoroughly, as they describe how to use these tools and even how to have them run automatically before each commit, so you won't forget.</p> <p>Passing the CI workflows is a requirement in order to get your pull request merged. If a maintainer sees a PR that's marked as ready for review, but isn't passing the CI, we'll often refrain from even reviewing it, as we consider it incomplete. If you have a technical reason why your PR can't pass the CI, let us know in the PR description or a comment.</p>"},{"location":"contributing/making-a-pr/#code-review","title":"Code Review","text":"<p>All pull requests will need to be reviewed by at least one team member before merging. The reviewer will provide feedback and suggestions for improvement.</p> <p>Once a reviewer approves your pull request, it can be merged into the <code>main</code> branch.</p> How do I request a review? <p>Request a review from a team member by assigning them as a reviewer to your pull request.</p> <p>However, you can also just wait until we get to your PR, you don't need to assign a reviewer unless you want someone specific to review. Just make sure that your PR is marked as ready for review and not draft.</p>"},{"location":"contributing/making-a-pr/#giving-feedback","title":"Giving Feedback","text":"<p>If you wish, you can also provide some feedback on other PRs. Doing so is a great way to fill the time while you're waiting for your PR to be reviewed by us and you're also speeding up the process, as it reduces the amount of time we'd have to spend reviewing those other PRs before getting to yours.</p> <p>When reviewing a pull request, aim to be constructive and specific. Highlight areas that need improvement and suggest potential solutions. If you have any questions on concerns about something in the code, don't hesitate to ask the author for clarification.</p> <p>Focus on the following aspects during a code review:</p> <ul> <li>Correctness and functionality</li> <li>Code quality and readability</li> <li>Adherence to the project guidelines</li> </ul> Good Code Review Feedback <p>Here are some examples of a good code review feedback:</p> <pre><code>- Great work on the new function! The implementation looks good overall.\n- The tests cover most of the functionality, but it's are missing a test case for edge case X. Could you add a test for that?\n- The logic in the new function is somewhat complex. Consider breaking it into smaller functions for better clarity.\n- The new feature is well-implemented, but it would be great to add more inline comments to explain the logic, as\n  it isn't trivial to understand.\n- There's a small typo in the docstring. Could you correct it?\n- The configuration settings are hard-coded. Can you move them to a configuration file to make it easier to manage?\n</code></pre> <p>Always be respectful and considerate when giving feedback. Remember that the goal is to improve the code and help the author grow as a developer.</p> <p>Be Positive</p> <p>Don't forget to acknowledge the positive aspects of the contribution as well!</p>"},{"location":"contributing/reporting-a-bug/","title":"Bug reports","text":"<p>Mcproto is an actively maintained project that we constantly strive to improve. With a project of this size and complexity, bugs may occur. If you think you have discovered a bug, you can help us by submitting an issue to our public issue tracker, following this guide.</p>"},{"location":"contributing/reporting-a-bug/#before-creating-an-issue","title":"Before creating an issue","text":"<p>Before opening a new issue with your bug report, please do the following things:</p>"},{"location":"contributing/reporting-a-bug/#upgrade-to-latest-version","title":"Upgrade to latest version","text":"<p>Chances are that the bug you discovered was already fixed in a subsequent version. Thus, before reporting an issue, ensure that you're running the latest version of mcproto.</p> <p>Bug fixes are not backported</p> <p>Please understand that only bugs that occur in the latest version of mcproto will be addressed. Also, to reduce duplicate efforts, fixes cannot be backported to earlier versions.</p>"},{"location":"contributing/reporting-a-bug/#search-for-existing-issues","title":"Search for existing issues","text":"<p>It's possible that the issue you're having was already reported. Please take some time and search the existing issues in the GitHub repository for your problem. If you do find an existing issue that matches the problem you're having, simply leave a  reaction instead (avoid commenting \"I have this issue too\" or similar, as that ultimately just clutters the discussion in that issue, but if you do think that you have something meaningful to add, please do).</p> <p>Note</p> <p>Make sure to also check the closed issues. By default, github issue search will start with: <code>is:issue is:open</code>, remove the <code>is:open</code> part to search all issues, not just the opened ones. It's possible that we seen this issue before, but closed the issue as something that we're unable to fix.</p>"},{"location":"contributing/reporting-a-bug/#creating-a-new-issue","title":"Creating a new issue","text":"<p>At this point, when you still haven't found a solution to your problem, we encourage you to create an issue. To do so, you can click here.</p>"},{"location":"contributing/reporting-a-bug/#writing-good-bug-reports","title":"Writing good bug reports","text":"<p>We have a GitHub issue template set up, which will guide you towards telling us everything that we need to know. However, for the best results, keep reading through this section. In here, we'll explain how a well formatted issue should look like in general and what it should contain.</p>"},{"location":"contributing/reporting-a-bug/#issue-title","title":"Issue Title","text":"<p>A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug you want to report can be inferred right from the title.</p> Example Clear Ping packet has incorrect ID Wordy The Ping packet has an incorrect packet ID of 0, when it should be 1 Unclear Ping packet is incorrect Non-english El paquete ping tiene una identificaci\u00f3n incorrecta Useless Help"},{"location":"contributing/reporting-a-bug/#bug-description","title":"Bug description","text":"<p>Now, to the bug you want to report. Provide a clear, focused, specific and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported to us. Adhere to the following principles:</p> <ol> <li>Explain the what, not the how \u2013 don't explain how to reproduce the bug here,    we're getting there. Focus on articulating the problem and its impact as clearly as possible.</li> <li>Keep it short and concise - if the bug can be precisely explained in one or two sentences, perfect. Don't    inflate it - maintainers and future users will be grateful for having to read less.</li> <li>Don't under-explain - don't leave out important details just to keep things short. While keeping things short is    important, if something is relevant, mention it. It is more important for us to have enough information to be able    to understand the bug, even if it means slightly longer bug report.</li> <li>One bug at a time - if you encounter several unrelated bugs, please create separate issues for them. Don't    report them in the same issue, as this makes it difficult for others when they're searching for existing issues and    also for us, since we can't mark such an issue as complete if only one of the bugs was fixed.</li> </ol> <p> Stretch goal \u2013 if you have a link to an existing page that describes the issue, or otherwise explains some of your claims, include it. Usually, this will be a https://wiki.vg link leading to the Minecraft protocol documentation for something.</p> <p> Stretch goal #2 \u2013 if you found a workaround or a way to fix the bug, you can help other users temporarily mitigate the problem before we maintainers can fix the bug in our code base.</p>"},{"location":"contributing/reporting-a-bug/#reproduction","title":"Reproduction","text":"<p>A minimal reproducible example is at the heart of every well-written bug report, as it allows us maintainers to instantly recreate the necessary conditions to inspect the bug and quickly find its root cause from there. It's a proven fact that issues with concise and small reproductions can be fixed much faster.</p> <p>Focus on creating a simple and small code snippet that we can run to see the bug. Do your best to avoid giving us large snippets or whole files just for the purpose of the reproducible example, do your best to reduce the amount of code as much as you can and try to avoid using external dependencies in the snippet (except for mcproto of course).</p> <p>Sometimes, the bug can't be described in terms of code snippets, such as when reporting a mistake in the documentation, in that case, provide a link to the documentation or whatever other relevant that will allows us to see the bug with minimal effort.</p>"},{"location":"contributing/reporting-a-bug/#next-steps","title":"Next steps","text":"<p>Once you submit the issue, the main part of reporting a bug is done, but things aren't completely over yet. You now have 2 choices:</p>"},{"location":"contributing/reporting-a-bug/#wait-for-us-to-get-to-the-problem","title":"Wait for us to get to the problem","text":"<p>If you don't wish to solve the bug yourself, all that remains is waiting for us to handle it.</p> <p>Please understand that we are all volunteers here and we work on the project simply the fun of it. This means that we may sometimes have other priorities in life or we just want to work on some more interesting tasks first. It might therefore take a while for us to get to your bug (don't worry though, in most cases, we're pretty quick). Even if things are slower, we kindly ask you to avoid posting comments like \"Any progress on this?\" as they are not helpful and create unnecessary clutter in the discussion.</p> <p>When we do address your issue, we might need further information from you. GitHub has a notification system, so once we respond, you will be notified there. Note that, by default, these notifications might not be forwarded to your email or elsewhere, so please check GitHub periodically for updates.</p> <p>Finally, when we fix your bug, we will mark the issue as closed (GitHub will notify you of this too). Once that happens, your bug should be fixed, but we appreciate it if you take the time to verify that everything is working correctly. If the issue persists, you can reopen the issue and let us know.</p> <p>Issues are fixed on the main branch</p> <p>Do note that when we close an issue, it means that we have fixed your bug in the <code>main</code> branch of the repository.   That doesn't necessarily mean the fix has been released on PyPI yet, so you might still need to wait for the next   release. Alternatively, you can also try the git installation to   get the project right from that latest <code>main</code> branch.</p>"},{"location":"contributing/reporting-a-bug/#attempt-to-solve-it-yourself","title":"Attempt to solve it yourself","text":"<p>Quote</p> <p>The fastest way to get something done is to avoid waiting on others.</p> <p>If you wish to try and tackle the bug yourself, let us know by commenting on the issue with something like \"I'd like to work on this\". This helps us avoid duplicate efforts and ensures that we don't work on something you're already addressing.</p> <p>Once a maintainer sees your comment, they will assign the issue to you. Being assigned is a soft approval from us, giving you the green light to start working.</p> <p>Of course, you are welcome to start working on the issue even before being officially assigned. However, please be aware that sometimes we choose not to fix certain bugs for specific reasons. In such cases, your work might not end up being used.</p> <p>Before starting your work though, make sure to also read our pull request guide.</p>"},{"location":"contributing/guides/","title":"Contributing guides &amp; guidelines","text":"<p>Welcome to the contributing guides &amp; guidelines for mcproto. This documentation is intended for our contributors, interested in writing or modifying mcproto itself. If you just wish to use mcproto in your project, you can safely skip this section.</p> <p>Mcproto is a relatively large project and maintaining it is no easy task. With a project like that, consistency and good code quality becomes very important to keep the code-base readable and bug-free. To achieve this, we have put together these guidelines that will explain the code style and coding practices that we expect our contributors to follow.</p> <p>This documentation will also include various guides that tell you how to set up our project for development and explain the automated tools that we use to improve our coding experience and enforce a bunch of the code style rules quickly and without the need for human review.</p>"},{"location":"contributing/guides/#the-golden-rules-of-contributing","title":"The Golden Rules of Contributing","text":"<p>These are the general rules which you should follow when contributing. You can glance over these and then go over the individual guides one by one, or use the references in these rules to get to the specific guide page explaining the rule.</p> <p>Note</p> <p>This list serves as a quick-reference rather than a full guide. Some of our guidelines aren't directly linked in these references at all and we heavily encourage you to go over each of the guide pages in the order they're listed in the docs.</p> <ol> <li>Lint before you push. We have multiple code linting rules, which define our general style of the code-base.    These are often enforced through certain tools, which you are expected to run before every push and ideally even    before every commit. The specifics of our linting rules are mentioned in our style guide.    Running all of these tools manually before every commit would however be quite annoying, so we use    pre-commit.</li> <li>Make great commits. Great commits should be atomic (do one thing only and do it well), with a commit message    that explaining what was done, and why. More on this here.</li> <li>Make an issue before the PR. Before you start working on your PR, open an issue and let us know what you're    planning. We described this further in our making a PR guide.</li> <li>Use assets licensed for public use. Whenever you're adding a static asset (e.g. images/video files/audio or    even code) that isn't owned/written by you, make sure it has a compatible license with our projects.</li> <li>Follow our Code of Conduct</li> </ol>"},{"location":"contributing/guides/#changes-to-these-guidelines","title":"Changes to these guidelines","text":"<p>While we're confident and happy with the current code style and tooling, we acknowledge that change is inevitable. New tools are constantly being developed, and we have already made significant updates to our code style in the past.</p> <p>Every project evolves over time, and these guidelines are no exception. This documentation is open to pull requests and changes from contributors. Just ensure that any updates to this document are in sync with the codebase. If you propose a code style change, you must apply that change throughout the codebase to maintain internal consistency.</p> <p>If you believe you have something valuable to add or change, please submit a pull request. For major style changes, we strongly encourage you to open an issue first, as we may not always agree with significant alterations. For minor clarity improvements or typo fixes, opening an issue isn't necessary.</p> <p>We tried to design our specifications to be straightforward and comprehensive, but we might not always succeed, as we're doing so from our perspective of already having extensive background knowledge. Therefore, we welcome any clarity improvements to the documentation. If you think you can explain something better, please contribute.</p>"},{"location":"contributing/guides/#footnotes","title":"Footnotes","text":"<p>We understand that going through all of these guidelines can be time-consuming and a lot to remember. However, we strongly encourage you to review them, especially if you haven't worked with these tools or followed such best practices before.</p> <p>Every page in this contributing guides category has an abstract at the top, summarizing its content. This allows you to quickly determine if you are already familiar with the topic or, if you're re-reading, to quickly recall what the page covers. Feel free to skip any guide pages if you're already familiar with what they cover.</p> <p>We believe these guides will be beneficial to you beyond our codebase, as they promote good coding practices and help make your code cleaner. You will likely be able to apply much of the knowledge you gain here to your own projects.</p>"},{"location":"contributing/guides/#disclaimer","title":"Disclaimer","text":"<p>These documents were inspired by Python Discord's CONTRIBUTING agreement.</p>"},{"location":"contributing/guides/changelog/","title":"Changelog fragments","text":"Abstract <p>This page describes our use of <code>towncrier</code> for the project's changelog. It explains the different changelog categories, the process of creating changelog fragment files and generating a changelog preview. Additionally, the page contains a guide on writing good changelog fragments.</p> <p>Our project contains a changelog which tracks all notable changes for easy and quick reference to both users and our contributors.</p> <p>To maintain our changelog, we're using <code>towncrier</code>, which allows us to create fragment files, which each contains a single changelog entry. Once a new release is created, all of these fragments will be used to create a changelog for that new release.</p> <p>We generally require every pull request to to include a new changelog fragment, summarizing what it does.</p> <p>Note</p> <p>If you think your change shouldn't require a changelog entry (it's a small / simple change that isn't worth noting), ask us to add the <code>skip-fragment-check</code> label to your PR, which will disable the automated check that enforces a presence of the changelog fragment.</p>"},{"location":"contributing/guides/changelog/#structure-of-a-fragment-file","title":"Structure of a fragment file","text":"<p>The fragment files are stored in the <code>changes/</code> directory in our project. These files follow the following naming format: <code>{pull_request_number}.{type}.md</code>.</p> <p>Possible fragment types are:</p> <ul> <li><code>feature</code>: New feature that affects the public API.</li> <li><code>bugfix</code>: A bugfix, which was affecting the public API.</li> <li><code>docs</code>: Change to the documentation, or updates to public facing docstrings</li> <li><code>breaking</code>: Signifying a breaking change of some part of the project's public API, which could cause issues for     end-users updating to this version. (Includes deprecation removals.)</li> <li><code>deprecation</code>: Signifying a newly deprecated feature, scheduled for eventual removal.</li> <li><code>internal</code> Fully internal change that doesn't affect the public API, but is significant enough to be mentioned,     likely because it affects project contributors. (Such as a new linter rule, change in code style, significant change     in internal API, ...)</li> </ul>"},{"location":"contributing/guides/changelog/#create-fragments-with-commands","title":"Create fragments with commands","text":"<p>While you can absolutely create these files manually, it's often a lot more convenient to use the <code>towncrier</code> CLI, which can create the file for you in the proper place automatically. With it, you can simply run:</p> <pre><code>towncrier create {pull_request_number}.{type}.md\n</code></pre> <p>After you ran the command, a new file will appear in the <code>changes/</code> directory. You can now open it and describe your change inside of it.</p> <p>If the change is simple enough, you can even use the <code>-c</code> / <code>--content</code> flag to specify it directly, like:</p> <pre><code>towncrier create 12.feature.md -c \"Add dinosaurs!\"\n</code></pre> <p>Terminal editors</p> <p>If you're used to terminal editors, there's also an <code>--edit</code> flag, which will open the file with your <code>$EDITOR</code>. (I would recommend <code>neovim</code>, but if you find it too complex, <code>nano</code> also works well)</p>"},{"location":"contributing/guides/changelog/#multiple-fragments-in-a-single-pr","title":"Multiple fragments in a single PR","text":"<p>If necessary, multiple fragment files can be created per pull-request, with different change types, if the PR covers multiple areas. For example for PR #13 that both introduces a feature, and changes the documentation, can add 2 fragment files: <code>13.feature.md</code> and <code>13.docs.md</code>.</p> <p>Additionally, if a single PR is addressing multiple unrelated topics in the same category, and needs to make multiple distinct changelog entries, an optional counter value can be added at the end of the file name (needs to be an integer). So for example PR #25 which makes 2 distinct internal changes can add these fragment files: <code>25.internal.1.md</code> and <code>25.internal.2.md</code>. (The numbers in this counter position will not be shown in the final changelog and are merely here for separation of the individual fragments.)</p> <p>However if the changes are related to some bigger overarching goal, you can also just use a single fragment file with the following format:</p> changes/25.internal.md<pre><code>Update towncrier categories\n\n    - Rename `documentation` category to shorter: `docs`\n    - Add `internal` category for changes unrelated to public API, but potentially relevant to contributors\n    - Add github workflow enforcing presence of a new changelog fragment file for each PR\n        - For insignificant PRs which don't require any changelog entry, a maintainer can add `skip-fragment-check` label.\n</code></pre> <p>Warning</p> <p>While possible, if you end up making multiple distinct changelog fragments like this, it's a sign that your PR might be too big, and you should split it up into multiple PRs instead. Making huge PRs that address several unrelated topics at once is generally a bad practice, and should be avoided. If you go overboard, your PR might even end up getting closed for being too big, and you'll be required to split it up.</p>"},{"location":"contributing/guides/changelog/#preview-changelog","title":"Preview changelog","text":"<p>To preview the latest changelog, run <code>towncrier build --draft --version latest</code>.</p> Meaning of the version value <p>The <code>--version</code> attribute usually takes the version number of the project, to which these changes apply. However, since we just want to preview the changes, it doesn't really matter for us, so we can just pass <code>latest</code> or whatever else you wish.</p> <p>For actual builds, the version is automatically obtained and this command is executed in our release CI workflow.</p> <p>This version will be used in the first line of the changelog (the header).</p> Meaning of --draft flag <p>The <code>--draft</code> flag will make sure that towncrier will only show you the contents of the next changelog version entry, but won't actually add that generated content to our <code>CHANGELOG.md</code> file, while consuming (removing) the changelog fragments.</p> <p>You will never need to run <code>towncrier</code> without the <code>--draft</code> flag, as our CI workflows for project releasing handle that automatically.</p> <p>To make this a bit easier, there is a taskipy task running the command above, so you can just use <code>poetry run task changelog-preview</code> to see the changelog, if you don't like remembering new commands.</p>"},{"location":"contributing/guides/changelog/#writing-good-changelog-fragments","title":"Writing good changelog fragments","text":"<p>Fragment files follow the same markdown syntax as our documentation.</p> <p>The contents of a fragment file should describe the change that you've made in a quick and general way. That said, the change descriptions can be a bit more verbose than just the PR title, but only if it's necessary. Keep in mind that these changes will be shown to the end users of the library, so try to explain your change in a way that a non-contributor would understand.</p> <p>Tip</p> <p>If your change needs some more in-depth explanations, perhaps with code examples and reasoning for why such a change was made, use the PR body (description) for this purpose. Each changelog entry will contain a link to the corresponding pull request, so if someone is interested in any additional details about a change, they can always look there.</p>"},{"location":"contributing/guides/changelog/#examples-of-good-changlog-fragment-files","title":"Examples of good changlog fragment files","text":"<p> Clear and descriptive</p> changes/171.feature.md<pre><code>Add `Account.check` function, to verify that the access token in use is valid, and the data the Account instance has matches the data minecraft API has.\n</code></pre> changes/179.docs.md<pre><code>Enforce presence of docstrings everywhere with pydocstyle. This also adds docstring to all functions and classes that didn't already have one. Minor improvements for consistency were also made to some existing docstrings.\n</code></pre> <p> Slightly on the longer side, but it's justified (Sometimes, it's important to explain the issue that this fixes, so that users know that it was there)</p> changes/330.bugfix.md<pre><code>Fix behavior of the `mcproto.utils.deprecation` module, which was incorrectly always using a fallback version, assuming mcproto is at version 0.0.0. This then could've meant that using a deprecated feature that is past the specified deprecation (removal) version still only resulted in a deprecation warning, as opposed to a full runtime error.\n</code></pre> <p> With an extra note about the breaking change (Adding some extra description isn't always bad, especially for explaining how a breaking change affects existing code)</p> changes/130.breaking.md<pre><code>Renamed \"shared_key\" field to \"shared_secret\" in `LoginEncryptionPacket`, following the official terminology.\n\n    This is a breaking change as `LoginEncryptionPacket`'s `__init__` method now uses \"shared_secret\" keyword only\n    argument, not \"shared_key\". Every initialization call to this packet needs to be updated.\n</code></pre> <p> With a list of subchanges that were made (Be careful with this one though, make sure you don't over-do it)</p> changes/129.feature.md<pre><code>Added a system for handling Minecraft authentication\n\n    - Yggdrasil system for unmigrated i.e. non-Microsoft accounts (supportng Minecraft accounts, and the really old\n      Mojang accounts)\n    - Microsoft OAuth2 system (Xbox live) for migrated i.e. Microsoft accounts\n</code></pre>"},{"location":"contributing/guides/changelog/#examples-of-bad-changelog-fragment-files","title":"Examples of bad changelog fragment files","text":"<p> Unclear (But what does this class do?)</p> changes/123.feature.md<pre><code>Update `Buffer` class.\n</code></pre> <p> Bad category (This is a feature, not a bugfix)</p> changes/161.bugfix.md<pre><code>Add support for encryption. Connection classes now have `enable_encryption` method, and some encryption related functions were added into a new mcproto.encryption module.\n</code></pre> <p> Starts with dash (Sometimes, it can feel natural to start your changelog entry with a <code>-</code>, as it is a list item in the final changelog, however, this dash will already be added automatically)</p> changes/171.feature.md<pre><code>-   Add `Account.check` function, to verify that the access token in use is valid, and the data the Account instance has matches the data minecraft API has.\n</code></pre> <p> Wrapped first line (Splitting up the first line into multiple lines is something we often do in markdown, because it should still be rendered as a single line, however, because of how towncrier merges these fragments, using multiple lines will cause issues and the changelog won't be formatter correctly! Further blocks can have wrapped lines.)</p> changes/330.bugfix.md<pre><code>Fix behavior of the `mcproto.utils.deprecation` module, which was incorrectly always using a fallback version, assuming\nmcproto is at version 0.0.0. This then could've meant that using a deprecated feature that is past the specified\ndeprecation (removal) version still only resulted in a deprecation warning, as opposed to a full runtime error.\n</code></pre> <p> No indent in description (Sometimes, we want to add additional description to our changelog entry. When doing so, we need to make sure that the description block is indented with 4 spaces and there is a blank line after the first / title line.)</p> changes/330.breaking.md<pre><code>Renamed \"shared_key\" field to \"shared_secret\" in `LoginEncryptionPacket`, following the official terminology.\n\nThis is a breaking change as `LoginEncryptionPacket`'s `__init__` method now uses \"shared_secret\" keyword only\nargument, not \"shared_key\". Every initialization call to this packet needs to be updated.\n</code></pre> <p> Way too long (This should've been the PR description)</p> changes/161.feature.md<pre><code>Introduce support for encryption handling.\n\n    Most servers (even offline ones) usually send an EncryptionRequest packet during the LOGIN state, with a public\n    (RSA) key that the client is expected to use to encrypt a randomly generated shared secret, to send back to the\n    server in EncryptionResponse packet. After that, all further communication is encrypted with this shared secret.\n\n    The encryption used is a AES/CFB8 stream cipher. That means the encrypted ciphertext will have the same amount\n    of bytes as the original plaintext, allowing us to still trust our reader/writer methods that rely on reading\n    specific amounts of bytes, even if their content don't make sense.\n\n    This directly uses the base connection classes and adds enable_encryption method to them, which after getting\n    called will automatically encrypt/decrypt any incomming/outcomming data.\n\n    This additionally also changes the LoginEncryptionRequest packet class, and makes the public key attribute\n    actually hold an RSA public key (from the cryptography library), instead of just the received bytes. This is\n    then much more useful to work with later on. This is a breaking change.\n</code></pre> <p>Verify if your changelog works</p> <p>Our CI will automatically build the documentation for your PR and post a link to it as a comment in the pull request. This documentation will include a preview of the changelog with all unreleased changes in the changelog page. You can take a look there to make sure that your change fragment(s) resulted in the proper output.</p> <p>Internal changes</p> <p>We're a bit more forgiving when it comes to describing your change if your change is in the <code>internal</code> category, as end users don't need to read those. Changes in this category can be a bit less descriptive.</p>"},{"location":"contributing/guides/changelog/#footnotes","title":"Footnotes","text":"<ul> <li>See https://keepachangelog.com for more info about why and how to properly maintain a changelog</li> <li>For more info about <code>towncrier</code>, check out it's documentation</li> </ul>"},{"location":"contributing/guides/deprecations/","title":"Deprecations","text":"<p>Work In Progress</p> <p>This page is still being written. The content below (if any) may change.</p>"},{"location":"contributing/guides/docstrings/","title":"Docstring formatting","text":"<p>Work In Progress</p> <p>This page is still being written. The content below (if any) may change.</p>"},{"location":"contributing/guides/docstrings/#docstring-formatting-directive","title":"Docstring formatting directive","text":""},{"location":"contributing/guides/great-commits/","title":"Great Commits","text":"Abstract <p>This guide describes how to make good commits that are helpful to maintainers, debuggable and readable when going over the <code>git log</code>, or <code>git blame</code>.</p> <p>It explains the purpose of a commit message and it's structure, goes over the importance of making commits \"atomic\" and the practice of partial staging, mentions why and how to avoid making a lot of fixing commits, describes force pushing after modifying the git history, alongside it's downsides and finally, it explains why these practices are worth following and how they make the developer's life easier.</p> <p>A well-structured git log is crucial for a project's maintainability, providing insight into changes as a reference for future maintainers (or old forgetful ones, like me). Here, we outline the best practices for making good commits in our project.</p>"},{"location":"contributing/guides/great-commits/#commit-message-guidelines","title":"Commit Message Guidelines","text":""},{"location":"contributing/guides/great-commits/#purpose","title":"Purpose","text":"<p>Every commit should represent a change in the source code. The commit message should not only describe what was changed but also why it was necessary and what it achieves.</p>"},{"location":"contributing/guides/great-commits/#more-than-just-the-first-line","title":"More than just the first line","text":"<p>Many developers are uesd to commiting changes with a simple <code>git commit -m \"My message\"</code>, and while this is enough and it's perfectly fine in many cases, sometimes you just need more space to describe what a change truly achieves.</p> <p>Surprisingly, many people don't even know that they can make a commit that has more in it's message than just the title/first line. That then leads to poorly documented changes, because single line sometimes just isn't enough.</p> <p>To create a commit with a bigger commit message, you can simply run the <code>git commit</code> command without the <code>-m</code> argument. This should open a temporary file in your text editor (<code>$EDITOR</code>), in which you can write out your commit message in full.</p> Use git commit by default <p>I\u2019d actually recommend making the simple <code>git commit</code> the default way you make new commits, since it invites you to write more about it, by just seeing that you have that space available. We usually don\u2019t even know what exactly we\u2019ll write in our new commit message before getting to typing it out, and knowing you have that extra space if you need it will naturally lead to using it, even if you didn\u2019t know you needed it ahead of time.</p> <p>Note</p> <p>That said, not every commit requires both a subject and a body. Sometimes, a change may be so simple, that no further context is necessary. With those changes, including a body would just be a waste of the readers time. For example:</p> <pre><code>Fix typo in README\n</code></pre> <p>This message doesn't need anything extra. Some people like to include what the typo was, but if you want to know that, you can just look at the actual changes that commit made. There's a whole bunch of ways to do that with git, like <code>git show</code>, <code>git diff</code> or <code>git log --patch</code>. So while in some cases, having extra context can be very valuable, you also shouldn't overdo it.</p>"},{"location":"contributing/guides/great-commits/#structure","title":"Structure","text":"<p>Git commits should be written in a very specific way. There\u2019s a few rules to follow:</p> <ol> <li>Subject Line:<ul> <li>Limit to 50 characters (This isn't a hard limit, but try not to go much longer. This limit ensures   readability and forces the author to thing about the most concise way to explain what's going on. Hint: If you're   having trouble summarizing, you might be committing too much at once)</li> <li>A single sentence (The summary should be a single sentence, multiple probably wouldn't fit into the character   limit anyways)</li> <li>Capitalize the first letter</li> <li>Don't end with a period (A period will only waste one of your precious 50 characters for the summary and   it's not very useful context wise)</li> <li>Use imperative mood (Imperative mood means \u201cwritten as if giving a command/instruction\u201d i.e.: \u201cAdd support   for X\u201d, not \u201cI added support for X\u201d or \u201cSupport for X was added\u201d, as a rule of thumb, a subject message should be   able to complete the sentence: \u201cIf implemented, this commit will \u2026\u201d)</li> </ul> </li> <li>Body:<ul> <li>Separate the body from the subject line with a blank line (Not doing so would make git think your summary   spans across multiple lines, rather than it being a body)</li> <li>Wrap at 72 characters (Commits are often printed into the terminal with the <code>git log</code> command. If the output   isn't wrapped, going over the terminals width can cause a pretty messy output. The recommended maximum width for terminal text output is 80 characters, but git tools can often add indents, so 72 characters is a sensible maximum)</li> <li>Avoid implementation details (The diff shows the \"how\", focus on the \"what\" and \"why\")</li> </ul> </li> </ol> <p>Git commits can use markdown, most other programs will understand it and it's a great way to bring in some more style, improving the readability. In fact, if you view the commit from a site like GitHub, it will automatically render any markdown in the commit for you.</p> Example commit <pre><code>Summarize changes in around 50 characters or less\n\nMore detailed explanatory text, if necessary. Wrap it to about 72\ncharacters or so. In some contexts, the first line is treated as the\nsubject of the commit and the rest of the text as the body. The\nblank line separating the summary from the body is critical (unless\nyou omit the body entirely); various tools like `log`, `shortlog`\nand `rebase` can get confused if you run the two together.\n\nExplain the problem that this commit is solving. Focus on why you\nare making this change as opposed to how (the code explains that).\nAre there side effects or other unintuitive consequences of this\nchange? Here's the place to explain them.\n\nFurther paragraphs come after blank lines.\n\n- Bullet points are okay too\n- They're very useful for listing something\n</code></pre> <p> Stretch goal \u2013 Include relevant keywords to make your commits easily searchable (e.g. the name of the class/function you modified).</p> <p> Stretch goal #2 \u2013 Keep it engaging! Provide some interesting context or debug processes to make the commit history both more informative and fun to read.</p>"},{"location":"contributing/guides/great-commits/#make-atomic-commits","title":"Make \"atomic\" commits","text":"<p>Definition</p> <p>Atomic: of or forming a single irreducible unit or component in a larger system.</p> <p>The term \u201catomic commit\u201d means that the commit is only representing a single change, that can\u2019t be further reduced into multiple commits, i.e. this commit only handles a single change. Ideally, it should be possible to sum up the changes that a good commit makes in a single sentence.</p> <p>That said, the irreducibility should only apply to the change itself, obviously, making a commit for every line of code wouldn\u2019t be very clean. Having a commit only change a small amount of code isn\u2019t what makes it atomic. While the commit certainly can be small, it can just as well be a commit that\u2019s changing thousands of lines. (That said, you should have some really good justification for it if you\u2019re actually making commits that big.)</p> <p>The important thing is that the commit is only responsible for addressing a single change. A counter-example would be a commit that adds a new feature, but also fixes a bug you found while implementing this feature, and also improves the formatting of some other function, that you encountered along the way. With atomic commits, all of these actions would get their own standalone commits, as they\u2019re unrelated to each other, and describe several different changes.</p> <p>Note that making atomic commits isn't just about splitting thins up to only represent single changes, indeed, while they should only represent the smallest possible change, it should also be a \u201ccomplete\u201d change. This means that a commit responsible for changing how some function works in order to improve performance should ideally also update the documentation, make the necessary adjustments to unit-tests so they still pass, and update all of the references to this updated function to work properly after this change.</p> <p>Summary</p> <p>So, an atomic commit is a commit representing a single (ideally an irreducible) change, that\u2019s fully implemented and integrates well with the rest of the codebase.</p>"},{"location":"contributing/guides/great-commits/#partial-adds","title":"Partial adds","text":"<p>Many people tend to always simply use <code>git add -A</code> (or <code>git add .</code>), to stage all of the changes they made, and then create a commit with it all. Sometimes, you might not even stage the changes and choose to use <code>git commit -a</code>, to quickly commit everything.</p> <p>In an ideal world, where you only made the changes you needed to make for this single atomic commit, this would work pretty well, and while sometimes this is the case, in many cases, you might've also fixed a bug or a typo that you noticed while working on your changes, or already implemented something else, that doesn't fit into your single atomic commit that you now wish to make.</p> <p>In this case, it can be very useful to know that you can instead make a \"partial\" add, and only stage those changes that belong to the commit. In some cases, all that you'll need is to only stage some specific files, which you can do with:</p> <pre><code>git add path/to/some/file path/to/other/file\n</code></pre> <p>That said, in most cases, you're left with a single file that contains multiple changes. When this happens, you can use the <code>-p</code>/<code>--patch</code> flag:</p> <pre><code>git add -p path/to/file\n</code></pre> <p>Git will then let you interactively go over every \"hunk\" (a chunk of code, with changes close to each other) and let you decide whether to accept it (hence staging that single hunk), split it into more chunks, skip it (avoids staging this hunk) or even modify it in your editor, allowing you to remove the intertwined code from multiple changes, so that your commit will really only perform a single change.</p> <p>Use --patch more often</p> <p>This git feature has slowly became one of my favorite tools, and I use it almost every time I need to commit something, even if I don't need to change or skip things, since it also allows me to quickly review the changes I'm making, before they make it into a commit.</p>"},{"location":"contributing/guides/great-commits/#avoid-fixing-commits","title":"Avoid fixing commits","text":"<p>A very common occurrence I see in a ton of different projects is people making sequences of commits that go like:</p> <ul> <li>Fix bug X</li> <li>Actually fix bug X</li> <li>Fix typo in variable name</li> <li>Sort imports</li> <li>Follow lint rules</li> <li>Run auto-formatter</li> </ul> <p>While people can obviously mess up sometimes, and just not get something right on the first try, a fixing commit is rarely a good way to solve that.</p> <p>Instead of making a new commit, you can actually just amend the original. To do this, we can use the <code>git commit --amned</code>, which will add your staged changes into the previous commit, even allowing you to change the message of that old commit.</p> <p>Not only that, if you've already made another commit, but now found something that needs changing in the commit before that, you can use interactive rebase with <code>git rebase -i HEAD~3</code>, allowing you to change the last 3 commits, or even completely remove some of those commits.</p> <p>For more on history rewriting, I'd recommend checking the official git documentation.</p>"},{"location":"contributing/guides/great-commits/#force-pushing","title":"Force pushing","text":"<p>Changing history is a great tool to clean up after yourself, but it works best with local changes, i.e. with changes you haven't yet pushed.</p> <p>If you're changing git history after you've already pushed, you will find that pushing again will not work, giving you a message like \"updates were rejected because the remote contains work that you do not have locally\".</p> <p>To resolve this issue, it is possible to make a \"force push\" with <code>git push --force</code> command. Running this will push your branch to the remote (to GitHub) regardless of what was in the remote already, hence overriding it.</p> <p>Warning</p> <p>Force pushing becomes risky if others have already pulled the branch you are working on. If you overwrite the branch with a force push, it can lead to several issues:</p> <ul> <li>Lost Work: Collaborators may have pushed to your branch already, following it's existing git history.   However, after your force-push, their changes would be ereased from the remote. Make sure you pull / rebase   from the remote before you make a force-push.</li> <li>Complex conflicts: If someone else has pulled your branch and did some changes that they didn't yet push   before you force-pushed, suddenly, their git history is now no longer in sync. Resolving conflicts like that is   possible, but it can be very annoying.</li> <li>Harder reviews: When reviewing your code, we sometimes like going over the individual commits to understand   your individual (atomic) changes better. It's often a lot easier to look at and review 10 different atomic   changes individually, that together form a PR than it would be to look at all of them at once. By force-pushing,   you're changing the commit history, making the changes to the code that we already reviewed. This is partially   GitHub's fault though, for not providing an easier way of showing these changes across force-pushes.</li> </ul>"},{"location":"contributing/guides/great-commits/#force-pushing-on-pr-feature-branches","title":"Force pushing on PR feature branches","text":"<p>In our project, we do allow force pushing on your individual feature branches that you use for your PR. This flexibility enables you to clean up your commit history and refine your changes before they are merged into the main branch. However, it's important to note that many other projects may not permit force pushing due to the risks involved. Always check the contributing guidelines of the project you are working on.</p> <p>Best practices</p> <p>To mitigate the risks associated with force pushing, consider following these best practices:</p> <ul> <li>Push less often: Try to limit of othen you push changes to the remote repository in general. Aim to push only   when you are satisfied with the set of changes you have. This reduces the likelihood of needing to force-push a   lot.</li> <li>Force push quickly: If you do need to force-push, try to do so as quickly as possible. The more time that has   passed since your normal push, the more likely it is that someone have already clonned/pulled your changes. If a   force push was made within just a few seconds of the original push (and it only overwrites the changes from that   last push), it's not very likely that someone will have those changes pulled already, so you probably won't break   anyone's local version.</li> <li>Pull before changing history: Make absolutely certain that you don't override anyone's changes with your   force-push. Sometimes, maintainers can create new commits in your branch, other times, that can even be you by   modifying something from GitHub, or clicking on the apply suggestion button from a code-review. By pulling before   you start changing history, you can make sure that you won't erease these changes and they'll remain a part of   your modified history.</li> </ul>"},{"location":"contributing/guides/great-commits/#benefits","title":"Benefits","text":"<p>Now that you've seen some of the best practices to follow when making new commits, let's talk a bit about why we follow these practices and what benefits we can gain from them.</p>"},{"location":"contributing/guides/great-commits/#a-generally-improved-development-workflow","title":"A generally improved development workflow","text":"<p>Speaking from my personal experience, I can confidently say that learning how to make good git commits, specifically the practice of making atomic commits will make you a better programmer overall. That might sound surprising, but it's really true.</p> <p>The reason is that it forces you to only tackle one issue at a time. This naturally helps you to think about how to split your problem into several smaller (atomic) subproblems and make commits addressing those single parts. This is actually one of very well known approaches to problem-solving, called the \"divide and conquer\" method, where you split your problem into really small, trivially simple chunks that you solve one by one.</p>"},{"location":"contributing/guides/great-commits/#easier-bug-hunting","title":"Easier bug hunting","text":"<p>Bugs in code are pretty much inevitable, even for the most experienced of developers. Sometimes, we just don't realise how certain part of the code-base will interact with another part, or we're just careless as we try and build something fast.</p> <p>The most annoying bugs are those that aren't discovered immediately during development. These bugs can require a lot of work to track down. With a good git log, filled with a lot of small commits, where each commit leaves the code-base in a usable state, you can make this process a lot simpler!</p> <p>Git has a command specifically for this: <code>git bisect</code>. It will first make you mark 2 commits, a good one and a bad one, after which it will perform a binary search, checking out the commits in between these two as you try and replicate the bug on each. This will quickly lead you to the specific commit that introduced this bug, without having to do any code debugging at all.</p> <p>The great advantage here is that users reporting bugs can often perform git bisects too, even without having to know much about development and the structure of our code-base and if the identified commit is small enough, the issue is often apparent just from looking at the diff. Even for bigger commits though, they can be often reverted to quickly fix the issue and give developers time to focus on actually resolving it, while using it's diff as a reference.</p>"},{"location":"contributing/guides/great-commits/#enhanced-git-blame","title":"Enhanced git blame","text":"<p>Clear commit messages can be very useful for understanding certain parts of the code. Git provides a tool called <code>git blame</code>, which can show you which commit is responsible for adding a specific line into the code-base. From there, you can then take a look at that commit specifically and see it's title &amp; description to further understand that change, along with the rest of the diff to give you proper context for how that line worked with the rest of the code.</p> <p>This can often be a great tool when refactoring, as sometimes it can be quite unclear why something is done the way it is and commits can sometimes help explain that.</p>"},{"location":"contributing/guides/great-commits/#efficient-cherry-picking","title":"Efficient cherry picking","text":"<p>In some cases, it can be useful to carry over certain change (commit) from one place to another. This process is called cherry-picking (<code>git cherry-pick</code>), which will copy a commit and apply it's diff elsewhere. With atomic commits, this will often work without any further adjustments, since each commit should itself leave you with a functioning project.</p>"},{"location":"contributing/guides/great-commits/#streamlined-pull-request-reviews","title":"Streamlined pull request reviews","text":"<p>Reviewers can often better understand and verify changes by examining your well-structured commits, improving the review process.</p>"},{"location":"contributing/guides/great-commits/#footnotes","title":"Footnotes","text":"<p>This guide took heavy inspiration from this article: https://itsdrike.com/posts/great-commits/.</p> <p>Quote</p> <p>P.S. It's not plagiarism if the original was written by me :P</p> <p>See the original article's sources for proper attributions.</p>"},{"location":"contributing/guides/precommit/","title":"Pre-commit","text":"Abstract <p>This guide explains what is pre-commit and how to set it up as a git hook that will run automatically before your commits. It also describes how to run pre-commit manually from the CLI, how to skip some or all of the individual checks it performs, what happens when hooks edit files and where it's configuration file is.</p> <p>Now that you've seen the linters, formatters, type-checkers and other tools that we use in the project, you might be wondering whether you're really expected to run all of those commands manually, after each change. And of course, no, you're not, that would be really annoying, and you'd probably also often just forget to do that.</p> <p>So, instead of that, we use a tool called <code>pre-commit</code>, which creates a git hook, that will automatically run before each commit you make. That means each time when you make a commit, all of these tools will run over the code you updated, and if any of these linters detects an issue, the commit will be aborted, and you will see which linter failed, and it's output telling you why.</p>"},{"location":"contributing/guides/precommit/#installing-pre-commit","title":"Installing pre-commit","text":"<p>To install pre-commit as a git hook all you need to do is to run:</p> <pre><code>pre-commit install\n</code></pre> <p>This will install pre-commit as a git hook into your git repository, which will mean it will run automatically before every new commit you make.</p> <p>Warning</p> <p>Pre-commit itself will be installed via poetry, which means you will need to have an activated poetry environment whenever you make a new commit, otherwise, the pre-commit git hook will fail with command not found.</p>"},{"location":"contributing/guides/precommit/#hooks-that-modify-files","title":"Hooks that modify files","text":"<p>Sometimes, hooks can end up modifying your files, for example the ruff format hook may do so if your file wasn't already formatted by ruff. When this happens, the hook itself will fail, which will make git abort the commit. At this point, you will be left with the original changes still staged, but some files may have been modified, which means you'll want to <code>git add</code> those again, staging these automatic modifications and then make the commit again.</p> <p>Note that in case you were only committing a partial change, which means you still had some parts of the file unstaged, pre-commit will not modify the files for you. Instead, the hook will just fail, leaving the rest up to you. You should now run the formatter yourself and perform another partial add, updating the staged changes to be compliant.</p>"},{"location":"contributing/guides/precommit/#running-manually","title":"Running manually","text":"<p>Even though in most cases, it will be more than enough to have pre-commit run automatically as a git hook, sometimes, you may want to run it manually without making a commit.</p> <p>Tip</p> <p>You can run this command without having pre-commit installed as a git hook at all. This makes it possible to avoid installing pre-commit and instead running all checks manually each time. That said, we heavily recommend that you instead install pre-commit properly, as it's very easy to forget to run these checks.</p> <p>To run pre-commit manually you can use the following command:</p> <pre><code>pre-commit run --all-files\n</code></pre> <p>Using this command will make pre-commit run on all files within the project, rather than just running against the git staged ones, which is the behavior of the automatically ran hook.</p>"},{"location":"contributing/guides/precommit/#skipping-pre-commit","title":"Skipping pre-commit","text":"<p>Automatic skipping</p> <p>Pre-commit is pretty smart and will skip running certain tools depending on which files you modified. For example some hooks only check the validity of Python code, so if you haven't modified any Python files, there is no need to run those hooks.</p> <p>Even though in most cases enforcing linting before each commit is what we want, there are some situations where we need to commit some code which doesn't pass these checks. This can happen for example after a merge, or as a result of making a single purpose small commit without yet worrying about linters. In these cases, you can use the <code>--no-verify</code> flag when making a commit, telling git to skip the pre-commit hooks and commit normally. When making a commit, this would look like:</p> <pre><code>git commit -m \"My unchecked commit\" --no-verify\n</code></pre> <p>You can also only skip a specific hook, by setting <code>SKIP</code> environmental variable (e.g. <code>SKIP=basedpyright</code>) or even multiple hooks (<code>SKIP=ruff-linter,ruff-formatter,slotscheck</code>). When making a commit, this would look like:</p> <pre><code>SKIP=\"check-toml,slotscheck,basedpyright\" git commit -m \"My partially checked commit\"\n</code></pre> <p>The names of the individual hooks are their ids, you can find those in the configuration file for pre-commit.</p> <p>Warning</p> <p>This kind of verification skipping should be used sparingly. We value a clean history which consistently follows our linting guidelines, and making commits with linting issues only leads to more commits, fixing those issues later.</p>"},{"location":"contributing/guides/precommit/#configuration","title":"Configuration","text":"<p>You can find pre-commit's configuration the <code>.pre-commit-config.yaml</code> file, where we define which tools should be ran and how. Currently, pre-commit runs ruff linter, ruff formatter, slotscheck and basedpyright, but also a checker for some issues in TOML/YAML files.</p>"},{"location":"contributing/guides/setup/","title":"Setting things up","text":"<p>Work In Progress</p> <p>This page is missing a guide on configuring vscode to pick up poetry environment.</p>"},{"location":"contributing/guides/setup/#setting-up-the-project","title":"Setting up the project","text":"Abstract <p>This guide describes the very basics of setting up our project.</p> <p>It explains how to use <code>poetry</code> to install the python dependencies for the project. After which it goes over using poetry (activating the virtual environment, keeping the dependencies up to date as we update them, adding / removing dependencies and poetry dependency group).</p>"},{"location":"contributing/guides/setup/#pre-requisites","title":"Pre-requisites","text":"<p>A basic knowledge of git and GitHub, alongside working within the terminal and running commands is a requirement to work on this project.</p> <p>This guide assumes you have already forked our repository, clonned it to your computer and created your own git branch to work on.</p> <p>If you wish to work from an already forked repository, make sure to check out the main branch and do a <code>git pull</code> to get your fork up to date. Now create your new branch.</p>"},{"location":"contributing/guides/setup/#poetry","title":"Poetry","text":"<p>This project uses <code>poetry</code>. Poetry is a tool for managing python dependencies in a reproducible way, ensuring that everyone is using the same versions. It creates virtual environments for each project, which ensures that your global dependencies won't clash with the project.</p> More about virtual environments <p>A python virtual environment is essentially a separate mini installation of python used purely for the project you're working on (as opposed to using your system-wide python installation for everything).</p> <p>The reason we do this is to avoid dependency conflicts. Consder this: Our project needs library \"foo\" at version 2.5.2, however, you also have another unrelated project, that also needs the \"foo\" library, but this project didn't yet update this dependency, and requires an older version of this library: 1.2.0. This is a problem, because our project won't work with a version that old, we're using some of the new features of that library, similarly, your project won't work with a newer version though.</p> <p>With a virtual environment, both projects will have their own isolated python installation, that only contains the dependencies listed for that project, avoiding any conflicts completely.</p> <p>You can create virtual environments manually, with the built-in <code>venv</code> python module, but poetry makes this much simpler. If you want to find out more about virutal environments, check the official python documentation.</p> <p>This means you will need to have poetry installed on your system to run our project. To do so, just follow their official documentation.</p>"},{"location":"contributing/guides/setup/#dependency-installation","title":"Dependency installation","text":"<p>Once installed, you will want to create a new environment for our project, with all of our dependencies installed. Open a terminal in the project's directory and run the following command:</p> <pre><code>poetry install\n</code></pre> <p>After running this command, the virtual environment will be populated with all of the dependencies that you will need for running &amp; developing the project.</p>"},{"location":"contributing/guides/setup/#activating-the-environment","title":"Activating the environment","text":"<p>The virtual environment that you just created will contain a bunch of executable programs, such as <code>ruff</code> (our linter). One of those executable programs is also <code>python</code>, which is the python interpreter for this environment, capable of using all of those dependencies installed in that environment.</p> <p>By default, when you run the <code>python</code> command, your machine will use the system-wide python installation though and the executables present in this environment will not be runnable at all. In order to make your terminal use the programs from this environment, instead of the global ones, you will need to \"activate\" the environment.</p> <p>Some IDEs/editors are capable of doing this automatically when you open the project, if your editor supports that, you should configure it to do so.</p> Configuring VSCode to use the poetry environment <p>TODO</p> <p>If your IDE doesn't have that option, or you just wish to work from the terminal, you can instead run:</p> <pre><code>poetry shell\n</code></pre> <p>Now you can start the IDE from your terminal, which should make it work within the poetry python environment.</p> <p>Execute a single command inside the virtual environment</p> <p>If you just want to urn a single command from the venv, without necessarily having to activate the environment (often useful in scripts), poetry provides a quick and simple way to do so. All you need to do is prefix any such command with <code>poetry run</code> (e.g. <code>poetry run ruff</code>).</p>"},{"location":"contributing/guides/setup/#keeping-your-dependencies-up-to-date","title":"Keeping your dependencies up to date","text":"<p>We often update the dependencies of mcproto to keep them up to date. Whenever we make such an update, you will need to update your virtual environment to prevent it from going out of date. An out of date environment could mean that you're using older versions of some libraries and what will run on your machine might not match what will run on other machines with the dependencies updated.</p> <p>Thankfully, poetry makes updating the dependencies very easy as all you have to do is re-run the installation command:</p> <pre><code>poetry install\n</code></pre> <p>It can sometimes be hard to know when you need to run the install command, in most cases, even if we did update something and you're still on an older version, nothing significant will actually happen, however, the moment you start seeing some errors when you try to run the project, or inconsistencies with the continuous integration workflows from your local runs, it's a good indication that your dependencies are probably out of date.</p> <p>Ideally, you should run this command as often as possible, if there aren't any new changes, it will simply exit instantly. You should be especially careful when switching git branches, as dependencies might have been changed (most likely a new dependency was introduced, or an old one got removed), so consider running this command whenever you switch to another branch, unless you know that branch didn't make any changes to the project dependencies.</p>"},{"location":"contributing/guides/setup/#poetry-dependency-groups","title":"Poetry dependency groups","text":"<p>Poetry has a really cool way of splitting up the dependencies that projects need into multiple groups. For example, you can have a group of dependencies for linting &amp; autoformatting, another group for documentation support, unit-testing, for releasing the project, etc.</p> <p>To see which dependencies belong to which group, you can check the <code>pyproject.toml</code> file for the <code>[tool.poetry.group.GROUP_NAME.dependencies]</code> sections.</p> <p>By default, <code>poetry install</code> will install all non-optional dependency groups. That means all development dependencies you should need will get installed.</p> <p>The reason why we use groups is because in some of our automated workflows, we don't always need all of the project dependencies and we can save time by only installing the group(s) that we need. It also provides a clean way to quickly see which dependencies are being used for what.</p> <p>The most important group is the <code>main</code> group. This group contains all runtime dependencies, which means without these dependencies, the project wouldn't be runnable at all. It is these libraries that will become the dependencies of our library when we make a release on PyPI.</p>"},{"location":"contributing/guides/setup/#installing-dependencies","title":"Installing dependencies","text":"<p>During the development, you may sometimes want to introduce a new library to the project, to do this, you will first need to decide which dependency group it should belong to. To do this, identify whether this new dependency will be required to run the project, or if it's just some tool / utility that's necessary only during the development.</p> <p>If it's a runtime dependency, all you need to do is run:</p> <pre><code>poetry add [name-of-your-dependency]\n</code></pre> <p>This will add the dependency to the <code>main</code> group.</p> <p>However, if you're working with a development dependency, you will want to go over the dependency groups we have (from <code>pyproject.toml</code>) and decide where it should belong. Once you figured that out, you can run:</p> <pre><code>poetry add --group [group-name] [name-of-your-dependency]\n</code></pre> <p>Note</p> <p>Sometimes, it might make sense to include the same dependency in multiple groups. (Though this is usually quite rare.)</p>"},{"location":"contributing/guides/setup/#uninstalling-dependencies","title":"Uninstalling dependencies","text":"<p>Similarly, we sometimes stop needing a certain dependency. Uninstalling is a very similar process to installation. First, find which group you want to remove this dependency from and then run:</p> <pre><code>poetry remove --group [group-name] [name-of-your-dependency]\n</code></pre>"},{"location":"contributing/guides/slotscheck/","title":"Slotscheck","text":"Abstract <p>This page explains how we enforce the proper use of <code>__slots__</code> on our classes with <code>slotscheck</code> tool. We go over what slotted classes, what slotscheck enforces, how to run slotscheck and how to configure it.</p> <p>On top of the tools you already saw (ruff &amp; basedpyright), we also have one more tool that performs static analysis on our code: slotscheck.</p>"},{"location":"contributing/guides/slotscheck/#what-is-slotscheck","title":"What is slotscheck","text":"<p>Slotscheck is a tool that focuses on enforcing proper use of <code>__slots__</code> on classes.</p> What are slotted classes <p>If you aren't familiar with slotted classes, you should check the official documentation. That said, if you just want a quick overview:</p> <ul> <li>Slots allow you to explicitly declare all member attributes of a class (e.g. declaring <code>__slots__ = (\"a\", \"b\")</code>   will make the class instances only contain variables <code>a</code> and <code>b</code>, trying to set any other attribute will result   in an <code>AttributeError</code>).</li> <li>The reason we like using slots is the efficiency they come with. Slotted classes use up less RAM and offer   a faster attribute access.</li> </ul> <p>Example of a slotted class:</p> <pre><code>class FooBar:\n    __slots__ = (\"foo\", \"bar\")\n\n    def __init__(self, foo: str, bar: str) -&gt; None:\n        self.foo = foo\n        self.bar = bar\n\nx = FooBar(\"a\", \"b\")\nprint(x.a, x.b)\nx.c = 5  # AttributeError\n</code></pre> <p>With a low level project like mcproto, efficiency is important and <code>__slots__</code> offer such efficiency at a very low cost (of simply defining them).</p> <p>The purpose of <code>slotscheck</code> is to check that our slotted classes are using <code>__slots__</code> properly, as sometimes, it is easy to make mistakes, which result in losing a lot of the efficiency that slots provide. Issues that slotscheck detects:</p> <ul> <li>Detect broken slots inheritance</li> <li>Detect overlapping slots</li> <li>Detect duplicate slots</li> </ul>"},{"location":"contributing/guides/slotscheck/#how-to-use-slotscheck","title":"How to use slotscheck","text":"<p>To run slotscheck on the codebase, you can use the following command:</p> <pre><code>slotscheck -m mcproto\n</code></pre> <p>Make you have an activated poetry virtual environment and you're in the project's root directory.</p>"},{"location":"contributing/guides/slotscheck/#configuring-slotscheck","title":"Configuring slotscheck","text":"<p>Sometimes, you may want to ignore certain files from being checked. To do so, you can modify the slotscheck configuration in <code>pyproject.toml</code>, under the <code>[tool.slotscheck]</code> option. That said, doing so should be very rare and you should have a very good reason to ignore your file instead of fixing the underlying issue.</p>"},{"location":"contributing/guides/style-guide/","title":"Style Guide","text":"<p>Work In Progress</p> <p>This page is missing a guide on ruff editor integration</p>"},{"location":"contributing/guides/style-guide/#style-guide","title":"Style Guide","text":"Abstract <p>This page describes how we use <code>ruff</code> to enforce a consistent code style in our project.</p> <p>For clarity and readability, adhering to a consistent code style across the whole project is very important. It is not unusual that style adjustments will be requested in pull requests.</p> <p>It is always a good practice to review the style of the existing code-base before and to adhere to that established style before adding something new. That applies even if it isn't the code style you generally prefer. (That said, if you think a code style change of some kind would be justified, feel free to open an issue about it and tell us why.)</p> <p>Quote</p> <p>A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.</p> <p>However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!</p> <p>\u2014 PEP 8, the general Style Guide for Python Code</p> Check out the PEP8 song <p>The Python Discord community have made an amazing song about PEP8, check it out here!</p>"},{"location":"contributing/guides/style-guide/#automatic-linting","title":"Automatic linting","text":"<p>As there is a lot of various code style rules we adhere to in our code base, describing all of them here would take way too long and it would be impossible to remember anyway. For that reason, we use automated tools to help us catch any code style violations automatically.</p> <p>Currently, we use <code>ruff</code> to enforce most of our code style requirements. That said, we do have some other tools that check the correctness of the code, we will describe those later.</p>"},{"location":"contributing/guides/style-guide/#ruff-linter-formatter","title":"Ruff linter &amp; formatter","text":"<p>Ruff is an all-in-one linter &amp; formatter solution, which aims to replace three previously very popular tools into a single package:</p> <ul> <li><code>flake8</code> linter</li> <li><code>isort</code> import sorter</li> <li><code>black</code> auto-formatter</li> </ul> Why pick ruff over the combination of these tools? <p>There were multiple reasons why we chose ruff instead of using the above tools individually, here's just some of them:</p> <ul> <li>Ruff is faster (written in rust! )</li> <li>A single tool is more convenient than 3 separate ones</li> <li>Ruff includes a lot of flake8 plugins with some great lint rules</li> <li>Ruff has a great community and is slowly managing to overtake these individual projects</li> <li>If you're already used to flake8, you'll feel right at home with ruff, it even has the same error codes (mostly)!</li> </ul> <p>You can check the ruff configuration we're using in <code>pyproject.toml</code> file, under the <code>[tool.ruff]</code> category (and it's subcategories). You can find which linter rules are enabled and which we choose to exclude, some file-specific overrides where the rules apply differently and a bunch of other configuration options.</p>"},{"location":"contributing/guides/style-guide/#linter","title":"Linter","text":"<p>To run ruff linter on the code, open the terminal in the project's root directory and run:</p> <pre><code>ruff check .\n</code></pre> <p>Don't forget to activate the poetry virtual environment before running ruff.</p> <p>Ruff is really smart and it can often automatically fix some of the style violations it found. To make ruff do that, you can add the <code>--fix</code> flag to the command:</p> <pre><code>ruff check --fix .\n</code></pre> <p>If you got a rule violation in your code and you don't understand what the rule's purpose is supposed to be / why we enforce it, you can use Ruff to show you some details about that rule. The explanation that ruff will give you will often even contain code examples. To achieve this, simply run:</p> <pre><code>ruff rule [rule-id]\n</code></pre> <p>With the <code>[rule-id]</code> being the rule you're interested in, for example <code>UP038</code>.</p> Use glow to render the markdown syntax from ruff rule command <p>The <code>ruff rule</code> command will output the rule explanation in markdown, however, since you're running this comand in a terminal, there won't be any helpful syntax highlighting for that by default.</p> <p>That's why I'd recommend using a markdown render such as <code>glow</code>. With it, you can pipe the output from ruff into it and have it produce a fancy colored output, that's much easier to read: <code>ruff rule UP038 | glow</code>.</p> <p>Alternatively, you can also find the rules and their description in the ruff documentation.</p>"},{"location":"contributing/guides/style-guide/#formatter","title":"Formatter","text":"<p>On top of being an amazing linter, ruff is also an automatic code formatter. That means ruff can actually make your code follow a proper and style automatically! It will just take your original unformatted (but valid) python code and edit it to meet our configured code style for you.</p> <p>To make ruff format your code, simply run:</p> <pre><code>ruff format .\n</code></pre>"},{"location":"contributing/guides/style-guide/#editor-integration","title":"Editor integration","text":"<p>TODO</p>"},{"location":"contributing/guides/style-guide/#other-style-guidelines","title":"Other style guidelines","text":"<p>While <code>ruff</code> can do a lot, it can't do everything. There are still some guidelines that you will need to read over and apply manually. You will find these guides on the next pages of this documentation.</p>"},{"location":"contributing/guides/type-hints/","title":"Type Hints","text":"Abstract <p>This article explains what python type-hints are, how they can be enforced with the use of type checkers and the type checker of our choice: basedpyright and it's editor integration.</p> <p>Most people only know python as a dynamically typed language, that doesn't offer any kind of type safety. In the very days of python, this was true, however today, things are a bit different. Even though Python on it's own is still a dynamically typed language, it does actually support specifying \"type hints\" which can even be enforced by external tools called \"type checkers\". With those, we can achieve a (mostly) type safe experience while using Python.</p>"},{"location":"contributing/guides/type-hints/#regular-python","title":"Regular python","text":"<p>In regular python, as most people know it, you might end up writing a function like this:</p> <pre><code>def add(x, y):\n  return x + y\n</code></pre> <p>In this code, you have no idea what the type of <code>x</code> and <code>y</code> arguments should be. So, even though you may have intended for this function to only work with numbers (ints), it's actually entirely possible to use it with something else. For example, running <code>add(\"hello\", \"world)</code> will return <code>\"helloworld\"</code> because the <code>+</code> operator works on strings too.</p> <p>The point is, there's nothing telling you what the type of these parameters should be, and that could lead to misunderstandings. Even though in some cases, you can figure out what the type should these variables have purely based on their name alongside the name of the function, in most cases, it's not that easy. It often requires looking through the docs, or going over the actual source code of such function.</p> <p>Annoyingly, python won't even prevent you from passing in types that are definitely incorrect, like: <code>add(1, \"hi\")</code>. Running this would cause a <code>TypeError</code>, but unless you have unit-tests that actually run that code, you won't find out about this bug until it actually causes an issue and at that point, it might already be too late, since your code has crashed a production app.</p> <p>Clearly then, this isn't ideal.</p>"},{"location":"contributing/guides/type-hints/#type-hints_1","title":"Type-Hints","text":"<p>While python doesn't require it, there is in fact a way to add a \"hint\" that indicates what type should a given variable have. So, when we take the function from above, adding type-hints to it would result in something like this:</p> <pre><code>def add(x: int, y: int) -&gt; int:\n  return x + y\n</code></pre> <p>We've now made the types very explicit to the programmer, which means they'll no longer need to spend a bunch of time looking through the implementation of that function, or going through the documentation just to know how to use this function. Instead, the type hints will tell just you.</p> <p>This is incredibly useful, because most editors will be able to pick up these type hints, and show them to you while calling the function, so you know what to pass right away, without even having to look at the function definition where the type-hints are defined.</p> <p>Not only that, specifying a type-hint will greatly improve the development experience in your editor / IDE, because you'll get much better auto-completion. The thing is, if you have a parameter like <code>x</code>, but your editor doesn't know what type it should have, it can't really help you if you start typing <code>x.remove</code>, looking for the <code>removeprefix</code> function. However, if you tell your editor that <code>x</code> is a string (<code>x: str</code>), it will now be able to go through all of the methods that strings have, and show you those that start with <code>remove</code> (being <code>removeprefix</code> and <code>removesuffix</code>).</p> <p>This makes type-hints great at saving you time while developing, even though you have to do some additional work when specifying them.</p>"},{"location":"contributing/guides/type-hints/#runtime-behavior","title":"Runtime behavior","text":"<p>Even though type-hints are a part of the Python language, the interpreter doesn't actually care about them. That means that the interpreter doesn't do any optimizations or checking when you're running your code, even if you have a function like <code>add</code> that we have added type-hints to, code like <code>add(1, \"hi\")</code> will not cause any immediate errors.</p> <p>Most editors are configured very loosely when it comes to type-hints. That means they will show you these hints when you're working with the function, but they won't produce warnings when you pass in the wrong thing. That's why they're called \"type hints\", they're only hints that can help you out, but they aren't actually enforced.</p>"},{"location":"contributing/guides/type-hints/#enforcing-type-hints-type-checkers","title":"Enforcing type hints - Type Checkers","text":"<p>Even though python on it's own indeed doesn't enforce the type-hints you specify, there are tools that can run \"static\" checks against your code. A static check is a check that works with your code in it's textual form. It will read the contents of your python files without actually running that file and analyze it purely based on that text content.</p> <p>Using these tools will allow you to analyze your code for typing mistakes before you ever even run your program. That means having a function call like <code>add(1, \"hi\")</code> anywhere in your code would be detected and reported as an issue.</p> <p>There is a bunch of these tools available for python, but the most common ones are <code>pyright</code> and <code>mypy</code>.</p>"},{"location":"contributing/guides/type-hints/#basedpyright","title":"BasedPyright","text":"<p>The type checker that we use in our code-base is basedpyright. It's a fork of pyright which adds some extra checks and features and focuses more on the open-source community, than the official Microsoft owned Pyright.</p>"},{"location":"contributing/guides/type-hints/#running-basedpyright","title":"Running BasedPyright","text":"<p>To run BasedPyright on the code-base, you can use the following command:</p> <pre><code>basedpyright .\n</code></pre> <p>You will need to run this from an activated poetry environment while in the project's root directory.</p>"},{"location":"contributing/guides/type-hints/#editor-integration","title":"Editor Integration","text":"VSCodeNeovim <p>On vscode, you can simply install the BasedPyright extension from the marketplace.</p> <p>Note that this extension does collide with the commonly used Pylance extension, which is installed automatically alongside the Python extension and provide intellisense for Python. The reason BasedPyright collides with this extension is that Pylance actually uses pyright as a language server in the background, and as we mentioned, basedpyright is an alternative, so using both would cause duplicate errors. This means that you will need to disable Pylance, at least within our codebase.</p> <p>If you're using Neovim, I would recommend setting up LSP (Language Server Protocol) and installing basedpyright, as it has language server support built into it. You can achieve this with the <code>lspconfig</code> plugin. You can then use <code>mason-lspconfig</code> to install <code>basedpyright</code>, or manually configure <code>lspconfig</code> and use your system-wide <code>basedpyright</code> executable.</p>"},{"location":"contributing/guides/type-hints/#great-resources","title":"Great resources","text":"<p>While type hinting might seem very simple from the examples shown above, there is actually a fair bit to it, and if you never worked within a type checked code-base, you should definitely check out some of these resources, which go over the basics.</p> <ul> <li>Getting started with type hints in Python - a   blog post / tutorial by decorator-factory.</li> <li>Basics of static typing - part of the BasedPyright documentation</li> <li>Mypy documentation - very extensive documentation on various typing   concepts. (Some things are mypy focused, but most things will cary over to basedpyright too)</li> <li>Python documentation for the <code>typing</code> module - Python's standard   library contains a <code>typing</code> module, which holds a bunch of useful structures that we often use while working with   type-hints.</li> <li>PEP 484 - formal specification of type hints for the Python langauge</li> </ul>"},{"location":"contributing/guides/unit-tests/","title":"Unit Tests","text":"<p>Work In Progress</p> <p>This page is still being written. The content below (if any) may change.</p>"},{"location":"installation/","title":"Installation","text":""},{"location":"installation/#pypi-stable-version","title":"PyPI (stable) version","text":"<p>Mcproto is available on PyPI and can be installed like any other python library with:</p>  pip poetry rye uv pdm <pre><code>pip install mcproto\n</code></pre> <p>pip is the main package installer for Python.</p> <pre><code>poetry add mcproto\n</code></pre> <p>Poetry is an all-in-one solution for Python project management.</p> <pre><code>rye add mcproto\n</code></pre> <p>Rye is an all-in-one solution for Python project management, written in Rust.</p> <pre><code>uv pip install mcproto\n</code></pre> <p>uv is an ultra fast dependency resolver and package installer, written in Rust.</p> <pre><code>pdm add mcproto\n</code></pre> <p>PDM is an all-in-one solution for Python project management.</p>"},{"location":"installation/#latest-git-version","title":"Latest (git) version","text":"<p>Alternatively, you may want to install the latest available version, which is what you currently see in the <code>main</code> git branch. Although this method will actually work for any branch with a pretty straightforward change.</p> <p>This kind of installation should only be done if you wish to test some new unreleased features and it's likely that you will encounter bugs.</p> <p>That said, since mcproto is still in development, changes can often be made quickly and it can sometimes take a while for these changes to carry over to PyPI. So if you really want to try out that latest feature, this is the method you'll want.</p> <p>To install the latest mcproto version directly from the <code>main</code> git branch, use:</p>  pip poetry rye uv pdm <pre><code>pip install 'mcproto@git+https://github.com/py-mine/mcproto@main'\n</code></pre> <p>pip is the main package installer for Python.</p> <pre><code>poetry add 'git+https://github.com/py-mine/mcproto#main'\n</code></pre> <p>Poetry is an all-in-one solution for Python project management.</p> <pre><code>rye add mcproto --git='https://github.com/py-mine/mcproto' --branch main\n</code></pre> <p>Rye is an all-in-one solution for Python project management, written in Rust.</p> <pre><code>uv pip install 'mcproto@git+https://github.com/py-mine/mcproto@main'\n</code></pre> <p>uv is an ultra fast dependency resolver and package installer, written in Rust.</p> <pre><code>pdm add \"git+https://github.com/py-mine/mcproto@main\"\n</code></pre> <p>PDM is an all-in-one solution for Python project management.</p>"},{"location":"installation/changelog/","title":"Changelog","text":"<p>Major and minor releases also include the changes specified in prior development releases.</p> <p>Tip</p> <p>Feel free to skip the Internal Changes category if you aren't a contributor / core developer of mcproto.</p> <p> Unreleased Changes </p>"},{"location":"installation/changelog/#exec-1--version-v050-219-g0c674-2024-10-22","title":"Version v0.5.0-219-g0c674 (2024-10-22)","text":""},{"location":"installation/changelog/#exec-1--features","title":"Features","text":"<ul> <li>#209: Added <code>InvalidPacketContentError</code> exception, raised when deserializing of a specific packet fails. This error inherits from <code>IOError</code>, making it backwards compatible with the original implementation.</li> <li> <p>#257: Added the <code>NBTag</code> to deal with NBT data</p> <ul> <li>The <code>NBTag</code> class is the base class for all NBT tags and provides the basic functionality to serialize and deserialize NBT data from and to a <code>Buffer</code> object.</li> <li>The classes <code>EndNBT</code>, <code>ByteNBT</code>, <code>ShortNBT</code>, <code>IntNBT</code>, <code>LongNBT</code>, <code>FloatNBT</code>, <code>DoubleNBT</code>, <code>ByteArrayNBT</code>, <code>StringNBT</code>, <code>ListNBT</code>, <code>CompoundNBT</code>, <code>IntArrayNBT</code>and <code>LongArrayNBT</code> were added and correspond to the NBT types described in the NBT specification.</li> <li>NBT tags can be created using the <code>NBTag.from_object()</code> method and a schema that describes the NBT tag structure.     Compound tags are represented as dictionaries, list tags as lists, and primitive tags as their respective Python types.     The implementation allows to add custom classes to the schema to handle custom NBT tags if they inherit the <code>:class: NBTagConvertible</code> class.</li> <li>The <code>NBTag.to_object()</code> method can be used to convert an NBT tag back to a Python object. Use include_schema=True to include the schema in the output, and <code>include_name=True</code> to include the name of the tag in the output. In that case the output will be a dictionary with a single key that is the name of the tag and the value is the object representation of the tag.</li> <li>The <code>NBTag.serialize()</code> can be used to serialize an NBT tag to a new <code>Buffer</code> object.</li> <li>The <code>NBTag.deserialize(buffer)</code> can be used to deserialize an NBT tag from a <code>Buffer</code> object.</li> <li>If the buffer already exists, the <code>NBTag.write_to(buffer, with_type=True, with_name=True)</code> method can be used to write the NBT tag to the buffer (and in that case with the type and name in the right format).</li> <li>The <code>NBTag.read_from(buffer, with_type=True, with_name=True)</code> method can be used to read an NBT tag from the buffer (and in that case with the type and name in the right format).</li> <li>The <code>NBTag.value</code> property can be used to get the value of the NBT tag as a Python object.</li> </ul> </li> <li> <p>Added further encryption related fucntions used by servers.</p> </li> <li>Update <code>LoginStart</code> packet to latest protocol version (<code>uuid</code> no longer optional)</li> </ul>"},{"location":"installation/changelog/#exec-1--bugfixes","title":"Bugfixes","text":"<ul> <li>#330: Fix behavior of the <code>mcproto.utils.deprecation</code> module, which was incorrectly always using a fallback version, assuming mcproto is at version 0.0.0. This then could've meant that using a deprecated feature that is past the specified deprecation (removal) version still only resulted in a deprecation warning, as opposed to a full runtime error.</li> </ul>"},{"location":"installation/changelog/#exec-1--documentation-improvements","title":"Documentation Improvements","text":"<ul> <li>#179: Enforce presence of docstrings everywhere with pydocstyle. This also adds docstring to all functions and classes that didn't already have one. Minor improvements for consistency were also made to some existing docstrings.</li> <li>#346: Complete documentation rewrite</li> <li>Add protocol and protocol pages (API reference docs)</li> </ul>"},{"location":"installation/changelog/#exec-1--internal-changes","title":"Internal Changes","text":"<ul> <li>#131: Any overridden methods in any classes now have to explicitly use the <code>typing.override</code> decorator (see PEP 698)</li> <li>#258: Fix readthedocs CI</li> <li>#259: Merge dependabot PRs automatically, if they pass all CI checks.</li> <li>#274: Update ruff<ul> <li>Update ruff version (the version we used was very outdated)</li> <li>Drop isort in favor of ruff's built-in isort module in the linter</li> <li>Drop black in favor of ruff's new built-in formatter</li> <li>Update ruff settings, including adding/enabling some new rule-sets</li> </ul> </li> <li>#285: Add <code>gen_serializable_test</code> function to generate tests for serializable classes, covering serialization, deserialization, validation, and error handling.</li> <li>#285: Rework the <code>Serializable</code> class</li> <li>#286: Update the docstring formatting directive in CONTRIBUTING.md to reflect the formatting practices currently in place.</li> <li> <p>#300: Update CI</p> <ul> <li>Fix CI not running unit tests on python 3.8 (only 3.11)</li> <li>Update to use python 3.12 (in validation and as one of the matrix versions in unit-tests workflow)</li> <li>Trigger and run lint and unit-tests workflows form a single main CI workflow.</li> <li>Only send status embed after the main CI workflow finishes (not for both unit-tests and validation)</li> <li>Use <code>--output-format=github</code> for <code>ruff check</code> in the validation workflow</li> <li>Fix the status-embed workflow</li> </ul> </li> <li> <p>#323: Enable various other ruff rules as a part of switching to blacklist model, where we explicitly disable the rules we don't want, rather than enabling dozens of rule groups individually.</p> </li> <li>#329: - Change the type-checker from <code>pyright</code> to <code>basedpyright</code><ul> <li>BasedPyright is a fork of pyright, which provides some additional typing features and re-implements various proprietary features from the closed-source Pylance vscode extension.</li> <li>Overall, it is very similar to pyright with some bonus stuff on top. However, it does mean all contributors who want proper editor support for the project will need to update their editor settings and add basedpyright. The instructions on how to do this are described in the updated <code>CONTRIBUTING.md</code>.</li> </ul> </li> <li>#347: Fix towncrier after an update (template file isn't ignored by default, so ignore it manually)</li> <li>#379: Remove codeclimate</li> </ul>"},{"location":"installation/changelog/#version-050-2023-08-10","title":"Version 0.5.0 (2023-08-10)","text":""},{"location":"installation/changelog/#breaking-changes","title":"Breaking Changes","text":"<ul> <li> <p>#130: Renamed \"shared_key\" field to \"shared_secret\" in <code>LoginEncryptionPacket</code>, following the official terminology.</p> <ul> <li>This is a breaking change, <code>LoginEncryptionPacket</code>'s <code>__init__</code> method now uses \"shared_secret\" keyword only argument, not \"shared_key\".</li> </ul> </li> <li> <p>#130: The <code>LoginStart</code> packet now contains a (required) UUID field (which can be explicitly set to <code>None</code>).</p> <ul> <li>For some reason, this field was not added when the login packets were introduced initially, and while the UUID field can indeed be omitted in some cases (it is an optional filed), in vast majority of cases, it will be present, and we should absolutely support it.</li> <li>As this is a new required field, the <code>__init__</code> function of <code>LoginStart</code> now also expects this <code>uuid</code> keyword argument to be present, making this a breaking change.</li> </ul> </li> <li> <p>#159: Fix packet compression handling in the interaction methods.</p> <p>This fixes a bug that didn't allow for specifying an exact compression threshold that the server specified in <code>LoginSetCompression</code> packet, and instead only allowing to toggle between compression on/off, which doesn't really work as server doesn't expect compression for packets below that threshold.</p> <ul> <li><code>sync_write_packet</code>, <code>async_write_pakcet</code>, <code>sync_read_packet</code> and <code>async_read_packet</code> functions now take <code>compression_threshold</code> instead of <code>compressed</code> bool flag</li> </ul> </li> <li> <p>#161: <code>LoginEncryptionRequest</code> now uses <code>cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey</code> to hold the public key, instead of just pure <code>bytes</code>. Encoding and decoding of this key happens automatically during serialize/deserialize. This is a breaking change for anyone relying on the <code>public_key</code> field from this packet being <code>bytes</code>, and for anyone initializing this packet directly with <code>__init__</code>, which now expects <code>RSAPublicKey</code> instance instead.</p> </li> </ul>"},{"location":"installation/changelog/#features","title":"Features","text":"<ul> <li>#129: Added a system for handling Minecraft authentication<ul> <li>Yggdrasil system for unmigrated i.e. non-Microsoft accounts (supportng Minecraft accounts, and the really old Mojang accounts)</li> <li>Microsoft OAuth2 system (Xbox live) for migrated i.e. Microsoft accounts</li> </ul> </li> <li>#160: Re-export the packet classes (or any other objects) from the gamestate modules (<code>mcproto.packets.handshaking</code>/<code>mcproto.packets.login</code>/...) directly. Allowing simpler imports (<code>from mcproto.packets.login import LoginStart</code> instead of <code>from mcproto.packets.login.login import LoginStart</code>)</li> <li>#161: Add support for encryption. Connection classes now have <code>enable_encryption</code> method, and some encryption related functions were added into a new <code>mcproto.encryption</code> module.</li> <li>#168: Add multiplayer related functionalities for requesting and checking joins for original (bought) minecraft accounts. This allows us to join online servers.</li> <li>#171: Add <code>Account.check</code> function, to verify that the access token in use is valid, and the data the Account instance has matches the data minecraft API has.</li> </ul>"},{"location":"installation/changelog/#bugfixes","title":"Bugfixes","text":"<ul> <li>#130: <code>LoginEncryptionResponse</code> now includes the <code>server_id</code> field. This field was previously hard-coded to 20 spaces (blank value), which is what all minecraft clients on minecraft 1.7.x or higher do, however with older versions, this field is set to 20 random characters, which we should respect.<ul> <li>This is not a breaking change, as <code>server_id</code> will default to <code>None</code> in <code>LoginEncryptionResponse</code>'s <code>__init__</code>, meaning any existing code utilizing this packet will still work. It is purely an additional option.</li> </ul> </li> <li>#167: Fix packet reading/writing when compression is enabled (use zlib as expected, instead of gzip which we were using before)</li> <li>#170: Preserve the call parameters and overloads in the typing signature of <code>mcproto.packets.packet_map.generate_packet_map</code> function. (This wasn't the case before, since <code>functools.lru_cache</code> doesn't preserve this data). Note that this loses on the typing information about the cache itself, as now it will appear to be a regular uncached function to the type-checker. We deemed this approach better to the alternative of no typing info for call arguments or overloads, but preserving cache info.</li> </ul>"},{"location":"installation/changelog/#documentation-improvements","title":"Documentation Improvements","text":"<ul> <li>#129: Mention lack of synchronous alternatives for certain functions (see issue #128)</li> <li>#139: Add a warning in version guarantees page, explaining pre-release guarantees (breaking changes in minor versions allowed)</li> <li>#141: Move installation instructions from README to Installation docs page</li> <li> <p>#144: Add attributetable internal sphinx extension for showing all attributes and methods for specified classes.</p> <ul> <li>This adds <code>attributetable</code> sphinx directive, which can be used before autodoc directive. This will create the attribute table, which will get dynamically moved right below the class definition from autodoc (using javascript).</li> <li>This extension was implemented by discord.py, this is just re-using that code, with some modifications to fit our code style and to fit the documentation design (furo theme).</li> </ul> </li> <li> <p>Updated contributing guidelines (restructure and rewrite some categories, to make it more readable)</p> </li> </ul>"},{"location":"installation/changelog/#internal-changes","title":"Internal Changes","text":"<ul> <li>#133: Enable enforcement of some optional pyright rules</li> <li>#153: Replace flake8 linter with ruff (mostly equivalent, but much faster and configurable from pyproject.toml)</li> <li> <p>#154: Enforce various new ruff linter rules:</p> <ul> <li>PGH: pygrep-hooks (replaces pre-commit version)</li> <li>PL: pylint (bunch of typing related linter rules)</li> <li>UP: pyupgrade (forces use of the newest possible standards, depending on target version)</li> <li>RET: flake8-return (various linter rules related to function returns)</li> <li>Q: flake8-quotes (always use double quotes)</li> <li>ASYNC: flake8-async (report blocking operations in async functions)</li> <li>INT: flake-gettext (gettext related linting rules)</li> <li>PTH: flake8-use-pathlib (always prefer pathlib alternatives to the os ones)</li> <li>RUF: ruff custom rules (various additional rules created by the ruff linter team)</li> </ul> </li> </ul>"},{"location":"installation/changelog/#version-040-2023-06-11","title":"Version 0.4.0 (2023-06-11)","text":""},{"location":"installation/changelog/#breaking-changes_1","title":"Breaking Changes","text":"<ul> <li>#41: Rename <code>mcproto.packets.abc</code> to <code>mcproto.packets.packet</code></li> <li>#116: Restructure the project, moving to a single protocol version model<ul> <li>This change does NOT have a deprecation period, and will very likely break most existing code-bases. However this change is necessary, as multi-version support was unsustainable (see issue #45 for more details)</li> <li>Any packets and types will no longer be present in versioned folders (mcproto.packets.v757.xxx), but rather be directly in the parent directory (mcproto.packets.xxx).</li> <li>This change doesn't affect manual communication with the server, connection, and basic IO writers/readers remain the same.</li> </ul> </li> </ul>"},{"location":"installation/changelog/#version-030-2023-06-08","title":"Version 0.3.0 (2023-06-08)","text":""},{"location":"installation/changelog/#features_1","title":"Features","text":"<ul> <li>#54: Add support for LOGIN state packets<ul> <li><code>LoginStart</code></li> <li><code>LoginEncryptionRequest</code></li> <li><code>LoginEncryptionResponse</code></li> <li><code>LoginSuccess</code></li> <li><code>LoginDisconnect</code></li> <li><code>LoginPluginRequest</code></li> <li><code>LoginPluginResponse</code></li> <li><code>LoginSetCompression</code></li> </ul> </li> </ul>"},{"location":"installation/changelog/#bugfixes_1","title":"Bugfixes","text":"<ul> <li>#75: Increase the stack level of warnings shown on protocol version fallbacks</li> <li>#113: TCP connections now properly shut down the connection gracefully (TCP FIN)</li> </ul>"},{"location":"installation/changelog/#documentation-improvements_1","title":"Documentation Improvements","text":"<ul> <li>#2: Add Sphinx and basic docs layout</li> <li>#18: Rewrite all docstrings into proper Sphinx format, instead of using markdown.</li> <li>#27: Add changelog page to docs, linking <code>CHANGELOG.md</code>, including unreleased changes from fragments.</li> <li>#28: Use furo theme for the documentation</li> <li>#34: Add version guarantees page</li> <li>#40: Move code of conduct to the docs.</li> <li>Improve readability of the changelog readme (changes/README.md)<ul> <li>Mention taskipy <code>changelog-preview</code> shorthand command</li> <li>Add category headers splitting things up, for better readability</li> <li>Explain how to express multiple changes related to a single goal in a changelog fragment.</li> </ul> </li> <li>Include <code>CHANGELOG.md</code> file in project's distribution files.</li> </ul>"},{"location":"installation/changelog/#internal-changes_1","title":"Internal Changes","text":"<ul> <li>#12: Replace HassanAbouelela setup-python action with ItsDrike/setup-python in CI workflows</li> <li>#17: Start using codeclimate to monitor code coverage and it's changes</li> <li>#35: Add more tests</li> <li>#38: Replace our implementation of <code>SemanticVersion</code> with a community-maintained <code>semantic-version</code> package.</li> <li>#53: Mark all packet classes as <code>typing.final</code>, making the type-checker enforce existence of concrete implementations for all abstract methods.</li> <li>#112: Removed <code>codespell</code> linter. This proved too annoying, especially when we already have a lot of linters here. Spelling mistakes can simply be caught in the review process.</li> <li>#114: Use latest poetry version in CI workflows (remove version lock - at 1.3.1)</li> <li>The <code>documentation</code> category of changelog was renamed to shorter <code>docs</code></li> </ul>"},{"location":"installation/changelog/#version-020-2022-12-30","title":"Version 0.2.0 (2022-12-30)","text":""},{"location":"installation/changelog/#features_2","title":"Features","text":"<ul> <li>#14: Add <code>__slots__</code> to most classes in the project<ul> <li>All connection classes are now slotted</li> <li>Classes in <code>mcproto.utils.abc</code> are now slotted</li> </ul> </li> <li>Separate packet interaction functions into <code>mcproto.packets.interactions</code>, (though they're reexported in   <code>mcproto.packets</code>, so no breaking changes)</li> </ul>"},{"location":"installation/changelog/#bugfixes_2","title":"Bugfixes","text":"<ul> <li>#14: Add missing <code>__slots__</code> to <code>ServerBoundPacket</code> and <code>ClientBoundPacket</code> subclasses, which inherited from slotted   <code>Packet</code>, but didn't themselves define <code>__slots__</code>, causing <code>__dict__</code> to be needlessly created.</li> <li>The error message produced by <code>RequiredParamsABCMixin</code> class when a required no MRO class variable isn't present now   includes a previously missing space, making it more readable.</li> </ul>"},{"location":"installation/changelog/#documentation-improvements_2","title":"Documentation Improvements","text":"<ul> <li>#7: Add and start keeping a changelog, managed by towncrier.</li> <li>#13: Add a security policy.</li> </ul>"},{"location":"installation/changelog/#internal-changes_2","title":"Internal Changes","text":"<ul> <li>#6: Rework deprecation system<ul> <li>Drop support for date-based deprecations, versions work better</li> <li>Provide <code>deprecation_warn</code> function, which emits warnings directly, no need for a decorator</li> <li>Add a <code>SemanticVersion</code> class, supporting version comparisons</li> <li>If the project's version is already higher than the specified deprecation removal version, raise a DeprecationWarning   as a full exception (rather than just a warning).</li> </ul> </li> <li>#7: Add towncrier for managing changelog</li> <li>#14: Add slotscheck, ensuring <code>__slots__</code> are defined properly everywhere.</li> <li>#14: Make <code>typing-extensions</code> a runtime dependency and use it directly, don't rely on <code>if typing.TYPE_CHECKING</code> blocks.</li> <li>#15: Add codespell tool, to automatically find spelling mistakes.</li> <li>Add README file into the <code>tests/</code> folder, explaining how we use unit-tests and some basics of testing.</li> <li>Add <code>CustomMockMixin</code> internal class, inheriting from <code>UnpropagatingMockMixin</code>, but also allowing to use <code>spec_set</code> as   class variable, as it will automatically pass it into <code>__init__</code> of the mock class.</li> <li>Add several new flake8 extensions, and rework flake8 config file</li> <li>Add support for specifying what child mock type to propagate in <code>UnpropagatingMockMixin</code> class (for unit-tests).</li> </ul> <p>The changelog was added during development of 0.2.0, so nothing prior is documented here. Try checking the GitHub releases, or git commit history directly.</p>"},{"location":"installation/version-guarantees/","title":"Version Guarantees","text":"<p>Pre-release phase</p> <p>Mcproto is currently in the pre-release phase (pre v1.0.0). During this phase, these guarantees will NOT be followed! This means that breaking changes can occur in minor version bumps. That said, micro version bumps are still strictly for bugfixes, and will not include any features or breaking changes.</p> <p>This library follows semantic versioning model, which means the major version is updated every time there is an incompatible (breaking) change made to the public API. However due to the fairly dynamic nature of Python, it can be hard to discern what can be considered a breaking change, and what isn't.</p> <p>First thing to keep in mind is that breaking changes only apply to publicly documented functions and classes. If it's not listed in the documentation here, it's an internal feature, that isn't considered a part of the public API, and thus is bound to change. This includes documented attributes that start with an underscore and documented API that is explicitly marked as internal.</p> <p>Note</p> <p>The examples below are non-exhaustive.</p>"},{"location":"installation/version-guarantees/#examples-of-breaking-changes","title":"Examples of Breaking Changes","text":"<ul> <li>Changing the default parameter value of a function to something else.</li> <li>Renaming (or removing) a function without an alias to the old function.</li> <li>Adding or removing parameters of a function.</li> <li>Removing deprecated alias to a renamed function.</li> </ul>"},{"location":"installation/version-guarantees/#examples-of-non-breaking-changes","title":"Examples of Non-Breaking Changes","text":"<ul> <li>Changing function's name, while providing a deprecated alias.</li> <li>Renaming (or removing) private underscored attributes.</li> <li>Adding an element into <code>__slots__</code> of a data class.</li> <li>Changing the behavior of a function to fix a bug.</li> <li>Changes in the typing definitions of the public API.</li> <li>Changes in the documentation.</li> <li>Modifying the internal protocol connection handling.</li> <li>Updating the dependencies to a newer version, major or otherwise.</li> </ul>"},{"location":"reference/private/","title":"Private API Reference","text":"<p>This is the reference documentation page for private mcproto API.</p> <p>Warning</p> <p>Private here means that the functions/classes documented here are only meant to be used internally by the library, you shouldn't use these in your code if you're just a user of this library. This page is here mainly as a reference for contributors and for providing proper linkable references. The backwards compatibility of these components will not be guarranteed, which means breaking changes may be introduced between patch versinos without any warnings.</p>"},{"location":"reference/private/abc/","title":"Utility Abstract Base Classes","text":"<p>These are some internal ABC classes that we utilize in various places.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.RequiredParamsABCMixin","title":"mcproto.utils.abc.RequiredParamsABCMixin","text":"<p>Mixin class to ABCs that require certain attributes to be set in order to allow initialization.</p> <p>This class performs a similar check to what :class:<code>~abc.ABC</code> already does with abstractmethods, but for class variables. The required class variable names are set with :attr:<code>._REQUIRED_CLASS_VARS</code> class variable, which itself is automatically required.</p> <p>Just like with ABCs, this doesn't prevent creation of classes without these required class vars defined, only initialization is prevented. This is done to allow creation of a more specific, but still abstract class.</p> <p>Additionally, you can also define :attr:<code>._REQUIRED_CLASS_VARS_NO_MRO</code> class var, holding names of class vars which should be defined on given class directly. That means inheritance will be ignored so even if a subclass defines the required class var, unless the latest class also defines it, this check will fail.</p> <p>This is often useful for classes that are expected to be slotted, as each subclass will need to define <code>__slots__</code>, otherwise a <code>__dict__</code> will automatically be made for it. However this is entirely optional, and if :attr:<code>._REQUIRED_CLASS_VARS_NO_MRO</code> isn't set, this check is skipped.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.RequiredParamsABCMixin.__new__","title":"mcproto.utils.abc.RequiredParamsABCMixin.__new__","text":"<pre><code>__new__(*a: Any, **kw: Any) -&gt; Self\n</code></pre> <p>Enforce required parameters being set for each instance of the concrete classes.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable","title":"mcproto.utils.abc.Serializable","text":"<p>               Bases: <code>ABC</code></p> <p>Base class for any type that should be (de)serializable into/from :class:<code>~mcproto.Buffer</code> data.</p> <p>Any class that inherits from this class and adds parameters should use the :func:<code>~mcproto.utils.abc.define</code> decorator.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.__attrs_post_init__","title":"mcproto.utils.abc.Serializable.__attrs_post_init__","text":"<pre><code>__attrs_post_init__() -&gt; None\n</code></pre> <p>Run the validation method after the object is initialized.</p> <p>This function is responsible for conversion/transformation of given values right after initialization (often for example to convert an int initialization param into a specific enum variant)</p> <p>.. note::     If you override this method, make sure to call the superclass method at some point to ensure that the     validation is run.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.deserialize","title":"mcproto.utils.abc.Serializable.deserialize  <code>abstractmethod</code> <code>classmethod</code>","text":"<pre><code>deserialize(buf: Buffer) -&gt; Self\n</code></pre> <p>Construct the object from a :class:<code>~mcproto.Buffer</code> (transmittable sequence of bytes).</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.serialize","title":"mcproto.utils.abc.Serializable.serialize","text":"<pre><code>serialize() -&gt; Buffer\n</code></pre> <p>Represent the object as a :class:<code>~mcproto.Buffer</code> (transmittable sequence of bytes).</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.serialize_to","title":"mcproto.utils.abc.Serializable.serialize_to  <code>abstractmethod</code>","text":"<pre><code>serialize_to(buf: Buffer) -&gt; None\n</code></pre> <p>Write the object to a :class:<code>~mcproto.Buffer</code>.</p>"},{"location":"reference/private/abc/#mcproto.utils.abc.Serializable.validate","title":"mcproto.utils.abc.Serializable.validate","text":"<pre><code>validate() -&gt; None\n</code></pre> <p>Validate the object's attributes, raising an exception if they are invalid.</p> <p>By default, this method does nothing. Override it in your subclass to add validation logic.</p> <p>.. note::     This method is called by :meth:<code>~mcproto.utils.abc.Serializable.__attrs_post_init__</code></p>"},{"location":"reference/private/authentication/","title":"Internal components for authentication","text":"<p>These are the utility components related to / used in the authentication module.</p>"},{"location":"reference/private/authentication/#mcproto.auth.msa.MSAAccount","title":"mcproto.auth.msa.MSAAccount","text":"<p>               Bases: <code>Account</code></p> <p>Minecraft account logged into using Microsoft OAUth2 auth system.</p>"},{"location":"reference/private/authentication/#mcproto.auth.msa.MSAAccount._get_access_token_from_xbox","title":"mcproto.auth.msa.MSAAccount._get_access_token_from_xbox  <code>async</code> <code>staticmethod</code>","text":"<pre><code>_get_access_token_from_xbox(client: AsyncClient, user_hash: str, xsts_token: str) -&gt; str\n</code></pre> <p>Obtain access token from an XSTS token from Xbox Live auth (for Microsoft accounts).</p>"},{"location":"reference/private/deprecation/","title":"Deprecation utilities","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated","title":"mcproto.utils.deprecation.deprecated","text":"<pre><code>deprecated(removal_version: str | Version, display_name: str | None = None, replacement: str | None = None, extra_msg: str | None = None) -&gt; DecoratorFunction\n</code></pre> <p>Mark an object as deprecated.</p> <p>Decorator version of :func:<code>.deprecation_warn</code> function.</p> <p>If the currently installed project version is already past the specified deprecation version, a :exc:<code>DeprecationWarning</code> will be raised as a full exception. Otherwise it will just get emitted as a warning.</p> <p>The deprecation message used will be constructed based on the input parameters.</p> <p>Parameters:</p> Name Type Description Default <code>str | None</code> <p>Name of the object that got deprecated (such as <code>my_function</code>).  By default, the object name is obtained automatically from <code>__qualname__</code> (falling back to <code>__name__</code>) of the decorated object. Setting this explicitly will override this obtained name and the <code>display_name</code> will be used instead.</p> <code>None</code> <code>str | Version</code> <p>Version at which this object should be considered as deprecated and should no longer be used.</p> required <code>str | None</code> <p>A new alternative to this (now deprecated) object.</p> <code>None</code> <code>str | None</code> <p>Additional message included in the deprecation warning/exception at the end.</p> <code>None</code>"},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(display_name)","title":"<code>display_name</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(removal_version)","title":"<code>removal_version</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(replacement)","title":"<code>replacement</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecated(extra_msg)","title":"<code>extra_msg</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn","title":"mcproto.utils.deprecation.deprecation_warn","text":"<pre><code>deprecation_warn(*, obj_name: str, removal_version: str | Version, replacement: str | None = None, extra_msg: str | None = None, stack_level: int = 3) -&gt; None\n</code></pre> <p>Produce an appropriate deprecation warning given the parameters.</p> <p>If the currently installed project version is already past the specified deprecation version, a :exc:<code>DeprecationWarning</code> will be raised as a full exception. Otherwise it will just get emitted as a warning.</p> <p>The deprecation message used will be constructed based on the input parameters.</p> <p>Parameters:</p> Name Type Description Default <code>str</code> <p>Name of the object that got deprecated (such as <code>my_function</code>).</p> required <code>str | Version</code> <p>Version at which this object should be considered as deprecated and should no longer be used.</p> required <code>str | None</code> <p>A new alternative to this (now deprecated) object.</p> <code>None</code> <code>str | None</code> <p>Additional message included in the deprecation warning/exception at the end.</p> <code>None</code> <code>int</code> <p>Stack level at which the warning is emitted.</p> <code>3</code>"},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(obj_name)","title":"<code>obj_name</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(removal_version)","title":"<code>removal_version</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(replacement)","title":"<code>replacement</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(extra_msg)","title":"<code>extra_msg</code>","text":""},{"location":"reference/private/deprecation/#mcproto.utils.deprecation.deprecation_warn(stack_level)","title":"<code>stack_level</code>","text":""},{"location":"reference/private/protocol/","title":"Internal components for protocol","text":"<p>These are the utility components related to / used in the protocol module.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.utils.from_twos_complement","title":"mcproto.protocol.utils.from_twos_complement","text":"<pre><code>from_twos_complement(number: int, bits: int) -&gt; int\n</code></pre> <p>Convert a given <code>number</code> from twos complement format of given amount of <code>bits</code>.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>Given <code>number</code> doesn't fit into given amount of <code>bits</code>. This likely means that you're using the wrong number, or that the number was converted into twos complement with higher amount of <code>bits</code>.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.utils.to_twos_complement","title":"mcproto.protocol.utils.to_twos_complement","text":"<pre><code>to_twos_complement(number: int, bits: int) -&gt; int\n</code></pre> <p>Convert a given <code>number</code> into twos complement format of given amount of <code>bits</code>.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>Given <code>number</code> is out of range, and can't be converted into twos complement format, since it wouldn't fit into the given amount of <code>bits</code>.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseAsyncWriter","title":"mcproto.protocol.base_io.BaseAsyncWriter","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding asynchronous write buffer/connection interactions.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseAsyncWriter._write_varuint","title":"mcproto.protocol.base_io.BaseAsyncWriter._write_varuint  <code>async</code>","text":"<pre><code>_write_varuint(value: int, /, *, max_bits: int | None = None) -&gt; None\n</code></pre> <p>Write an arbitrarily big unsigned integer in a variable length format.</p> <p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p> <p>Writing will be limited up to integer values of <code>max_bits</code> bits, and trying to write bigger values will rase a :exc:<code>ValueError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes will be sent, in this case it would actually take at most 5 bytes, due to the variable encoding overhead.</p> <p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseSyncWriter","title":"mcproto.protocol.base_io.BaseSyncWriter","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding synchronous write buffer/connection interactions.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseSyncWriter._write_varuint","title":"mcproto.protocol.base_io.BaseSyncWriter._write_varuint","text":"<pre><code>_write_varuint(value: int, /, *, max_bits: int | None = None) -&gt; None\n</code></pre> <p>Write an arbitrarily big unsigned integer in a variable length format.</p> <p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p> <p>Writing will be limited up to integer values of <code>max_bits</code> bits, and trying to write bigger values will rase a :exc:<code>ValueError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes will be sent, in this case it would actually take at most 5 bytes, due to the variable encoding overhead.</p> <p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseAsyncReader","title":"mcproto.protocol.base_io.BaseAsyncReader","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding asynchronous read buffer/connection interactions.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseAsyncReader._read_varuint","title":"mcproto.protocol.base_io.BaseAsyncReader._read_varuint  <code>async</code>","text":"<pre><code>_read_varuint(*, max_bits: int | None = None) -&gt; int\n</code></pre> <p>Read an arbitrarily big unsigned integer in a variable length format.</p> <p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p> <p>Reading will be limited up to integer values of <code>max_bits</code> bits, and trying to read bigger values will rase an :exc:<code>IOError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes will be read, in this case we would actually read at most 5 bytes, due to the variable encoding overhead.</p> <p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseSyncReader","title":"mcproto.protocol.base_io.BaseSyncReader","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding synchronous read buffer/connection interactions.</p>"},{"location":"reference/private/protocol/#mcproto.protocol.base_io.BaseSyncReader._read_varuint","title":"mcproto.protocol.base_io.BaseSyncReader._read_varuint","text":"<pre><code>_read_varuint(*, max_bits: int | None = None) -&gt; int\n</code></pre> <p>Read an arbitrarily big unsigned integer in a variable length format.</p> <p>This is a standard way of transmitting ints, and it allows smaller numbers to take less bytes.</p> <p>Reading will be limited up to integer values of <code>max_bits</code> bits, and trying to read bigger values will rase an :exc:<code>IOError</code>. Note that setting <code>max_bits</code> to for example 32 bits doesn't mean that at most 4 bytes will be read, in this case we would actually read at most 5 bytes, due to the variable encoding overhead.</p> <p>Varints send bytes where 7 least significant bits are value bits, and the most significant bit is continuation flag bit. If this continuation bit is set (1), it indicates that there will be another varint byte sent after this one. The least significant group is written first, followed by each of the more significant groups, making varints little-endian, however in groups of 7 bits, not 8.</p>"},{"location":"reference/private/types/","title":"Internal components for types","text":"<p>These are the utility components related to / used in the types module.</p>"},{"location":"reference/private/types/#mcproto.types.nbt.NBTag","title":"mcproto.types.nbt.NBTag","text":"<p>               Bases: <code>MCType</code>, <code>NBTagConvertible</code></p> <p>Base class for NBT tags.</p> <p>In MC v1.20.2+ the type and name of the root tag is not written to the buffer, and unless specified, the type of the tag is assumed to be TAG_Compound.</p>"},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._read_header","title":"mcproto.types.nbt.NBTag._read_header  <code>classmethod</code>","text":"<pre><code>_read_header(buf: Buffer, read_type: bool = True, with_name: bool = True) -&gt; tuple[str, NBTagType]\n</code></pre> <p>Read the header of the NBT tag.</p> <p>Parameters:</p> Name Type Description Default <code>Buffer</code> <p>The buffer to read from.</p> required <code>bool</code> <p>Whether to read the type of the tag from the buffer. * If <code>True</code>, the tag type will be read from the buffer * If <code>False</code> and called from a subclass, the tag type will be inferred from the subclass. * If <code>False</code> and called from the base class, the tag type will be TAG_Compound.</p> <code>True</code> <code>bool</code> <p>Whether to read the name of the tag. If set to <code>False</code>, the tag will have the name <code>\"\"</code>.</p> <code>True</code> <p>Returns:</p> Type Description <code>tuple[str, NBTagType]</code> <p>A tuple containing the name and the tag type.  .. note:: It is possible that this function reads nothing from the buffer if both <code>with_name</code> and <code>read_type</code> are set to <code>False</code>.</p>"},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._read_header(buf)","title":"<code>buf</code>","text":""},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._read_header(read_type)","title":"<code>read_type</code>","text":""},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._read_header(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._write_header","title":"mcproto.types.nbt.NBTag._write_header","text":"<pre><code>_write_header(buf: Buffer, with_type: bool = True, with_name: bool = True) -&gt; None\n</code></pre> <p>Write the header of the NBT tag to the buffer.</p> <p>Parameters:</p> Name Type Description Default <code>Buffer</code> <p>The buffer to write to.</p> required <code>bool</code> <p>Whether to include the type of the tag in the serialization.</p> <code>True</code> <code>bool</code> <p>Whether to include the name of the tag in the serialization.</p> <code>True</code>"},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._write_header(buf)","title":"<code>buf</code>","text":""},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._write_header(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/private/types/#mcproto.types.nbt.NBTag._write_header(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/private/types/#mcproto.types.nbt._NumberNBTag","title":"mcproto.types.nbt._NumberNBTag","text":"<p>               Bases: <code>NBTag</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for NBT tags representing a number.</p> <p>This class is not meant to be used directly, but rather through its subclasses.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._NumberNBTag.payload","title":"mcproto.types.nbt._NumberNBTag.payload  <code>instance-attribute</code>","text":"<pre><code>payload: int\n</code></pre>"},{"location":"reference/private/types/#mcproto.types.nbt._FloatingNBTag","title":"mcproto.types.nbt._FloatingNBTag","text":"<p>               Bases: <code>NBTag</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for NBT tags representing a floating-point number.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._FloatingNBTag.payload","title":"mcproto.types.nbt._FloatingNBTag.payload  <code>instance-attribute</code>","text":"<pre><code>payload: float\n</code></pre>"},{"location":"reference/private/types/#mcproto.types.nbt._NumberArrayNBTag","title":"mcproto.types.nbt._NumberArrayNBTag","text":"<p>               Bases: <code>NBTag</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for NBT tags representing an array of numbers.</p>"},{"location":"reference/private/types/#mcproto.types.nbt._NumberArrayNBTag.payload","title":"mcproto.types.nbt._NumberArrayNBTag.payload  <code>instance-attribute</code>","text":"<pre><code>payload: list[int]\n</code></pre>"},{"location":"reference/public/authentication/","title":"Authentication","text":""},{"location":"reference/public/authentication/#mcproto.auth.account.Account","title":"mcproto.auth.account.Account","text":"<p>Base class for an authenticated Minecraft account.</p>"},{"location":"reference/public/authentication/#mcproto.auth.account.Account.check","title":"mcproto.auth.account.Account.check  <code>async</code>","text":"<pre><code>check(client: AsyncClient) -&gt; None\n</code></pre> <p>Check with minecraft API whether the account information stored is valid.</p> <p>Raises:</p> Type Description <code>MismatchedAccountInfoError</code> <p>If the information received from the minecraft API didn't match the information currently stored in the account instance.</p> <code>InvalidAccountAccessTokenError</code> <p>If the access token is not valid.</p>"},{"location":"reference/public/authentication/#mcproto.auth.account.InvalidAccountAccessTokenError","title":"mcproto.auth.account.InvalidAccountAccessTokenError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when the access token of the account was reported as invalid.</p>"},{"location":"reference/public/authentication/#mcproto.auth.account.MismatchedAccountInfoError","title":"mcproto.auth.account.MismatchedAccountInfoError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when info stored in the account instance doesn't match one from API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiError","title":"mcproto.auth.yggdrasil.AuthServerApiError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the authserver API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiError.msg","title":"mcproto.auth.yggdrasil.AuthServerApiError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiErrorType","title":"mcproto.auth.yggdrasil.AuthServerApiErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the authserver API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.AuthServerApiErrorType.from_status_error","title":"mcproto.auth.yggdrasil.AuthServerApiErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(code: int, short_msg: str, full_msg: str, cause_msg: str | None) -&gt; AuthServerApiErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount","title":"mcproto.auth.yggdrasil.YggdrasilAccount","text":"<p>               Bases: <code>Account</code></p> <p>Minecraft account logged into using Yggdrasil (legacy/unmigrated) auth system.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.authenticate","title":"mcproto.auth.yggdrasil.YggdrasilAccount.authenticate  <code>async</code> <code>classmethod</code>","text":"<pre><code>authenticate(client: AsyncClient, login: str, password: str) -&gt; Self\n</code></pre> <p>Authenticate using the Yggdrasil system (for non-Microsoft accounts).</p> <p>Parameters:</p> Name Type Description Default <code>str</code> <p>E-Mail of your Minecraft account, or username for (really old) Mojang accounts.</p> required <code>str</code> <p>Plaintext account password.</p> required"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.authenticate(login)","title":"<code>login</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.authenticate(password)","title":"<code>password</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.refresh","title":"mcproto.auth.yggdrasil.YggdrasilAccount.refresh  <code>async</code>","text":"<pre><code>refresh(client: AsyncClient) -&gt; None\n</code></pre> <p>Refresh the Yggdrasil access token.</p> <p>This method can be called when the access token expires, to obtain a new one without having to go through a complete re-login. This can happen after some time period, or for example when someone else logs in to this minecraft account elsewhere.</p>"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.signout","title":"mcproto.auth.yggdrasil.YggdrasilAccount.signout  <code>async</code>","text":"<pre><code>signout(client: AsyncClient, username: str, password: str) -&gt; None\n</code></pre> <p>Sign out using the Yggdrasil system (for non-Microsoft accounts).</p> <p>Parameters:</p> Name Type Description Default <p>E-Mail of your Minecraft account, or username for (really old) Mojang accounts.</p> required <code>str</code> <p>Plaintext account password.</p> required"},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.signout(login)","title":"<code>login</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.signout(password)","title":"<code>password</code>","text":""},{"location":"reference/public/authentication/#mcproto.auth.yggdrasil.YggdrasilAccount.validate","title":"mcproto.auth.yggdrasil.YggdrasilAccount.validate  <code>async</code>","text":"<pre><code>validate(client: AsyncClient) -&gt; bool\n</code></pre> <p>Check if the access token is (still) usable for authentication with a Minecraft server.</p> <p>If this method fails, the stored access token is no longer usable for for authentcation with a Minecraft server, but should still be good enough for :meth:<code>refresh</code>.</p> <p>This mainly happens when one has used another client (e.g. another launcher).</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.MSAAccount","title":"mcproto.auth.msa.MSAAccount","text":"<p>               Bases: <code>Account</code></p> <p>Minecraft account logged into using Microsoft OAUth2 auth system.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.MSAAccount.from_xbox_access_token","title":"mcproto.auth.msa.MSAAccount.from_xbox_access_token  <code>async</code> <code>classmethod</code>","text":"<pre><code>from_xbox_access_token(client: AsyncClient, access_token: str) -&gt; Self\n</code></pre> <p>Construct the account from the xbox access token, using it to get the rest of the profile information.</p> <p>See :meth:<code>_get_access_token_from_xbox</code> for how to obtain the <code>access_token</code>. Note that in most cases, you'll want to use :meth:<code>xbox_auth</code> rather than this method directly.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.MSAAccount.xbox_auth","title":"mcproto.auth.msa.MSAAccount.xbox_auth  <code>async</code> <code>classmethod</code>","text":"<pre><code>xbox_auth(client: AsyncClient, user_hash: str, xsts_token: str) -&gt; Self\n</code></pre> <p>Authenticate using an XSTS token from Xbox Live auth (for Microsoft accounts).</p> <p>See :func:<code>mcproto.auth.microsoft.xbox.xbox_auth</code> for how to obtain the <code>user_hash</code> and <code>xsts_token</code>.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIError","title":"mcproto.auth.msa.ServicesAPIError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the Minecraft services API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIError.msg","title":"mcproto.auth.msa.ServicesAPIError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIErrorType","title":"mcproto.auth.msa.ServicesAPIErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the Minecraft services API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.msa.ServicesAPIErrorType.from_status_error","title":"mcproto.auth.msa.ServicesAPIErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(code: int, err_msg: str | None) -&gt; ServicesAPIErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthRequestData","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthRequestData","text":"<p>               Bases: <code>TypedDict</code></p> <p>Data obtained from Microsoft OAuth2 API after making a new authentication request.</p> <p>This data specifies where (URL) we can check with the Microsoft OAuth2 servers for a client confirmation of this authentication request, how often we should check with this server, and when this request expires.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseData","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseData","text":"<p>               Bases: <code>TypedDict</code></p> <p>Data obtained from Microsoft OAuth2 API after a successful authentication.</p> <p>This data contains the access and refresh tokens, giving us the requested account access and the expiry information.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the Microsoft OAuth2 API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError.msg","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the Microsoft OAuth2 API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType.from_status_error","title":"mcproto.auth.microsoft.oauth.MicrosoftOauthResponseErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(error: str) -&gt; MicrosoftOauthResponseErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.full_microsoft_oauth","title":"mcproto.auth.microsoft.oauth.full_microsoft_oauth  <code>async</code>","text":"<pre><code>full_microsoft_oauth(client: AsyncClient, client_id: str) -&gt; MicrosoftOauthResponseData\n</code></pre> <p>Perform full Microsoft Oauth2 sequence, waiting for user to authenticated (from the browser).</p> <p>See :func:<code>microsoft_oauth_request</code> (OAuth2 start) and :func:<code>microsoft_oauth_authenticate</code> (OAuth2 end).</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.microsoft_oauth_authenticate","title":"mcproto.auth.microsoft.oauth.microsoft_oauth_authenticate  <code>async</code>","text":"<pre><code>microsoft_oauth_authenticate(client: AsyncClient, client_id: str, device_code: str) -&gt; MicrosoftOauthResponseData\n</code></pre> <p>Complete Microsoft Oauth2 flow and authenticate.</p> <p>This functon should be called after :func:<code>microsoft_oauth_request</code>. If the user has authorized the request, we will get an access token back, allowing us to perform certain actions on behaf of the microsoft user that has authorized this request. Alternatively, this function will fal with :exc:<code>MicrosoftOauthResponseError</code>.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.oauth.microsoft_oauth_request","title":"mcproto.auth.microsoft.oauth.microsoft_oauth_request  <code>async</code>","text":"<pre><code>microsoft_oauth_request(client: AsyncClient, client_id: str) -&gt; MicrosoftOauthRequestData\n</code></pre> <p>Initiate Microsoft Oauth2 flow.</p> <p>This requires a <code>client_id</code>, which can be obtained by creating an application on <code>Microsoft Azure &lt;https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app&gt;</code>_, with 'Allow public client flows' set to 'Yes' (can be set from the 'Authentication' tab).</p> <p>This will create a device id, used to identify our request and a user code, which the user can manually enter to https://www.microsoft.com/link and confirm, after that, :func:<code>microsoft_oauth_authenticate</code> should be called, with the returend device id as an argument.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSErrorType","title":"mcproto.auth.microsoft.xbox.XSTSErrorType","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that the Xbox Secure Token Server (XSTS) API can report.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSErrorType.from_status_error","title":"mcproto.auth.microsoft.xbox.XSTSErrorType.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(xerr_no: int) -&gt; XSTSErrorType\n</code></pre> <p>Determine the error kind based on the error data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSRequestError","title":"mcproto.auth.microsoft.xbox.XSTSRequestError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised on a failure from the Xbox Secure Token Server (XSTS) API.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XSTSRequestError.msg","title":"mcproto.auth.microsoft.xbox.XSTSRequestError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.XboxData","title":"mcproto.auth.microsoft.xbox.XboxData","text":"<p>               Bases: <code>NamedTuple</code></p> <p>Xbox authentication data.</p>"},{"location":"reference/public/authentication/#mcproto.auth.microsoft.xbox.xbox_auth","title":"mcproto.auth.microsoft.xbox.xbox_auth  <code>async</code>","text":"<pre><code>xbox_auth(client: AsyncClient, microsoft_access_token: str, bedrock: bool = False) -&gt; XboxData\n</code></pre> <p>Authenticate into Xbox Live account and obtain user hash and XSTS token.</p> <p>See :func:<code>~mcproto.auth.microsoft.oauth.full_microsoft_oauth</code> for info on <code>microsoft_access_token</code>.</p>"},{"location":"reference/public/encryption/","title":"Encryption utilities","text":"<p>The following components are used for encryption related interacions (generally needed during the communication with the server, after an encryption request during the login process)</p>"},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret","title":"mcproto.encryption.decrypt_token_and_secret","text":"<pre><code>decrypt_token_and_secret(private_key: RSAPrivateKey, verification_token: bytes, shared_secret: bytes) -&gt; tuple[bytes, bytes]\n</code></pre> <p>Decrypts the verification token and shared secret with the server's private key.</p> <p>Parameters:</p> Name Type Description Default <code>RSAPrivateKey</code> <p>The RSA private key generated by the server</p> required <code>bytes</code> <p>The verification token encrypted and sent by the client</p> required <code>bytes</code> <p>The shared secret encrypted and sent by the client</p> required <p>Returns:</p> Type Description <code>tuple[bytes, bytes]</code> <p>A tuple containing (decrypted token, decrypted secret)</p>"},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret(private_key)","title":"<code>private_key</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret(verification_token)","title":"<code>verification_token</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.decrypt_token_and_secret(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret","title":"mcproto.encryption.encrypt_token_and_secret","text":"<pre><code>encrypt_token_and_secret(public_key: RSAPublicKey, verification_token: bytes, shared_secret: bytes) -&gt; tuple[bytes, bytes]\n</code></pre> <p>Encrypts the verification token and shared secret with the server's public key.</p> <p>Parameters:</p> Name Type Description Default <code>RSAPublicKey</code> <p>The RSA public key provided by the server</p> required <code>bytes</code> <p>The verification token provided by the server</p> required <code>bytes</code> <p>The generated shared secret</p> required <p>Returns:</p> Type Description <code>tuple[bytes, bytes]</code> <p>A tuple containing (encrypted token, encrypted secret)</p>"},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret(public_key)","title":"<code>public_key</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret(verification_token)","title":"<code>verification_token</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.encrypt_token_and_secret(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/encryption/#mcproto.encryption.generate_rsa_key","title":"mcproto.encryption.generate_rsa_key","text":"<pre><code>generate_rsa_key() -&gt; RSAPrivateKey\n</code></pre> <p>Generate a random RSA key pair for server.</p> <p>This key pair will be used for :class:<code>~mcproto.packets.login.login.LoginEncryptionRequest</code> packet, where the client will be sent the public part of this key pair, which will be used to encrypt the shared secret (and verification token) sent in :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet. The server will then use the private part of this key pair to decrypt that.</p> <p>This will be a 1024-bit RSA key pair.</p>"},{"location":"reference/public/encryption/#mcproto.encryption.generate_shared_secret","title":"mcproto.encryption.generate_shared_secret","text":"<pre><code>generate_shared_secret() -&gt; bytes\n</code></pre> <p>Generate a random shared secret for client.</p> <p>This secret will be sent to the server in :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet, and used to encrypt all future communication afterwards.</p> <p>This will be symetric encryption using AES/CFB8 stream cipher. And this shared secret will be 16-bytes long.</p>"},{"location":"reference/public/encryption/#mcproto.encryption.generate_verify_token","title":"mcproto.encryption.generate_verify_token","text":"<pre><code>generate_verify_token() -&gt; bytes\n</code></pre> <p>Generate a random verify token.</p> <p>This token will be sent by the server in :class:<code>~mcproto.packets.login.login.LoginEncryptionRequest</code>, to be encrypted by the client as a form of verification.</p> <p>This token doesn't need to be cryptographically secure, it's just a sanity check that the client has encrypted the data correctly.</p>"},{"location":"reference/public/multiplayer/","title":"Multiplayer utilities","text":"<p>The following components are used for various multiplayer interacions (generally needed during the server joining process).</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.JoinAcknowledgeData","title":"mcproto.multiplayer.JoinAcknowledgeData","text":"<p>               Bases: <code>TypedDict</code></p> <p>Response from :func:<code>join_check</code> (hasJoined minecraft API endpoint).</p> <p>This response contains information on the user has submitted the :func:<code>join_request</code>. (uuid, name, and player skin properties)</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.JoinAcknowledgeProperty","title":"mcproto.multiplayer.JoinAcknowledgeProperty","text":"<p>               Bases: <code>TypedDict</code></p> <p>Skin blob data from :class:<code>JoinAcknowledgeData</code>.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinCheckFailedError","title":"mcproto.multiplayer.UserJoinCheckFailedError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when :func:<code>join_check</code> fails.</p> <p>This signifies that the Minecraft session API server didn't contain a join request for the <code>server_hash</code> and <code>client_username</code>, and it therefore didn't acknowledge the join.</p> <p>This means the user didn't confirm this join with Minecraft API (didn't call :func:<code>join_request</code>), hence the validity of this account can't be verified. The server should kick the user and end the join flow.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestErrorKind","title":"mcproto.multiplayer.UserJoinRequestErrorKind","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>Enum for various different kinds of exceptions that can occur during :func:<code>join_request</code>.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestErrorKind.from_status_error","title":"mcproto.multiplayer.UserJoinRequestErrorKind.from_status_error  <code>classmethod</code>","text":"<pre><code>from_status_error(code: int, err_msg: str | None) -&gt; UserJoinRequestErrorKind\n</code></pre> <p>Determine the error kind based on the status code and error message.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestFailedError","title":"mcproto.multiplayer.UserJoinRequestFailedError","text":"<p>               Bases: <code>Exception</code></p> <p>Exception raised when :func:<code>join_request</code> fails.</p> <p>This can be caused by various reasons. See: :class:<code>UserJoinRequestErrorKind</code> enum class. The most likely case for this error is invalid authentication token, or the user being banned from multiplayer.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.UserJoinRequestFailedError.msg","title":"mcproto.multiplayer.UserJoinRequestFailedError.msg  <code>property</code>","text":"<pre><code>msg: str\n</code></pre> <p>Produce a message for this error.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.compute_server_hash","title":"mcproto.multiplayer.compute_server_hash","text":"<pre><code>compute_server_hash(server_id: str, shared_secret: bytes, server_public_key: RSAPublicKey) -&gt; str\n</code></pre> <p>Compute a hash to be sent as 'serverId' field to Mojang session server.</p> <p>This function is used for :func:<code>join_request</code> and :func:<code>join_check</code> functions, which require this hash value.</p> <p>This SHA1 hash is computed based on the <code>server_id</code>, <code>server_public_key</code> and <code>shared_secret</code>. Together, these values ensure that there can't be any middle-man listening in after encryption is established.</p> <p>This is because a middle man/proxy who would want to listed into the encrypted communication would need to know the encryption key (<code>shared_secret</code>). A proxy can capture this key, as the client sends it over to the server in :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet, however it is sent encrypted. The client performs this encryption with a public key, which it got from the server, in :class:<code>mcproto.packets.login.login.LoginEncryptionRequest</code> packet.</p> <p>That mans that for a proxy to be able to actually obtain this shared secret value, it would need to be able to capture the encryption response, and decrypt the shared secret value. That means it would need to send a spoofed version of the encryption request packet, with the server's public key replaced by one that the proxy owns a private key for. This will work, and the proxy could indeed decrypt the sent shared secret now. All it would need to do now is send this shared secret to the server. That's easy, just re-encrypt it with the server's original public key, and send it in a custom encryption request!</p> <p>So then it seems that it's possible to intercept the client-server communication and spy in, and indeed, this will work with offline mode (warez) servers, however with online mode servers, that's where this function comes in!</p> <p>Online mode servers rely on an API server from Mojang's (session server), which the client informs of the join. The server then queries this server for an acknowledgement of this join, and only if this session server confirms that the client did indeed inform it of this join will the server allow this client to join.</p> <p>The trick is, this request to inform the session server of the join can only be performed by the client directly, a proxy can't simulate it, because this request requires a token for the minecraft account, which only the launcher has. The client never sends this token to the server, only to the Mojang's session server, so a proxy wouldn't have it.</p> <p>This join request then contains those 3 variables, one of which being the public key itself, so if the proxy sent a different key, the server would no longer arrive at the same server hash, and the check would fail, so the server wouldn't allow this client to join.</p>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check","title":"mcproto.multiplayer.join_check  <code>async</code>","text":"<pre><code>join_check(client: AsyncClient, client_username: str, server_hash: str, client_ip: str | None = None) -&gt; JoinAcknowledgeData\n</code></pre> <p>Check with the Mojang session server if a join request was made.</p> <p>This function is called by the server in online mode (non-warez), to verify that the joining client really does have an official minecraft account. The client will first inform the server about this join request (:func:<code>join_request</code>), server then runs this check confirming the client is who they say they are.</p> <p>This request should be performed after receiving the after receiving the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet.</p> <p>This request uses a <code>server_hash</code>, this is the value under which the client has submitted their join request, and we'll now be checking for that submission with that same value. This is a hash composed of various values, which together serve as a way to prevent any MITMA (man in the middle attacks). To obtain this hash, see :func:<code>compute_server_hash</code>. This function's docstring also includes description for why and how this prevents a MITMA.</p> <p>Parameters:</p> Name Type Description Default <code>AsyncClient</code> <p>HTTPX async client to make the HTTP request with.</p> required <code>str</code> <p>Must match joining the username of the joining client (case sensitive).  Note: This is the in-game nickname of the selected profile, not Mojang account name (which is never sent to the server). Servers should use the name in \"name\" field which was received in the :class:<code>~mcproto.packets.login.login.LoginStart</code> packet.</p> required <code>str</code> <p>SHA1 hash of the server (see :func:<code>compute_server_hash</code>)</p> required <code>str | None</code> <p>IP address of the connecting player (optional)  Servers only include this when 'prevent-proxy-connections' is set to true in server.properties</p> <code>None</code>"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(client)","title":"<code>client</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(client_username)","title":"<code>client_username</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(server_hash)","title":"<code>server_hash</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_check(client_ip)","title":"<code>client_ip</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request","title":"mcproto.multiplayer.join_request  <code>async</code>","text":"<pre><code>join_request(client: AsyncClient, account: Account, server_hash: str) -&gt; None\n</code></pre> <p>Inform the Mojang session server about this new user join.</p> <p>This function is called by the client, when joining an online mode (non-warez) server. This is required and the server will check that this request was indeed made (:func:<code>join_check</code>).</p> <p>This request should be performed after receiving the :class:<code>~mcproto.packets.login.login.LoginEncryptionRequest</code> packet, but before sending the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code>.</p> <p>Performing this request requires an :class:<code>~mcproto.auth.account.Account</code> instance, as this request is here to ensure that only original Minceraft accounts (officially bought accounts) can join.</p> <p>This request uses a <code>server_hash</code> to identify which server is the client attempting to join. This hash is composed of various values, which together serve as a way to prevent any MITMA (man in the middle attacks). To obtain this hash, see :func:<code>compute_server_hash</code>. This function's docstring also includes description for why and how this prevents a MITMA.</p> <p>Parameters:</p> Name Type Description Default <code>AsyncClient</code> <p>HTTPX async client to make the HTTP request with.</p> required <code>Account</code> <p>Instance of an account containing the minecraft token necessary for this request.</p> required <code>str</code> <p>SHA1 hash of the server (see :func:<code>compute_server_hash</code>)</p> required"},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request(client)","title":"<code>client</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request(account)","title":"<code>account</code>","text":""},{"location":"reference/public/multiplayer/#mcproto.multiplayer.join_request(server_hash)","title":"<code>server_hash</code>","text":""},{"location":"reference/public/packets/","title":"Packets","text":""},{"location":"reference/public/packets/#base-classes-and-interaction-functions","title":"Base classes and interaction functions","text":""},{"location":"reference/public/packets/#mcproto.packets.ClientBoundPacket","title":"mcproto.packets.ClientBoundPacket","text":"<p>               Bases: <code>Packet</code></p> <p>Packet bound to a client (Server -&gt; Client).</p>"},{"location":"reference/public/packets/#mcproto.packets.GameState","title":"mcproto.packets.GameState","text":"<p>               Bases: <code>IntEnum</code></p> <p>All possible game states in minecraft.</p>"},{"location":"reference/public/packets/#mcproto.packets.Packet","title":"mcproto.packets.Packet","text":"<p>               Bases: <code>Serializable</code>, <code>RequiredParamsABCMixin</code></p> <p>Base class for all packets.</p>"},{"location":"reference/public/packets/#mcproto.packets.PacketDirection","title":"mcproto.packets.PacketDirection","text":"<p>               Bases: <code>IntEnum</code></p> <p>Represents whether a packet targets (is bound to) a client or server.</p>"},{"location":"reference/public/packets/#mcproto.packets.ServerBoundPacket","title":"mcproto.packets.ServerBoundPacket","text":"<p>               Bases: <code>Packet</code></p> <p>Packet bound to a server (Client -&gt; Server).</p>"},{"location":"reference/public/packets/#mcproto.packets.async_read_packet","title":"mcproto.packets.async_read_packet  <code>async</code>","text":"<pre><code>async_read_packet(reader: BaseAsyncReader, packet_map: Mapping[int, type[T_Packet]], *, compression_threshold: int = -1) -&gt; T_Packet\n</code></pre> <p>Read a packet.</p> <p>Parameters:</p> Name Type Description Default <code>BaseAsyncReader</code> <p>The connection/reader to receive this packet from.</p> required <code>Mapping[int, type[T_Packet]]</code> <p>A mapping of packet id (number) -&gt; Packet (class).  This mapping should contain all of the packets for the current gamestate and direction. See :func:<code>~mcproto.packets.packet_map.generate_packet_map</code></p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).  Note that during reading, we don't actually need to know the specific threshold, just whether or not is is non-negative (whether compression is enabled), as the packet format fundamentally changes when it is. That means you can pass any positive number here to enable compresison, regardess of what it actually is.</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.async_read_packet(reader)","title":"<code>reader</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_read_packet(packet_map)","title":"<code>packet_map</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_read_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_write_packet","title":"mcproto.packets.async_write_packet  <code>async</code>","text":"<pre><code>async_write_packet(writer: BaseAsyncWriter, packet: Packet, *, compression_threshold: int = -1) -&gt; None\n</code></pre> <p>Write given <code>packet</code>.</p> <p>Parameters:</p> Name Type Description Default <code>BaseAsyncWriter</code> <p>The connection/writer to send this packet to.</p> required <code>Packet</code> <p>The packet to be sent.</p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.async_write_packet(writer)","title":"<code>writer</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_write_packet(packet)","title":"<code>packet</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.async_write_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.generate_packet_map","title":"mcproto.packets.generate_packet_map  <code>cached</code>","text":"<pre><code>generate_packet_map(direction: Literal[SERVERBOUND], state: GameState) -&gt; Mapping[int, type[ServerBoundPacket]]\n</code></pre><pre><code>generate_packet_map(direction: Literal[CLIENTBOUND], state: GameState) -&gt; Mapping[int, type[ClientBoundPacket]]\n</code></pre> <pre><code>generate_packet_map(direction: PacketDirection, state: GameState) -&gt; Mapping[int, type[Packet]]\n</code></pre> <p>Dynamically generated a packet map for given <code>direction</code> and <code>state</code>.</p> <p>This generation is done by dynamically importing all of the modules containing these packets, filtering them to only contain those pacekts with the specified parameters, and storing those into a dictionary, using the packet id as key, and the packet class itself being the value.</p> <p>As this fucntion is likely to be called quite often, and it uses dynamic importing to obtain the packet classes, this function is cached, which means the logic only actually runs once, after which, for the same arguments, the same dict will be returned.</p>"},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet","title":"mcproto.packets.sync_read_packet","text":"<pre><code>sync_read_packet(reader: BaseSyncReader, packet_map: Mapping[int, type[T_Packet]], *, compression_threshold: int = -1) -&gt; T_Packet\n</code></pre> <p>Read a packet.</p> <p>Parameters:</p> Name Type Description Default <code>BaseSyncReader</code> <p>The connection/reader to receive this packet from.</p> required <code>Mapping[int, type[T_Packet]]</code> <p>A mapping of packet id (number) -&gt; Packet (class).  This mapping should contain all of the packets for the current gamestate and direction. See :func:<code>~mcproto.packets.packet_map.generate_packet_map</code></p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).  Note that during reading, we don't actually need to know the specific threshold, just whether or not is is non-negative (whether compression is enabled), as the packet format fundamentally changes when it is. That means you can pass any positive number here to enable compresison, regardess of what it actually is.</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet(reader)","title":"<code>reader</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet(packet_map)","title":"<code>packet_map</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_read_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet","title":"mcproto.packets.sync_write_packet","text":"<pre><code>sync_write_packet(writer: BaseSyncWriter, packet: Packet, *, compression_threshold: int = -1) -&gt; None\n</code></pre> <p>Write given <code>packet</code>.</p> <p>Parameters:</p> Name Type Description Default <code>BaseSyncWriter</code> <p>The connection/writer to send this packet to.</p> required <code>Packet</code> <p>The packet to be sent.</p> required <code>int</code> <p>A threshold packet length, whcih if crossed compression should be enabled.  You can get this number from :class:<code>~mcproto.packets.login.login.LoginSetCompression</code> packet. If this packet wasn't sent by the server, set this to -1 (default).</p> <code>-1</code>"},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet(writer)","title":"<code>writer</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet(packet)","title":"<code>packet</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.sync_write_packet(compression_threshold)","title":"<code>compression_threshold</code>","text":""},{"location":"reference/public/packets/#handshaking-gamestate","title":"Handshaking gamestate","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake","title":"mcproto.packets.handshaking.handshake.Handshake","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Initializes connection between server and client. (Client -&gt; Server).</p> <p>Initialize the Handshake packet.</p> <p>Parameters:</p> Name Type Description Default <p>Protocol version number to be used.</p> required <p>The host/address the client is connecting to.</p> required <p>The port the client is connecting to.</p> required <p>The next state for the server to move into.</p> required"},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(protocol_version)","title":"<code>protocol_version</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(server_address)","title":"<code>server_address</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(server_port)","title":"<code>server_port</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake(next_state)","title":"<code>next_state</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.Handshake.serialize_to","title":"mcproto.packets.handshaking.handshake.Handshake.serialize_to","text":"<pre><code>serialize_to(buf: Buffer) -&gt; None\n</code></pre> <p>Serialize the packet.</p>"},{"location":"reference/public/packets/#mcproto.packets.handshaking.handshake.NextState","title":"mcproto.packets.handshaking.handshake.NextState","text":"<p>               Bases: <code>IntEnum</code></p> <p>Enum of all possible next game states we can transition to from the :class:<code>Handshake</code> packet.</p>"},{"location":"reference/public/packets/#status-gamestate","title":"Status gamestate","text":""},{"location":"reference/public/packets/#mcproto.packets.status.ping.PingPong","title":"mcproto.packets.status.ping.PingPong","text":"<p>               Bases: <code>ClientBoundPacket</code>, <code>ServerBoundPacket</code></p> <p>Ping request/Pong response (Server &lt;-&gt; Client).</p> <p>Initialize the PingPong packet.</p> <p>Parameters:</p> Name Type Description Default <p>Random number to test out the connection. Ideally, this number should be quite big, however it does need to fit within the limit of a signed long long (-2 ** 63 to 2 ** 63 - 1).</p> required"},{"location":"reference/public/packets/#mcproto.packets.status.ping.PingPong(payload)","title":"<code>payload</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.status.status.StatusRequest","title":"mcproto.packets.status.status.StatusRequest","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Request from the client to get information on the server. (Client -&gt; Server).</p>"},{"location":"reference/public/packets/#mcproto.packets.status.status.StatusResponse","title":"mcproto.packets.status.status.StatusResponse","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Response from the server to requesting client with status data information. (Server -&gt; Client).</p> <p>Initialize the StatusResponse packet.</p> <p>Parameters:</p> Name Type Description Default <p>JSON response data sent back to the client.</p> required"},{"location":"reference/public/packets/#mcproto.packets.status.status.StatusResponse(data)","title":"<code>data</code>","text":""},{"location":"reference/public/packets/#login-gamestate","title":"Login gamestate","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginDisconnect","title":"mcproto.packets.login.login.LoginDisconnect","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to kick a player while in the login state. (Server -&gt; Client).</p> <p>Initialize the LoginDisconnect packet.</p> <p>Parameters:</p> Name Type Description Default <p>The reason for disconnection (kick).</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginDisconnect(reason)","title":"<code>reason</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest","title":"mcproto.packets.login.login.LoginEncryptionRequest","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Used by the server to ask the client to encrypt the login process. (Server -&gt; Client).</p> <p>Initialize the LoginEncryptionRequest packet.</p> <p>Parameters:</p> Name Type Description Default <p>Server's public key.</p> required <p>Sequence of random bytes generated by server for verification.</p> required <p>Empty on minecraft versions 1.7.X and higher (20 random chars pre 1.7).</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest(public_key)","title":"<code>public_key</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest(verify_token)","title":"<code>verify_token</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionRequest(server_id)","title":"<code>server_id</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse","title":"mcproto.packets.login.login.LoginEncryptionResponse","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Response from the client to :class:<code>LoginEncryptionRequest</code> packet. (Client -&gt; Server).</p> <p>Initialize the LoginEncryptionResponse packet.</p> <p>Parameters:</p> Name Type Description Default <p>Shared secret value, encrypted with server's public key.</p> required <p>Verify token value, encrypted with same public key.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse(verify_token)","title":"<code>verify_token</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginEncryptionResponse.serialize_to","title":"mcproto.packets.login.login.LoginEncryptionResponse.serialize_to","text":"<pre><code>serialize_to(buf: Buffer) -&gt; None\n</code></pre> <p>Serialize the packet.</p>"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest","title":"mcproto.packets.login.login.LoginPluginRequest","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to implement a custom handshaking flow. (Server -&gt; Client).</p> <p>Initialize the LoginPluginRequest.</p> <p>Parameters:</p> Name Type Description Default <p>Message id, generated by the server, should be unique to the connection.</p> required <p>Channel identifier, name of the plugin channel used to send data.</p> required <p>Data that is to be sent.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest(message_id)","title":"<code>message_id</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest(channel)","title":"<code>channel</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginRequest(data)","title":"<code>data</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginResponse","title":"mcproto.packets.login.login.LoginPluginResponse","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Response to LoginPluginRequest from client. (Client -&gt; Server).</p> <p>Initialize the LoginPluginRequest packet.</p> <p>Parameters:</p> Name Type Description Default <p>Message id, generated by the server, should be unique to the connection.</p> required <p>Optional response data, present if client understood request.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginResponse(message_id)","title":"<code>message_id</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginPluginResponse(data)","title":"<code>data</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSetCompression","title":"mcproto.packets.login.login.LoginSetCompression","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to specify whether to use compression on future packets or not (Server -&gt; Client).</p> <p>Initialize the LoginSetCompression packet.</p> <p>Parameters:</p> Name Type Description Default <p>Maximum size of a packet before it is compressed. All packets smaller than this will remain uncompressed. To disable compression completely, threshold can be set to -1.  .. note:: This packet is optional, and if not set, the compression will not be enabled at all.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSetCompression(threshold)","title":"<code>threshold</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginStart","title":"mcproto.packets.login.login.LoginStart","text":"<p>               Bases: <code>ServerBoundPacket</code></p> <p>Packet from client asking to start login process. (Client -&gt; Server).</p> <p>Initialize the LoginStart packet.</p> <p>Parameters:</p> Name Type Description Default <p>Username of the client who sent the request.</p> required <p>UUID of the player logging in (if the player doesn't have a UUID, this can be <code>None</code>)</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginStart(username)","title":"<code>username</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginStart(uuid)","title":"<code>uuid</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSuccess","title":"mcproto.packets.login.login.LoginSuccess","text":"<p>               Bases: <code>ClientBoundPacket</code></p> <p>Sent by the server to denote a successful login. (Server -&gt; Client).</p> <p>Initialize the LoginSuccess packet.</p> <p>Parameters:</p> Name Type Description Default <p>The UUID of the connecting player/client.</p> required <p>The username of the connecting player/client.</p> required"},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSuccess(uuid)","title":"<code>uuid</code>","text":""},{"location":"reference/public/packets/#mcproto.packets.login.login.LoginSuccess(username)","title":"<code>username</code>","text":""},{"location":"reference/public/packets/#play-gamestate","title":"Play gamestate","text":"<p>Work In Progress</p> <p>Packets for the Play gamestate aren't yet implemented.</p>"},{"location":"reference/public/protocol/","title":"Protocol documentation","text":"<p>This is the documentation for components related to interactions with the minecraft protocol and connection establishing.</p> <p>               Bases: <code>BaseSyncWriter</code>, <code>BaseSyncReader</code>, <code>bytearray</code></p> <p>In-memory bytearray-like buffer supporting the common read/write operations.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader","title":"mcproto.protocol.base_io.BaseAsyncReader","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding asynchronous read buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read","title":"mcproto.protocol.base_io.BaseAsyncReader.read  <code>abstractmethod</code> <code>async</code>","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Underlying read method, obtaining the raw data.</p> <p>All of the reader functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_ascii","title":"mcproto.protocol.base_io.BaseAsyncReader.read_ascii  <code>async</code>","text":"<pre><code>read_ascii() -&gt; str\n</code></pre> <p>Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_bytearray","title":"mcproto.protocol.base_io.BaseAsyncReader.read_bytearray  <code>async</code>","text":"<pre><code>read_bytearray() -&gt; bytearray\n</code></pre> <p>Read an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_optional","title":"mcproto.protocol.base_io.BaseAsyncReader.read_optional  <code>async</code>","text":"<pre><code>read_optional(reader: Callable[[], Awaitable[R]]) -&gt; R | None\n</code></pre> <p>Read a bool showing if a value is present, if so, also reads this value with <code>reader</code> function.</p> <ul> <li>When <code>False</code> is read, the function will not read anything and <code>None</code> is returned.</li> <li>When <code>True</code> is read, the <code>reader</code> function is called, and it's return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_utf","title":"mcproto.protocol.base_io.BaseAsyncReader.read_utf  <code>async</code>","text":"<pre><code>read_utf() -&gt; str\n</code></pre> <p>Read a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be read + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>IOError</code> <ul> <li>If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all, and :exc:<code>IOError</code> will be raised immediately. * If the received string has more than the maximum amount of characters (32767). Note that in this case, the string will still get read in it's entirety, since it fits into the maximum bytes limit (131068), which was simply read at once. This limitation is here only to replicate the behavior of minecraft's implementation.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_value","title":"mcproto.protocol.base_io.BaseAsyncReader.read_value  <code>async</code>","text":"<pre><code>read_value(fmt: INT_FORMATS_TYPE) -&gt; int\n</code></pre><pre><code>read_value(fmt: FLOAT_FORMATS_TYPE) -&gt; float\n</code></pre><pre><code>read_value(fmt: Literal[BOOL]) -&gt; bool\n</code></pre><pre><code>read_value(fmt: Literal[CHAR]) -&gt; str\n</code></pre> <pre><code>read_value(fmt: StructFormat) -&gt; object\n</code></pre> <p>Read a value as given struct format (<code>fmt</code>) in big-endian mode.</p> <p>The amount of bytes to read will be determined based on the struct format automatically.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_varint","title":"mcproto.protocol.base_io.BaseAsyncReader.read_varint  <code>async</code>","text":"<pre><code>read_varint() -&gt; int\n</code></pre> <p>Read a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncReader.read_varlong","title":"mcproto.protocol.base_io.BaseAsyncReader.read_varlong  <code>async</code>","text":"<pre><code>read_varlong() -&gt; int\n</code></pre> <p>Read a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter","title":"mcproto.protocol.base_io.BaseAsyncWriter","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding asynchronous write buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write","title":"mcproto.protocol.base_io.BaseAsyncWriter.write  <code>abstractmethod</code> <code>async</code>","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Underlying write method, sending/storing the data.</p> <p>All of the writer functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_ascii","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_ascii  <code>async</code>","text":"<pre><code>write_ascii(value: str) -&gt; None\n</code></pre> <p>Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_bytearray","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_bytearray  <code>async</code>","text":"<pre><code>write_bytearray(data: bytes) -&gt; None\n</code></pre> <p>Write an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_optional","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_optional  <code>async</code>","text":"<pre><code>write_optional(value: T | None, /, writer: Callable[[T], Awaitable[R]]) -&gt; R | None\n</code></pre> <p>Write a bool showing if a <code>value</code> is present, if so, also writes this value with <code>writer</code> function.</p> <ul> <li>When <code>value</code> is <code>None</code>, a bool of <code>False</code> will be written, and <code>None</code> is returned.</li> <li>When <code>value</code> is not <code>None</code>, a bool of <code>True</code> is written, after which the <code>writer</code> function is called,   and the return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_utf","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_utf  <code>async</code>","text":"<pre><code>write_utf(value: str) -&gt; None\n</code></pre> <p>Write a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be written + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the given string <code>value</code> has more characters than the allowed maximum (32767).</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_value","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_value  <code>async</code>","text":"<pre><code>write_value(fmt: INT_FORMATS_TYPE, value: int) -&gt; None\n</code></pre><pre><code>write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[BOOL], value: bool) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[CHAR], value: str) -&gt; None\n</code></pre> <pre><code>write_value(fmt: StructFormat, value: object) -&gt; None\n</code></pre> <p>Write a given <code>value</code> as given struct format (<code>fmt</code>) in big-endian mode.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_varint","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_varint  <code>async</code>","text":"<pre><code>write_varint(value: int) -&gt; None\n</code></pre> <p>Write a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseAsyncWriter.write_varlong","title":"mcproto.protocol.base_io.BaseAsyncWriter.write_varlong  <code>async</code>","text":"<pre><code>write_varlong(value: int) -&gt; None\n</code></pre> <p>Write a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader","title":"mcproto.protocol.base_io.BaseSyncReader","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding synchronous read buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read","title":"mcproto.protocol.base_io.BaseSyncReader.read  <code>abstractmethod</code>","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Underlying read method, obtaining the raw data.</p> <p>All of the reader functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_ascii","title":"mcproto.protocol.base_io.BaseSyncReader.read_ascii","text":"<pre><code>read_ascii() -&gt; str\n</code></pre> <p>Read ISO-8859-1 encoded string, until we encounter NULL (0x00) at the end indicating string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_bytearray","title":"mcproto.protocol.base_io.BaseSyncReader.read_bytearray","text":"<pre><code>read_bytearray() -&gt; bytearray\n</code></pre> <p>Read an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_optional","title":"mcproto.protocol.base_io.BaseSyncReader.read_optional","text":"<pre><code>read_optional(reader: Callable[[], R]) -&gt; R | None\n</code></pre> <p>Read a bool showing if a value is present, if so, also reads this value with <code>reader</code> function.</p> <ul> <li>When <code>False</code> is read, the function will not read anything and <code>None</code> is returned.</li> <li>When <code>True</code> is read, the <code>reader</code> function is called, and it's return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_utf","title":"mcproto.protocol.base_io.BaseSyncReader.read_utf","text":"<pre><code>read_utf() -&gt; str\n</code></pre> <p>Read a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be read + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>IOError</code> <ul> <li>If the prefix varint is bigger than the maximum (131068) bytes, the string will not be read at all, and :exc:<code>IOError</code> will be raised immediately. * If the received string has more than the maximum amount of characters (32767). Note that in this case, the string will still get read in it's entirety, since it fits into the maximum bytes limit (131068), which was simply read at once. This limitation is here only to replicate the behavior of minecraft's implementation.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_value","title":"mcproto.protocol.base_io.BaseSyncReader.read_value","text":"<pre><code>read_value(fmt: INT_FORMATS_TYPE) -&gt; int\n</code></pre><pre><code>read_value(fmt: FLOAT_FORMATS_TYPE) -&gt; float\n</code></pre><pre><code>read_value(fmt: Literal[BOOL]) -&gt; bool\n</code></pre><pre><code>read_value(fmt: Literal[CHAR]) -&gt; str\n</code></pre> <pre><code>read_value(fmt: StructFormat) -&gt; object\n</code></pre> <p>Read a value into given struct format in big-endian mode.</p> <p>The amount of bytes to read will be determined based on the struct format automatically.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_varint","title":"mcproto.protocol.base_io.BaseSyncReader.read_varint","text":"<pre><code>read_varint() -&gt; int\n</code></pre> <p>Read a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncReader.read_varlong","title":"mcproto.protocol.base_io.BaseSyncReader.read_varlong","text":"<pre><code>read_varlong() -&gt; int\n</code></pre> <p>Read a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._read_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter","title":"mcproto.protocol.base_io.BaseSyncWriter","text":"<p>               Bases: <code>ABC</code></p> <p>Base class holding synchronous write buffer/connection interactions.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write","title":"mcproto.protocol.base_io.BaseSyncWriter.write  <code>abstractmethod</code>","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Underlying write method, sending/storing the data.</p> <p>All of the writer functions will eventually call this method.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_ascii","title":"mcproto.protocol.base_io.BaseSyncWriter.write_ascii","text":"<pre><code>write_ascii(value: str) -&gt; None\n</code></pre> <p>Write ISO-8859-1 encoded string, with NULL (0x00) at the end to indicate string end.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_bytearray","title":"mcproto.protocol.base_io.BaseSyncWriter.write_bytearray","text":"<pre><code>write_bytearray(data: bytes) -&gt; None\n</code></pre> <p>Write an arbitrary sequence of bytes, prefixed with a varint of it's size.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_optional","title":"mcproto.protocol.base_io.BaseSyncWriter.write_optional","text":"<pre><code>write_optional(value: T | None, /, writer: Callable[[T], R]) -&gt; R | None\n</code></pre> <p>Write a bool showing if a <code>value</code> is present, if so, also writes this value with <code>writer</code> function.</p> <ul> <li>When <code>value</code> is <code>None</code>, a bool of <code>False</code> will be written, and <code>None</code> is returned.</li> <li>When <code>value</code> is not <code>None</code>, a bool of <code>True</code> is written, after which the <code>writer</code> function is called,   and the return value is forwarded.</li> </ul>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_utf","title":"mcproto.protocol.base_io.BaseSyncWriter.write_utf","text":"<pre><code>write_utf(value: str) -&gt; None\n</code></pre> <p>Write a UTF-8 encoded string, prefixed with a varint of it's size (in bytes).</p> <p>The maximum amount of UTF-8 characters is limited to 32767.</p> <p>Individual UTF-8 characters can take up to 4 bytes, however most of the common ones take up less. Assuming the worst case of 4 bytes per every character, at most 131068 data bytes will be written + 3 additional bytes from the varint encoding overhead.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the given string <code>value</code> has more characters than the allowed maximum (32767).</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_value","title":"mcproto.protocol.base_io.BaseSyncWriter.write_value","text":"<pre><code>write_value(fmt: INT_FORMATS_TYPE, value: int) -&gt; None\n</code></pre><pre><code>write_value(fmt: FLOAT_FORMATS_TYPE, value: float) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[BOOL], value: bool) -&gt; None\n</code></pre><pre><code>write_value(fmt: Literal[CHAR], value: str) -&gt; None\n</code></pre> <pre><code>write_value(fmt: StructFormat, value: object) -&gt; None\n</code></pre> <p>Write a given <code>value</code> as given struct format (<code>fmt</code>) in big-endian mode.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_varint","title":"mcproto.protocol.base_io.BaseSyncWriter.write_varint","text":"<pre><code>write_varint(value: int) -&gt; None\n</code></pre> <p>Write a 32-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code>.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.BaseSyncWriter.write_varlong","title":"mcproto.protocol.base_io.BaseSyncWriter.write_varlong","text":"<pre><code>write_varlong(value: int) -&gt; None\n</code></pre> <p>Write a 64-bit signed integer in a variable length format.</p> <p>For more information about variable length format check :meth:<code>._write_varuint</code> docstring.</p>"},{"location":"reference/public/protocol/#mcproto.protocol.base_io.StructFormat","title":"mcproto.protocol.base_io.StructFormat","text":"<p>               Bases: <code>str</code>, <code>Enum</code></p> <p>All possible write/read struct types.</p> <p>.. seealso:     :module:<code>struct</code> module documentation.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.remaining","title":"mcproto.buffer.Buffer.remaining  <code>property</code>","text":"<pre><code>remaining: int\n</code></pre> <p>Get the amount of bytes that's still remaining in the buffer to be read.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.clear","title":"mcproto.buffer.Buffer.clear","text":"<pre><code>clear(only_already_read: bool = False) -&gt; None\n</code></pre> <p>Clear out the stored data and reset position.</p> <p>Parameters:</p> Name Type Description Default <code>bool</code> <p>When set to <code>True</code>, only the data that was already marked as read will be cleared, and the position will be reset (to start at the remaining data). This can be useful for avoiding needlessly storing large amounts of data in memory, if this data is no longer useful.  Otherwise, if set to <code>False</code>, all of the data is cleared, and the position is reset, essentially resulting in a blank buffer.</p> <code>False</code>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.clear(only_already_read)","title":"<code>only_already_read</code>","text":""},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.flush","title":"mcproto.buffer.Buffer.flush","text":"<pre><code>flush() -&gt; bytearray\n</code></pre> <p>Read all of the remaining data in the buffer and clear it out.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.read","title":"mcproto.buffer.Buffer.read","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Read data stored in the buffer.</p> <p>Reading data doesn't remove that data, rather that data is treated as already read, and next read will start from the first unread byte. If freeing the data is necessary, check the :meth:<code>.clear</code> function.</p> <p>Parameters:</p> Name Type Description Default <code>int</code> <p>Amount of bytes to be read.  If the requested amount can't be read (buffer doesn't contain that much data/buffer doesn't contain any data), an :exc:<code>IOError</code> will be reaised.  If there were some data in the buffer, but it was less than requested, this remaining data will still be depleted and the partial data that was read will be a part of the error message in the :exc:<code>IOError</code>. This behavior is here to mimic reading from a real socket connection.</p> required"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.read(length)","title":"<code>length</code>","text":""},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.reset","title":"mcproto.buffer.Buffer.reset","text":"<pre><code>reset() -&gt; None\n</code></pre> <p>Reset the position in the buffer.</p> <p>Since the buffer doesn't automatically clear the already read data, it is possible to simply reset the position and read the data it contains again.</p>"},{"location":"reference/public/protocol/#mcproto.buffer.Buffer.write","title":"mcproto.buffer.Buffer.write","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Write/Store given <code>data</code> into the buffer.</p>"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection","title":"mcproto.connection.AsyncConnection","text":"<p>               Bases: <code>BaseAsyncReader</code>, <code>BaseAsyncWriter</code>, <code>ABC</code></p> <p>Base class for all classes handling asynchronous connections.</p>"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.close","title":"mcproto.connection.AsyncConnection.close  <code>async</code>","text":"<pre><code>close() -&gt; None\n</code></pre> <p>Close the connection (it cannot be used after this).</p>"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.enable_encryption","title":"mcproto.connection.AsyncConnection.enable_encryption","text":"<pre><code>enable_encryption(shared_secret: bytes) -&gt; None\n</code></pre> <p>Enable encryption for this connection, using the <code>shared_secret</code>.</p> <p>After calling this method, the reading and writing process for this connection will be altered, and any future communication will be encrypted/decrypted there.</p> <p>You will need to call this method after sending the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet.</p> <p>Parameters:</p> Name Type Description Default <code>bytes</code> <p>This is the cipher key for the AES symetric cipher used for the encryption.  See :func:<code>mcproto.encryption.generate_shared_secret</code>.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.enable_encryption(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.make_client","title":"mcproto.connection.AsyncConnection.make_client  <code>abstractmethod</code> <code>async</code> <code>classmethod</code>","text":"<pre><code>make_client(address: tuple[str, int], timeout: float) -&gt; Self\n</code></pre> <p>Construct a client connection (Client -&gt; Server) to given server <code>address</code>.</p> <p>Parameters:</p> Name Type Description Default <code>tuple[str, int]</code> <p>Address of the server to connection to.</p> required <code>float</code> <p>Amount of seconds to wait for the connection to be established. If connection can't be established within this time, :exc:<code>TimeoutError</code> will be raised. This timeout is then also used for any further data receiving.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.make_client(address)","title":"<code>address</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.make_client(timeout)","title":"<code>timeout</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.read","title":"mcproto.connection.AsyncConnection.read  <code>async</code>","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Receive data sent through the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform a decryption of the received data.</p> <p>Parameters:</p> Name Type Description Default <code>int</code> <p>Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an :exc:<code>IOError</code> will be raised.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.read(length)","title":"<code>length</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.AsyncConnection.write","title":"mcproto.connection.AsyncConnection.write  <code>async</code>","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Send given <code>data</code> over the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform an encryption of the input data.</p>"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection","title":"mcproto.connection.SyncConnection","text":"<p>               Bases: <code>BaseSyncReader</code>, <code>BaseSyncWriter</code>, <code>ABC</code></p> <p>Base class for all classes handling synchronous connections.</p>"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.close","title":"mcproto.connection.SyncConnection.close","text":"<pre><code>close() -&gt; None\n</code></pre> <p>Close the connection (it cannot be used after this).</p>"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.enable_encryption","title":"mcproto.connection.SyncConnection.enable_encryption","text":"<pre><code>enable_encryption(shared_secret: bytes) -&gt; None\n</code></pre> <p>Enable encryption for this connection, using the <code>shared_secret</code>.</p> <p>After calling this method, the reading and writing process for this connection will be altered, and any future communication will be encrypted/decrypted there.</p> <p>You will need to call this method after sending the :class:<code>~mcproto.packets.login.login.LoginEncryptionResponse</code> packet.</p> <p>Parameters:</p> Name Type Description Default <code>bytes</code> <p>This is the cipher key for the AES symetric cipher used for the encryption.  See :func:<code>mcproto.encryption.generate_shared_secret</code>.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.enable_encryption(shared_secret)","title":"<code>shared_secret</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.make_client","title":"mcproto.connection.SyncConnection.make_client  <code>abstractmethod</code> <code>classmethod</code>","text":"<pre><code>make_client(address: tuple[str, int], timeout: float) -&gt; Self\n</code></pre> <p>Construct a client connection (Client -&gt; Server) to given server <code>address</code>.</p> <p>Parameters:</p> Name Type Description Default <code>tuple[str, int]</code> <p>Address of the server to connection to.</p> required <code>float</code> <p>Amount of seconds to wait for the connection to be established. If connection can't be established within this time, :exc:<code>TimeoutError</code> will be raised. This timeout is then also used for any further data receiving.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.make_client(address)","title":"<code>address</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.make_client(timeout)","title":"<code>timeout</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.read","title":"mcproto.connection.SyncConnection.read","text":"<pre><code>read(length: int) -&gt; bytearray\n</code></pre> <p>Receive data sent through the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform a decryption of the received data.</p> <p>Parameters:</p> Name Type Description Default <code>int</code> <p>Amount of bytes to be received. If the requested amount can't be received (server didn't send that much data/server didn't send any data), an :exc:<code>IOError</code> will be raised.</p> required"},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.read(length)","title":"<code>length</code>","text":""},{"location":"reference/public/protocol/#mcproto.connection.SyncConnection.write","title":"mcproto.connection.SyncConnection.write","text":"<pre><code>write(data: bytes) -&gt; None\n</code></pre> <p>Send given <code>data</code> over the connection.</p> <p>Depending on :attr:<code>encryption_enabled</code> flag (set from :meth:<code>enable_encryption</code>), this might also perform an encryption of the input data.</p>"},{"location":"reference/public/protocol/#mcproto.connection.TCPAsyncConnection","title":"mcproto.connection.TCPAsyncConnection","text":"<p>               Bases: <code>AsyncConnection</code>, <code>Generic[T_STREAMREADER, T_STREAMWRITER]</code></p> <p>Asynchronous TCP connection using :class:<code>~asyncio.StreamWriter</code> and :class:<code>~asyncio.StreamReader</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.TCPAsyncConnection.socket","title":"mcproto.connection.TCPAsyncConnection.socket  <code>property</code>","text":"<pre><code>socket: socket\n</code></pre> <p>Obtain the underlying socket behind the :class:<code>~asyncio.Transport</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.TCPSyncConnection","title":"mcproto.connection.TCPSyncConnection","text":"<p>               Bases: <code>SyncConnection</code>, <code>Generic[T_SOCK]</code></p> <p>Synchronous connection using a TCP :class:<code>~socket.socket</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.UDPAsyncConnection","title":"mcproto.connection.UDPAsyncConnection","text":"<p>               Bases: <code>AsyncConnection</code>, <code>Generic[T_DATAGRAM_CLIENT]</code></p> <p>Asynchronous UDP connection using :class:<code>~asyncio_dgram.DatagramClient</code>.</p>"},{"location":"reference/public/protocol/#mcproto.connection.UDPSyncConnection","title":"mcproto.connection.UDPSyncConnection","text":"<p>               Bases: <code>SyncConnection</code>, <code>Generic[T_SOCK]</code></p> <p>Synchronous connection using a UDP :class:<code>~socket.socket</code>.</p>"},{"location":"reference/public/types/","title":"Types","text":""},{"location":"reference/public/types/#mcproto.types.abc","title":"mcproto.types.abc","text":""},{"location":"reference/public/types/#mcproto.types.abc.MCType","title":"mcproto.types.abc.MCType","text":"<p>               Bases: <code>Serializable</code></p> <p>Base class for a minecraft type structure.</p>"},{"location":"reference/public/types/#mcproto.types.chat","title":"mcproto.types.chat","text":""},{"location":"reference/public/types/#mcproto.types.chat.ChatMessage","title":"mcproto.types.chat.ChatMessage","text":"<p>               Bases: <code>MCType</code></p> <p>Minecraft chat message representation.</p>"},{"location":"reference/public/types/#mcproto.types.chat.ChatMessage.__eq__","title":"mcproto.types.chat.ChatMessage.__eq__","text":"<pre><code>__eq__(other: object) -&gt; bool\n</code></pre> <p>Check equality between two chat messages.</p> <p>..warning: This is purely using the <code>raw</code> field, which means it's possible that a chat message that appears the same, but was representing in a different way will fail this equality check.</p>"},{"location":"reference/public/types/#mcproto.types.chat.ChatMessage.as_dict","title":"mcproto.types.chat.ChatMessage.as_dict","text":"<pre><code>as_dict() -&gt; RawChatMessageDict\n</code></pre> <p>Convert received <code>raw</code> into a stadard :class:<code>dict</code> form.</p>"},{"location":"reference/public/types/#mcproto.types.chat.RawChatMessageDict","title":"mcproto.types.chat.RawChatMessageDict","text":"<p>               Bases: <code>TypedDict</code></p> <p>Dictionary structure of JSON chat messages when serialized.</p>"},{"location":"reference/public/types/#mcproto.types.nbt","title":"mcproto.types.nbt","text":""},{"location":"reference/public/types/#mcproto.types.nbt.FromObjectSchema","title":"mcproto.types.nbt.FromObjectSchema  <code>module-attribute</code>","text":"<pre><code>FromObjectSchema: TypeAlias = Union['type[NBTag]', 'type[NBTagConvertible]', 'Sequence[FromObjectSchema]', 'Mapping[str, FromObjectSchema]']\n</code></pre> <p>Represents the type of a schema, used to define how an object should be converted to an NBT tag(s).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.FromObjectType","title":"mcproto.types.nbt.FromObjectType  <code>module-attribute</code>","text":"<pre><code>FromObjectType: TypeAlias = Union[int, float, bytes, str, 'NBTagConvertible', 'Sequence[FromObjectType]', 'Mapping[str, FromObjectType]']\n</code></pre> <p>Represents any object holding some data that can be converted to an NBT tag(s).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.PayloadType","title":"mcproto.types.nbt.PayloadType  <code>module-attribute</code>","text":"<pre><code>PayloadType: TypeAlias = Union[int, float, bytes, str, 'NBTag', 'Sequence[PayloadType]', 'Mapping[str, PayloadType]']\n</code></pre> <p>Represents the type of a payload that can be stored in an NBT tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.__all__","title":"mcproto.types.nbt.__all__  <code>module-attribute</code>","text":"<pre><code>__all__ = ['ByteArrayNBT', 'ByteNBT', 'CompoundNBT', 'DoubleNBT', 'EndNBT', 'FloatNBT', 'IntArrayNBT', 'IntNBT', 'ListNBT', 'LongArrayNBT', 'LongNBT', 'NBTag', 'NBTagConvertible', 'NBTagType', 'ShortNBT', 'StringNBT']\n</code></pre> <p>Implementation of the NBT (Named Binary Tag) format used in Minecraft as described in the NBT specification</p> <p>Source : <code>Minecraft NBT Spec &lt;https://web.archive.org/web/20110723210920/http://www.minecraft.net/docs/NBT.txt&gt;</code>_</p> <p>Named Binary Tag specification</p> <p>NBT (Named Binary Tag) is a tag based binary format designed to carry large amounts of binary data with smaller amounts of additional data. An NBT file consists of a single GZIPped Named Tag of type TAG_Compound.</p> <p>A Named Tag has the following format:</p> <pre><code>byte tagType\nTAG_String name\n[payload]\n</code></pre> <ul> <li>The tagType is a single byte defining the contents of the payload of the tag.</li> <li>The name is a descriptive name, and can be anything (eg \"cat\", \"banana\", \"Hello World!\").   The purpose for this name is to name tags so parsing is easier and can be made to only look for certain recognized   tag names. Exception: If tagType is TAG_End, the name is skipped and assumed to be \"\".</li> <li>The [payload] varies by tagType.</li> </ul> <p>Note that ONLY Named Tags carry the name and tagType data. Explicitly identified Tags (such as TAG_String) only contains the payload.</p> <p>.. seealso:: :class:<code>NBTagType</code></p>"},{"location":"reference/public/types/#mcproto.types.nbt.ByteArrayNBT","title":"mcproto.types.nbt.ByteArrayNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing an array of bytes. The length of the array is stored as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ByteArrayNBT.__bytes__","title":"mcproto.types.nbt.ByteArrayNBT.__bytes__","text":"<pre><code>__bytes__() -&gt; bytes\n</code></pre> <p>Get the bytes value of the ByteArrayNBT tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ByteNBT","title":"mcproto.types.nbt.ByteNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing a single byte value, represented as a signed 8-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT","title":"mcproto.types.nbt.CompoundNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing a compound of named tags.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT.__eq__","title":"mcproto.types.nbt.CompoundNBT.__eq__","text":"<pre><code>__eq__(other: object) -&gt; bool\n</code></pre> <p>Check equality between two CompoundNBT tags.</p> <p>Parameters:</p> Name Type Description Default <code>object</code> <p>The other CompoundNBT tag to compare to.</p> required <p>Returns:</p> Type Description <code>bool</code> <p>True if the tags are equal, False otherwise.  .. note:: The order of the tags is not guaranteed, but the names of the tags must match. This function assumes that there are no duplicate tags in the compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT.__eq__(other)","title":"<code>other</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.CompoundNBT.__iter__","title":"mcproto.types.nbt.CompoundNBT.__iter__","text":"<pre><code>__iter__()\n</code></pre> <p>Iterate over the tags in the compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.DoubleNBT","title":"mcproto.types.nbt.DoubleNBT","text":"<p>               Bases: <code>_FloatingNBTag</code></p> <p>NBT tag representing a double-precision floating-point value, represented as a 64-bit IEEE 754-2008 binary64.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.EndNBT","title":"mcproto.types.nbt.EndNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>Sentinel tag used to mark the end of a TAG_Compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.FloatNBT","title":"mcproto.types.nbt.FloatNBT","text":"<p>               Bases: <code>_FloatingNBTag</code></p> <p>NBT tag representing a floating-point value, represented as a 32-bit IEEE 754-2008 binary32 value.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.IntArrayNBT","title":"mcproto.types.nbt.IntArrayNBT","text":"<p>               Bases: <code>_NumberArrayNBTag</code></p> <p>NBT tag representing an array of integers. The length of the array is stored as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.IntNBT","title":"mcproto.types.nbt.IntNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing an integer value, represented as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ListNBT","title":"mcproto.types.nbt.ListNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing a list of tags. All tags in the list must be of the same type.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.ListNBT.__iter__","title":"mcproto.types.nbt.ListNBT.__iter__","text":"<pre><code>__iter__() -&gt; Iterator[NBTag]\n</code></pre> <p>Iterate over the tags in the list.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.LongArrayNBT","title":"mcproto.types.nbt.LongArrayNBT","text":"<p>               Bases: <code>_NumberArrayNBTag</code></p> <p>NBT tag representing an array of longs. The length of the array is stored as a signed 32-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.LongNBT","title":"mcproto.types.nbt.LongNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing a long value, represented as a signed 64-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag","title":"mcproto.types.nbt.NBTag","text":"<p>               Bases: <code>MCType</code>, <code>NBTagConvertible</code></p> <p>Base class for NBT tags.</p> <p>In MC v1.20.2+ the type and name of the root tag is not written to the buffer, and unless specified, the type of the tag is assumed to be TAG_Compound.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.value","title":"mcproto.types.nbt.NBTag.value  <code>abstractmethod</code> <code>property</code>","text":"<pre><code>value: PayloadType\n</code></pre> <p>Get the payload of the NBT tag in a python-friendly format.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize","title":"mcproto.types.nbt.NBTag.deserialize  <code>classmethod</code>","text":"<pre><code>deserialize(buf: Buffer, with_name: bool = True, with_type: bool = True) -&gt; NBTag\n</code></pre> <p>Deserialize the NBT tag.</p> <p>Parameters:</p> Name Type Description Default <code>Buffer</code> <p>The buffer to read from.</p> required <code>bool</code> <p>Whether to read the name of the tag. (Passed to :meth:<code>_read_header</code>)</p> <code>True</code> <code>bool</code> <p>Whether to read the type of the tag. (Passed to :meth:<code>_read_header</code>)</p> <code>True</code> <p>Returns:</p> Type Description <code>NBTag</code> <p>The deserialized NBT tag.  This tag will be an instance of the class, that is associated with the tag type obtained from :meth:<code>_read_header</code> (see: :const:<code>ASSOCIATED_TYPES</code>).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize(buf)","title":"<code>buf</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.deserialize(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object","title":"mcproto.types.nbt.NBTag.from_object  <code>staticmethod</code>","text":"<pre><code>from_object(data: FromObjectType, schema: FromObjectSchema, name: str = '') -&gt; NBTag\n</code></pre> <p>Create an NBT tag from a python object and a schema.</p> <p>Parameters:</p> Name Type Description Default <code>FromObjectType</code> <p>The python object to create the NBT tag from.</p> required <code>FromObjectSchema</code> <p>The schema used to create the NBT tags.  This is a description of the types of the <code>data</code> in the python object. It can be a subclass of :class:<code>NBTag</code> (e.g. :class:<code>IntNBT</code>, :class:<code>StringNBT</code>, :class:<code>CompoundNBT</code>, etc.), a :class:<code>dict</code>, a :class:<code>list</code>, a :class:<code>tuple</code>, or a class that has a <code>to_nbt</code> method.  Example of schema:  .. code-block:: python  schema = { \"string\": StringNBT, \"list_of_floats\": [FloatNBT], \"list_of_compounds\": [{ \"key\": StringNBT, \"value\": IntNBT, }], \"list_of_lists\": [[IntNBT], [StringNBT]], }  This would be translated into a :class:<code>CompoundNBT</code>.</p> required <code>str</code> <p>The name of the NBT tag.</p> <code>''</code> <p>Returns:</p> Type Description <code>NBTag</code> <p>The NBT tag created from the python object.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object(data)","title":"<code>data</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object(schema)","title":"<code>schema</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.from_object(name)","title":"<code>name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.read_from","title":"mcproto.types.nbt.NBTag.read_from  <code>abstractmethod</code> <code>classmethod</code>","text":"<pre><code>read_from(buf: Buffer, with_type: bool = True, with_name: bool = True) -&gt; NBTag\n</code></pre> <p>Read the NBT tag from the buffer.</p> <p>Implementation shortcut used in :meth:<code>deserialize</code>. (Subclasses can override this, avoiding some repetition when compared to overriding <code>deserialize</code> directly.)</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize","title":"mcproto.types.nbt.NBTag.serialize","text":"<pre><code>serialize(with_type: bool = True, with_name: bool = True) -&gt; Buffer\n</code></pre> <p>Serialize the NBT tag to a new buffer.</p> <p>Parameters:</p> Name Type Description Default <code>bool</code> <p>Whether to include the type of the tag in the serialization. (Passed to :meth:<code>_write_header</code>)</p> <code>True</code> <code>bool</code> <p>Whether to include the name of the tag in the serialization. (Passed to :meth:<code>_write_header</code>)</p> <code>True</code> <p>Returns:</p> Type Description <code>Buffer</code> <p>The buffer containing the serialized NBT tag.  .. note:: The <code>with_type</code> and <code>with_name</code> parameters only control the first level of serialization.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to","title":"mcproto.types.nbt.NBTag.serialize_to  <code>abstractmethod</code>","text":"<pre><code>serialize_to(buf: Buffer, with_type: bool = True, with_name: bool = True) -&gt; None\n</code></pre> <p>Serialize the NBT tag to a buffer.</p> <p>Parameters:</p> Name Type Description Default <code>Buffer</code> <p>The buffer to write to.</p> required <code>bool</code> <p>Whether to include the type of the tag in the serialization.</p> <code>True</code> <code>bool</code> <p>Whether to include the name of the tag in the serialization.  .. seealso:: :meth:<code>serialize</code></p> <code>True</code>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to(buf)","title":"<code>buf</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to(with_type)","title":"<code>with_type</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.serialize_to(with_name)","title":"<code>with_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_nbt","title":"mcproto.types.nbt.NBTag.to_nbt","text":"<pre><code>to_nbt(name: str = '') -&gt; NBTag\n</code></pre> <p>Convert the object to an NBT tag.</p> <p>.. warning:: This is already an NBT tag, so it will modify the name of the tag and return itself.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_object","title":"mcproto.types.nbt.NBTag.to_object","text":"<pre><code>to_object(include_schema: bool = False, include_name: bool = False) -&gt; PayloadType | Mapping[str, PayloadType] | tuple[PayloadType | Mapping[str, PayloadType], FromObjectSchema]\n</code></pre> <p>Convert the NBT tag to a python object.</p> <p>Parameters:</p> Name Type Description Default <code>bool</code> <p>Whether to return a schema describing the types of the original tag.</p> <code>False</code> <code>bool</code> <p>Whether to include the name of the tag in the output. If the tag has no name, the name will be set to \"\".</p> <code>False</code> <p>Returns:</p> Type Description <code>PayloadType | Mapping[str, PayloadType] | tuple[PayloadType | Mapping[str, PayloadType], FromObjectSchema]</code> <p>Either of: * A python object representing the payload of the tag. (default) * A dictionary containing the name associated with a python object representing the payload of the tag. * A tuple which includes one of the above and a schema describing the types of the original tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_object(include_schema)","title":"<code>include_schema</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTag.to_object(include_name)","title":"<code>include_name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTagConvertible","title":"mcproto.types.nbt.NBTagConvertible","text":"<p>               Bases: <code>Protocol</code></p> <p>Protocol for objects that can be converted to an NBT tag.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagConvertible.to_nbt","title":"mcproto.types.nbt.NBTagConvertible.to_nbt","text":"<pre><code>to_nbt(name: str = '') -&gt; NBTag\n</code></pre> <p>Convert the object to an NBT tag.</p> <p>Parameters:</p> Name Type Description Default <code>str</code> <p>The name of the tag.</p> <code>''</code> <p>Returns:</p> Type Description <code>NBTag</code> <p>The NBT tag created from the object.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagConvertible.to_nbt(name)","title":"<code>name</code>","text":""},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType","title":"mcproto.types.nbt.NBTagType","text":"<p>               Bases: <code>IntEnum</code></p> <p>Enumeration of the different types of NBT tags.</p> <p>See the documentation of the individual variants for more information.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.BYTE","title":"mcproto.types.nbt.NBTagType.BYTE  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>BYTE = 1\n</code></pre> <p>A single signed byte (8 bits).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.BYTE_ARRAY","title":"mcproto.types.nbt.NBTagType.BYTE_ARRAY  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>BYTE_ARRAY = 7\n</code></pre> <p>The payload is a TAG_Int representing the length, followed by an array of  bytes."},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.COMPOUND","title":"mcproto.types.nbt.NBTagType.COMPOUND  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>COMPOUND = 10\n</code></pre> <p>A sequential list of Named Tags. This array keeps going until a TAG_End is found.</p> <ul> <li>If there's a nested TAG_Compound within this tag, that one will also have a TAG_End,   so simply reading until the next TAG_End will not work.</li> <li>The names of the named tags have to be unique within each TAG_Compound.</li> <li>The order of the tags is not guaranteed.</li> </ul>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.DOUBLE","title":"mcproto.types.nbt.NBTagType.DOUBLE  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>DOUBLE = 6\n</code></pre> <p>A floating point value (64 bits, big endian, IEEE 754-2008, binary64).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.END","title":"mcproto.types.nbt.NBTagType.END  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>END = 0\n</code></pre> <p>This tag is used to mark the end of a list. It doesn't carry any payload, and it cannot be named!</p> <p>If this type appears where a Named Tag is expected, the name is assumed to be <code>\"\"</code>. (In other words, this Tag is always just a single <code>0x00</code> byte when named, and nothing in all other cases)</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.FLOAT","title":"mcproto.types.nbt.NBTagType.FLOAT  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>FLOAT = 5\n</code></pre> <p>A floating point value (32 bits, big endian, IEEE 754-2008, binary32).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.INT","title":"mcproto.types.nbt.NBTagType.INT  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>INT = 3\n</code></pre> <p>A signed integer (32 bits, big endian).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.INT_ARRAY","title":"mcproto.types.nbt.NBTagType.INT_ARRAY  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>INT_ARRAY = 11\n</code></pre> <p>The payload is a TAG_Int representing the length, followed by an array of  TAG_Int elements."},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.LIST","title":"mcproto.types.nbt.NBTagType.LIST  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>LIST = 9\n</code></pre> <p>The payload is a TAG_Byte representing the type of the items in the list, followed by a TAG_Int representing the length of the list, followed by an array of  NBTags. <p>All the tags in the list must be of the same type.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.LONG","title":"mcproto.types.nbt.NBTagType.LONG  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>LONG = 4\n</code></pre> <p>A signed long (64 bits, big endian).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.LONG_ARRAY","title":"mcproto.types.nbt.NBTagType.LONG_ARRAY  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>LONG_ARRAY = 12\n</code></pre> <p>The payload is a TAG_Int representing the length, followed by an array of  TAG_Long elements."},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.SHORT","title":"mcproto.types.nbt.NBTagType.SHORT  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>SHORT = 2\n</code></pre> <p>A signed short (16 bits, big endian).</p>"},{"location":"reference/public/types/#mcproto.types.nbt.NBTagType.STRING","title":"mcproto.types.nbt.NBTagType.STRING  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>STRING = 8\n</code></pre> <p>The payload is a TAG_Short representing the length, followed by an array of  bytes, holding a string in UTF-8 format."},{"location":"reference/public/types/#mcproto.types.nbt.ShortNBT","title":"mcproto.types.nbt.ShortNBT","text":"<p>               Bases: <code>_NumberNBTag</code></p> <p>NBT tag representing a short value, represented as a signed 16-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.nbt.StringNBT","title":"mcproto.types.nbt.StringNBT","text":"<p>               Bases: <code>NBTag</code></p> <p>NBT tag representing an UTF-8 string value. The length of the string is stored as a signed 16-bit integer.</p>"},{"location":"reference/public/types/#mcproto.types.uuid","title":"mcproto.types.uuid","text":""},{"location":"reference/public/types/#mcproto.types.uuid.UUID","title":"mcproto.types.uuid.UUID","text":"<p>               Bases: <code>UUID</code>, <code>MCType</code></p> <p>Minecraft UUID type.</p> <p>In order to support potential future changes in protocol version, and implement McType, this is a custom subclass, however it is currently compatible with the stdlib's <code>uuid.UUID</code>.</p>"},{"location":"usage/","title":"Usage","text":"<p>This part of the documentation contains various guides and explanations on how to use the different parts of mcproto.</p> <p>Work In Progress</p> <p>This category is still being written. Many pages are missing.</p> <p>Didn't find what you were looking for?</p> <p>If you were looking for a guide on something, but you didn't find it documented here and you feel like it's something that others would benefit from seeing too, you can create a github issue and ask us to write one.</p>"},{"location":"usage/authentication/","title":"Minecraft account authentication","text":"<p>Mcproto has first party support to handle authentication, allowing you to use your own minecraft account. This is needed if you wish to login to \"online mode\" (non-warez) servers as a client (player).</p>"},{"location":"usage/authentication/#microsoft-migrated-accounts","title":"Microsoft (migrated) accounts","text":"<p>This is how authentication works for already migrated minecraft accounts, using Microsoft accounts for authentication. (This will be most accounts. Any newly created minecraft accounts - after 2021 will always be Microsoft linked accounts.)</p>"},{"location":"usage/authentication/#creating-azure-application","title":"Creating Azure application","text":"<p>To authenticate with a microsoft account, you will need to go through the entire OAuth2 flow. Mcproto has functions to hide pretty much all of this away, however you will need to create a new Microsoft Azure application, that mcproto will use to obtain an access token.</p> <p>We know this is annoying, but it's a necessary step, as Microsoft only allows these applications to request OAuth2 authentication, and to avoid potential abuse, we can't really just use our registered application (like with say MultiMC), as this token would have to be embedded into our source-code, and since this is python, that would mean just including it here in plain text, and because mcproto is a low level library that can be used for any kind of interactions, we can't trust that you won't abuse this token.</p> <p>Instead, everyone using mcproto should register a new application, and get their own MSA token for your application that uses mcproto in the back.</p> <p>To create a new application, follow these steps (this is a simplified guide, for a full guide, feel free to check the Microsoft documentation):</p> <ol> <li>Go to the Azure portal and log in (create an account if you need to).</li> <li>Search for and select Azure Active Directory.</li> <li>On the left navbar, under Manage section, click on App registrations.</li> <li>Click on New registration on top navbar.</li> <li>Pick a name for the application. Anyone using your app to authenticate will see this name.</li> <li>Choose Personal Microsoft accounts only from the Supported account types.</li> <li>Leave the Redirect URI (optional) empty.</li> <li>Click on Register.</li> </ol> <p>From there, you will need to enable this application to be used for OAuth2 flows. To do that, follow these steps:</p> <ol> <li>On the left navbar, under Manage section, click on Authentication.</li> <li>Set Allow public content flows to Yes.</li> <li>Click Save.</li> </ol> <p>After that, you can go back to the app (click Overview from the left navbar), and you'll want to copy the Application (client) ID. This is the ID you will need to pass to mcproto. (You will also need the Display name, and the Directory (Tenant) ID for [Registering the application with Minecraft] - first time only)</p> <p>If you ever need to access this application again, follow these steps (as Microsoft Azure is pretty unintuitive, we document this too):</p> <ol> <li>Go to the Azure portal and log in.</li> <li>Click on Azure Active Directory (if you can't find it on the main page, you can use the search).</li> <li>On the left navbar, under Manage section, click on App registrations.</li> <li>Click on View all applications from personal account (assuming you registered the app from a personal account).</li> <li>Click on your app.</li> </ol>"},{"location":"usage/authentication/#registering-the-application-with-minecraft","title":"Registering the application with Minecraft","text":"<p>Previously, this step wasn't required, however due to people maliciously creating these applications to steal accounts, Mojang have recently started to limit access to the https://api.minecraftservices.com, and only allow explicitly white listed Client IDs to use this API.</p> <p>This API is absolutely crucial step in getting the final minecraft token, and so you will need to register your Client ID to be white listed by Mojang. Thankfully, it looks like Mojang is generally pretty lenient and at least for me, they didn't cause any unnecessary hassles when I asked for my application to be registered, for development purposes and work on mcproto.</p> <p>That said, you will need to wait a while (about a week, though it could be more), until Mojang reviews your application and approves it. There isn't much we can do about this.</p> <p>To get your Azure application registered, you will need to fill out a simple form, where you accept the EULA, provide your E-Mail, Application name, Application Client ID and Tennant ID.</p> <p>More annoyingly you will additionally also need to provide an associated website or domain for your project/brand. (This application is generally designed for more user-facing programs, such as full launchers. When registering mcproto, I just used the GitHub URL). Lastly, you'll want to describe why you need access to this API in the Justification section.</p> <p>Visit the Mojang article describing this process. There is also a link to the form to fill out.</p>"},{"location":"usage/authentication/#the-code","title":"The code","text":"<p>Finally, after you've managed to register your application and get it approved by Mojang, you can use it with mcproto, go through the Microsoft OAuth2 flow and authorize this application to access your Microsoft account, which mcproto will then use to get the minecraft token you'll then need to login to online servers.</p> <pre><code>import httpx\nfrom mcproto.auth.microsoft.oauth import full_microsoft_oauth\nfrom mcproto.auth.microsoft.xbox import xbox_auth\nfrom mcproto.auth.msa import MSAAccount\n\nMY_MSA_CLIENT_ID = \"[REDACTED]\"  # Paste your own Client ID here\n\nasync def authenticate() -&gt; MSAAccount:\n    async with httpx.AsyncClient() as client:\n        microsoft_token = await full_microsoft_oauth(client, MY_MSA_CLIENT_ID)\n        user_hash, xsts_token = xbox_auth(client, microsoft_token)\n        return MSAAccount.xbox_auth(cilent, user_hash, xsts_token)\n</code></pre> <p>Note that the <code>full_microsoft_oauth</code> function will print a message containing the URL you should visit in your browser, and a one time code to type in once you reach this URL. That will then prompt you to log in to your Microsoft account, and then allow you to authorize the application to use your account.</p>"},{"location":"usage/authentication/#caching","title":"Caching","text":"<p>You will very likely want to set up caching here, and store at least the <code>microsoft_token</code> somewhere, so you don't have to log in each time your code will run. Here's some example code that caches every step of the way, always resorting to the \"closest\" functional token. Note that this is using <code>pickle</code> to store the tokens, you may want to use JSON or other format instead, as it would be safer. Also, be aware that these are sensitive and if compromised, someone could gain access to your minecraft account (though only for playing, they shouldn't be able to change your password or anything like that), so you might want to consider encrypting these cache files before storing:</p> <pre><code>from __future__ import annotations\n\nimport logging\nimport pickle\nfrom pathlib import Path\n\nimport httpx\n\nfrom mcproto.auth.microsoft.oauth import full_microsoft_oauth\nfrom mcproto.auth.microsoft.xbox import XSTSRequestError, xbox_auth\nfrom mcproto.auth.msa import MSAAccount, ServicesAPIError\n\nlog = logging.getLogger(__name__)\n\nMY_MSA_CLIENT_ID = \"[REDACTED]\"  # Paste your own Client ID here\nCACHE_DIR = Path(\".cache/\")\n\n\nasync def microsoft_login(client: httpx.AsyncClient) -&gt; MSAAccount:  # noqa: PLR0912,PLR0915\n    \"\"\"Obtain minecraft account using Microsoft authentication.\n\n    This function performs full caching of every step along the way, allowing for recovery\n    without manual intervention for as long as at least the root token (from Microsoft OAuth2)\n    is valid. Any later tokens will be refreshed and re-cached once invalid.\n\n    If all tokens are invalid, or this function was ran for the first time (without any cached\n    data), you will be shown a URL and a code. You have to go to this URL with your browser and\n    enter the code, completing the OAuth2 flow, obtaining the root token.\n    \"\"\"\n    CACHE_DIR.mkdir(parents=True, exist_ok=True)\n\n    access_token_cache = CACHE_DIR.joinpath(\"xbox_access_token.pickle\")\n    if access_token_cache.exists():\n        with access_token_cache.open(\"rb\") as f:\n            access_token: str = pickle.load(f)  # noqa: S301\n\n        try:\n            account = await MSAAccount.from_xbox_access_token(client, access_token)\n            log.info(\"Logged in with cached xbox minecraft access token\")\n            return account\n        except httpx.HTTPStatusError as exc:\n            log.warning(f\"Cached xbox minecraft access token is invalid: {exc!r}\")\n    else:\n        log.warning(\"No cached access token available, trying Xbox Secure Token Service (XSTS) token\")\n\n    # Access token either doesn't exist, or isn't valid, try XSTS (Xbox) token\n    xbox_token_cache = CACHE_DIR.joinpath(\"xbox_xsts_token.pickle\")\n    if xbox_token_cache.exists():\n        with xbox_token_cache.open(\"rb\") as f:\n            user_hash, xsts_token = pickle.load(f)  # noqa: S301\n\n        try:\n            access_token = await MSAAccount._get_access_token_from_xbox(client, user_hash, xsts_token)\n        except ServicesAPIError as exc:\n            log.warning(f\"Invalid cached Xbox Secure Token Service (XSTS) token: {exc!r}\")\n        else:\n            log.info(\"Obtained xbox access token from cached Xbox Secure Token Service (XSTS) token\")\n            log.info(\"Storing xbox minecraft access token to cache and restarting auth\")\n            with access_token_cache.open(\"wb\") as f:\n                pickle.dump(access_token, f)\n            return await microsoft_login(client)\n    else:\n        log.warning(\"No cached Xbox Secure Token Service (XSTS) token available, trying Microsoft OAuth2 token\")\n\n    # XSTS token either doesn't exist, or isn't valid, try Microsoft OAuth2 token\n    microsoft_token_cache = CACHE_DIR.joinpath(\"microsoft_token.pickle\")\n    if microsoft_token_cache.exists():\n        with microsoft_token_cache.open(\"rb\") as f:\n            microsoft_token = pickle.load(f)  # noqa: S301\n\n        try:\n            user_hash, xsts_token = await xbox_auth(client, microsoft_token)\n        except (httpx.HTTPStatusError, XSTSRequestError) as exc:\n            log.warning(f\"Invalid cached Microsoft OAuth2 token {exc!r}\")\n        else:\n            log.info(\"Obtained Xbox Secure Token Service (XSTS) token from cached Microsoft OAuth2 token\")\n            log.info(\"Storing Xbox Secure Token Service (XSTS) token to cache and restarting auth\")\n            with xbox_token_cache.open(\"wb\") as f:\n                pickle.dump((user_hash, xsts_token), f)\n            return await microsoft_login(client)\n    else:\n        log.warning(\"No cached microsoft token\")\n\n    # Microsoft OAuth2 token either doesn't exist, or isn't valid, request user auth\n    log.info(\"Running Microsoft OAuth2 flow, requesting user authentication\")\n    microsoft_token = await full_microsoft_oauth(client, MY_MSA_CLIENT_ID)\n    log.info(\"Obtained Microsoft OAuth2 token from user authentication\")\n    log.info(\"Storing Microsoft OAuth2 token and restarting auth\")\n    with microsoft_token_cache.open(\"wb\") as f:\n        pickle.dump(microsoft_token[\"access_token\"], f)\n    return await microsoft_login(client)\n</code></pre>"},{"location":"usage/authentication/#minecraft-non-migrated-accounts","title":"Minecraft (non-migrated) accounts","text":"<p>If you haven't migrated your account into a Microsoft account, follow this guide for authentication. (Any newly created Minecraft accounts will be using Microsoft accounts already.) This method of authentication is called \"yggdrasil\".</p> <p>Warning</p> <p>The account migration process has been concluded in  September 19, 2023. See: https://www.minecraft.net/en-us/article/account-migration-last-call</p> <p>That means that it's no longer possible to migrate this old account into a microsoft account and it's only a matter of time until the authentication servers handling these accounts are turned off entirely.</p> <p>Mcproto will remove support for this old authentication methods once this happens.</p> <p>This method of authentication doesn't require any special app registrations, however it is significantly less secure, as you need to enter your login and password directly.</p> <pre><code>  import httpx\n  from mcproto.auth.yggdrasil import YggdrasilAccount\n\n  LOGIN = \"mail@example.com\"\n  PASSWORD = \"my_password\"\n\n  async def authenticate() -&gt; YggdrasilAccount:\n      async with httpx.AsyncClient() as client:\n          return YggdrasilAccount.authenticate(client, login=LOGIN, password=PASSWORD)\n</code></pre> <p>The Account instance you will obtain here will contain a refresh token, and a shorter lived access token, received from Mojang APIs from the credentials you entered. Just like with Microsoft accounts, you may want to cache these tokens to avoid needless calls to request new ones and go through authentication again. That said, since doing so doesn't necessarily require user interaction, if you make the credentials accessible from your code directly, this is a lot less annoying.</p> <p>If you will decide to use caching, or if you plan on using these credentials in a long running program, you may see the access token expire. You can check whether the token is expired with the <code>YggdrasilAccount.validate</code> method, and if it is (call returned <code>False</code>), you can call <code>YggdrasilAccount.refresh</code> to use the refresh token to obtain a new access token. The refresh token is much more long lived than the access token, so this should generally be enough for you, although if you login from elsewhere, or after a really long time, the refresh token might be invalidated, in that case, you'll need to go through the full login again.</p>"},{"location":"usage/authentication/#legacy-mojang-accounts","title":"Legacy Mojang accounts","text":"<p>If your minecraft account is still using the (really old) Mojang authentication, you can simply follow the non-migrated guide, as it will work with these legacy accounts too, the only change you will need to make is to use your username, instead of an email.</p>"}]}
\ No newline at end of file
diff --git a/pr-preview/pr-346/sitemap.xml b/pr-preview/pr-346/sitemap.xml
index f0713917..e4a6b79d 100644
--- a/pr-preview/pr-346/sitemap.xml
+++ b/pr-preview/pr-346/sitemap.xml
@@ -2,138 +2,138 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://py-mine.github.io/mcproto/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/community/attribution/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/community/code-of-conduct/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/community/license/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/making-a-pr/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/reporting-a-bug/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/changelog/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/deprecations/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/docstrings/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/great-commits/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/precommit/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/setup/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/slotscheck/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/style-guide/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/type-hints/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/contributing/guides/unit-tests/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/installation/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/installation/changelog/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/installation/version-guarantees/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/private/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/private/abc/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/private/authentication/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/private/deprecation/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/private/protocol/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/private/types/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/public/authentication/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/public/encryption/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/public/multiplayer/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/public/packets/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/public/protocol/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/reference/public/types/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/usage/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
     <url>
          <loc>https://py-mine.github.io/mcproto/usage/authentication/</loc>
-         <lastmod>2024-10-20</lastmod>
+         <lastmod>2024-10-22</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/pr-preview/pr-346/sitemap.xml.gz b/pr-preview/pr-346/sitemap.xml.gz
index 77689154..07d539e5 100644
Binary files a/pr-preview/pr-346/sitemap.xml.gz and b/pr-preview/pr-346/sitemap.xml.gz differ