Troubleshooting Your Designs
1. Introduction2. What have you just been working on?3. Finding error messages4. Analyse what your code is doing5. Comment out suspect parts6. Use Developer Mode7. Write down in words what your code ought to be doing8. Use the console to test values in-game9. Use a test MessageBox10. Assign asteroid names to the values of your variables11. Ask on the forums for help12. Sleep on it1. IntroductionSo 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.
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?
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 messagesSuppose your map won't load and you can't spot which part of your code is wrong.
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++. 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.
The console is accessed by pressing the Tilde key. (`)
The tilde key is the key to the left of "1" on most keyboards.
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 doingTry 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.
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 partsWe 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.
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 ModePressing 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.
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 doingSometimes the simple act of writing things down helps you to realise where your code and your intentions differ.
Don't underestimate the usefulness of this exercise for both planning and troubleshooting!
8. Use the console to test values in-gameIf 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.
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 MessageBoxEufloria 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:
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.
10. Assign asteroid names to the values of your variablesIf 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:
GetAsteroid(0).Name = MyVariableWhere "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 helpThat'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.
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 itHey, soldier. Been working on this for a while?
Is it 3am?
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. :>
