********************************************************************************
* ####    ####    ############    ############    ############    ############ *
* ####    ####    ############    ############    ############    ############ *
* ####    ####        ####        ####            ####                ####     *
* ####    ####        ####        ########        ############        ####     *
* ####    ####        ####        ########        ############        ####     *
* ####    ####        ####        ####                    ####        ####     *
* ####    ####        ####        ####                    ####        ####     *
* ############        ####        ############    ############        ####     *
* ############        ####        ############    ############        ####     *
********************************************************************************
*  uTest - Feralidragon                                                        *
*  Version 1.0 (27-05-2011)                                                    *
*  Platform: UT v436 (Unreal Engine 1)                                         *
********************************************************************************

Index
    1. Intro
    2. How does it work?
    3. Usage
    4. Properties
    5. Tips
    6. Permissions
    7. Disclaimer

--------------------------------------------------------------------------------
1. Intro

    uTest is basically a script for testing other scripts timings. :)
    
    Since Unreal Tournament (UT for short) does not have any timestamp function 
   to record the current time at the moment of a given script (unlike UT2004 for
   example), it has been always very difficult, next to impossible, know the time
   a script takes to be processed by this engine, therefore everything known so far
   about performance of each script is based many times in assumptions taken from
   UT2004. Although many of them are correct and proved, some others kept as assumptions
   and even somewhat "tabu" to be used in coding.
   
    Therefore, I created this actor which only objective is NOT to give an exact
   time, but an aproximate, yet accurate value, of the speed of one script relative
   to another.
   
    Do NOT use this script if you want to know the exact time one single instruction
   takes to be processed, instead use this script if you want to know the difference
   of performance between 2 or more scripts, usefull to avoid crashes and general lag,
   and boost the performance of your mod when there is more than 1 way to do it.
   
    You would be surprised about the amount of myths and methods of doing stuff considered
   to be faster and more efficient when they actually aren't, and this simple script proves
   those and posterior implementation of those scripts in the mods themselves (it worked
   very well with me to figure out how to optimize many "heavy" code, and proved me wrong
   about certain assumptions I had relative the speed of the engine, for the better).

--------------------------------------------------------------------------------

2. How does it work?

    Basically, it's still impossible to know the exact time of the execution of a script
   in UT, however it's known that Tick Time or DeltaTime (NOT Tick Rate) varies depending 
   on the amount of processing ocurred in the last frame. So DeltaTime is exactly equal
   to all the times all the code took to run, both UScript and C++.
   
    Taking this into account, in an "ideal" moment where 2 "equal" frames take the
   "same exact time" to execute completelly, if one of them runs an extra script,
   the difference noticed in DeltaTime is the exact time that script took to be
   completelly executed.
   
    However, in the game you never get 2 frames with exact the same time, ever.
    So the first thing uTest does is taking a sample of several DeltaTime values
   in each Tick, and calculate a "stable" value as reference for the testing. This
   value can be the average, median, maximum or minimum value of that sample.
   
    From there, the actual testings are started.
    Since this reference value is still an aproximation of the constant tick time,
   executing a script once won't produce accurate values. The differences in timing
   won't be noticeable at all since UScript is very fast (faster than you may think).
    Therefore, to get accurate values, uTest uses instruction repetition or cicles.
   Giving an high number of cicles to make a script run several times in a single Tick
   will provide much higher, solid and accurate values, and the time taken to execute a 
   testing script starts to be measured in miliseconds rather than in nanoseconds
   (check the logExample.txt provided).
   
    All the final results are printed to the UnrealTournament.log.

--------------------------------------------------------------------------------

3. Usage
    
    In case you're using Unreal Editor (UEd1.x or UEd2.0), copy uTest.u file to your
   system folder, open the package into the editor, go to:
        Actor > uTestMain > uTest, and modify it or expand uTestMain itself.
    
    In case you're using Notepad++ and "ucc make"/UMake like me (:P), or another
   external program, modify uTest or subclass uTestMain and then compile it normally.
   
    Check how uTest class is made and you shall have a strong clue how to test your own
   scripts.
   
   Once in-game, type:
    summon utest.utest (or utest.whatever_subclass_you_made)

    REMEMBER, the values will be different all the time, here is the actual proportion
   between 2 or more timings that matters.
   
    Once all the testings finish off, a message will appear on your screen saying:
        "TESTING FINISHED" (with a beep in case bTestEndBeep is activated)

--------------------------------------------------------------------------------

4. Properties

    TickBaseType - Select which method should be used to calculated the tick time reference:
        * TICK_Average;
        * TICK_Median;
        * TICK_Minimum;
        * TICK_Maximum;
        Median is the most accurate method to calculate the reference, as Average is very 
       affected by big deviations in data.
    
    TimingType - Select the unit used to represent the timings:
        * TIME_NanoSeconds;
        * TIME_MiliSeconds;
        * TIME_Seconds;
        Miliseconds should be what you will want the most.
    
    TickBaseCalcPrecision - Basically the "amount of ticks" to use to retrieve tick times data. 
        The higher the amount of ticks used to calculate it, the more accurate the 
       reference will be. This precision is limited by 100 when using TickBaseType=TICK_Median.
   
    CyclesPerTest - Amount of repetitions of each single test. Should be an high value to give
        accurate results (between 50 and 250), as the higher the value, the more accurate the
        difference between the performance of 2 or more scripts.
        NOTE: Do not attempt to set ridiculously hight values such as 10000 or so, otherwise
       the game may stall during the test for several seconds or even crash.
       Higher this value until you do NOT get negative timings (negative timings is a strong
       clue that CyclesPerTest is too low).
       
    bTestEndBeep - When the test ends, beep.
    
    TestDelay - The amount of time the test should take until it actually starts after the 
        actor spawn (due to high fluctuations in DeltaTime after spawn). A value between 1 
       and 2 seconds should be fine.
       
    bShowFinalResultsInTable - Organize the final results in a nice small table (in the log).
    
    Tests(n) - The actual tests controller. Each n (Test[n]) corresponds to "function Testn()",
        for example: Test(4) corresponds to "function Test4()".
        Each one of these test elements have 3 basic properties you can set:
            * enableTest: This test should be executed or not;
            * TestTitle: Test title to show up in the log;
            * TestName: The name of the test (should only contain the following characters: a-z, A-Z, 0-9 and _, 
                NO spaces NOR special characters);
    
    
    For a full example in how to use the this actor, check the uTest class in the source.
    
--------------------------------------------------------------------------------

5. Tips

    Some tips regarding the usage of this script:
        a) Instead of always typing "summon utest.utest", bind a key when doing several testings,
            like "set input Q summon utest.utest" (everytime you hit Q it will spawn a new uTest instance);
        b) Use TICK_Median for a more accurate tick reference;
        c) Use TIME_MiliSeconds as most of the times these are the values you will want to compare;
        d) When testing "light scripts", setup a higher CyclesPerTest value, when testing "heavier scripts",
            setup a lower value instead. Be carefull while setting up CyclesPerTest: a very high value with heavy scripts 
            may lead to a system freeze for some seconds until finish the test to even crash the game;
        e) When doing several tests, if you want to deactivate one test and just compare others, don't delete
            your Test function, disable it on Test(n)->enableTest instead;
        f) Never use this to check a precise single script timing, use it only to compare scripts between eachothers.

--------------------------------------------------------------------------------

6. Permissions

    You're free to modify this version anyway and anyhow you want. Everything I ask is you to update the "Version" number
   and add your name to the header (and a change log would be nice as well) so any developer knows exactly which version 
   he/she is using without having sudden surprises.

--------------------------------------------------------------------------------
   
7. Disclaimer

    I do NOT take absolutelly any responsability for any crash or freezes (or any other kind of side-effect) 
   caused by this script: be responsible by your own actions when adjusting values, as if you're using this,
   then you're a developer, so you should know better. :)