<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<script type="text/javascript" language="JavaScript">
//<![CDATA[
function reDo() {
if (innerWidth != origWidth || innerHeight != origHeight)
location.reload();
}
if ((parseInt(navigator.appVersion) == 4) && (navigator.appName == "Netscape")) {
origWidth = innerWidth;
origHeight = innerHeight;
onresize = reDo;
}
onerror = null;
//]]>
</script>
<style type="text/css">/*<![CDATA[*/
< !-- div.WebHelpPopupMenu {
position: absolute;
left: 0px;
top: 0px;
z-index: 4;
visibility: hidden;
}
p.WebHelpNavBar {
text-align: right;
}
-->
/*]]>*/</style>
<script type="text/javascript">//<![CDATA[
gRootRelPath = "../../..";
gCommonRootRelPath = "../../..";
gTopicId = "9.1.2.0_10";
//]]></script>
<script type="text/javascript" src="../../../template/scripts/rh.min.js"></script>
<script type="text/javascript" src="../../../template/scripts/common.min.js"></script>
<script type="text/javascript" src="../../../template/scripts/topic.min.js"></script>
<script type="text/javascript" src="../../../template/scripts/topicwidgets.min.js"></script>
<script type="text/javascript" src="../../../whxdata/projectsettings.js"></script>
<link rel="stylesheet" type="text/css" href="../../../template/styles/topic.min.css"/>
<link rel="stylesheet" type="text/css" href="../../../template/Charcoal_Grey/topicheader.css"/>
<meta name="topic-status" content="Draft"/>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>with</title>
<meta name="generator" content="Adobe RoboHelp 2019"/>
<link rel="stylesheet" href="../../../assets/css/default.css" type="text/css"/>
<meta name="rh-authors" content="Mark Alexander"/>
<meta name="topic-comment" content="Page outlining the with function"/>
<meta name="rh-index-keywords" content="with"/>
<meta name="search-keywords" content="with"/>
</head>
<body>
<div class="topic-header rh-hide" id="rh-topic-header" onclick="rh._.goToFullLayout()">
<div class="logo">
</div>
<div class="nav">
<div class="title" title="with">
<span>with</span>
</div>
<div class="gotohome" title="Click here to see this page in full context">
<span>Click here to see this page in full context</span>
</div>
</div>
</div>
<div class="topic-header-shadow rh-hide" id="rh-topic-header-shadow"></div>
<!--<div class="body-scroll" style="top: 150px;">-->
<h1>with</h1>
<p>As indicated in the section <a href="../Addressing_Variables_In_Other_Instances.htm">Addressing Variables in Other Instances</a>, it is possible to read and change the value of variables in instances other than the one currently executing any given
code. However, in a number of cases you want to do a lot more than just change a single variable within those other instances, and may want to perform more complex code actions that require multiple functions and lines of code. For example, imagine
that you want to move all the ball objects in your game 8 pixels. You may think that this is achieved simply by the following piece of code:</p>
<p class="code">obj_ball.y = obj_ball.y + 8;</p>
<p>But this is not correct, as the right side of the assignment gets the value of the y-coordinate of the first ball and adds 8 to it. Next this new value is set as y-coordinate of <em>all </em>balls, so the result is that all balls get the same y-coordinate,
and even if you use the following:</p>
<p class="code">obj_ball.y += 8;</p>
<p>it will have exactly the same effect because it is simply an abbreviation of the first statement. So how <i>do</i> we achieve something like this? This is why the <tt>with</tt> statement exists in GML. The with statement has the following syntax:</p>
<p class="code">with (<expression>)<br/> {<br/> <statement>;<br/> <statement>;<br/> ...<br/> }</p>
<p>For the <a class="tooltip" title="An expression is a combination of one or more constants, variables, operators, and/or functions that are interpreted according to particular rules of precedence and association to return another value. A simple expression would be (5 + 5), which returns 10.">expression</a>, you can indicate one or more instances to perform th code on, using an instance ID, the object ID (which indicatesthat <i>all instances</i> in the room of this object
are to run the code block) or one of the special <a href="../Instance_Keywords.htm">keywords</a> (<tt>all</tt> or <tt>other</tt>). This will then change the <strong>scope</strong> of the code within the curly brackets <span class="inline">{}</span> from the
instance or function that actually holds the code to the instance (or instances) given in the expression.</p>
<p>Once the expression has set the scope of the <span class="inline">with</span>, the <a class="tooltip" title="In programming, a statement is a single line of code written legally in a programming language that expresses an action to be carried out. A statement might have internal components of its own, including expressions, operators and functions. An example of a statement is A = B + 5. A GameMaker Studio 2 program is nothing but a sequence of one or more statements that together perform a task (like move the player). ">statement</a> will then be executed for each of the indicated instances, as if that instance is the current (
<span class="inline">self</span>) instance. So, returning to our original problem, to move all instances of the ball object 8 pixels down you would type:</p>
<p class="code">with (obj_ball)<br/> {
<br/> y += 8;<br/> }
</p>
<p>Essentially this is a loop, and each <a class="tooltip" title="An iteration is a single pass through a set of operations in your project code. One form of iteration in computer programming is via loops. A loop will repeat a certain segment of code until a condition is met and it can proceed further. Each time the computer runs a loop, it is known as an iteration. In simple terms, iteration is the process of repeating a particular snippet of code over and over again to perform a certain action.">iteration</a> of the loop, the code will run on one instance of the object <span class="inline">obj_ball</span>.</p>
<p>If you want to execute multiple statements, just include them in the curly brackets, the same as you would around any other code block. So for example, to move all the balls in our example to a random position and gve them a random speed and direction,
you would use:</p>
<p class="code">with (obj_ball)<br/> {
<br/> x = random(room_width);<br/> y = random(room_height);<br/> speed = 1 + random(2);<br/> direction = random(360);<br/> }
</p>
<p>As mentioned above, within the statement(s), the indicated instance has become the target (<span class="inline">self</span>) instance that runs the code block, which means that the original instance (that contains the <tt>with</tt> and the code block)
has become the <tt>other</tt> instance. So for example, to move all balls to the position of the current instance that actually contains the code, you can type this:</p>
<p class="code">with (obj_ball)<br/> {
<br/> x = other.x;<br/> y = other.y;<br/> }
</p>
<p>The <tt>with</tt> statement is an extremely powerful tool and is useful in many, many circumstances so it is important that you understand fully how it can be used. To help there are a few more examples of use below:</p>
<p class="code">with (instance_create_layer(x, y, "Instances", obj_Ball))<br/> {
<br/> speed = other.speed;<br/> direction = other.direction;<br/> }
</p>
<p>The above code will create an instance of <tt>obj_Ball</tt> and assign it the speed and direction of the instance that runs the whole code block.</p>
<p class="code">with (instance_nearest(x, y, obj_Ball))<br/> {
<br/> instance_destroy();
<br/> }
</p>
<p>The above code will destroy the instance of <tt>obj_Ball</tt> nearest to the instance running the code.</p>
<p class="code">var _inst = noone;<br/> with (obj_ball)<br/> {
<br/> if (str > other.str)<br/> {
<br/> _inst = id;<br/> }
<br/> }
<br/> if (_inst != noone)<br/> {
<br/> target = _inst;<br/> }
</p>
<p>The above code is slightly more complex than previous ones due to it using a <a href="../Variables_And_Variable_Scope.htm">local variable</a>. This variable is local to the either the <em>event</em> or the <em>script </em><em>function</em> and not to
the instance and so can be used and accessed by all instances that are referenced within the code block. So, in the code we have set it to the special keyword <tt>noone</tt> and then use the <tt>with</tt> construction to have every instance of <tt>obj_Ball</tt> check
their <tt>str</tt> variable against that of the instance running the code block. If the value of the variable is larger, then they store their unique ID in the <tt>inst</tt> local variable, meaning that at the end of the code, only the instance with
a value greater than the calling instance (or the keyword <tt>noone</tt> if none are larger) will be stored in the local variable <span class="inline">_inst</span>.</p>
<p>It is worth noting that you can use the special <span class="inline"><a href="break.htm">break</a></span> and <span class="inline"><a href="continue.htm">continue</a></span> statements within a
<font face="Lucida Console"><span style="font-size: 16px;"><b>with</b></span></font> call too. Using <span class="inline">break</span> will immediately exit the <span class="inline">with</span> code block and move on to any code that is in the event or function after the
<span class="inline">with</span> should have finished, eg:</p>
<p class="code">var count = 0;<br/> with (obj_Enemy)<br/> {
<br/> if (++count > 10)<br/> {
<br/> break;
<br/> }
<br/> hp = 100;<br/> }
</p>
<p>The above code loops through the instances in the room of the object <span class="inline">obj_Enemy</span> and sets the variable <span class="inline">hp</span> to 100 for the first 10 it finds. If any more than 10 instances exist, the with code will
call <span class="inline">break</span> and end.</p>
<p>An example of using <span class="inline">continue</span> in a <span class="inline">with</span> loop would be:</p>
<p class="code">with (obj_Enemy_Parent)<br/> {<br/> if (invulnerable == true)<br/> {<br/> continue;<br/> }<br/> hp -= 25;<br/> }</p>
<p>This code will loop through all instance with the parent <span class="inline">obj_Enemy_Parent</span>, then checks each instance to see if the <span class="inline">invulnerable</span> instance variable is <span class="inline">true</span> or not. If
it is, the <span class="inline">continue</span> keyword ends the current iteration of the loop and moves on to the next available instance, otherwise it removes 25 from the <span class="inline">hp</span> variable. This will repeat until all instances
with that parent have been checked.</p>
<p> </p>
<p> </p>
<p> </p>
<div class="footer">
<div class="buttons">
<div class="clear">
<div style="float:left">Back: <a href="../Language_Features.htm">Language Features</a></div>
<div style="float:right">Next: <a href="return.htm">return</a></div>
</div>
</div>
<h5>© Copyright YoYo Games Ltd. 2020 All Rights Reserved</h5>
</div>
<!-- KEYWORDS
with
-->
<!-- TAGS
with
-->
</body></html>