A while back I added a new feature to FRED to make it easier to figure out why events in a mission don't work.
You may have noticed these tickboxes appear in FRED but not know how to use them. Since I've added an explanation to the Diaspora FREDdocs, I figured I should submit it here too for those of you who haven't read through them (Although you probably should if you want to FRED, they're useful even if you have no interest in Diaspora).
------------------------------------------------------------
Debugging is one of the most time consuming and confusing aspects of mission design. Very often you'll have a good idea what SEXPs you think you need in order to make an event but when you run the game you find the event doesn't trigger correctly, or triggers too soon, or doesn't trigger at all. So you go back to FRED and look at the offending events but you're stuck, you can't see anything wrong with your logic, the event looks correct. At this point you have two choices. You can figure out why your event isn't working and fix the problem, or you can tinker with the mission until you find something that works. Many FREDers choose to do the latter. It can definitely be quicker at times but the problem with this attitude is that you don't learn why the previous SEXP didn't work. The result is that it's easy to fall into a pattern of deciding that certain SEXPs are cursed or don't work when in fact it's simply the case that you used them incorrectly.
A better solution is to avoid this kind of superstition and try to figure out why the event isn't working instead of changing it. Those of us FREDders who also are coders will often turn to the coding tools we have and use these to see step by step what the code is doing. This is undoubtedly the most powerful tool a mission designer has at their disposale but for those of us who aren't coders, or who wish to try something else first, there is another tool you can use.
When it comes to debugging missions, the event.log is possibly one of the most powereful tools you have available. Every time the game runs it will write a log to the Diaspora/<Your Currently Active Mod>/data folder (so by default you'll find it in Diaspora/data). The log is a simple text file which can be opened with notepad or the like. By default the log is completely empty apart from the names of any missions that were played. If you want to actually log something, you need to tell the game what you want to log. So let's look at some common problems and how the debug log can be used to help you.
The event log is controlled by the Log These States To The Event Log tickboxes in the events editor. You can turn on as many or as few of these as you wish. If a flag is set, the mission writes to the log every time it tests an event and finds it to be in that state. So if you tick the true box the mission will write to the log when the event triggers. If you set false then the mission will write to the log every time the mission tests the event but doesn't trigger. I'll be giving you examples of some events that don't work correctly and showing how the event log can allow you to quickly narrow down which SEXP is the one causing the problem.
My Event Triggers Too Early!
Suppose we have an event like this one which we are having issues with. The event is supposed to go off at a certain time in the mission but instead is happening near the start of the mission and you can't see why. The event.log can show you what's going on there.Simply tick the True option and run the mission. When you play the game the events.log will be written to as soon as the event triggers. When you quit the mission, you can then look at the event.log and you'll now see output that looks like this.
02/03 10:58:54~ FS2_Open Mission Log - Opened
Mission Learning Curve loaded.
Event: Persephone In Range at mission time 99 seconds (99053 milliseconds)
when returned TRUE
clear-goals returned TRUE
and returned TRUE
is-event-incomplete returned TRUE
< returned TRUE
distance returned 399Let's look at this in a bit more detail. The first two lines simply tell us that we've started the log and loaded the mission. The next line tells us which event we are looking at. After that we get a line which tells us that the when SEXP returned true. Since this is the top level trigger the event also returned true. We only ticked the true box, so this result is not surprising.
Due to the way the SEXP code works, the rest of the log is not in the same order as in FRED. First you'll get a list of the action operators that actually do things in the mission, and then you'll get a list of the SEXPs that were actually involved in deciding whether or not to trigger the SEXP. So the next SEXP we see in the log is the clear-goals SEXP. Action operators should always return TRUE so we can ignore this one.
Finally we get to the real meat of the event. We can see that the distance between the ships was 399, and the "Going after Basestar 2" event was still incomplete, which lead to the event triggering. So now we know what we did wrong, either the two ships are closer than we thought early in the mission, or the "Going after Basestar 2" event still hasn't triggered 99 seconds into the mission, even though we expected it would. Either way, we're much closer to solving the problem.
My Event Doesn't Trigger! 
In this case we have a fairly simple event that isn't triggering. When the Bolitho is at 50% the mission should trigger the event. But in the few tests the FREDder has noticed that even when the Bolitho is destroyed the event still hasn't triggered. More advanced FREDders have already figured out why, but let's pretend we're still confused. You can solve this by using the False option. The log this produces is very long (the event evaluates to false every single frame. So you'll get around 60 entries for every second you play the game!). But we only really need to look at two of the entries to see what the problem is. Basically we'd scroll down until we find the entry that includes "hits-left returned 50" and see why the event didn't trigger then.
When we try this, we see that there is no such entry.
........
Event: Bolitho Damaged at mission time 65 seconds (65233 milliseconds)
when returned FALSE
= returned FALSE
hits-left returned 54
Event: Bolitho Damaged at mission time 65 seconds (65297 milliseconds)
when returned FALSE
= returned FALSE
hits-left returned 48
.........and it's easy to see what the problem is. The Bolitho was hit by something that knocked it from 54% to 48% in one hit. It never passed through 50% so as far as the game is concerned there is no reason to ever trigger this event. This is actually the reason most FREDders will tell you to always test if the hull is less than 51% rather than equal to 50.
How To Use The Other Flags. The other flags are fairly easy to understand if you've grasped how the first two work. First Repeat will trigger the first time a repeating event is triggered. It's basically the same as using True without the clutter of all the other repeats writing to the log. Last Repeat works in the same way but only records the last triggering of the event. Using both together is good if the event triggers but something is going wrong with it between first and last repeat. First Trigger and Last Trigger are the same but use Trigger Count instead of Repeat Count. Log Previous State tells the log to output the state of the event in this frame and the previous frame. This is very useful when you have a multipart trigger and you are trying to figure out which part of it was the last one to turn true.
How To Use The Snapshot KeyOne other useful feature is the ability to record all the SEXPs tested this frame to the event log. Of course, this will result in a very long log entry if you have a big mission but it is very useful when casually playing a mission if you spot a bug. Pressing the snapshot key writes the state of all your events to the log allowing you to look over it after the game has finished. You can snapshot the mission as many times as you want (although you will end up with huge log files if you do it often!) so that you can compare the state of the mission at various times. At time of writing, snapshotting requires that you are running a debug build of the game, or have entered the cheat code (type "freespace2.com" in mission). Press ~O to snapshot.
