Skip to content

docs(feature): Document that function overrides in child objects requ… #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
gurpreetsinghmatharoo wants to merge 1 commit into from
Closed

docs(feature): Document that function overrides in child objects requ… #265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 21 additions & 3 deletions Manual/contents/GameMaker_Language/GML_Overview/Method_Variables.htm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,9 @@ <h2>Creating Methods</h2>
<span>}</span>
</p>
<p class="note"><span data-conref="../../assets/snippets/Tag_note.hts"> </span> To create a function in <span data-keyref="GML_Visual">GML Visual</span>, use <a data-xref="{title}" href="../../Drag_And_Drop/Drag_And_Drop_Reference/Common/Declare_A_New_Function.htm">Declare A New Function</a>.</p>
<p>In general, however, you would use the <em>first </em>form for methods, and the second form for defining <a href="Script_Functions.htm">script functions</a>, since the second form will also assign a script index to the function while the first form will be a &quot;true&quot; method.</p>
<p>It is recommended that you should use the <em>first </em>form for methods, and the second form for defining <a href="Script_Functions.htm">script functions</a>, since the second form will also assign a script index to the function while the first form will be a &quot;true&quot; method. Using the second form introduces differences that are covered in <a data-xref="{text}" href="Script_Functions_vs_Methods.htm#h">Overridden Script Functions</a>.</p>
<p>Defining a function in an Object&#39;s event using either syntax will make the function only available in the context of its instance (i.e. using the script function syntax will <strong>not</strong> make the function globally available unless it is in a Script asset).</p>
<p class="note"><span data-conref="../../assets/snippets/Tag_note.hts"> </span> You can check this by using both forms in a script and then calling the runtime function <span class="inline3_func"><a data-xref="{title}" href="../GML_Reference/Variable_Functions/typeof.htm">typeof</a></span> on each of them. One will be classed as a &quot;ref&quot; - since it returns a script function reference - and the other will be classed as a &quot;method&quot;.</p>
<p class="note"><span data-conref="../../assets/snippets/Tag_note.hts"> </span> Defining a function in an Object&#39;s event using either syntax will make the function only available in the context of its instance (i.e. using the script function syntax will <strong>not</strong> make the function globally available unless it is in a Script asset).</p>
<p class="note"><span data-conref="../../assets/snippets/Tag_note.hts"> </span> A function defined in an Object&#39;s event using the script function syntax will be available to its instances throughout their lifetime, even when the event has not run yet. For example, defining a script function in the Alarm 0 event will make the function available to call in the Create event, regardless of when that alarm event runs (or whether it runs at all).</p>
<p>So, keep in mind that - in general - we will always be referring to functions that have <em>not </em>been defined with a script index when we are talking about methods and method variables.</p>
<p>The syntax for defining a method inside a <strong>struct literal</strong> is similar to the first syntax above, however the <span class="inline2">=</span> is replaced by a <span class="inline2">:</span> as required by struct literals:</p>
Expand Down Expand Up @@ -94,6 +94,24 @@ <h3>Optional Arguments</h3>
<p>The above function takes three arguments, where the last two are optional. If they are not passed in when the function is called, then they&#39;ll use the instance&#39;s <span class="inline">x</span> and <span class="inline">y</span> coordinates by default.</p>
<p>Note that if an argument is not passed in, and it does not have a default value, then it will be equal to <span class="inline">undefined</span>.</p>
<p>Methods can also make use of static variables, which maintain their values throughout every function call. Please <a href="Functions/Static_Variables.htm">read this page</a> for more information.</p>
<h3>Method Overriding</h3>
<p>Methods created inside instances or structs can be overridden later by assigning a new function to the same variable, e.g. in the same event in a child object:</p>
<p class="code">// obj_parent Create event<br />
say_hello = function()<br />
{<br />
   show_message(&quot;I am the parent!&quot;);<br />
}<br />
<br />
// obj_child Create event<br />
event_inherited();<br />
<br />
say_hello = function()<br />
{<br />
   show_message(&quot;I am the child!&quot;);<br />
}
</p>
<p>All calls to <span class="inline2">say_hello</span> in <span class="inline2">obj_child</span> will print <span class="inline2">&quot;I am the child!&quot;</span>.</p>
<p>Also see: <a data-xref="{text}" href="Script_Functions_vs_Methods.htm#h">Overridden Script Functions</a></p>
<h3 id="h">Methods Are Structs</h3>
<p><span data-keyref="GameMaker Name">GameMaker</span> stores methods as structs, where each &quot;method struct&quot; holds a reference to the script function to call and the struct or instance to which it is bound. You can get the script function behind a method by calling <span class="inline3_func"><a href="../GML_Reference/Variable_Functions/method_get_index.htm">method_get_index</a></span> and its bound struct or instance with <span class="inline3_func"><a href="../GML_Reference/Variable_Functions/method_get_self.htm">method_get_self</a></span>.</p>
<p><strong>Methods being structs is irrelevant in most cases</strong> as you would call them as functions and pass them into other functions that take methods - you would not use them as structs. However this detail can be important in a few edge cases, for example with the <a data-xref="{title}" href="Structs/Static_Structs.htm">Static Struct</a>, as each function in <span data-keyref="GameMaker Name">GameMaker</span> has a static struct and each struct can have its own static struct that forms the <a data-xref="{text}" href="Structs/Static_Structs.htm#h">Static Chain</a>. However the static struct functionality for method structs is <strong>disabled</strong> so you can directly access the static struct of the function behind it. Calling <span class="inline3_func"><a data-xref="{title}" href="../GML_Reference/Variable_Functions/static_get.htm">static_get</a></span> will give you the static struct for the function behind the method and calling <span class="inline3_func"><a data-xref="{title}" href="../GML_Reference/Variable_Functions/static_set.htm">static_set</a></span> on a method will do nothing.</p>
Expand All @@ -117,7 +135,7 @@ <h2>Function Reference</h2>
<div style="float:right">Next: <a data-xref="{title}" href="Script_Functions_vs_Methods.htm">Script Functions vs. Methods</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2025 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
Script Functions
Expand Down
30 changes: 0 additions & 30 deletions Manual/contents/GameMaker_Language/GML_Overview/Script_Functions.htm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,36 +229,6 @@ <h2>Script Scope</h2>
<p>Using the above function name would mean that the function <span class="inline">gmcallback_create_button()</span> will not be obfuscated and so can be used in JavaScript extensions and other areas of your game, for example, when using the <a href="../GML_Reference/Web_And_HTML5/Web_And_HTML5.htm"><span class="inline">clickable_*</span></a> functions.</p>
<h2>Static Variables</h2>
<p>Functions can also make use of static variables, which maintain their values throughout every function call. Please <a href="Functions/Static_Variables.htm">read this page</a> for more information.</p>
<h2>Notes</h2>
<p>This section contains miscellaneous usage notes regarding functions.</p>
<ul class="colour">
<li>If a function, defined in an event, contains a call to another function that was defined in the same event, without specifying a scope (e.g. <span class="inline2">self</span>), the call will be made to the function defined in the event, even if the variable it is assigned to was later overridden with a new function. To call whichever function is assigned to the instance variable at the time of the function call, specify the <span class="inline2">self</span> scope when calling (e.g. <span class="inline2">self.function()</span>). See the following example:</li>
</ul>
<p class="code">// Create event<br />
function overridden()<br />
{<br />
    show_debug_message(&quot;i&#39;m the original&quot;);<br />
}<br />
<br />
call_overridden = function()<br />
{<br />
    overridden();<br />
}<br />
<br />
// Room Start event<br />
function overridden()<br />
{<br />
    show_debug_message(&quot;i&#39;ve been overridden&quot;);<br />
}<br />
<br />
// Key Press - Space<br />
call_overridden();<br />
overridden();<br />
<br />
// call_overridden() will print &quot;i&#39;m the original&quot; to the log, calling the original function defined in the same event as call_overridden<br />
// overridden() will print &quot;i&#39;ve been overridden&quot; as it is referring to whichever function is stored in the overridden instance variable<br />
// Calling self.overridden() inside call_overridden changes the first logged message to &quot;i&#39;ve been overridden&quot;
</p>
<p> </p>
<p> </p>
<p> </p>
Expand Down
36 changes: 31 additions & 5 deletions Manual/contents/GameMaker_Language/GML_Overview/Script_Functions_vs_Methods.htm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
</head>
<body>
<h1><span data-field="title" data-format="default">Script Functions vs. Methods</span></h1>
<p>This page covers essential information about using script functions vs. methods.</p>
<p>This page covers essential information about using <a href="Script_Functions.htm">script functions</a> vs. <a href="Method_Variables.htm">methods</a>.</p>
<h2>Basic Difference</h2>
<p>A <a href="Script_Functions.htm">script function</a> is created with this syntax:</p>
<p class="code">function name()<br />
Expand All @@ -28,8 +28,8 @@ <h2>Basic Difference</h2>
{<br />
    code;<br />
}</p>
<p>You should use the first syntax in scripts, to create global functions that can be called from anywhere in your game. Execution of script functions retains the scope that was in use when the function was called.</p>
<p>You should use the second syntax when creating functions in <a href="Structs.htm">structs/constructors</a> and instances. This syntax creates a variable containing a method that is bound to the struct or instance that created the function and always uses that scope during execution.</p>
<p>You should use the first syntax in <a href="../../The_Asset_Editors/Scripts.htm">Script assets</a>, to create global functions that can be called from anywhere in your game. Execution of script functions retains the scope that was in use when the function was called.</p>
<p>You should use the second syntax when creating functions in <a href="Structs.htm">structs/constructors</a> and instances. This syntax creates a method variable containing a function that is bound to the struct or instance that created the function and always uses that scope during execution.</p>
<h2>Direct Calls</h2>
<p>You can call both script functions and methods directly by using parentheses <span class="inline2">()</span>,  just like a <a href="Runtime_Functions.htm">runtime function</a>:</p>
<p class="code">// Create the function<br />
Expand All @@ -41,7 +41,33 @@ <h2>Direct Calls</h2>
// Call the function<br />
reset_x();
</p>
<p>You can also use the function <a href="../GML_Reference/Asset_Management/Scripts/script_execute.htm"><span class="inline">script_execute()</span></a> to run a script function.</p>
<p>You can also use the function <a href="../GML_Reference/Asset_Management/Scripts/script_execute.htm"><span class="inline2">script_execute()</span></a> to run a script function.</p>
<h2 id="h">Overridden Script Functions</h2>
<p>Calls to script functions are optimised at a compiler level. This may result in function overrides not being respected if script functions are defined inside Objects.</p>
<p>Consider the following example:</p>
<p class="code">// obj_parent<br />
function talk()<br />
{<br />
   say_hello();<br />
}<br />
function say_hello()<br />
{<br />
   show_message(&quot;I am the parent!&quot;);<br />
}<br />
<br />
// obj_child<br />
event_inherited();<br />
<br />
function say_hello()<br />
{<br />
   show_message(&quot;I am the child!&quot;);<br />
}<br />
<br />
talk();
</p>
<p>Since <span class="inline2">talk</span> is called inside the child, you would expect it to call the overridden <span class="inline2">say_hello</span> from the child. However since the functions are defined with the script function syntax, it will instead call the parent&#39;s <span class="inline2">say_hello</span> and print <span class="inline2">&quot;I am the parent!&quot;</span>, as it calls the defined script function with that name directly without looking up the function assigned to the variable.</p>
<p>This is easily fixed by using the method variable syntax, i.e. <span class="inline2">say_hello = function()</span>, to define all your functions inside the Objects, as recommended at the start of this page. This way all calls are done through the method variable and the function assigned to the variable is called.</p>
<p>Alternatively, you can explicitly call the method variable using <span class="inline2">self</span>, e.g. <span class="inline2">self.say_hello()</span> so it always calls whichever function is assigned to the variable at the time of the call, instead of the defined script function with the same name.</p>
<h2>Indirect Calls: Methods</h2>
<p>You can store a reference to a method in another variable, to call it later through that different variable:</p>
<p class="code">// Create method<br />
Expand Down Expand Up @@ -91,7 +117,7 @@ <h2>Indirect Calls: Script Functions</h2>
<div>Next: <a data-xref="{title}" href="Functions/Static_Variables.htm">Static Variables</a></div>
</div>
</div>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2024 All Rights Reserved</span></h5>
<h5><span data-keyref="Copyright Notice">© Copyright YoYo Games Ltd. 2025 All Rights Reserved</span></h5>
</div>
<!-- KEYWORDS
Script Functions vs. Methods
Expand Down