HPL2/HPL2 Helper Scripts/Debug - Revision history

Mrbehemo at 01:07, 11 February 2024

2024-02-11T01:07:11Z

Mrbehemo at 02:31, 5 December 2023

2023-12-05T02:31:27Z

Mrbehemo: Manual undo of internal link adding - too big a job to do across all pages

2023-11-30T00:32:24Z

Manual undo of internal link adding - too big a job to do across all pages

Mrbehemo: Undo revision 6601 by Mrbehemo (talk)

2023-11-30T00:29:32Z

Undo revision 6601 by Mrbehemo (talk)

Mrbehemo: Added internal links

2023-11-29T23:55:25Z

Added internal links

Mrbehemo: Added internal links

2023-11-29T23:45:34Z

Added internal links

Mrbehemo: Improved spacing.

2023-11-24T18:43:55Z

Improved spacing.

Mrbehemo: Expanded outline structure to better fit multiple classes on a page.

2023-11-24T17:37:41Z

Expanded outline structure to better fit multiple classes on a page.

Mrbehemo at 19:10, 23 November 2023

2023-11-23T19:10:41Z

Mrbehemo: Update links to remove redirects following page move.

2023-11-23T19:08:38Z

Update links to remove redirects following page move.

@@ Line 129: / Line 129: @@
 ===Message()===
-<br>Message() can be used to post a debug message to the log and/or screen. It is as a replacement for AddDebugMessage() and Print().
+<br>Message() can be used to post a debug message to the log and/or screen. It is intended as a replacement for AddDebugMessage() and Print().
 <br>There are multiple overloads of Message() that allow for different types of arguments. In each case the string computation only happens if the message will actually be posted.
 <br>alPrio represents the importance of your message, 1-3. alPrio is checked against the relevant verbosity limit. In general, use priority level 1 for errors, warnings and important messages, level 2 for more general, more frequent debug information, and level 3 for very detailed "spammy" debug messages.

@@ Line 214: / Line 214: @@
 ====Message with string formatting====
 <syntaxhighlight lang="cpp">
-void Message(const alPrio, Str[] argArray)
+void Message(const alPrio, Str@[] argArray)
 void Message(uint alPrio, Str arg0, Str arg1, ... Str arg7);
 </syntaxhighlight>
-The most versatile overload of Message(). This uses the String.Format() method, allowing an arbitrary number of variables to be inserted into a string, using the Str class, regardless of data type. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable. The debug message is a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero.
+The most versatile overload of Message(). The debug message is a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero.
 #''alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
 #''asText'' - The text of the message as a template containing tokens ("{i}") to be replaced by the other arguments.
-#''Str[] argArray, or Str arg0'' - An array of Str instances, or a single Str instance, to replace tokens in the string.
+#''Str@[] argArray, or Str arg0'' - An array of Str handles, or a single Str instance, to replace tokens in the string.
 #''Str arg1 ... Str arg7'' - An additional 7 single Str arguments can be given. '''(Optional, when not using an array.)'''
 <syntaxhighlight lang="cpp">
@@ Line 229: / Line 231: @@
 int lScoreMax = 10;
 Debug.Message(1, "{0} has been given {1}/{2} by {3}!", Str(sSuitorName), Str(lScore), Str(lScoreMax), Str(sPlayerName));
-// outputs "Basile has been given 7/10 by Justine!"
+// Outputs "Basile has been given 7/10 by Justine!"
 // Example 2:
@@ Line 235: / Line 237: @@
 string sMonsterType = "ManPig";
 Debug.Message(1, "Error: Too many {3}s! {0} out of {1} found. Pork = {2}!", Str(lNumMonsters), Str(12), Str(lNumMonsters > 12), Str(sMonsterType));
-// outputs "Error: Too many ManPigs! 13 out of 12 found. Pork = true!"
+// Outputs "Error: Too many ManPigs! 13 out of 12 found. Pork = true!"
 // Note that the numbers match the order of the args, not the order of insertion.
 // Example 3:
-Str[] someArgs(2);
+Str@[] someArgs(2);
 someArgs[0] = Str("strange");
 someArgs[1] = Str("unnartural");
 Debug.Message(3, "The darkness in the Storage feels {0} and {1}.", someArgs);
-// outputs "The darkness in the Storage feels strange and unnatural."
+// Outputs "The darkness in the Storage feels strange and unnatural."
 </syntaxhighlight>
 __FORCETOC__

@@ Line 8: / Line 8: @@
 ===Verbosity===
-The first is '''verbosity levels'''. Verbosity means "wordiness". Debug defines three verbosity values that control how much debug information is posted to screen and log files. The modder can control the verbosity level in script, and create lots of debug output whilst only spamming the screen and log when actually needed. The [[HPL2/HPL2_Helper_Scripts/Debug#SetVerbosity.28.29|SetVerbosity()]] method, and the properties [[HPL2/HPL2_Helper_Scripts/Debug#VerbosityInLogFile|VerbosityInLogFile]], [[HPL2/HPL2_Helper_Scripts/Debug#VerbosityOnScreen|VerbosityOnScreen]] and [[HPL2/HPL2_Helper_Scripts/Debug#LogInReleaseMode|LogInReleaseMode]], can be used to set a verbosity level 0-3 for posting messages to the screen in debug mode, to the log in debug mode and to the log in normal mode.
+The first is '''verbosity levels'''. Verbosity means "wordiness". Debug defines three verbosity values that control how much debug information is posted to screen and log files. The modder can control the verbosity level in script, and create lots of debug output whilst only spamming the screen and log when actually needed. The SetVerbosity() method, and the properties VerbosityInLogFile, VerbosityOnScreen and LogInReleaseMode, can be used to set a verbosity level 0-3 for posting messages to the screen in debug mode, to the log in debug mode and to the log in normal mode.
-<br>When using Debug's [[HPL2/HPL2_Helper_Scripts/Debug#Message.28.29|Message()]] method to post debug messages, they are given a priority level, 1-3, which is checked against the verbosity level. Priority level 1 should be used for errors, warnings and important messages, level 2 for more general, more frequent debug information, and level 3 for very detailed "spammy" debug messages. For example:
+<br>When using Debug's Message() method to post debug messages, they are given a priority level, 1-3, which is checked against the verbosity level. Priority level 1 should be used for errors, warnings and important messages, level 2 for more general, more frequent debug information, and level 3 for very detailed "spammy" debug messages. For example:
 <syntaxhighlight lang="cpp">
 Debug.VerbosityInLogFile = 2;
@@ Line 20: / Line 20: @@
 ===New Types and Formatting===
-Secondly, Debug provides methods to pass multiple '''new argument types'''. As well as composing messages from strings, ints, etc., you can also pass arrays, [[HPL2/HPL2_Helper_Scripts/Lists|lists]], [[HPL2/HPL2_Helper_Scripts/Vectors|vectors]], or make use of the [[HPL2/HPL2_Helper_Scripts/String#Format.28.29|String.Format()]] method and [[HPL2/HPL2_Helper_Scripts/String#Str_class|Str]] class.
+Secondly, Debug provides methods to pass multiple '''new argument types'''. As well as composing messages from strings, ints, etc., you can also pass arrays, lists, vectors, or make use of the String.Format() method and Str class.
@@ Line 55: / Line 55: @@
 uint VerbosityInLogFile
 </syntaxhighlight>
-The integer property VerbosityInLogFile can get or set the minimum priority for Debug messages printed to the log file. (See also: [[HPL2/HPL2_Helper_Scripts/Debug#SetVerbosity.28.29|SetVerbosity()]])
+The integer property VerbosityInLogFile can get or set the minimum priority for Debug messages printed to the log file. (See also: SetVerbosity())
 <syntaxhighlight lang="cpp">
 // Example:
@@ Line 66: / Line 66: @@
 uint VerbosityOnScreen
 </syntaxhighlight>
-The integer property VerbosityOnScreen can get or set the minimum priority for Debug messages shown on-screen. (See also: [[HPL2/HPL2_Helper_Scripts/Debug#SetVerbosity.28.29|SetVerbosity()]])
+The integer property VerbosityOnScreen can get or set the minimum priority for Debug messages shown on-screen. (See also: SetVerbosity())
 <syntaxhighlight lang="cpp">
 // Example:
@@ Line 77: / Line 77: @@
 bool LogInReleaseMode
 </syntaxhighlight>
-The bool property LogInReleaseMode can get or set whether to print debug messages to the log file even when debug mode is off. If set to true, the same priority as VerbosityInLogFile is used. (See also: [[HPL2/HPL2_Helper_Scripts/Debug#SetVerbosity.28.29|SetVerbosity()]])
+The bool property LogInReleaseMode can get or set whether to print debug messages to the log file even when debug mode is off. If set to true, the same priority as VerbosityInLogFile is used. (See also: SetVerbosity())
 <syntaxhighlight lang="cpp">
 // Example:
@@ Line 103: / Line 103: @@
 void SetVerbosity(uint aulOnScreen, uint aulLogAlways, uint aulLogDebug)
 </syntaxhighlight>
-Changes the verbosity limits at runtime. They are not saved, so they will reset to default on level load. (See also: [[HPL2/HPL2_Helper_Scripts/Debug#VerbosityInLogFile|VerbosityInLogFile]], [[HPL2/HPL2_Helper_Scripts/Debug#VerbosityOnScreen|VerbosityOnScreen]] and [[HPL2/HPL2_Helper_Scripts/Debug#LogInReleaseMode|LogInReleaseMode]] properties)
+Changes the verbosity limits at runtime. They are not saved, so they will reset to default on level load. (See also: VerbosityInLogFile, VerbosityOnScreen and LogInReleaseMode properties)
 #''uint aulOnScreen'' - The new minimum priority for Debug messages shown on-screen.
 #''uint aulLogAlways'' - The new minimum priority for Debug messages printed to the log file when debug mode is off.
@@ Line 217: / Line 217: @@
 void Message(uint alPrio, Str arg0, Str arg1, ... Str arg7);
 </syntaxhighlight>
-The most versatile overload of Message(). This uses the [[HPL2/HPL2_Helper_Scripts/String#Format.28.29|String.Format()]] method, allowing an arbitrary number of variables to be inserted into a string, using the [[HPL2/HPL2_Helper_Scripts/String#Str_class|Str]] class, regardless of data type. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable. The debug message is a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero.
+The most versatile overload of Message(). This uses the String.Format() method, allowing an arbitrary number of variables to be inserted into a string, using the Str class, regardless of data type. The Str class is just a container for a variable that can be turned into a string. In other languages we might use a template or a loosely typed variable. The debug message is a string in which tokens like "{i}" have been replaced, where i is the index of the additional arguments, starting from zero.
 #''alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
 #''asText'' - The text of the message as a template containing tokens ("{i}") to be replaced by the other arguments.

@@ Line 165: / Line 165: @@
 #''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
 #''string asText'' - The text of the message, to be appended to.
-#''string arg, uint arg, int arg, float arg, double arg, bool arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cVector|cVector]] arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cPoint|cPoint]] arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cRotator|cRotator]] arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cBezier|cBezier]] arg, or [[HPL2/HPL2_Helper_Scripts/Vectors#cSpline|cSpline]] arg'' - A variable to be appended to the message.
+#''string arg, uint arg, int arg, float arg, double arg, bool arg, cVector arg, cPoint arg, cBezier arg, or cSpline arg'' - A variable to be appended to the message.
 <syntaxhighlight lang="cpp">
 // Example:
@@ Line 178: / Line 178: @@
 void Message(uint alPrio, string asText, cListBase ahList)
 </syntaxhighlight>
-Appends a [[HPL2/HPL2_Helper_Scripts/Lists|list]] object to the message. The list is only evaluated if the message will actually be posted. Any derived list class can be used, including [[HPL2/HPL2_Helper_Scripts/Lists#List_classes|cListInt, cListFloat, cListBool,]] etc.. Uses the [[HPL2/HPL2_Helper_Scripts/Lists#ToStringArray.28.29|ToStringArray()]] function of the list, which is turn uses the ToString() function of the relevant node class. alPrio is optional and defaults to 1 if omitted.
+Appends a [[HPL2/HPL2_Helper_Scripts/Lists|list]] object to the message. The list is only evaluated if the message will actually be posted. Any derived list class can be used, including cListInt, cListFloat, cListBool, etc.. Uses the ToStringArray() function of the list, which is turn uses the ToString() function of the relevant node class. alPrio is optional and defaults to 1 if omitted.
 #''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam).  '''(Optional, default = 1)'''
 #''string asText'' - The text of the message.

@@ Line 165: / Line 165: @@
 #''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam). '''(Optional, default = 1)'''
 #''string asText'' - The text of the message, to be appended to.
-#''string arg, uint arg, int arg, float arg, double arg, bool arg, cVector arg, cPoint arg, cBezier arg, or cSpline arg'' - A variable to be appended to the message.
+#''string arg, uint arg, int arg, float arg, double arg, bool arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cVector|cVector]] arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cPoint|cPoint]] arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cRotator|cRotator]] arg, [[HPL2/HPL2_Helper_Scripts/Vectors#cBezier|cBezier]] arg, or [[HPL2/HPL2_Helper_Scripts/Vectors#cSpline|cSpline]] arg'' - A variable to be appended to the message.
 <syntaxhighlight lang="cpp">
 // Example:
@@ Line 178: / Line 178: @@
 void Message(uint alPrio, string asText, cListBase ahList)
 </syntaxhighlight>
-Appends a [[HPL2/HPL2_Helper_Scripts/Lists|list]] object to the message. The list is only evaluated if the message will actually be posted. Any derived list class can be used, including cListInt, cListFloat, cListBool, etc.. Uses the ToStringArray() function of the list, which is turn uses the ToString() function of the relevant node class. alPrio is optional and defaults to 1 if omitted.
+Appends a [[HPL2/HPL2_Helper_Scripts/Lists|list]] object to the message. The list is only evaluated if the message will actually be posted. Any derived list class can be used, including [[HPL2/HPL2_Helper_Scripts/Lists#List_classes|cListInt, cListFloat, cListBool,]] etc.. Uses the [[HPL2/HPL2_Helper_Scripts/Lists#ToStringArray.28.29|ToStringArray()]] function of the list, which is turn uses the ToString() function of the relevant node class. alPrio is optional and defaults to 1 if omitted.
 #''uint alPrio'' - An integer specifying the priority of the message, 1-3 (rare/important-to-verbose/spam).  '''(Optional, default = 1)'''
 #''string asText'' - The text of the message.

@@ Line 1: / Line 1: @@
 {{TocRight}}
 This page documents "HelperScripts_Debug.hps" - part of ''[[HPL2/HPL2 Helper Scripts]]'', a modder-made package of .hps files by Aetheric Games, containing script classes and functions that may be useful to HPL2 modders and custom story creators. See the [[HPL2/HPL2 Helper Scripts|main page]] for more information, including [[HPL2/HPL2 Helper Scripts#Set-up|set-up instructions]].
 =Summary=
 The script file "HelperScripts_Debug.hps" provides more control and options for how debug messages are written to the screen and to the log. There are three purposes behind Debug.
 ===Verbosity===
@@ Line 15: / Line 17: @@
 Debug.Message(3, "With the current settings, this won't appear anywhere.");
 </syntaxhighlight>
 ===New Types and Formatting===
 Secondly, Debug provides methods to pass multiple '''new argument types'''. As well as composing messages from strings, ints, etc., you can also pass arrays, lists, vectors, or make use of the String.Format() method and Str class.
 ===Performance===
@@ Line 30: / Line 34: @@
 </syntaxhighlight>
 Both examples give the same output, visually. In example 1, the work to compose the final string happens at the point of calling AddDebugMessage(), ''regardless of whether debug mode is active or not''. That's not a big deal if it's not used often, but processing a lot of complex debug messages can have a performance impact even while the player is playing the game outside of debug mode. In example 2, Debug provides methods to pass the parts of the string as individual arguments, and the string computation only takes place if the message will actually be posted to the screen or log file. This doesn't improve performance in debug mode, but if a lot of complex debug messages are used then it will improve performance in normal play mode.
 =Debug=
 ==Behaviours==
@@ Line 39: / Line 45: @@
 Debug.LogInReleaseMode = false;
 </syntaxhighlight>
 ==Properties==
 Debug provides the following properties:
 ====VerbosityInLogFile====
@@ Line 52: / Line 60: @@
 Debug.VerbosityInLogFile = 3;
 </syntaxhighlight>
 ====VerbosityOnScreen====
@@ Line 62: / Line 71: @@
 Debug.VerbosityOnScreen = 1;
 </syntaxhighlight>
 ====LogInReleaseMode====
@@ Line 72: / Line 82: @@
 Debug.LogInReleaseMode = true;
 </syntaxhighlight>
 ====CheckForDuplicates====
@@ Line 82: / Line 93: @@
 Debug.CheckForDuplicates = true;
 </syntaxhighlight>
 ==Methods==
 Debug provides the following methods:
 ====SetVerbosity()====
@@ Line 98: / Line 111: @@
 Debug.SetVerbosity(0, 1, 3);
 </syntaxhighlight>
 ====TestPriority()====
@@ Line 112: / Line 126: @@
+}
 </syntaxhighlight>
 ===Message()===
@@ Line 117: / Line 132: @@
 <br>There are multiple overloads of Message() that allow for different types of arguments. In each case the string computation only happens if the message will actually be posted.
 <br>alPrio represents the importance of your message, 1-3. alPrio is checked against the relevant verbosity limit. In general, use priority level 1 for errors, warnings and important messages, level 2 for more general, more frequent debug information, and level 3 for very detailed "spammy" debug messages.
 ====Basic message====
 <syntaxhighlight lang="cpp">
@@ Line 129: / Line 146: @@
 Debug.Message("Something else has happened."); // Priority 1.
 </syntaxhighlight>
 ====Message appended with a variable====
 <syntaxhighlight lang="cpp">
@@ Line 153: / Line 172: @@
 // outputs "Player is in spooky zone: true" at verbosity level 2
 </syntaxhighlight>
 ====Message appended with a list====
 <syntaxhighlight lang="cpp">
@@ Line 169: / Line 190: @@
 // outputs "Let's print some floats: [11.1], [2.22]" at verbosity level 3
 </syntaxhighlight>
 ====Message appended with an array====
 <syntaxhighlight lang="cpp">
@@ Line 187: / Line 210: @@
 // outputs "You're a: [good], [boy], [Daniel]" at verbosity level 1
 </syntaxhighlight>
 ====Message with string formatting====
 <syntaxhighlight lang="cpp">

← Older revision		Revision as of 19:10, 23 November 2023
Line 220:		Line 220:

	__FORCETOC__		__FORCETOC__
−	~~__NOINDEX__~~