Debug OXP - Revision history

Cholmondely: /* Links */ Added links to recent work

2024-09-22T19:41:22Z

‎Links: Added links to recent work

Cholmondely: Added link

2024-07-01T09:45:37Z

Added link

Cholmondely: /* Profiling */ Updated link

2024-06-30T09:14:23Z

‎Profiling: Updated link

Cag: removed duplicate link to topic f=4&t=20512

2024-05-28T05:26:21Z

removed duplicate link to topic f=4&t=20512

Phkb: Updating BB links

2024-02-29T01:33:02Z

Updating BB links

Cholmondely: Added an introductory snippet by a_c

2024-01-23T15:37:34Z

Added an introductory snippet by a_c

Cholmondely: /* Links */ Added another

2023-12-26T18:44:34Z

‎Links: Added another

Alnivel: /* The console script */ Updated the example and added a section about using variables

2023-05-26T21:01:24Z

‎The console script: Updated the example and added a section about using variables

Alnivel: Added "Profiling" section

2023-05-26T18:10:18Z

Added "Profiling" section

Alnivel: /* Console Properties */ Rearranged and formatted section

2023-05-26T16:59:09Z

‎Console Properties: Rearranged and formatted section

@@ Line 318: / Line 318: @@
 == Links ==
 * [https://bb.oolite.space/viewtopic.php?f=3&t=20965 How do I? .... (on Debug Console)] (2021) - change system, change ship... - 2 pages
@@ Line 325: / Line 327: @@
 * [https://bb.oolite.space/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (cag 2020) - an improved console for Linux & Windows

@@ Line 26: / Line 26: @@
 The Debug menu provides options to
 * Show the Oolite run log in the standard [[OXP_howto#OXP_Verifier|Console]] application.
-* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
+* Enable or disable various classes of log message at runtime (like editing [[logcontrol.plist]], without the need to restart Oolite).
 * Enable various testing features, such as drawing of bounding boxes.
 * Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)

@@ Line 172: / Line 172: @@
 Once the bottlenecks have been identified, then you know where you need to turn to and apply all the tips contained here. If you want performance, always profile.
-|Source=([https://bb.oolite.space/viewtopic.php?p=257063#p257063 another_commander] regarding [[Optimization_tips|optimization tips]])}}
+|Source=([https://bb.oolite.space/viewtopic.php?p=257063#p257063 another_commander] regarding [[Javascript optimization tips]])}}
 ==== <code>profile</code> ====

@@ Line 325: / Line 325: @@
-* [https://bb.oolite.space/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (CAG 2020) - an improved Debug console - see below
+* [https://bb.oolite.space/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (cag 2020) - an improved console for Linux & Windows
 * [https://bb.oolite.space/viewtopic.php?f=4&t=17731 Some Tips] on using the Debug Console (2015) - 1 page
 * [https://bb.oolite.space/viewtopic.php?f=4&t=12030 Hints and tips for using the debug console] (2012) - 5 pages

@@ Line 19: / Line 19: @@
 == Mac OS X-specific features ==
-Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms. This was originally written by [http://www.aegidian.org/bb/viewtopic.php?f=8&t=3661 Jens Ayton/Ahruman] for version 1.69 (TR) back in 2007. To use this you need the '''Debug OXP''' in your AddOns folder ''and'' the '''Test Release''' version of Oolite.
+Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms. This was originally written by [https://bb.oolite.space/viewtopic.php?f=8&t=3661 Jens Ayton/Ahruman] for version 1.69 (TR) back in 2007. To use this you need the '''Debug OXP''' in your AddOns folder ''and'' the '''Test Release''' version of Oolite.
 === Debug menu (Mac OS X only) ===
@@ Line 172: / Line 172: @@
 Once the bottlenecks have been identified, then you know where you need to turn to and apply all the tips contained here. If you want performance, always profile.
-|Source=([http://www.aegidian.org/bb/viewtopic.php?p=257063#p257063 another_commander] regarding [[Optimization_tips|optimization tips]])}}
+|Source=([https://bb.oolite.space/viewtopic.php?p=257063#p257063 another_commander] regarding [[Optimization_tips|optimization tips]])}}
 ==== <code>profile</code> ====
@@ Line 208: / Line 208: @@
   console.getProfile(function(){PS.position.add([0, 0, 0])})
-<!-- Seems like it is broken now - it just executes function silently, but it should do this - http://www.aegidian.org/bb/viewtopic.php?p=127089#p127089
+<!-- Seems like it is broken now - it just executes function silently, but it should do this - https://bb.oolite.space/viewtopic.php?p=127089#p127089
 ==== <code>trace</code> ====
   function '''trace'''(func : function [, this : Object]) : Object
@@ Line 317: / Line 317: @@
 == Links ==
-* [http://www.aegidian.org/bb/viewtopic.php?f=3&t=20965 How do I? .... (on Debug Console)] (2021) - change system, change ship... - 2 pages
+* [https://bb.oolite.space/viewtopic.php?f=3&t=20965 How do I? .... (on Debug Console)] (2021) - change system, change ship... - 2 pages
-* Debug console issues: [http://www.aegidian.org/bb/viewtopic.php?f=10&t=20877 Problem with external debug console on Mac] (2021+)
+* Debug console issues: [https://bb.oolite.space/viewtopic.php?f=10&t=20877 Problem with external debug console on Mac] (2021+)
-* [http://aegidian.org/bb/viewtopic.php?f=9&t=12779 Handy tip for starting the Debug Console in Linux] (2012)
+* [https://bb.oolite.space/viewtopic.php?f=9&t=12779 Handy tip for starting the Debug Console in Linux] (2012)
-* [http://aegidian.org/bb/viewtopic.php?f=9&t=21459&p=291751#p291751 Debug Console on Ubuntu 22.04 - problems] (2023)
+* [https://bb.oolite.space/viewtopic.php?f=9&t=21459&p=291751#p291751 Debug Console on Ubuntu 22.04 - problems] (2023)
-* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (CAG 2020) - an improved Debug console - see below
+* [https://bb.oolite.space/viewtopic.php?f=4&t=20512 (WIP) new GUI for debug console] (CAG 2020) - an improved Debug console - see below
-* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=20512 Debug Console] for Python and Windows (CAG 2020)
+* [https://bb.oolite.space/viewtopic.php?f=4&t=20512 Debug Console] for Python and Windows (CAG 2020)
-* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=17731 Some Tips] on using the Debug Console (2015) - 1 page
+* [https://bb.oolite.space/viewtopic.php?f=4&t=17731 Some Tips] on using the Debug Console (2015) - 1 page
-* [http://www.aegidian.org/bb/viewtopic.php?f=4&t=12030 Hints and tips for using the debug console] (2012) - 5 pages
+* [https://bb.oolite.space/viewtopic.php?f=4&t=12030 Hints and tips for using the debug console] (2012) - 5 pages

← Older revision		Revision as of 15:37, 23 January 2024
Line 2:		Line 2:

	'''To run this OXP you need the [http://www.oolite.org/download/ ''OXP Developer release''] version of Oolite.''' There are subtle differences between the versions for each of the three platforms (AppleMac, Windows & Linux).		'''To run this OXP you need the [http://www.oolite.org/download/ ''OXP Developer release''] version of Oolite.''' There are subtle differences between the versions for each of the three platforms (AppleMac, Windows & Linux).
		+
		+	== Overview ==
		+	The Debug OXP/Debug Console is an external app that allows you to execute Javascript commands, methods ''etc.'' from within the game, in real time. Any property that is visible to the JS interface can be viewed and, if writeable, changed on the fly. Scripts can be set up and executed on the fly. Ships can be spawned, huds changed, supernovas initiated, you get the idea.

	=== Downloads ===		=== Downloads ===

@@ Line 210: / Line 210: @@
 Logs the hierarchy of calls made, which can help track down where an error is occurring.
 -->
 === The console script ===
@@ Line 223: / Line 279: @@
+  {
       // Ensure debug console is installed
-      if (!debugConsole)  return
+      if (!console)  return
-      // Save original implementation of consolePerformJSCommand
+      // Save the original implementation of consolePerformJSCommand
       // Note the prefix, used to ensure uniqueness. If several scripts patch
       // the same method, it's important that they use different names.
-      debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand
+      console.script.mySuperConsoleMacros_original_consolePerformJSCommand = console.script.consolePerformJSCommand
-      // Replace debugConsole.consolePerformJSCommand with custom function
+      // Replace console.script.consolePerformJSCommand with custom function
-      debugConsole.consolePerformJSCommand = function(command)
+      console.script.consolePerformJSCommand = function(command)
+      {
-          // Note that in this function "this" will refer to debugconsole, not
+          // Note that in this function "this" will refer to console.script, "oolite-debug-console", not
-          // my-super-console-macros, since the function will be called as a
+          // "my-super-console-macros", since the function will be called as a
-          // method of debugConsole.
+          // method of the console.
-          // Strip leading spaces, same code as original function.
+          // Strip leading spaces, same code as the original function.
           while (command.charAt(0) == " ")
+          {
@@ Line 250: / Line 306: @@
           else
+          {
-              // Otherwise, call through to original method.
+              // Otherwise, call through to the original method.
-              debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
+              console.script.mySuperConsoleMacros_original_consolePerformJSCommand(command)
+          }
+      }

← Older revision		Revision as of 18:10, 26 May 2023
Line 159:		Line 159:

	<!-- There is also boolean pedanticMode (r/w), but I failed to find what this even means, except that it's not "use strict" -->		<!-- There is also boolean pedanticMode (r/w), but I failed to find what this even means, except that it's not "use strict" -->
		+
		+	=== Profiling ===
		+	{{QuoteText\|Text=
		+	Just pointing out the obvious here, but I think it needs to be noted that all these optimization techniques explained here are not themselves the objective, but the means to get performance. These techniques are not there to jump in and start writing complicated code. They should be used when there is need and where they are needed. And to find this out, the biggest weapon we have is profiling. I fully recommend that before you change anything in your code, you profile it and find out where it really needs attention.
		+
		+	Oolite Test Release writes something in the log header that may have escaped the attention of many, but if you look more carefully, you'll see it: It says: Build options: [...] JavaScript profiling. So you can use Oolite itself to see where bottlenecks in your OXP might be and then you can apply all these techniques exactly where there is a gain to be obtained.
		+
		+	. . .
		+
		+	Once the bottlenecks have been identified, then you know where you need to turn to and apply all the tips contained here. If you want performance, always profile.
		+	\|Source=([http://www.aegidian.org/bb/viewtopic.php?p=257063#p257063 another_commander] regarding [[Optimization_tips\|optimization tips]])}}
		+
		+	==== <code>profile</code> ====
		+	function '''profile'''(func : function [, this : Object]) : String
		+	Time the specified function, report the time spent in various Oolite functions and how much time is excluded from the time limiter mechanism. If the second argument isn't specified it defaults to the console world script.
		+
		+	Example of use:
		+	console.profile(function() { return this._systemName(42) }, worldScripts["oolite-contracts-helpers"])
		+	It will result in something like this:
		+	Total time: 0.059 ms
		+	JavaScript: 0.034 ms, native: 0.024 ms
		+	Counted towards limit: 0.0439983 ms, excluded: 0.0150017 ms
		+	Profiler overhead: 0.034 ms
		+	NAME T COUNT TOTAL SELF TOTAL% SELF% SELFMAX
		+	(oolite-contracts-helpers.js:161) <anonymous> J 1 0.05 0.02 81.4 40.7 0.02
		+	SystemInfoGetProperty N 4 0.02 0.01 28.8 20.3 0.01
		+	(<console input>) <anonymous> J 1 0.06 0.01 98.3 16.9 0.01
		+	GetJSSystemInfoForSystem N 1 0.00 0.00 8.5 8.5 0.00
		+	OOJSNativeObjectFromJSObject N 4 0.00 0.00 6.8 6.8 0.00
		+	SystemStaticInfoForSystem N 1 0.01 0.00 10.2 1.7 0.00
		+	OOStringFromJSString N 4 0.00 0.00 1.7 1.7 0.00
		+	GlobalGetProperty N 1 0.00 0.00 1.7 1.7 0.00
		+	-[NSString(OOJavaScriptExtensions) oo:jsValueInContext:] N 1 0.00 0.00 0.0 0.0 0.00
		+	The table contains the trace of the calls, with separate metrics for each one of them, as well as their type (J for Javascript, N for Native).
		+
		+	You may want to copy the result to the editor with a monospace font if the columns don't appear to be aligned.
		+
		+
		+	'''Note:''' while profile() is running, the time limiter is effectively disabled (specifically, it's set to ten million seconds).
		+
		+
		+	==== <code>getProfile</code> ====
		+	function '''getProfile'''(func : function [, this : Object]) : Object
		+	Like <code>profile()</code>, but returns an object, which is more amenable to processing in scripts. To see the structure of the object, run:
		+	console.getProfile(function(){PS.position.add([0, 0, 0])})
		+
		+	<!-- Seems like it is broken now - it just executes function silently, but it should do this - http://www.aegidian.org/bb/viewtopic.php?p=127089#p127089
		+	==== <code>trace</code> ====
		+	function '''trace'''(func : function [, this : Object]) : Object
		+	Logs the hierarchy of calls made, which can help track down where an error is occurring.
		+	-->

	=== The console script ===		=== The console script ===

@@ Line 75: / Line 75: @@
 === Console Properties ===
-The console has several properties. They are accessible with "console.Foo":
+The <code>console</code> object has several properties. To see the full list of them check <code>oolite-debug-console.js</code> inside your copy of the Debug OXP.
-With <code>debugFlags</code> you can selective set/disable debugging options. Every debugging option is activated by setting a corresponding bit in the <code>debugFlags</code>:
+==== Debug Flags ====
-  Linked Lists                = 0x00000001
+ '''debugFlags''' : Number (integer, read/write)
-  Collisions                  = 0x00000004
+An integer bit mask specifying various debug options. Note that the flags vary between builds.
-  Docking                     = 0x00000008
+The current flags can be seen in OODebugFlags.h in the Oolite source code, for instance at:
-  Octrees - Verbose Logging   = 0x00000010
+https://github.com/OoliteProject/oolite/blob/master/src/Core/Debug/OODebugFlags.h
-  Bounding Boxes              = 0x00000040
-  Octrees - Draw              = 0x00000080
+  DEBUG_LINKED_LISTS       = 0x00000001
-  Normals                     = 0x00000100
+  DEBUG_COLLISIONS         = 0x00000004
-  Hide Dust		    = 0x00000200
+  DEBUG_DOCKING            = 0x00000008
-  disable Shader Fallback	    = 0x00000400
+  DEBUG_OCTREE_LOGGING     = 0x00000010
-  Extra Shader Validation	    = 0x00000800
+  DEBUG_BOUNDING_BOXES     = 0x00000040
-  Miscellaneous	            = 0x10000000
+  DEBUG_OCTREE_DRAW        = 0x00000080
 === The console script ===