prodebug | plugin for unity - ivxivprodebug | plugin for unity v. 2.0.0 by ivxiv software :...

20
ProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : www.ivxiv.com ProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : www.ivxiv.com

Upload: others

Post on 04-Aug-2020

37 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

Page 2: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

TableofContents

Introduction....................................................................................................................................................................................3

Overview.........................................................................................................................................................................................3

Enhanced“Debug”Class..................................................................................................................................................................5

DemoExamples...............................................................................................................................................................................6CrashReportGUIOverlay(CrashHandlerExample.cs,CrashUploaderExample.cs).....................................................................................................................6UserCrashReportviaEmail.................................................................................................................................................................................................................................7HierarchicalDebugMenuSystem(DebugMenuExample.cs,GUIDebugMenu…cs)............................................................................8

C#CommandExecutor(DebugCommandExecutor.cs)...................................................................................................................10

HOWTOSetupSteps......................................................................................................................................................................12Debug/Assertions/Must..................................................................................................................................................................................................................................12CustomDebugActionHandlers........................................................................................................................................................................................................................12Example:CrashUploader..............................................................................................................................................................14

Example:DebugMenu..................................................................................................................................................................15GUIDebugMenuDisplaySettings.......................................................................................................................................................................................................................18Contact.........................................................................................................................................................................................20

Page 3: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

IntroductionTheProDebugpluginforUnitymakesasuiteofpowerfuldebuggingaidsavailabletoallUnitydevelopers,enablingyoutodebugyourapplicationsmorequicklyandefficientlytohelpproducethehighestqualitysoftwareproductpossible!TheProDebugpluginsupportsUnityversions3.5andup,andhasbeentestedagainstUnityversionsasrecentas2017.DemosofProDebugareavailableonlineat:http://www.ivxiv.com/Unity/ProDebug/ProDebug.html

OverviewThispackageincludesanumberofinvaluabledebuggingaidsthatyouendupre-implementingforeachnewprojectorgameengine:

• Adrop-inreplacementfortheUnityEngineDebugclass,AssertandMustextensions.ThereplacementDebugclassallowsyoutoattachyourowncodeintotheDebuglogging,assertionandexceptionhandlers.

• Ahierarchicaldebug-GUImenusystem–toallowforaquickandeasymethodforprogrammerstohookupaGUIinveryquickly!Themenucanbeconstructedeitherdirectlyincode,orinUnity5.3andlatercompletelyinJSON,makinguseofC#reflectiontotiethemenudescriptionJSONintoyourcode.

• Anexampledebugloggingutility–demonstratingattachinghandlerstothereplacementDebugclass,toprovideforloggingtoaconsoledisplay,toafile,toanetworkresource,etc.

• Exampleautomatedcrash-reportingsystem–thisexampleclassattachestothereplacementDebugclasstodemonstratehowonecansendvaluabledatafromcrashesthatoccuronteammembers’systemsduringdevelopmentandtesting(orinthewild)uptoanetworkresource.

• Acommandconsoleinputsystem–toallowforentryofcustomcommandsatatextinputconsoleforimmediateexecutionatruntime.

Page 4: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

MoredetailsontheutilitiesincludedintheProDebugpluginforUnity:

• Enhanced“Debug”class[Debug.cs]:thisisadrop-inreplacementforUnity’sbuilt-inDebug class,whichprovidesallthesamefunctionalityasUnityEngine.Debugbutwithimprovedperformanceandthefollowingextrafeatures:

o Customizableloggingbehavior–youhavecompletecontroloverthebehavioroftheDebug.Log(),Debug.LogWarning(),Debug.LogError()andDebug.LogException()methods.ThedefaultProDebugbehaviorforthesemethodcallsistypicallyanorderofmagnitudefasterthanthedefaultUnityEngine.Debugloggingmethodsintermsofruntimeperformance,especiallyonmobileplatforms.

o UnhandledExceptionsatruntimecanberoutedthroughtheDebugloggingsystemautomatically(veryusefulforcatchingunhandledexceptionswhichwouldotherwisepassthroughtheUnityEditorenvironmentwithnothingmorethanalogentry,butwouldotherwiseresultinanapplicationterminationon-devicewhenrunningoniOSorAndroidplatforms,forexample).Catchnastybugsbeforetheymakeitontodevice!

o OlderversionsofUnitycannowaccesstheAssert()methodsandMustextensionsintroducedrecently.• HierarchicalDebugMenuSystem[GUIDebugMenu.csandfriends]:Acompletehierarchicalmenusystembuiltupon

theUnityGUI,whichincludesGUIwidgetsforthefollowingtypeofmenuentries:o RuntimemanipulationofC#primitivetypes(Boolean, Byte, SByte, Char, Int16, UInt16,

Int32, UInt32, Int64, UInt64, Single, Double, Decimal, String, Enum)aswellasthefollowingUnitytypes:Color, Color32, Vector2, Vector3 and Vector4

o Runtimefunctionexecution(executecodewhenselected)o MenuscanbeconstructedfromJSON(Unity5.3+)ordirectlyfromsourcecode.

• Cross-platformlogfileexample[Demo/DebugLogger.cs]:thisexampleclassusesthereplacementDebugclasstoprovideautomaticloggingtofileofallDebug.Log(),Debug.LogWarning(),Debug.LogError()andDebug.LogException() calls,forruntimeplatformsthatsupportfileIO.

• C#CommandExecutor[Demo/DebugCommandExecutor.cs]:AsimpleclasswhichallowsforexecutionofarbitraryC#staticmethods,witharguments,atruntime.

• Examplecrashreportingsystem[Demo/CrashUploaderExample.cs]:crashreportssentviaemail,aswellaswithanexampleimplementationofautomaticHTTPuploadofcrashreports

• Theentiresystemcanbedisabledwithasinglecompile-timeoption,toremovealldebugfunctionalityfromproductioncode.

Page 5: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

ThefollowingsectionsgointodetailoneachoftheseaspectsoftheProDebugplugin.

Enhanced“Debug”ClassTheenhancedDebugclasstakesadvantageofC#assembly/namespaceprecedenceconventions,andbyusingmethodswithidenticalcallingsignaturestothoseoftheUnityEngine.Debugclass,providesforaseamlessdrop-inreplacement.ItsimplementationoftheDebug.Log(),Debug.LogWarning(),Debug.LogError()andDebug.LogException()methodsaretocallintoevents,towhichdelegatesareattached.Inthisway,onehascompletecontrolovertheruntimebehaviorofthesemethods.Tieintothefollowingeventstotakeadvantageofthesehooks:

• Debug.OnLog • Debug.OnWarning • Debug.OnError • Debug.OnException • Debug.OnAssertionFail

ReviewDebug.cs, Assert.cs and Must.cssourcefilesformoreinformation.

Page 6: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

DemoExamplesWiththeincludedexampleproject,themainscenecontainsaGameObjectnameddebug_managerwhichhasanumberofMonoBehavioursattachedtoittoprovideinterestingfunctionality,suchasaadebugGUImenusystem,crash-reportingsystemwithanuploader(whichsimplybouncesthecrashinformationoffofanechoserverviaHTTP)thatishookedintotheenhancedDebugclassassertmethodsandunhandledexceptionreportermakeuseofinordertopropagatetheseeventsuptotheusersothatdiagnosticinformationcanbedisplayedthemomentanassertionfailsoranexceptionisraisedandgoesunhandled.ThinkofitasafriendlyBSODJ.Theseexampleuseswillnowbedescribedinmoredetail.

CrashReportGUIOverlay(CrashHandlerExample.cs,CrashUploaderExample.cs)Intheeventofanassertionfailureoranunhandledexception,afull-screenoverlaywillbedisplayedtotheuser,containingadescriptivemessageidentifyingwhathasjustoccurredalongwithafullcallstackfromthetimeofthecrash.IfyouarerunningintheUnityEditor,orwithadebuggerattached,youwillalsobreakatthetimeofthecrash.Assumingtheprogramisabletosurvivewhateverhasjustoccurred,youhavethefollowingoptionsavailabletoyouatthiscrashreporterGUIoverlay:

• SendanemailcontainingaURL-encodedreportofthecrash(optionallyincludingthefullcontentsofthedebuglogfile,ifthe“+log”toggleisselected),onplatformswithanavailableemailclient.

• Copythecontentsofthecrashreportmessageandcallstack(thetextisdisplayedinawidgetwhichwillallowyoutoselectandcopythecontents,butnoteditthem)

• Whenfinishedviewingthereport,theusercanclickthe“Dismiss”buttontoclosethecrashreportGUIoverlay.

Page 7: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

UserCrashReportviaEmailAsmentionedearlier,thecrashreportGUIoverlayprovidesamechanismtoemailcrashreportstoadestinationofyourchoosing(thedefaultdestinationaddressisconfigurableinthescriptcomponent,butofcoursetheusercanoverridethisintheiremailclientaswell).Thesubjectandcontentsoftheseemails(includingthecontentsofthedebuglogfile,ifincluded)areURLencodedforcross-applicationandInternettransportability.Thedecodingistrivial–forexample,PHP’surldecodemethod.TheimagetotherightisanexampleofonesuchcrashreportbeingsentfromaniPhoneappusingtheProDebugplugin.PassingthecontentsofthisemailthroughaURLdecoderwillresultintheoriginalcrashreporttextbeingrecovered.

Page 8: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

HierarchicalDebugMenuSystem(DebugMenuExample.cs,GUIDebugMenu…cs)TheProDebugpluginincludesafullhierarchicalmenusystembuiltupontheUnityGUI,whichincludesGUIwidgetsforthefollowingtypeofmenuentries:

• RuntimemanipulationofthestandardC#primitivetypes(Boolean, Byte, SByte, Char, Int16, UInt16, Int32, UInt32, Int64, UInt64, Single, Double, Decimal, String, Enum)

• RuntimemanipulationofUnitytypes:Color, Color32, Vector2, Vector3 and Vector4(thesecanbeusedastemplatesforothervectortypes,ifdesired)

• Runtimefunctioncallbackexecution(executecodewhenselected)

• Submenuentry(acontainerofasubmenuofmoreentries)

YourcustommenuscanbeconstructedfromJSON(seesample_menu.json)whenusingUnity5.3+,ordirectlyincodeaswell(thoughmuchmoretedious).MenufieldsattachtostaticvariablesandmethodsinyoursourcecodeusingC#reflection.Thetop-levelmenubarisimplementedasatoolbar,optionallyalways-onortoggledbytheleft-mostbutton(inthesampleproject,thisbuttonisthe‘ladybug’button).Thistop-levelmenucanbepositionedateitherthetopedgeorbottomedgeoftheplayerscreen,bymeansofthe“Location”property.Thetop-levelmenusareexpanded/collapsedbyclickingonthetoolbarbuttons,andfortoolbarmenusthatexceedthewidthofthescreen,ahorizontalscrollbarallowsnavigationbackandforth

Page 9: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

acrossthelengthofthemenu.Similarly,forexpandedverticalmenusthataretallerthanthescreen,averticalscrollbarwillallownavigationalongthelengthofthemenu.Thefollowinginteractionswithmenuelementsaresupported:

• Booleanvaluemanipulatorsareradiotogglebuttons.• Numericvaluemanipulatorsarerepresentedasaslider,allowingmanipulationacrossafiniterangeofvalues.• Stringvaluemanipulatorsarerepresentedasaneditabletextfield.• Enumvaluemanipulatorsarerepresentedbyabuttonthatcanbeclickedtocyclethroughtherangeofpossiblevalues.• VectorandColorvaluemanipulatorsarerepresentedbyaseriesofslidersallowingmanipulationofeachcolorchannel.• Functioncallbackmenuitemsarerepresentedbyabuttonthatwhenclickedcausestheattachedfunctioncallbacktobe

invoked.• Submenuitemsarerepresentedbyabuttonwhencollapsed,andwhenclickedcausetheirmenubranchtosupplantthe

existingverticalmenu(andsoon,foreachlevelofdepthinthemenuhierarchy).Tonavigatebackupalevelinasubmenuhierarchy,clicktheparenttoolbarmenubutton.

Page 10: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

C#CommandExecutor(DebugCommandExecutor.cs)TheProDebugpluginincludesa“commandconsole”systembywayoftheDebugCommandExecutorclass.ThisclassprovidesamethodbywhichyoucaninvokeanyarbitraryC#staticmethodwithappropriateargumentsatruntime.ThesystemusesC#reflectionforitsfunctionality.ThesyntaxforthesecommandstringentriestotheDebugCommandExecutorisasfollows:[AssemblyName:]ObjectType.Method arg0 arg1 ... ; where:

• AssemblyNameisanoptionalparameter,specifyingthenameoftheassemblycontainingthemethodyouareinvoking.Thisisonlynecessaryifthemethodyouareinvokingiscompiledintoanexternalassemblylinkedintoyourapplication(forexample,anythingcontainedintheUnityEngineassembly).IfAssemblyNameisspecified,acoloncharacter(‘:’)mustfollowitimmediately.

• ObjectTypeisthefullyqualifiednameoftheclasscontainingthemethodyouareinvoking.Aperiod‘.’charactermustimmediatelyfollowtheObjectTypeparameter.

• Methodspecifiesthestaticmethodyouwishtoinvoke.• Anyrequiredargumentsshouldfollowthemethodname,allseparatedbyawhitespacecharacter,inthesameformat

thattheywouldtypicallybeenteredinC#code.• Finally,aterminatingsemicolon‘;’characterisrequiredattheendofyourcommandstatement,usedtoindicate

terminationforparsingandexecutiontobeattempted.

Page 11: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

TheProDebugexampleapplicationincludesamenuitemwidgetinthefirstdebugtoolbarmenulabeled“C#Console”à“MethodExec”,whichmakesuseoftheC#stringmenuedititemtypeforitsdebugmenuentry.BelowaresomescreenshotsshowingthissystembeingusedonaniPhoneplatform:

Testitoutyourselfwiththeseexamplecommands:

• DebugMenuExample.TestMethod "sample string" 3.14159 90210;-thiswillexecuteaparticularstaticmethodintheDebugMenuExampleclass(outputissenttothedebugconsole).Notethatasthismethodispartofthedemoapplicationsourcecode,youdonotneedtospecifytheassemblyname.

• UnityEngine:UnityEngine.Application.OpenURL http://www.ivxiv.com;–thiswillloadtheIVxIV.comwebsiteinyourdefaultbrowser.TheUnityEngineassemblynameisrequiredhereinordertoresolvethemethodname.

• UnityEngine:UnityEngine.Application.Quit;-thiswillexittheapplication(onlyworksinstandaloneapp,notinthebrowser).Again,theUnityEngineassemblynameisrequiredhereinordertoresolvethemethodname.

Page 12: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

HOWTOSetupStepsInordertomakeuseofthevariousfeaturesoftheProDebugplugin,yousimplyincludetheappropriatescriptsinyourPluginsdirectory.Thesearedescribedbelow.

Debug/Assertions/MustTousetheenhancedDebugclassfunctionality,simplyincludetheDebug.cs(andAssert.cs,Must.csscripts)toenabletheiruseinyourproject.

CustomDebugActionHandlersThedebug_managerGameObjectintheincludeddemohasvariousattachedMonoBehavioursthathookintotheProDebugpluginDebugclasstoprovidecustomcrashhandling/crashreporterfunctionality.TakealookattheC#scriptfilesfortheseMonoBehaviourstoseehowtheyhookintotheProDebugfunctionality.Hereisabriefdescriptionofthesomeofthefieldsinthedebug_managerGameObject:

• DebugClassPreset:adrop-downselectorspecifyingadesiredpresetbehaviorofthe“Debug”class,canbeoneofthefollowing:

o ProDebug:debugloggingwillusethehighperformanceProDebugsystems,alongwithautomaticloggingtothedebugfileofalllogentriesonplatformssupportingfileIO.Thisisthedefault.

Page 13: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

o UnityDefault:debugloggingwillmimicthedefaultUnityEngine.Debugbehavior,forthemostpart(NOTE:youwillstillhavetheDebug.Assert() methodsavailabletoyou)

o None:theDebugclassloggingmethodswillbedisconnectedfromperforminganywork.UsethisoptionifyouintendtoimplementyourowncustomDebugloggingbehaviors.

• CrashReporterSkin:referencetoanoptionalGUISkinobjecttobeusedforskinningthecrashreporterUI.• CrashReporterElementInset:Inset,inpixels,ofthevariousUIelementsinthecrashreporterUI.• CrashReporterButtonWidth:WidthinpixelsofthecrashreporterGUIbuttons.• CrashReporterButtonHeight:HeightinpixelsofthecrashreporterGUIbuttons.• CrashReporterDismissButtonLabel:Stringlabelusedonthe“dismiss”buttonofthecrashreporterGUI.• CrashReporterEmailButtonLabel:Stringlabelusedonthe“email”buttonofthecrashreporterGUI.• CrashReporterEmailDestination:Stringentrydefiningthedefaultemailaddressdestinationforcrashreportemails.• CrashReporterDebugLogEmailToggleLabel:Stringlabelusedonthetogglebuttonforoptionalinclusionofthe

debuglogfilewithcrashreportemails.

Page 14: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

Example:CrashUploaderOnepowerfulexampleofbuildinguponProDebugfunctionalityistheinclusionofasimple,automaticcrashreportuploader.ThisisprovidedwiththeCrashUploaderExampleclass.ThisclasshooksintotheenhancedDebugclasseventsOnAssertionFailandOnException,andwhentheseeventsaretriggeredthisclassusestheUnityWWWclasstouploadtoasimpleHTTPechoscripthostedontheivxiv.comwebsite(thePHPscriptforthisechoserverisincludedwiththeexampleproject).WiththeProDebugpluginandthisobjectaddedtoyourscene,anyassertionfailureorunhandledexceptionwouldnowuploadasynchronouslyinacoroutinetothisHTTPechoserver(theuploadresultsaredisplayedbacktotheDebuglog).Thissamplescriptdemonstratesthatwithjustafewlinesofcode,newpowerfuldebugfunctionalitycanbeaddedtoyourprojectthroughtheuseoftheProDebugplugin.

Page 15: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

Example:DebugMenuAsingleGUIDebugMenuscriptobjectisrequiredtoaddtheProDebugDebugMenuobjecttoyourUnityscene.

Page 16: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

IntheProDebugexampleproject,thedebug_managerGameObjecthashadtheGUIDebugMenuscriptaddedtoit,withanassociatedsample_menu.jsonfileforconstructingthesamplemenuatstartup(Unity5.3+).InolderversionsofUnity,thesamesamplemenuisconstructedincodebyasecondscript,DebugMenuExample.cs.ByaddingoneoftheseMonoBehaviourstoyourscene,youwillnowhaveaProDebugDebugMenuinyourscene.Allthatisleftistopopulateitwithyourownmenuentries.Theincludedexampleprojectincludesafullsetofsamplemenus,withvariousbehaviorsthatcanbeusedasareferenceforyourowndebugmenus.Thisisdescribedingreaterdetailbelow.

HereisabriefdescriptionofthefieldsintheGUIDebugMenuobject:

• InitiallyVisible:aBooleanflagindicatingwhetherornottheGUIDebugMenushouldinitiallybevisibleornot.• MenuToggleButton:aBooleanflagindicatingwhetherornottheleft-mosttoolbarmenuon/offtogglebuttonshould

beusedornot.• PrecacheFontData:aBooleanflagindicatingwhetherornottheGUIDebugMenushouldinitiallyattempttoprecache

dynamicfontglyphdata.Thisisusefulfordebugmenusthatusedynamicfonts.• Location:anenumerationfield,eitherToporBottom,whichtellsthemenutoattachtoeitherthetoporbottomedge

ofthedisplay,respectively.• MenuJSON:referencetoaJSONtextfileusedtoconstructyourmenusystem.• PlatformSettingsList:AnarrayofreferencestoGUIDebugMenuSettingsobjects,whichareusedtoprovideplatform-

specificdisplaysettingsforyourDebugMenuifdesired.MoreinformationontheGUIDebugMenuSettingsobjectsisgiveninthefollowingsection.

TheexampleprojectincludedwiththeProDebugplugincontainsafairlyextensivehierarchicaldebugmenustructure,representativeofthekindsofthingsyoumightwanttoincludeinyourowndebug-UImenu.Youareencouragedtostudythecontentsofsample_menu.jsonandDebugMenuExample.cs,aswellasthesupportingdebugGUImenuclassesinordertogainabetterunderstandingofthesystemandhowtoassembleyourownhierarchicaldebugmenus.BelowisabriefdescriptionoftheexampledebugmenuconstructedbyDebugMenuExampleforthesampleproject:

• C# Consoleàtop-levelmenufortheDebugCommandExecutorexample.o Method Execàstringmanipulatorentryusedfordebugcommandentry.

• Debugàtop-levelmenuforvariousentriesdemonstratingfunctionalityoftheenhancedDebugclass.

Page 17: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

o Show ToggleàBooleanmanipulatorentrywiredtotheDebugMenu’sMenuToggleButtonproperty,allowingyoutotoggletheshow/hidetogglebuttonon/off,respectively.

o Menu LocationàenummanipulatorentrywiredtotheDebugMenu’sLocationproperty,allowingyoutotogglebetweenattachingthemenutotheToporBottomofthedisplay.

o Debug.LogàstringmanipulatorentrywiredintotheDebug.Logmethodo Debug.LogWarningàstringmanipulatorentrywiredintotheDebug.LogWarningmethodo Debug.LogErroràstringmanipulatorentrywiredintotheDebug.LogErrormethodo ProDebug Perf Testàafunctioncallbackmenuitemwhich,wheninvoked,willperformatimedtestof

100Debug.Logcalls.(onmanyplatforms,especiallymobileplatforms,thiswilltypicallycompleteanorderofmagnitudefasterthanthesubsequenttestwhichusesthestandardUnity.Debugclass)

o Unity Debug Perf Testàafunctioncallbackmenuitemwhich,wheninvoked,willperformatimedtestof100UnityEngine.Debug.Logcalls.

o Crash Test…àasubmenuentrycontainingapairofitemswhichcausespecifictypesofcrashes§ Assert Test–afunctioncallbackmenuitemwhich,wheninvoked,triggersanassertionfailure.§ Dereference null–afunctioncallbackmenuitemwhich,wheninvoked,dereferencesanullgame

objectreferenceinordertoraiseanunhandledexception.• Teapotàtop-levelmenuforentriesthatareusedtomanipulatevariablesassociatedwiththeteapotgameobject.Try

thevariousentriesout!Notethatanimationmustbeturnedoff(viathefirstsubmenuentry)inorderforanyofthefollowingtransformentriestohaveaneffect.

• Base Typesàtop-levelmenuforentriesthatareusedtomanipulatevariablesofvariousC#primitivetypes.Givethematry!

• Colorsàtop-levelmenuforentriesthatareusedtomanipulateUnityColorandColor32variables.• Deepàtop-levelmenuforentriesthatareusedtodemonstrateadeeplynestedsubmenustructure(eachsubmenu

being3levelsdeep).MostoftheitemsaresimplefunctioncallbackmenuitemsthatprintaDebug.Logmessage.However,thedeepestentryfollowingthefirstsubmenuentryateachstepalongthehierarchywillcontainacoupleofspecialentries:

o Delete this itemàafunctioncallbackmenuitemwhich,wheninvoked,willremovethatmenuitemfromthesubmenu.

o Delete this submenuàafunctioncallbackmenuitemwhich,wheninvoked,willremovethatentiresubmenufromthemenuhierarchy.

Page 18: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

GUIDebugMenuDisplaySettings

Thisobjectisusedtospecifyplatform-specificdisplaysettingsfortheProDebugGUI.Youcanoptionallycreateoneoftheseforeachplatformyouaretargeting,andaddthemtothePlatformSettingsListinyourGUIDebugMenuobject,wheretheper-platformassociationoftheseobjectswillbehandled.ThedeterminationofwhichofthesewillbeusedatruntimeisbasedofftheruntimeevaluationofUnity’s“Application.platform”property.TheexampleprojectincludedhasGUIDebugMenuDisplaySettingsobjectspre-configuredforanumberofcommonplatforms.IfyouaddtheincludedEditorscriptstoyourUnityproject,youcancreatenewGUIDebugMenuDisplaySettingsobjectsfromthe“AssetsàCreateàGUIDebugMenuDisplaySettings”menuoption:

Hereisabriefdescriptionofthefieldsinthisobject:

• PlatformNames:stringof1ormorecomma-separatedvaluescorrespondingtoUnityRuntimePlatformenumerations.Usedtoassociatethisdisplaysettingsobjectwiththedesiredruntimeplatform(s).

Page 19: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

• DebugMenuSkin:OptionalreferencetoaUnityGUISkin,whichifspecifiedisusedtoskintheappearanceoftheDebugMenu.

• VariousColorfields:ThesecolorfieldsareusedforcoloringvariousDebugMenufields.• ToolbarCollapsedPrefix:Stringusedtoprefixtop-levelDebugMenutoolbarbuttonentrieswhentheirmenuisinthe

“collapsed”state.• ToolbarExpandedPrefix:Stringusedtoprefixtop-levelDebugMenutoolbarbuttonentrieswhentheirmenuisinthe

“expanded”(selected)state.• SubmenuPostfix:Stringappendedtotheitemlabelforasub-menuDebugMenuentry.• GUIMenuToggleButtonWidth:WidthoftheDebugMenutogglebutton(thebuttonwhichisusedtoshow/hidethe

DebugMenu).• GUIMenuToggleButtonLabel:OptionalstringlabelfortheDebugMenutogglebutton.• GUIMenuToggleButtonTexture:OptionaltexturetoapplytotheDebugMenutogglebutton.Ifspecified,itwillbeused

inplaceofanyspecifiedbuttonlabelstring.• GUIToolbarButtonWidth:Widthofthetop-levelDebugMenutoolbarbuttons.• GUIElementHeight:HeightofallDebugMenuGUIitemelements(toolbarbuttons,menuitems,etc.).• GUIDebugMenuWidth:WidthofDebugMenuhierarchicalmenus.• GUIElementPadding:Amountofpadding(inpixels)tobeappliedaroundDebugMenuelements.• GUIScrollBarThicknessHint:AhintastothethicknessoftheUnityGUIscrollbarwidgets.Avalueof18pixelshas

seemedtoworkwellfornumerousplatforms…YMMV.Note:theUnityEditorscriptforcreatingtheseobjectsmakesuseoftheScriptableObjectUtilityclass,includedwiththeexampleprojectandfoundat:http://wiki.unity3d.com/index.php/CreateScriptableObjectAsset

Page 20: ProDebug | Plugin for Unity - IVxIVProDebug | Plugin for Unity v. 2.0.0 By IVxIV Software : Introduction The ProDebug plugin for Unity makes a suite of powerful debugging aids available

ProDebug|PluginforUnityv.2.0.0ByIVxIVSoftware:www.ivxiv.com

ContactForquestionsormoreinformation,feelfreetocontacttheauthorofProDebugat:Email:[email protected]’llkeepaneyeout!Thankyouandhappydebugging!