Euflorium: The Eufloria Community

Eufloria => Eufloria Classic => Eufloria Classic Mods => Topic started by: annikk.exe on June 28, 2011, 07:00:32 PM

Title: Troubleshooting Your Designs
Post by: annikk.exe on June 28, 2011, 07:00:32 PM
Troubleshooting Your Designs


(http://i4.photobucket.com/albums/y101/CountJWolf/God.jpg)


1.  Introduction (#post_intro)
2.  What have you just been working on? (#post_workingon)
3.  Finding error messages (#post_finderror)
4.  Analyse what your code is doing (#post_analyse)
5.  Comment out suspect parts (#post_comment)
6.  Use Developer Mode (#post_devmode)
7.  Write down in words what your code ought to be doing (#post_writedown)
8.  Use the console to test values in-game (#post_console)
9.  Use a test MessageBox (#post_messagebox)
10. Assign asteroid names to the values of your variables (#post_assign)
11. Ask on the forums for help (#post_ask)
12. Sleep on it (#post_sleep)








1. Introduction

So you made it through the beginners guide!  ...or maybe you didn't.  I can't possibly hope to cover every individual bug you might encounter, so instead I will cover the basic tools and techniques used to troubleshoot a map.

Understand that everyone gets bugs.  If you made it through all the examples in the beginners guide without a single bug along the way, you are definitely the exception rather than the rule!
Bugs are something you will constantly have to deal with, so it makes sense to get comfortable with troubleshooting them early on.

(http://www.pc-xp.com/wp-content/uploads/2010/12/bug_no_400.png)

So.  You've got a bug.  Lets say for example your map doesn't load at all.  Where do you start?




2. What have you just been working on?

If you've just added 2 new lines of code, and now the level won't load anymore, the chances are high that the lines you just entered caused the problem.  Go and take another look at them.  Is there a typo?
(http://2.bp.blogspot.com/_kB_WS92SNpA/SyCr65AMfDI/AAAAAAAAB78/xLbFSrEDAY0/s400/d5401935a859b4afd2da0b1f939cb26b08282a35_m.jpg)
Are you referring to any variables that haven't been assigned a value yet?  Did you use a dot instead of a colon or vice versa?  EG did you write GetAsteroid(0).AddSeedlings(100) instead of GetAsteroid(0):AddSeedlings(100)?  The difference is small but it can be sufficient to prevent the level from loading.

Look for common mistakes and correct any you find.




3. Finding error messages

Suppose your map won't load and you can't spot which part of your code is wrong.

(http://img534.imageshack.us/img534/9836/errorexample.png)

Eufloria will typically give you an error message.  Read what this says!!  It will often give a number, this is the line number where the code causing the error is located so be sure to look for that.
If your text editor does not display line numbers, I suggest you download Notepad++ (http://notepad-plus-plus.org/).  It's free and awesome.

Eufloria will sometimes give you specific information about what caused the bug, sometimes even mentioning a specific variable that is causing the problem.  Then again, sometimes it does not give specific information, but is more generalised.

There are more error messages too - not just the popup error messages you see when your level fails to load.  Sometimes your level will load but stop working instantly, so any active scripting won't proceed.  In this case, you will probably be able to tell something is not right, but you have no clues as to what the problem is because the level managed to get past the initial loading, so there is no messagebox with the error message.

In this case, it's a good idea to check the console to look for the error message there.

(http://img838.imageshack.us/img838/845/consolel.png)

The console is accessed by pressing the Tilde key.  (`)
The tilde key is the key to the left of "1" on most keyboards.
(http://blog.highlandsolutions.com/zimbra/wp-content/uploads/2010/01/tilde_key1.jpg)

When you open the console, any recent error messages will be displayed there.  As with the above, it will sometimes be specific, other times general.. sometimes it mentions a line number, other times it does not.

Note: Occasionally an error message gets "stuck" in the console.  To check if there is a stuck error message, just type something into the console and press enter.  You can type anything you like, eg type in "fish" and press enter.  You should see an error message in response, because obviously Eufloria doesn't know any "fish" command...  if there was a stuck error message, you will also see this appear now.




4. Analyse what your code is doing

Try to think about all the possible values your variables might be assigned.  Will they ever run into a situation where a number is divided by zero?  If that case arises, you have a crash on your hands.

(http://www.justsaypictures.com/images/divided-by-zero-01.png)

Try to spot logic flaws in your code.  If you have a condtional statement like "if x > y then", make sure that this condition is met when it's appropriate.  Think everything through, and take your time.  Avoid changing things randomly and hoping for the best - that almost never works.  Instead, work on your understanding of what is happening in the code, and let that guide your changes.




5. Comment out suspect parts

We covered commenting briefly in the Beginner's Guide.  If you put a double dash (--) at the start of a line, you "comment it out".  This means anything on that line written after the double-dashes will no longer be run and instead is just treated as a comment.
The aim of this troubleshooting approach is to comment out large sections of your code until you've stripped the level back to a state where it will load again.

(http://img543.imageshack.us/img543/4358/commentn.png)

Then, un-comment your code a few lines at a time until you discover the point where it no longer works.
This helps you to pinpoint which part of the code is causing the issue.




6. Use Developer Mode

Pressing CTRL-D during gameplay toggles Developer Mode on and off.
Once you have activated Developer Mode, you can use the Function keys F1-F12 to activate different useful functions.  F4 and F12 are the most useful ones.

(http://img9.imageshack.us/img9/6422/devmode.png)

Spend 2 minutes learning what these do, and your level designing will be that much easier going forward.




7. Write down in words what your code ought to be doing

Sometimes the simple act of writing things down helps you to realise where your code and your intentions differ.

(http://img864.imageshack.us/img864/7581/distance.png)

Don't underestimate the usefulness of this exercise for both planning and troubleshooting!




8. Use the console to test values in-game

If your level loads but produces unexpected results, this can often be the best investigative tool.
Suppose you are trying to draw a line on the screen, and the line's location is to be based on the position of an asteroid.
Maybe you have an "angle" variable which is calculated, and then used in a subsequent calculation to figure out the coordinates of the line.

At certain points, you know that "angle" ought to be within a certain range.  For example, at the start of the level you expect (from your plans) that "angle" will have a value of about 50.

Test whether it really does have a value of 50!  Load up your level and open the console.
Then type the following: print (angle)
Press enter and the console will show the value of the "angle" variable.

(http://img856.imageshack.us/img856/8131/printh.png)

Maybe it turns out to be 12484382834832483248324.12321 - then you KNOW something isn't right!  Time to study the way "angle" is being calculated...




9. Use a test MessageBox

Eufloria stops running your level code if it encounters an error.
It's possible to exploit this behaviour to see "how far through the code does it get before reaching the error?"
If you have a long section of code and you know at a certain point it is failing, try adding the following line at an opportune point:

Code: [Select]
MessageBox("Fish")
Now run the level.  If you see a Fish messagebox, you know that the code ran fine up until the message box....  so you know the code above it must be fine, and the code below must contain the error.  Go move the Fish command further down a bit, and then try again.  Repeat in this manner until you find the line that is causing the problem.

(http://img171.imageshack.us/img171/586/fishtime.png)




10. Assign asteroid names to the values of your variables

If you have a variable that you want to monitor closely during testing, one neat trick is to place a command like this inside your LevelLogic's While loop:

Code: [Select]
GetAsteroid(0).Name = MyVariable
Where "MyVariable" is the variable you want to monitor.
Now when the game is running, the name of the asteroid will constantly change to reflect the value of MyVariable.  This allows you to see the values fluctuating in real time while the code is running, and can help a great deal in spotting problems.




11. Ask on the forums for help

That's what we're here for!  You could be the greatest coder in the world, sometimes it just takes another pair of eyes to spot the problem.

(http://img535.imageshack.us/img535/9620/headersj.png)

When asking for help, please ALWAYS post the level file you are working on.  Don't just post the part of the code you think is causing the problem.  Maybe you don't think the other stuff is relevant but people - including me - have assumed that before, and then later discovered some of that "irrelevant" code was actually the root cause of the problem.  Learn from my mistake and just attach the whole .lua file.  :>




12. Sleep on it

Hey, soldier.  Been working on this for a while?

Is it 3am?

(http://www.kudosweb.com/kudosweb/media/images/photos/city_at_night_lg.jpg)

4am?

If it's really late and you've been working on this for ages, sometimes the best thing to do is to just call it a night and get some sleep.  When you wake up, your mind will be more focused, and last night's impossible barriers become mere toy puzzles in the face of your well-rested intellect.  Going to sleep is not giving up.. it's a tactical retreat.  :>
Title: Re: Troubleshooting your designs
Post by: Bonobo on June 28, 2011, 10:01:49 PM
Quote from: annikk.exe on June 28, 2011, 07:00:32 PM
[..]
Going to sleep is not giving up.. it's a tactical retreat.
This is going to be a CLASSIC!
Title: Re: Troubleshooting your designs
Post by: Aino on June 28, 2011, 11:02:00 PM
Finally :D

And sleeping on it works, just so you know... You clear up your minsd just as you go sleeping, after that yiou think and think untill you sleep, that's my case atleast :P
Title: Re: Troubleshooting your designs
Post by: dragoonreas on June 29, 2011, 12:04:55 AM
I didn't actually know about the developer mode was until you talked about it recently in another thread, and it sounds really handy. I'll certainly be using it the next time I'm debugging & testing something.

The only suggestion I have to add to the guide would be to mention the print function, and maybe suggest using it instead of MessageBox in the "Use the console to test values in-game" section. This way the values you look up will be saved as output in the console so they can be referred to later, rather than just having them disappear when you close the message box.
Title: Re: Troubleshooting your designs
Post by: annikk.exe on June 29, 2011, 12:11:52 AM
Hmmm yes that is a good idea.  It's not what I do, but it's probably a better habit to get new people into.. :>
Title: Re: Troubleshooting your designs
Post by: Pilchard123 on June 29, 2011, 03:26:02 AM
Quote from: annikk.exe on June 28, 2011, 07:00:32 PM
Sleep on it
Is it 3am?  Answer honestly... ;)
If it's really late and you've been at this for ages, sometimes the best thing to do is to just call it a night and get some sleep.  When you wake up, your mind will be more focused, and last night's impossible barriers become mere toy puzzles in the face of your well-rested intellect.  Going to sleep is not giving up.. it's a tactical retreat.  :>

You're a fine one to talk, Annikk.

(click to show/hide)

And my personal favourite:

(click to show/hide)
Yeah, do as the man says, not as he does.  :P
Title: Re: Troubleshooting your designs
Post by: Aino on June 29, 2011, 04:02:18 AM
Lol Pilchard, that was hilarious :)

I never sleep that much either, because it is in the shine of the fullmoon I code fastest and most logical, thats why GetMouseX() and GetMouseY() came up, would you even imagine that it should look like that... I can't even remember how I put that together xD
Title: Re: Troubleshooting your designs
Post by: Bonobo on June 29, 2011, 04:19:45 AM
Quote from: Pilchard123 on June 29, 2011, 03:26:02 AM
[..]

Yeah, do as the man says, not as he does.  :P
Vvvvvvvery cool, Pilchard123! There’s a Turkish proverb that says: “Do as your teacher says, not as he does!”
Title: Re: Troubleshooting your designs
Post by: annikk.exe on June 29, 2011, 08:28:23 PM
Indeed, do as I say, not as I do :P

I do go to sleep though, eventually.  I reach a certain point where I know my brain is not operating properly, and I normally call it quits at that point because I worry I'm going to make poor changes and mess everything up..

I've done a massive update on this today.  Any further feedback?  I'm particularly interested to know if any of the parts don't seem clear.  Is it all very easy to understand?
Title: Re: Troubleshooting your designs
Post by: Aino on June 29, 2011, 09:29:24 PM
To clean it up: Use anchors :)

Like this:

The text  starts here, this is an actual anchor!

Code: [Select]
[anchor=Start]The text  starts here, this is an actual anchor![/anchor]
(click to show/hide)

and to go to the top:

Go to top (#post_Start)

Code: [Select]
[iurl=#Start]Go to top[/iurl]
NOTE: yuo can use this to go up and down, not only up :)
Title: Re: Troubleshooting your designs
Post by: annikk.exe on June 29, 2011, 09:33:22 PM
Awesome, I didn't know you could do that.  :>
Title: Re: Troubleshooting your designs
Post by: Aino on June 29, 2011, 09:36:36 PM
Well, it's hard to do it on SMF BBCode, atleast hard to find out how, took me 15 minutes to google around just for posting that :P
Title: Re: Troubleshooting your designs
Post by: annikk.exe on June 29, 2011, 09:46:21 PM
I've never come across that BBcode functionality before.  Cheers for that! :>
Title: Re: Troubleshooting Your Designs
Post by: Aino on June 29, 2011, 09:48:42 PM
Looking good, and much easier to find what you want, maybe do this to all the other posts you have too?
Title: Re: Troubleshooting Your Designs
Post by: annikk.exe on June 29, 2011, 10:15:18 PM
Yeah I have a lot of plans for the other guides.. I'd like to roll them all into one big thread to reduce some of the sticky clutter in this subform.  I want to totally overhaul the beginner's guide, to get people using While GameRunning() do right from the outset, etc.  I also want to do an advanced guide where I will cover things like drawing, matrices, converting maths to code, and other crazyness.  One thing at a time though... :>
Title: Re: Troubleshooting Your Designs
Post by: Aino on June 29, 2011, 10:25:17 PM
Hehe, hope it turns out good :P
Title: Re: Troubleshooting Your Designs
Post by: collapsoul on December 06, 2011, 05:30:03 PM
Bringin' topic up, it very well deserves that.
Title: Re: Troubleshooting Your Designs
Post by: annikk.exe on May 28, 2012, 05:54:17 PM
I should really organise all my guides into one big thread...
Title: Re: Troubleshooting Your Designs
Post by: Tomfloria on May 28, 2012, 06:38:23 PM
You should Annikk haha, you have loads haha
Title: Re: Troubleshooting Your Designs
Post by: annikk.exe on May 28, 2012, 06:49:41 PM
It'd be a big task..
Title: Re: Troubleshooting Your Designs
Post by: Eufloria Admin on May 28, 2012, 07:55:01 PM
Ok, doing it.

Going to take a while though...
Title: Re: Troubleshooting Your Designs
Post by: Eufloria Admin on May 28, 2012, 08:00:38 PM
Witness my admin form!
Title: Re: Troubleshooting Your Designs
Post by: Pilchard123 on May 29, 2012, 01:28:26 AM
Wow, when did you hit your limit break? You haven't been this powerful for months!

Just...no Supernova, please. I don't want to have to wait for years just to carry on coding.