Difference between revisions of "HPL2/Tutorials/Scripts/Debugging"

From Frictional Wiki
Jump to navigation Jump to search
(Upload from wiki)
 
m (Updated moved link)
 
(4 intermediate revisions by one other user not shown)
Line 1: Line 1:
−
= Introduction =
+
=Debugging scripts=
 +
This article provides some tips about debugging HPL scripts.
  
 +
==Introduction==
 +
Here are some fast tips to make your scripting process much easier.
  
−
Hello, stepper here! Today i am going in the depths of finding problems yourself! So you don't have to wait for answers and do it quickly.
+
*Make sure you have [[HPL2/Development_Environment|the debug menu]] turned on. This will allow you to reload the script easily (use the '''F2''' shortcut).
 +
*Use windowed mode to switch (Alt-Tab) between the game and your code faster
 +
*Make sure to use a text editor with syntax highlighting (use C++) and a line count. The most common one is [[Hpl2:Third_party_tools:text:notepad|Notepad++]]. Check the ones available [[HPL2/Third party tools|here]] for alternatives. '''Syntax highlighting is <u>crucial</u> for finding bugs quickly.'''
  
 +
{{tip|Don't change scripts before you load the map. Doing that with any errors in the script will make the game crash when loading that map. Instead, load the map in the game before editing the script.}}
  
−
= Error menu =
+
==The Error window==
  
 +
If your script has an error, starting or reloading the map it is tied to will result in an error screen (or a crash screen). The errors which will cause a crash are syntax errors, which for example are missing a colon (;), a bracket (one of these: {}), a quotation mark (") around a string.
 +
The crash window looks like this:
  
−
As always you see a error menu when you start the map with the error. There are error with misplacing, spelling errors, all that kind of stuff. <br />
+
[[File:HPLcrash.png|frame|left|A crash window.]] {{clr}}
−
The menu looks like this:
 
  
 +
If you reload the map with script syntax errors in the game, it will pop up a window with a similar message.
  
−
While this error is hard to find in a large script. I put it in a short script.
+
In the message, you can see:
  
 +
*The map which caused the crash (indicated by the mentioned .hps file)
 +
*Code position which caused the crash: <code>main (132, 2): ERR : Unexpected end of file.</code>
  
−
[http://i.imgur.com/knVOP.png    ]
+
In this example, 132 is the line of code which caused the crash and 2 is the column. The column will rarely be useful as it is inprecise and uncomfortable to count. Keep in mind that certain errors will show an incorrect line of code - this happens when the engine knows where something starts and you missed the "end" marker.
  
 +
==Syntax highlighting==
  
−
As you can see is in wich map it is included, and what the name is. (custom_stories''/name'' /maps''/mapname''.hps)<br />
+
[[File:shlcode.jpg|frame|left|Syntax highlighting - note the colours!]]{{clr}}
−
As you also can see is the main (132, 2): ERR : Unexpected end of file.<br />
 
−
The 132 in my line is the position, this is really hard to find in Notepad. But easy in Notepad++, it's on the side.<br />
 
−
So, i now know 132 is the position from up to down in my script. 2 is the position in that line. (left to right)<br />
 
−
So, the position is 132 to down and 2 to right. Now you can go look what is missing, or wrong.
 
  
 +
If you use syntax highlighting capability that comes with code editors, you will be able to find the bug much more quickly. This is because string literals (the things written in double quotes, "like this") are displayed in a different color then the rest of the text; so if you forget a closing quote, the entire rest of the code will be highlighted in the same colour. Your error will be close to where the colour starts.
  
−
= Fixing the errors. =
+
Even if the error is of a different nature (it might not be too easy to spot) it will be easier compared to not having syntax highlighting, when the text looks uniformly black.
  
 +
Most importantly, having syntax highlighting will help you avoid this type of error ''as you write the script'', since you'll be immediately able to see that you've accidentally omitted a quotation mark.
  
−
Debugging the error that cause the game to crash before it even starts is a pain; fortunately, you don't have to restart the game every time - there's an easier way to do it, assuming you've [[hpl2:amnesia:devenvguide|set up your development environment correctly]]. Make a copy of the your current, erroneous script text, and store it somewhere for the time being. The goal is to make the map load correctly. So, either revert your map script to an earlier, working version, or just delete everything, and just put in an empty OnStart() method. Also, make sure that the game launches in ''windowed mode'', so that you can edit the script while the game is running.
+
HPL2 engine uses AngelScript for scripting, but since its syntax is almost identical to C++, you can set up your editor to use syntax highlighting for C++. To make scripting more comfortable:
  
−
 
+
*In your OS, associate .hps files with your editor (you will be able to double click them and it will start the editor)
−
Once the game loads the map successfully, bring up the development menu (F1), and then go to your script editor, delete everything, and paste back the original, error producing code. Save, switch back to the game window, and reload the script. This time, the game will show you an error message, but it will not crash. ''This is a huge timesaver!'' Take note of the error message; it will usually give you a reasonably accurate description of what the problem is (although sometimes it might be a bit cryptic), and it will point you to the line in the file where the problem appears to be (often, it is the correct line, sometimes, it is one line above, or below, or close by). Note that the code editors like [[hpl2:third_party_tools:text:notepad|Notepad++]] or [[hpl2:third_party_tools:text:geany|Geany]] show you what line you're on in their status line. Also, they support syntax highlighting, with will greatly improve the readability of your code and also help you find some of the common errors. These are third-party tools, and are free.
+
*Associaste the .hps extension with C++. This way you won't have to set the language each time you load a script.
−
 
 
−
 
 
−
Now we are going to fix the errors. I have put some errors right here, if you have another error, please Message me (stepper) on the forums.
 
−
 
 
−
== Unexpected end of file ==
 
−
 
 
−
 
 
−
This error can be the most common, it's mostly the missing of another " somewhere, the most irritating of this is, you will need to look over the whole script for to know where it is.
 
−
 
 
−
 
 
−
[http://i.imgur.com/SyBQW.png?direct&]
 
−
 
 
−
 
 
−
Oh look, i found it. My error tells that it's on (132, etc…) altough it's actually on (19, etc…) (not shown on the image) So now i just replace it. And Done!
 
−
 
 
−
 
 
−
However, if you use syntax highlighting capability that comes with code editors, you will probably be able to find the problem spot more quickly. This is because, if syntax highlighting is enabled, string literals (the things written in double quotes, "like this") are displayed in a different color then the rest of the text; so if you forget a closing quote, there will be a piece of your code that will ''look a bit wrong''. Your error will be there. Even so, the error still might not be too easy to spot, but it will be easier compared to not having syntax highlighting, when the text looks uniformly black.
 
−
 
 
−
 
 
−
In any case, having syntax highlighting will help you avoid this type of error ''as you write the script'', since you'll be immediately able to see that you've accidentally omitted a quotation mark.
 
−
 
 
−
 
 
−
Here's how syntax highlighting looks like:
 
−
 
 
−
 
 
−
[[File:shlcode.jpg]]
 
−
 
 
−
 
 
−
 
 
−
HPL2 engine uses AngelScript for scripting, but since it's syntax is similar to the languages in the C family, you can set up your editor to use syntax highlighting for C# or C++, or, if you're using Notepad++ or Geany, configure your editor as described on the corresponding page on this wiki.
 

Latest revision as of 19:52, 2 August 2020

Debugging scripts

This article provides some tips about debugging HPL scripts.

Introduction

Here are some fast tips to make your scripting process much easier.

  • Make sure you have the debug menu turned on. This will allow you to reload the script easily (use the F2 shortcut).
  • Use windowed mode to switch (Alt-Tab) between the game and your code faster
  • Make sure to use a text editor with syntax highlighting (use C++) and a line count. The most common one is Notepad++. Check the ones available here for alternatives. Syntax highlighting is crucial for finding bugs quickly.
Icon tip.png Tip: Don't change scripts before you load the map. Doing that with any errors in the script will make the game crash when loading that map. Instead, load the map in the game before editing the script.

The Error window

If your script has an error, starting or reloading the map it is tied to will result in an error screen (or a crash screen). The errors which will cause a crash are syntax errors, which for example are missing a colon (;), a bracket (one of these: {}), a quotation mark (") around a string. The crash window looks like this:

A crash window.

If you reload the map with script syntax errors in the game, it will pop up a window with a similar message.

In the message, you can see:

  • The map which caused the crash (indicated by the mentioned .hps file)
  • Code position which caused the crash: main (132, 2): ERR : Unexpected end of file.

In this example, 132 is the line of code which caused the crash and 2 is the column. The column will rarely be useful as it is inprecise and uncomfortable to count. Keep in mind that certain errors will show an incorrect line of code - this happens when the engine knows where something starts and you missed the "end" marker.

Syntax highlighting

Syntax highlighting - note the colours!

If you use syntax highlighting capability that comes with code editors, you will be able to find the bug much more quickly. This is because string literals (the things written in double quotes, "like this") are displayed in a different color then the rest of the text; so if you forget a closing quote, the entire rest of the code will be highlighted in the same colour. Your error will be close to where the colour starts.

Even if the error is of a different nature (it might not be too easy to spot) it will be easier compared to not having syntax highlighting, when the text looks uniformly black.

Most importantly, having syntax highlighting will help you avoid this type of error as you write the script, since you'll be immediately able to see that you've accidentally omitted a quotation mark.

HPL2 engine uses AngelScript for scripting, but since its syntax is almost identical to C++, you can set up your editor to use syntax highlighting for C++. To make scripting more comfortable:

  • In your OS, associate .hps files with your editor (you will be able to double click them and it will start the editor)
  • Associaste the .hps extension with C++. This way you won't have to set the language each time you load a script.
Retrieved from "https://wiki.frictionalgames.com/page?title=HPL2/Tutorials/Scripts/Debugging&oldid=2712"