2024.11 monthly manual

.github/workflows/trigger-all-sync-upstream.yml

@@ -4,13 +4,13 @@ on:
   workflow_dispatch:
      inputs:
         Language:
-         description: "Select All languages to build"
+         description: "Select All languages to sync"
          required: false
          type: choice
          options:
           - ALL
         COUNTRY:
-         description: "Select individual language to build"
+         description: "Select individual language to sync"
          required: false
          type: choice
          options:
@@ -33,18 +33,18 @@ jobs:
      runs-on: ubuntu-22.04
      strategy:
       matrix:
-        language: [PT-BR, DE, ES, FR, IT, JA, KO, PL, RU, ZH]
+        language: [PT-BR, DE, ES, FR, IT, JA, KO, PL, RU, ZH] 
      steps:
-      - name: Invoke Localisation Workflows
-        if: ${{ github.event.inputs.Language }} == 'ALL'
+      - name: Invoke Localisation Syncing
+        if: ${{ github.event.inputs.Language == 'ALL' }} 
         uses: benc-uk/workflow-dispatch@v1
         with:
           workflow: sync.yml
           repo: YoYoGames/GameMaker-Manual-${{ matrix.language }}
           token: ${{ secrets.GH_TOKEN }} 
         continue-on-error: false 
-      - name: Invoke Localisation Workflows
-        if: ${{ github.event.inputs.COUNTRY }} == ''
+      - name: Invoke Localisation Syncing
+        if: ${{ github.event.inputs.COUNTRY != ''}} 
         uses: benc-uk/workflow-dispatch@v1
         with:
           workflow: sync.yml

Manual/contents/Additional_Information/Additional_Information.htm

@@ -17,22 +17,16 @@
   <h1><span data-field="title" data-format="default">Additional Information</span></h1>
   <p>This section of the manual contain a collection of miscellaneous articles related to programming and the way the GameMaker Language works. The following articles are designed as companion articles to further expand your understanding of how <span data-keyref="GameMaker Name">GameMaker</span> works and how to get the most from the different language features available:</p>
   <ul class="colour">
-    <li><a href="Best_Practices_When_Programming.htm">Best Practices When Programming</a></li>
-    <li><a data-xref="{title}" href="Objects_vs_Instances.htm">Objects vs. Instances</a></li>
-    <li><a href="Bitwise_Operators.htm">Bitwise Operators</a></li>
-    <li><a href="Type_Tables.htm">Type Tables</a></li>
-    <li><a data-xref="{title}" href="Whitespace_Characters.htm">White-space Characters</a></li>
-    <li><a href="Vectors.htm">Vectors</a></li>
-    <li><a href="Guide_To_Using_Buffers.htm">Guide To Using Buffers</a></li>
-    <li><a href="Guide_To_Using_Particles.htm">Guide To Using Particles</a></li>
-    <li><a href="Guide_To_Using_Shaders.htm">Guide To Using Shaders</a></li>
-    <li><a href="Guide_To_Primitives_And_Vertex_Building.htm">Guide To Primitives And Vertex Building</a></li>
-    <li><a href="Guide_To_Using_Blendmodes.htm">Guide To Using Blendmodes</a></li>
+    <li><a data-xref="{title}" href="Guide_To_Using_Buffers.htm">Guide To Using Buffers</a></li>
+    <li><a data-xref="{title}" href="Guide_To_Using_Particles.htm">Guide To Using Particles</a></li>
+    <li><a data-xref="{title}" href="Guide_To_Using_Shaders.htm">Guide To Using Shaders</a></li>
+    <li><a data-xref="{title}" href="Guide_To_Primitives_And_Vertex_Building.htm">Guide To Primitives And Vertex Building</a></li>
+    <li><a data-xref="{title}" href="Guide_To_Using_Blendmodes.htm">Guide To Using Blendmodes</a></li>
     <li><a data-xref="{title}" href="Guide_To_Using_JSON.htm">Guide To Using JSON</a></li>
     <li><a data-xref="{title}" href="Project_Format.htm">Project Format</a></li>
-    <li><a href="Compatibility_Functions.htm">Compatibility Functions</a></li>
-    <li><a href="Compatibility_Scripts.htm">Compatibility Scripts</a></li>
-    <li><a href="Obsolete_Functions.htm">Obsolete Functions</a></li>
+    <li><a data-xref="{title}" href="Compatibility_Functions.htm">Compatibility Functions</a></li>
+    <li><a data-xref="{title}" href="Compatibility_Scripts.htm">Compatibility Scripts</a></li>
+    <li><a data-xref="{title}" href="Obsolete_Functions.htm">Obsolete Functions</a></li>
     <li><a data-xref="{title}" href="../Introduction/The_Marketplace.htm">The Marketplace</a></li>
   </ul>
   <p> </p>

Manual/contents/Additional_Information/Best_Practices_When_Programming.htm

@@ -133,7 +133,7 @@ <h1>Best Practices When Programming</h1>
   <div class="footer">
     <div class="buttons">
       <div class="clear">
-        <div style="float:left">Back: <a href="Additional_Information.htm">Additional Information</a></div>
+        <div style="float:left">Back: <a data-xref="{title}" href="../GameMaker_Language/GML_Overview/GML_Overview.htm">GML Code Overview</a></div>
         <div style="float:right">Next: <a data-xref="{title}" href="Objects_vs_Instances.htm">Objects vs. Instances</a></div>
       </div>
     </div>

Manual/contents/Additional_Information/Bitwise_Operators.htm

@@ -4,7 +4,7 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>Bitwise Operators</title>
-  <meta name="generator" content="Adobe RoboHelp 2020" />
+  <meta name="generator" content="Adobe RoboHelp 2022" />
   <link rel="stylesheet" href="../assets/css/default.css" type="text/css" />
   <script src="../assets/scripts/main_script.js" type="module"></script>
   <meta name="rh-authors" content="Mark Alexander" />
@@ -117,7 +117,7 @@ <h1>Bitwise Operators And Binary</h1>
     BOOM = 0;<br />
     A = A | (1 &lt;&lt; ACTIVE) | (1 &lt;&lt; BOOM);</p>
   <p>This may look like a lot of code, but if these numbers are constants, the compiler will pre-compile these operations into a single value so that we end up with this as actual code.</p>
-  <p class="code">A = A | 13421772;</p>
+  <p class="code">A = A | 134217729;</p>
   <p>Clearing these bits (as we saw above) is simply a matter of using the NOT modifier, like this:</p>
   <p class="code">A = A &amp; ~((1 &lt;&lt; ACTIVE) | (1 &lt;&lt; BOOM));</p>
   <p>So this happily lets us set and clear any bits we&#39;d like, and it also lets us compress out data structures massively. Compressing data structures is a good thing, because if you use less memory, you get less cache misses, and your code just runs faster. Put it this way, what&#39;s quicker, copying 32Mb or data, or 4Mb? Well, quite clearly 4 is. So if you can pack all yours flags down into a single memory access, this is good!</p>
@@ -130,7 +130,7 @@ <h1>Bitwise Operators And Binary</h1>
     var Y_index = y &gt;&gt; 5;<br />
     cell_data = mygrid[# X_index,Y_index];</p>
   <p>So, what if we wanted the remainder? Perhaps this remainder is used as some kind of order flag or something. Whatever the reason, getting a remainder is as simple as doing an <span class="inline">AND</span>:</p>
-  <p class="code">var remainder = x &amp; 31<br />
+  <p class="code">var remainder = x &amp; 31;<br />
     var X_Index = x &gt;&gt; 5;</p>
   <p>Now, you might have noticed we&#39;ve used multiple lines of code here (as is so often the case), but this is still only a couple of very fast instructions. But why the 31? Well, as bit 5 is 32, then all the bits below would be 31, and that&#39;s the maximum remainder so that&#39;s what we <span class="inline">AND</span> with (we could also use <span class="inline">(1 &lt;&lt; 5) - 1</span> which would make <span class="inline">32 - 1 = 31</span>). Now, if I were to do this without understanding binary, it would look like this:</p>
   <p class="code">var r = x mod 32;<br />
@@ -195,15 +195,14 @@ <h1>Bitwise Operators And Binary</h1>
   </div>
   <p> </p>
   <p> </p>
-  <p> </p>
   <div class="footer">
     <div class="buttons">
       <div class="clear">
-        <div style="float:left">Back: <a href="Additional_Information.htm">Additional Information</a></div>
-        <div style="float:right">Next: <a href="Type_Tables.htm">Type Tables</a></div>
+        <div style="float:left">Back: <a data-xref="{title}" href="../GameMaker_Language/GML_Overview/GML_Overview.htm">GML Code Overview</a></div>
+        <div style="float:right">Next: <a data-xref="{title}" href="Type_Tables.htm">Type Tables</a></div>
       </div>
     </div>
-    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2022 All Rights Reserved</span></h5>
+    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
   </div>
   <!-- KEYWORDS
 Bitwise Operators

Manual/contents/Additional_Information/Error_Reporting.htm

@@ -4,7 +4,7 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>Error Reporting</title>
-  <meta name="generator" content="Adobe RoboHelp 2020" />
+  <meta name="generator" content="Adobe RoboHelp 2022" />
   <link rel="stylesheet" href="../assets/css/default.css" type="text/css" />
   <script src="../assets/scripts/main_script.js" type="module"></script>
   <meta name="rh-authors" content="Mark Alexander" />
@@ -32,11 +32,11 @@ <h1>Error Reporting</h1>
   <div class="footer">
     <div class="buttons">
       <div class="clear">
-        <div style="float:left">Back: <a href="Additional_Information.htm">Additional Information</a></div>
+        <div style="float:left">Back: <a data-xref="{title}" href="../Settings/Game_Settings.htm">GameMaker Runner</a></div>
         <div style="float:right">Next: <a data-xref="{title}" href="../Settings/Runner_Details/Runner_Details.htm">Runner &amp; Compiler</a></div>
       </div>
     </div>
-    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2023 All Rights Reserved</span></h5>
+    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
   </div>
   <!-- KEYWORDS
 Error Reporting

Manual/contents/Additional_Information/Errors/Syntax_Errors.htm

@@ -4,7 +4,7 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>Syntax Errors (Feather Messages)</title>
-  <meta name="generator" content="Adobe RoboHelp 2020" />
+  <meta name="generator" content="Adobe RoboHelp 2022" />
   <link rel="stylesheet" href="../../assets/css/default.css" type="text/css" />
   <script src="../../assets/scripts/main_script.js" type="module"></script>
   <meta name="rh-authors" content="Mark Alexander" />
@@ -16,7 +16,17 @@
   <!--<div class="body-scroll" style="top: 150px;">-->
   <h1><span data-field="title" data-format="default">Syntax Errors (Feather Messages)</span></h1>
   <p>The first level of error reporting when programming your games in <span data-keyref="GameMaker Name">GameMaker</span> is in the code or GML Visual editor, and it&#39;s the <a class="glossterm" data-glossterm="syntax" href="#">syntax</a> checker. As you write your code - or add your actions - <span data-keyref="GameMaker Name">GameMaker</span> will check that it follows the established syntax for the language, and flag any issues that it finds so you can fix them before it comes to running the game or compiling an executable.</p>
-  <p>Syntax error checking happens differently depending on whether you have enabled <a href="../../The_Asset_Editors/Code_Editor_Properties/Feather_Features.htm">Feather</a> in the <a href="../../Setting_Up_And_Version_Information/IDE_Preferences/Feather_Settings.htm">Feather Settings</a>.</p>
+  <p>Syntax error checking happens differently depending on whether you have enabled <a href="../../The_Asset_Editors/Code_Editor_Properties/Feather_Features.htm">Feather</a> in the <a href="../../Setting_Up_And_Version_Information/IDE_Preferences/Feather_Settings.htm">Feather Settings</a>. It is enabled by default.</p>
+  <h2 id="h">Feather Messages (Feather enabled)</h2>
+  <p>When Feather is enabled the Syntax Errors window is replaced by the Feather Messages window: </p>
+  <p><img class="center" src="../../assets/Images/Scripting_Reference/Additional_Information/Output_Feather_Searchable_Sortable.png" />The Feather Messages window lists the errors and warnings that Feather encounters in your code, as well as the suggestions that it gives when it finds certain specific code patterns. Which types of errors are shown here depends on the profile that you define in the <a href="../../Setting_Up_And_Version_Information/IDE_Preferences/Feather_Settings.htm">Feather Settings</a> under Message Severity.</p>
+  <p>In this window the list of messages can be sorted ascending or descending by message code, by message text (alphabetically) or by resource (alphabetically by resource name). You can also search using the search box in the top right corner of the window.</p>
+  <p>Feather messages fall into three categories:</p>
+  <ul class="colour">
+    <li><img src="../../assets/Images/Scripting_Reference/Additional_Information/i_Feather_Warning.png" /> <strong>Warnings</strong>: These are shown for possible errors, which, in most cases, won&#39;t stop the game from compiling, but might provoke runtime errors. The most common causes of these warnings is when a variable is used in an expression and it hasn&#39;t been defined yet anywhere else, or when a variable has been defined but hasn&#39;t been used.</li>
+    <li><img src="../../assets/Images/Scripting_Reference/Additional_Information/i_Feather_Error.png" /> <strong>Errors</strong>: These are problems that will not permit the game to compile, let alone run. These should be fixed before doing anything further with the code.</li>
+    <li><img src="../../assets/Images/Scripting_Reference/Additional_Information/i_Feather_Suggestion.png" /> <strong>Suggestions</strong>: These are suggestions for possible improvements to the code, related to a variety of things.</li>
+  </ul>
   <h2>Syntax Errors (Feather disabled)</h2>
   <p><img alt="Syntax Errors Example" class="center" src="../../assets/Images/Scripting_Reference/Additional_Information/Errors_Syntax_Example.png" /></p>
   <p>These errors fall into two main categories:</p>
@@ -241,15 +251,7 @@ <h3>Syntax Error List</h3>
       </tr>
     </tbody>
   </table>
-  <h2 id="h">Feather Messages (Feather enabled)</h2>
-  <p>When Feather is enabled the Syntax Errors window is replaced by the Feather Messages window: </p>
-  <p><img class="center" src="../../assets/Images/Scripting_Reference/Additional_Information/Output_Feather_Searchable_Sortable.png" />The Feather Messages window lists the errors and warnings that Feather encounters in your code, as well as the suggestions that it gives when it finds certain specific code patterns. Which types of errors are shown here depends on the profile that you define in the <a href="../../Setting_Up_And_Version_Information/IDE_Preferences/Feather_Settings.htm">Feather Settings</a> under Message Severity.</p>
-  <p>In this window the list of messages can be sorted ascending or descending by message code, by message text (alphabetically) or by resource (alphabetically by resource name). You can also search using the search box in the top right corner of the window.</p>
-  <p>Feather messages fall into three categories:</p>
   <ul class="colour">
-    <li><img src="../../assets/Images/Scripting_Reference/Additional_Information/i_Feather_Warning.png" /> <strong>Warnings</strong>: These are shown for possible errors, which, in most cases, won&#39;t stop the game from compiling, but might provoke runtime errors. The most common causes of these warnings is when a variable is used in an expression and it hasn&#39;t been defined yet anywhere else, or when a variable has been defined but hasn&#39;t been used.</li>
-    <li><img src="../../assets/Images/Scripting_Reference/Additional_Information/i_Feather_Error.png" /> <strong>Errors</strong>: These are problems that will not permit the game to compile, let alone run. These should be fixed before doing anything further with the code.</li>
-    <li><img src="../../assets/Images/Scripting_Reference/Additional_Information/i_Feather_Suggestion.png" /> <strong>Suggestions</strong>: These are suggestions for possible improvements to the code, related to a variety of things.</li>
   </ul>
   <h3> </h3>
   <p> </p>
@@ -260,7 +262,7 @@ <h3> </h3>
         <div style="float:right">Next: <a href="Compiler_Errors.htm">Compiler Errors</a></div>
       </div>
     </div>
-    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2022 All Rights Reserved</span></h5>
+    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
   </div>
   <!-- KEYWORDS
 Syntax Errors

Manual/contents/Additional_Information/Guide_To_Using_Buffers.htm

@@ -54,7 +54,7 @@ <h1><span data-field="title" data-format="default">Guide To Using Buffers</span>
   <p>The actual code to create a buffer would look something like this:</p>
   <p class="code">player_buffer = buffer_create(16384, buffer_fixed, 2);</p>
   <p><br />
-    That would create a fixed buffer of 16384 bytes and byte-aligned to 2, with the function returning a unique ID value that is stored in a variable for later referencing of this buffer.</p>
+    That would create a fixed buffer of 16384 bytes and byte-aligned to 2, with the function returning a buffer handle that is stored in a variable for later referencing of this buffer.</p>
   <p>When reading and writing data to a buffer, you do it in &quot;chunks&quot; of data defined by their &quot;data type&quot;. The &quot;data type&quot; sets the number of bytes allocated within the buffer for the value being written, and it is essential that you get this correct otherwise you will get some very strange results (or even errors) for your code.</p>
   <p>Buffers are written to (and read from) <strong>sequentially</strong>, in that one piece of data is written after another, with each piece of data being of a set type. This means that you should ideally be aware of what data you are writing to the buffer at all times. These data types are defined in GML by the following constants:</p>
   <div data-conref="../assets/snippets/buffer_data_type_constants.hts"> </div>
@@ -136,7 +136,7 @@ <h1><span data-field="title" data-format="default">Guide To Using Buffers</span>
         <div style="float:right">Next: <a href="Bitwise_Operators.htm">Bitwise Operators</a></div>
       </div>
     </div>
-    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2023 All Rights Reserved</span></h5>
+    <h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
   </div>
   <!-- KEYWORDS
 Buffers