Skip to content

Commit

Permalink
Merge pull request #49 from YoYoGames/develop.bart
Browse files Browse the repository at this point in the history 
Develop.bart
  • Loading branch information
@gurpreetsinghmatharoo
gurpreetsinghmatharoo authored Nov 13, 2023
2 parents 7a4f3c6 + 05c5a7e commit 6680b48
Show file tree
Hide file tree
Showing 88 changed files with 3,773 additions and 790 deletions.
14 changes: 6 additions & 8 deletions Manual/contents/Additional_Information/The_File_System.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>The File System</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" />
Expand All @@ -17,22 +17,21 @@
<h1><span data-field="title" data-format="default">The File System</span></h1>
<p>When using the <a href="../GameMaker_Language/GML_Reference/File_Handling/File_Handling.htm">file system functions</a> or <a href="../Settings/Included_Files.htm">included files</a> with <span data-keyref="GameMaker Name">GameMaker</span> it is vitally important to know exactly how the file system works and what things are going on behind the scenes. To that end, this section is designed to explain and clarify exactly <em>how</em> things are stored, <em>where</em> they are stored and what possible limits or workarounds there may be to this system.</p>
<p>The first and most important thing to note about the file functions is that they are limited - in general and by default - to the <strong>sandbox</strong>. What this means is that <span data-keyref="GameMaker Name">GameMaker</span> <strong>cannot save or load files from anywhere that is not part of the game bundle or the local storage for the device</strong> without <em>explicit </em>input from the user, and even then this input is limited to only Windows, macOS and Ubuntu (Linux) target platforms.</p>
<p class="note"><span data-conref="../assets/snippets/Tag_important.hts"> </span> It is possible to turn off the sandboxing, however, on the Desktop targets (Windows, macOS, and Ubuntu (Linux)) by checking the <strong>Disable file system sandbox</strong> option in the <a href="../Settings/Game_Options.htm">Game Options</a> for the target platform. You do this at your own risk, and while this will open up file saving and loading and permit you to access files anywhere on the given system, it may still be limited by the OS permissions, and you will not be able to write to the <a href="../GameMaker_Language/GML_Reference/File_Handling/File_Directories/program_directory.htm"><span style="font-size:1px;"><span class="inline" style="font-size: 14px">program_directory</span></span></a> folder.</p>
<p class="note"><span data-conref="../assets/snippets/Tag_important.hts"> </span> It is possible to turn off the sandboxing, however, on the Desktop targets (Windows, macOS, and Ubuntu (Linux)) by checking the <strong>Disable file system sandbox</strong> option in the <a href="../Settings/Game_Options.htm">Game Options</a> for the target platform. You do this at your own risk, and while this will open up file saving and loading and permit you to access files anywhere on the given system, it may still be limited by the OS permissions, and you will not be able to write to the <span class="inline2"><a data-xref="{title}" href="../GameMaker_Language/GML_Reference/File_Handling/File_Directories/program_directory.htm">program_directory</a></span> folder.</p>
<p>To understand the sandbox first of all you need to understand that there are two distinct areas for files:</p>
<ul class="colour">
<li><strong>The File Bundle</strong> - this is where all the files that are packaged with the executable game are stored, including the files that you have added to the <strong>Included Files</strong> asset list from the <span data-keyref="GameMaker Name">GameMaker</span> IDE (which are the external files that you want packaged with the game).</li>
<li><strong>The Save Area</strong> - this is an area of device storage that can be safely written to by the game and the game is guaranteed that this is a writable area.</li>
</ul>
<p>The following diagram may help you to visualise this better:</p>
<p><img alt="File System Save Areas" class="center" src="../assets/Images/Scripting_Reference/Additional_Information/Files_SaveAreas.png" /></p>
<p class="note"><span data-conref="../assets/snippets/Tag_note.hts"> </span> You can never write to the File Bundle (program) directory.</p>
<p>When your game is sandboxed, the two target areas - the bundle directory and the local storage area - are available on each target platform, but on each one they will work slightly differently. However <span data-keyref="GameMaker Name">GameMaker</span> has abstracted out the main essence of what can and can&#39;t be done, making it easier to re-target games to multiple environments.</p>
<p>To start with, you should understand what is meant when we talk of the <a href="../GameMaker_Language/GML_Reference/File_Handling/File_Directories/working_directory.htm"><span class="inline">working_directory</span></a>. This is a synonym for the two possible save locations (as illustrated by the diagram above) and when you use that directory it will do one of two things depending on whether you are reading or writing, and whether the file you are reading from has been changed or not:</p>
<p>To start with, you should understand what is meant when we talk of the <a href="../GameMaker_Language/GML_Reference/File_Handling/File_Directories/working_directory.htm"><span class="inline2">working_directory</span></a>. This is a synonym for the two possible save locations (as illustrated by the diagram above) and when you use that directory it will do one of two things depending on whether you are reading or writing, and whether the file you are reading from has been changed or not:</p>
<ul class="colour">
<li><strong>Reading Operations</strong> - working_directory will first check the save area to see if the file being accessed is there, and if it is uses that. However if the file does not exists in the save area, it then checks the file bundle area and uses that (if the file being looked for is an included file with your game).</li>
<li><strong>Reading Operations</strong> - <span class="inline2">working_directory</span> will first check the save area to see if the file being accessed is there, and if it is uses that. However if the file does not exist in the save area, it then checks the file bundle area and uses that (if the file being looked for is an included file with your game).</li>
<li><strong>Writing Operations</strong> - This can only happen in the save area.</li>
</ul>
<p class="note"><span data-conref="../assets/snippets/Tag_note.hts"> </span> in general <span data-keyref="GameMaker Name">GameMaker</span> will handle all this for you and you <strong>rarely </strong>need to use the <span class="inline" style="font-size: 14px">working_directory</span> built in variable.</p>
<p class="note"><span data-conref="../assets/snippets/Tag_note.hts"> </span> In general <span data-keyref="GameMaker Name">GameMaker</span> will handle all this for you and you <strong>rarely </strong>need to use the <span class="inline2"><a data-xref="{title}" href="../GameMaker_Language/GML_Reference/File_Handling/File_Directories/working_directory.htm">working_directory</a></span> built-in variable.</p>
<p>Using these two simple rules we can now see how the following functions work (these are examples to help you to visualise the process for the different functions available):</p>
<ul class="colour">
<li><a href="../GameMaker_Language/GML_Reference/File_Handling/File_Directories/directory_create.htm"><span class="inline">directory_create()</span></a> (and the other directory functions) will only work in the <strong>save </strong>area.</li>
Expand All @@ -50,8 +49,7 @@ <h1><span data-field="title" data-format="default">The File System</span></h1>
<li><strong>iOS</strong> / <strong>tvOS</strong>: Storage is the standard location (as viewed through iTunes).</li>
<li><strong>Android</strong>: Files are in the standard location (which is invisible unless the device is rooted) <span class="inline">/data/&lt;package name&gt;</span>.</li>
</ul>
<p>It is worth noting that the HTML5 target module has a limit on local storage (which can be between 1MB and 5MB depending on the browser) meaning that you will not be permitted to save large sprites, screenshots etc...</p>
<p> </p>
<p>It is worth noting that the HTML5 target module has a limit on local storage (which can be between 1MB and 5MB depending on the browser) meaning that you will not be permitted to save large sprites, screenshots, etc.</p>
<p> </p>
<p> </p>
<div class="footer">
Expand Down
2 changes: 1 addition & 1 deletion Manual/contents/GameMaker_Language/GML_Overview/Functions/Static_Variables.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
<h1><span data-field="title" data-format="default">Static Variables</span></h1>
<p>An interesting feature of <a href="../Script_Functions.htm">script functions</a> and <a href="../Method_Variables.htm">method variables</a> is that they can have <strong>static variables</strong>.</p>
<p>A static variable is defined the first time the function is called and will maintain its value from then onward. It can only be changed inside the original function, and returning it will simply give you a copy of its value - essentially the shared static variable can only be changed by the function that contains it.</p>
<p class="note"><span data-conref="../../../assets/snippets/Tag_note.hts"> </span> <span data-field="title" data-format="default">Static Variables</span> cannot be declared outside of functions.</p>
<p class="note"><span data-conref="../../../assets/snippets/Tag_warning.hts"> </span> <span data-field="title" data-format="default">Static Variables</span> cannot be declared outside of functions.</p>
<p>To create a static variable you need to define it using the <span class="inline">static</span> keyword, as shown in this simple example:</p>
<p class="code">counter = function()<br />
{<br />
Expand Down
5 changes: 3 additions & 2 deletions ...tents/GameMaker_Language/GML_Reference/Asset_Management/Assets_And_Tags/asset_get_ids.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
<h1><span data-field="title" data-format="default">asset_get_ids</span></h1>
<p>This function gets an array of references to assets of the given asset type.</p>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span> The returned array contains assets that you added through <a data-xref="{title}" href="../../../../Introduction/The_Asset_Browser.htm">The Asset Browser</a> as well as assets that you added <a href="../Asset_Management.htm#dynamically_adding_assets">dynamically at runtime</a>.</p>
<p class="note"><span data-conref="../../../../assets/snippets/Tag_note.hts"> </span> For the asset type <span class="inline2">asset_script</span> the function returns both script assets (the ones you add to <a data-xref="{title}" href="../../../../Introduction/The_Asset_Browser.htm">The Asset Browser</a>) and the <a href="../../../GML_Overview/Script_Functions.htm">script functions</a> they contain.</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code"><span data-field="title" data-format="default">asset_get_ids</span>(asset_type);</p>
Expand All @@ -34,14 +35,14 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>asset_type</td>
<td><span data-keyref="Type_Constant_Asset_Type"><a href="../../../../../GameMaker_Language/GML_Reference/Asset_Management/Assets_And_Tags/asset_get_type.htm" target="_blank">Asset Type Constant</a></span></td>
<td><span data-keyref="Type_Constant_Asset_Type"><a href="asset_get_type.htm" target="_blank">Asset Type Constant</a></span></td>
<td>The type of asset to return in the array</td>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Array"><a href="../../../../../GameMaker_Language/GML_Overview/Arrays.htm" target="_blank">Array</a></span> of <span data-keyref="Type_Asset"><a href="../../../../../The_Asset_Editors/The_Asset_Editors.htm" target="_blank">Asset</a></span></p>
<p class="code"><span data-keyref="Type_Array"><a href="../../../GML_Overview/Arrays.htm" target="_blank">Array</a></span> of <span data-keyref="Type_Asset"><a href="../../../../The_Asset_Editors/The_Asset_Editors.htm" target="_blank">Asset</a></span></p>
<p> </p>
<h4>Example:</h4>
<p class="code">var _arr_ids = <span data-field="title" data-format="default">asset_get_ids</span>(asset_sprite);</p>
Expand Down
2 changes: 1 addition & 1 deletion ...ents/GameMaker_Language/GML_Reference/Asset_Management/Assets_And_Tags/asset_get_type.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>name_or_ref</td>
<td><span data-keyref="Type_String"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">String</a></span></td>
<td><span data-keyref="Type_Asset"><a href="../../../../The_Asset_Editors/The_Asset_Editors.htm" target="_blank">Asset</a></span> or <span data-keyref="Type_String"><a href="../../../GML_Overview/Data_Types.htm" target="_blank">String</a></span></td>
<td>The name of or a reference to the game asset to get the type of.</td>
</tr>
</tbody>
Expand Down
24 changes: 12 additions & 12 deletions .../GML_Reference/Asset_Management/Rooms/General_Layer_Functions/layer_get_element_layer.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>layer_get_element_layer</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" />
Expand All @@ -15,11 +15,12 @@
</head>
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>layer_get_element_layer</h1>
<p>You can use this function to get the <i>Layer ID</i> that the given element is on. You supply the unique element ID value (for example, as returned by the function that created the element or from the room editor) and the function will return the unique ID of the layer that the element is found on. If the element ID given is not a valid one, then the function will return -1.</p>
<h1><span data-field="title" data-format="default">layer_get_element_layer</span></h1>
<p>This function gets the layer ID that the given element is on.</p>
<p>You supply the unique element ID value (for example, as returned by the function that created the element or from <a data-xref="{title}" href="../../../../../The_Asset_Editors/Rooms.htm">The Room Editor</a>) and the function will return the unique ID of the layer that the element is found on. If the element ID given is not a valid one, then the function will return -1.</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code">layer_get_element_layer(element_id)</p>
<p class="code"><span data-field="title" data-format="default">layer_get_element_layer</span>(element_id)</p>
<table>
<tbody>
<tr>
Expand All @@ -29,29 +30,28 @@ <h4>Syntax:</h4>
</tr>
<tr>
<td>element_id</td>
<td><span data-keyref="Type_ID_Layer_Element">Layer Element ID</span></td>
<td><span data-keyref="Type_ID_Layer_Element"><a href="layer_get_all_elements.htm" target="_blank">Layer Element ID</a></span></td>
<td>The unique ID value of the element to get the layer of</td>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_ID_Layer">Layer ID</span> or -1 (if the element is invalid)</p>
<p class="code"><span data-keyref="Type_ID_Layer"><a href="layer_get_id.htm" target="_blank">Layer ID</a></span> or -1 (if the element is invalid)</p>
<p> </p>
<h4>Example:</h4>
<p class="code">element = layer_get_element_layer(asset_1);</p>
<p>The above code gets layer ID for the element with the ID stored in the variable &quot;asset_1&quot; and stores it in a variable.</p>
<p> </p>
<p class="code">element = <span data-field="title" data-format="default">layer_get_element_layer</span>(asset_1);</p>
<p>The above code gets the layer ID for the element with the ID stored in the variable <span class="inline2">asset_1</span> and stores it in a variable.</p>
<p> </p>
<p> </p>
<div class="footer">
<div class="buttons">
<div class="clear">
<div style="float:left">Back: <a href="General_Layer_Functions.htm">General Layer Functions</a></div>
<div style="float:right">Next: <a href="layer_get_element_type.htm">layer_get_element_type</a></div>
<div style="float:left">Back: <a data-xref="{title}" href="General_Layer_Functions.htm">General Layer Functions</a></div>
<div style="float:right">Next: <a data-xref="{title}" href="layer_get_element_type.htm">layer_get_element_type</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. 2023 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
layer_get_element_layer
Expand Down
14 changes: 7 additions & 7 deletions ...e/GML_Reference/Asset_Management/Rooms/General_Layer_Functions/layer_get_element_type.htm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>layer_get_element_type</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" />
Expand All @@ -16,15 +16,15 @@
<body>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1><span data-field="title" data-format="default">layer_get_element_type</span></h1>
<p>You can use this function to get the <i>element type</i> for the given element. You supply the unique element ID value (for example, as returned the function that created the element or from the room editor) and the function will return one of the following constants: </p>
<p>You can use this function to get the <i>element type</i> for the given element. You supply the unique element ID value (for example, as returned the function that created the element or from <a data-xref="{title}" href="../../../../../The_Asset_Editors/Rooms.htm">The Room Editor</a>) and the function will return one of the following constants: </p>
<table>
<colgroup>
<col />
<col />
</colgroup>
<tbody>
<tr>
<th colspan="2"><span data-keyref="Type_Constant_Layer_Element_Type"><a href="../../../../../../GameMaker_Language/GML_Reference/Asset_Management/Rooms/General_Layer_Functions/layer_get_element_type.htm" target="_blank">Layer Element Type Constant</a></span></th>
<th colspan="2"><span data-keyref="Type_Constant_Layer_Element_Type"><a href="layer_get_element_type.htm" target="_blank">Layer Element Type Constant</a></span></th>
</tr>
<tr>
<th>Constant</th>
Expand Down Expand Up @@ -60,7 +60,7 @@ <h1><span data-field="title" data-format="default">layer_get_element_type</span>
</tr>
<tr>
<td><span class="inline">layerelementtype_sequence</span></td>
<td>The element is a sequence asset.</td>
<td>The element is a sequence.</td>
</tr>
<tr>
<td><span class="inline">layerelementtype_undefined</span></td>
Expand All @@ -80,15 +80,15 @@ <h4>Syntax:</h4>
<th>Description</th>
</tr>
<tr>
<td>layer</td>
<td><span data-keyref="Type_ID_Layer_Element"><a href="../../../../../../GameMaker_Language/GML_Reference/Asset_Management/Rooms/General_Layer_Functions/layer_get_all_elements.htm" target="_blank">Layer Element ID</a></span></td>
<td>element_id</td>
<td><span data-keyref="Type_ID_Layer_Element"><a href="layer_get_all_elements.htm" target="_blank">Layer Element ID</a></span></td>
<td>The unique ID value of the element to get the type of</td>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code"><span data-keyref="Type_Constant_Layer_Element_Type"><a href="../../../../../../GameMaker_Language/GML_Reference/Asset_Management/Rooms/General_Layer_Functions/layer_get_element_type.htm" target="_blank">Layer Element Type Constant</a></span> (layerelementtype_undefined if element does not exist or is invalid)</p>
<p class="code"><span data-keyref="Type_Constant_Layer_Element_Type"><a href="layer_get_element_type.htm" target="_blank">Layer Element Type Constant</a></span> (layerelementtype_undefined if element does not exist or is invalid)</p>
<p> </p>
<h4>Example:</h4>
<p class="code">var a = layer_get_all_elements(layer);<br />
Expand Down
Loading

0 comments on commit 6680b48

Please # to comment.