Frictional Game Wiki

<h1>Beginner Scripting Tutorial 1</h1> <div class="level1"> <p> <em>This is an easy tutorial for beginners. It is not intended to teach you new techniques but more to show you all the neat stuff you can do with the functions and the HPL2 engine.</em> </p> <p> In this tutorial you'll learn how to make entities 'float' or rather make them seem to be very very light. Possible uses could be for some strange sanity effects or even simulating an underwater environment! </p> </div> <h2>Getting started</h2> <div class="level2"> <p> Start by creating a new level in the level editor and then saving the map. There are no real limits, but keep it simple and include some movable entities you can use the script on. In my little room it's the skull and two books. You should include another entity you don't use the effect on, so you can compare their characteristics! </p> <p> My room looks like this: </p> <p> <a href="http://imgur.com/OiFEr.png" class="urlextern" title="http://imgur.com/OiFEr.png" rel="nofollow">Link</a> </p> <p> After you have saved your map, create a .hps file with the same name. This is where we'll do all the scripting, add the default script there. I have removed the if-clause in my example, it's not needed. </p> <pre class="code c"><span class="co1">////////////////////////////</span> <span class="co1">// Run first time starting map</span> <span class="kw4">void</span> OnStart<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> GiveItemFromFile<span class="br0">(</span>"lantern"<span class="sy0">,</span> "lantern.<span class="me1">ent"</span><span class="br0">)</span><span class="sy0">;</span>   <span class="kw1">for</span><span class="br0">(</span><span class="kw4">int</span> i<span class="sy0">=</span><span class="nu0">0</span><span class="sy0">;</span>i< 10<span class="sy0">;</span>i<span class="sy0">++</span><span class="br0">)</span> GiveItemFromFile<span class="br0">(</span>"tinderbox_"<span class="sy0">+</span>i<span class="sy0">,</span> "tinderbox.<span class="me1">ent"</span><span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span>   <span class="co1">////////////////////////////</span> <span class="co1">// Run when entering map</span> <span class="kw4">void</span> OnEnter<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span>   <span class="br0">}</span>   <span class="co1">////////////////////////////</span> <span class="co1">// Run when leaving map</span> <span class="kw4">void</span> OnLeave<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span>   <span class="br0">}</span> </pre><p> </p> </div> <h2>The scripting</h2> <div class="level2"> <p> Now we'll do the actual scripting! The floating effect is based on timer functions, and one of these we'll add in <em>OnStart()</em> so it is immediately called when the level loads! The syntax for timer function looks like this: </p> <pre class="code c"><span class="co1">//Function syntax: Func(string &in asTimer)</span> <span class="kw4">void</span> AddTimer<span class="br0">(</span>string<span class="sy0">&</span> asName<span class="sy0">,</span> <span class="kw4">float</span> afTime<span class="sy0">,</span> string<span class="sy0">&</span> asFunction<span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> The first string <em>asName</em> is the name of our timer, <em>afTime</em> is the time when the timer will call the function in <em>asFunction</em> after the timer is executed. Adding our timer in <em>OnStart()</em> will make our code look like this: </p> <pre class="code c"><span class="co1">////////////////////////////</span> <span class="co1">// Run first time starting map</span> <span class="kw4">void</span> OnStart<span class="br0">(</span><span class="br0">)</span> <span class="br0">{</span> GiveItemFromFile<span class="br0">(</span>"lantern"<span class="sy0">,</span> "lantern.<span class="me1">ent"</span><span class="br0">)</span><span class="sy0">;</span> <span class="kw1">for</span><span class="br0">(</span><span class="kw4">int</span> i<span class="sy0">=</span><span class="nu0">0</span><span class="sy0">;</span>i<span class="sy0"><</span> <span class="nu0">10</span><span class="sy0">;</span>i<span class="sy0">++</span><span class="br0">)</span> GiveItemFromFile<span class="br0">(</span>"tinderbox_"<span class="sy0">+</span>i<span class="sy0">,</span> "tinderbox.<span class="me1">ent"</span><span class="br0">)</span><span class="sy0">;</span>   AddTimer<span class="br0">(</span>"FloatTime"<span class="sy0">,</span> <span class="nu16">0.01</span><span class="sy0">,</span> "FloatObjects"<span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> As you can see, <b>FloatTime</b> is the name of our timer which calls the function <b>FloatObjects</b> after a very short time, exactly 0.01 seconds. The purpose of this will be explained after we created <b>FloatObjects</b>! </p> <p> For actually making the objects float, we'll add this function in <b>FloatObjects</b>: </p> <pre class="code c">AddPropImpulse<span class="br0">(</span>string<span class="sy0">&</span> asName<span class="sy0">,</span> <span class="kw4">float</span> afX<span class="sy0">,</span> <span class="kw4">float</span> afY<span class="sy0">,</span> <span class="kw4">float</span> afZ<span class="sy0">,</span> string<span class="sy0">&</span> asCoordSystem<span class="br0">)</span><span class="sy0">;</span> </pre><p> </p> <p> <b>AddPropImpulse</b> gives a specified entity an impulse, which means pushing it in a certain way with certain force. <em>asName</em> is the name of the entitity, The floats <em>afX</em>, <em>afY</em> and <em>afZ</em> are the direction coordinates the push has to follow and <em>asCoordSystem </em> specifies the coordinate system the game refers to. You can leave it empty, but valid strings would be "World" for using the XYZ planes you can see in the editor or "local" if it should use the XYZ axis of the object you are adressing.<br/> <b>AddPropImpulse</b> has to be created for <b>every</b> object you want to float, which makes three of them in my case! The last thing we add in <b>FloatObjects</b> is a timer function that practically calls itself so we can create a loop that will continually execute <b>FloatObjects</b> and give our entities a little push every 0.01 seconds! Our function should look like this: </p> <pre class="code c"><span class="kw4">void</span> FloatObjects<span class="br0">(</span>string <span class="sy0">&</span>in asTimer<span class="br0">)</span> <span class="br0">{</span> AddPropImpulse<span class="br0">(</span>"human_skull_1"<span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> <span class="nu16">0.15</span><span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> ""<span class="br0">)</span><span class="sy0">;</span> AddPropImpulse<span class="br0">(</span>"book01_1"<span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> <span class="nu16">0.15</span><span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> ""<span class="br0">)</span><span class="sy0">;</span> AddPropImpulse<span class="br0">(</span>"book01_2"<span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> <span class="nu16">0.15</span><span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> ""<span class="br0">)</span><span class="sy0">;</span> AddTimer<span class="br0">(</span>"FloatTime"<span class="sy0">,</span> <span class="nu16">0.01</span><span class="sy0">,</span> "FloatObjects"<span class="br0">)</span><span class="sy0">;</span> <span class="br0">}</span> </pre><p> </p> <p> So now I've added an impulse for every object I want to float (the skull and the two books) and a timer that calls itself, repeating <b>FloatObjects</b> over and over. </p> <p> You may have noticed that I've only put in a value for the <em>afY</em> float. That means the impulse only goes in the Y direction or UP! 0.15 is a very weak impulse, but it is applied every 0.01 seconds so all the little pushes can't be noticed by the player which creates the effect of the objects floating or falling very slowly. You can now save the .hps file and load your level. Have fun and thanks for reading! </p> </div> <h2>Additional information</h2> <div class="level2"> <p> Here you can put the little things you've noticed while playing around and testing my script. Stuff I've already found out: </p> <ul> <li class="level1"> Different entities need different <em>afY</em> values! For small objects like books 0.15 is enough, but everything bigger than 2 will make them float upwards like a helium balloon.</li> <li class="level1"> Play around with <em>afTime</em>! Bigger values like 0.5 combined with larger impulses like 5 can create some crazy bouncing effect!</li> </ul> </div>