Debug Essentials Documentation - 0.0.3

debug-essentials-doc-0.0.3.txt

		//----------  Debugging Essentials by Edward Neave  ----------//
If you have any issues, feedback or suggestions please don't hesitate to let me know on the itch.io
page or you can email me at feetupgaming@gmail.com

Please be aware that i can only provide assistance with the functions and tools and cannot help with
integration of these functions as this will depend heavily on your own unique project.


("**" indicates a function which is available in the free demo version)


//----------Notable Macros and Variables
dE_LogFileSize - Can be used to modify the max log file size before a new one will be create.

dE_LogFileDir - Where the log file will be saved to and modified from.

dE_logFileName - The name and extensive of the current event log file

dE_logFileNameOld - The name and extension of the old (full) event log file

dE_overlayColor - Sets the color of font and basic shapes to use for the overlay
	functions.

global.dE_showObjectName - Boolean to determine if the object is shown at the end of debug messages.

global.dE_showEventName - Boolean to determine if the event is shown at the end of debug messages.

global.dE_loggingLevel - Sets the current logging severity level filter, only log events of
	the set level or lower will be saved to the log file
	(unless using log_event_custom function).
	
dE_showNotifications - Enable/disable the creation and displaying of notifications when using notify() function

dE_notificationShadowEnabled - Enabled/disable the basic drop shadow of the notification text
	CAUTION: This is not an optimised drop shadow and may cause performance issues with larger projects
	or when used on older hardware.

dE_notificationDrawTime - How long in seconds to draw notifications on screen for (default 1.5 seconds)


//----------Debugging Functions
**debug( value, ... ); - Shows a debug message, Accepts multiple arguments all value types,
	joins arguments together and adds prefix of "Debug > " and suffix of the object name
	in current scope if possible.
	
**debug_warning( value, ... ); - Shows a debug message same as debug()
	but with the prefix "Warning > ".
	
**debug_error( value, ... ); - Same as debug_warning only with the prefix "ERROR > ".

debug_delayed( value, ... ); - Acts the same as debug() but will attempt to only show
	debug message once every second to allow use in step or draw events so to not
	flood the output console.
	
**debug_custom( prefix, value, ...); - Will show a debug message with a custom prefix
	For example this is used in the benchmarking functions to give a prefix "Benchmark"
	
**debug_spacer(  ); - Inserts a spacer of characters with time stamp and new line in the
	output console to make reading important messages easier.


//----------Logging Functions
log_info_event( value, ... ); - Appends an event of the given values to the log file
	at level 3 (Info), which will only be saved if the global.dE_loggingLevel variable
	is set at that level or higher. The log file can usually be found in local app data
	working directory + logs/log.txt by default.
	
log_warning_event( value, ... ); - Logs a level 2 (Warning) event to the log file
	global.dE_loggingLevel must be set to 2 or higher.

log_critical_event( value, ... ); - Logs a level 1 (Critical) event to the log file
	global.dE_loggingLevel must be set to 1 or higher.
	
log_custom_event( level, value, ... ); - This function can be used to log events at custom
	levels of severity however these will completely ignore the current loggingLevel and
	will always be saved to the log file.


//----------Overlay Functions
debug_draw_mouse(  ); - Draws vertical and horizontal assistive lines accross the project and
	displays the mouses gui and room position for helping with placing objects and UI elements

**debug_draw_fps(  ); - Draws a simple fps and averaged fps_real value in the top left of the
	screen, a little quicker than typing draw_text it manually.

debug_draw_collisions( object ); - Draws collision boxes aligned on h/v axis, object is defaulted
	to the "all" keyword which will draw collision boxes for all objects if visible and has a sprite
	
debug_draw_collisions_rotated( object ); - Draws collision boxes respecting the objects rotation


//----------Notification Functions
notify( text, color ); - Adds a notification to be displayed with the given text and color

notifications_draw( x, y, width, horizontalAlign, verticalDirection ); - Draw the notifications array
	to the screen at the given position and text will stay within the given width. The text will be
	alligned horizontally and the vertical direction determines how the notifications are displayed.
	a verticalDirection (_vdir) of -1 will make the notifications move upwards with newest at the bottom
	and verticalDirection of 1 will make them go downwards with newest at the top.


//----------Tools Functions
**induce_lag( level ); - Induces lag on the project at the given level, This can help with stress
	testing your projects
	
induce_chaotic_lag( level ); - The same as induce_lag however the amount of lag per frame is
	random to provide a more chaotic stress test. May be more realistic depending on project.

benchmark_start( name ); - Starts a benchmark time test, which stores the current microsecond
	value to benchmark the time it takes for different scripts. If a name is given that already
	exists the previous one will be ended before starting a new test (lap style feature)
	
benchmark_end( name ); - Ends the given benchmark time test, and gives a custom debug message
	of the result, will give a debug_warning if the given name doesn't exist as a benchmark.


//----------Other Functions
**get_time_stamp(  ); - Used for debug messages and log events. It returns the current system time
	as "hour:minute:second".
	
**get_date_stamp(  ); - Used for log events. Returns the current system date as "Year-Month-Day".

**event_get_name( event ); - Used within the debug message functions, it returns the name as a
	string of the provided event number.

**debug_get_object(  ); - Used in debug message and critical log event functions, attempts to
	return the name of the object within current scope. This can cause errors if used during
	compile so i have wrapped it within an empty try/catch block.