Editing a mission in a text editor

Mission data files (.fs2) in FreeSpace are completely text-based, and can be opened and modified easily with a conventional text editor.

This article will use "WordPad" instead of "any conventional text editor" for the sake of simplicity. Wherever the word WordPad occurs, it is interchangeable with the text editor you prefer using.

Precautions

Before you start tampering with your mission in WordPad, it is highly advised to make an emergency copy until you become confident in your abilities to repair all the mission breaks that your edits might cause.

Remember not to use double quotation marks (" ") and semicolons (;) at all. These notations are restricted to the mission's code. Using them yourself will break the mission.

Least importantly, make sure that before you start editing your mission, FreeSpace is able to load your mission without any error messages. If it can't, find a solution to it.

It is also useful to open the mission file and look around a little bit before any edits are made. By the time you decide to actually change something, you will have familiarized yourself with the mission's "hard code" on a basic level.

Advantages

In WordPad, you can quickly open your mission without even running FRED. Certain minor alterations can be made very quickly. (See the "Uses" section below).

FRED has a tendency to break the mission (on rare occasions) and render it unreadable. This happens most frequently while you are performing other actions during the saving process (changing windows using Alt-TAB; pressing keys, etc.) These breaks can be prevented and even remedied in WordPad.

Saving in WordPad also preserves the mission's build requirement. Do some touchups and keep your mission compatible with FreeSpace Open 3.6.9, while you are already using FRED 3.6.10. Saving in FRED 3.6.10 will also add some additional new fields into your mission's code, which may not be readable for 3.6.9 users.

This is not all of it, see the "Uses" section for a number of possible uses.

Disadvantages

The most frequent (and possibly most obvious) disadvantage is that, in inexperienced or inattentive hands, a mission's code can be broken easily. In contrast to the crashes FRED produces, these crashes are triggered by human hands in all cases. Sometimes you accidentally remove a $ mark or add a semicolon (;) into a text. The more experienced you are, the more likely you are able to pinpoint the bit responsible for breaking the code, and mend it. It is imperative that you try to run the mission you altered to see if the very least FreeSpace can load it safely.

Another disadvantage is that you cannot edit everything you wish, due to the code in which FS missions are stored. There are several bitfields (like for Player Orders and Mission Flags, eg Red Alert status) that are only a series of numbers.

Uses

Here are some possible reasons to prefer editing in WordPad rather than in FRED.

Changing Event hierarchies

While FRED allows you to change the positions of your Events in the Mission Event Edit window, it is not reliable. Changing the order of Events will confuse FRED. A ship that was intended to arrive after Event B came true may now arrive after Event C came true.

Changing the order of your Events is necessary in only one case: chained Events. You may realize that you do not want your Event C to be chained to Event B, but to Event G. Performing the move in WordPad can be done with the following method:

• Use the Search function (Ctrl-F) and look for the Event you want to move.
• Select the relevant Event; your selection should range from $Formula until +Team. Beware not to select the bit starting with "+Name: <Your Event's name>" and end with the last curly bracket "}" of the formula field that is below it, because it does not belong to the Event you want to move!
• Press Ctrl-X (Cut) and find the Event that you want your selected Event to be chained to. The find the Event you are looking for and paste it (Ctrl-Insert) beneath it. Again, be careful about where you are pasting.
• Make sure that there aren't any unnecessary characters that you may have accidentally added.
• Run the mission and test. If it can be loaded successfully, you did not break the mission's code.

Proofreading

For more information, see this.

Changing all text-based data like briefings, messages, or ship names belong here. Making these changes can be done in FRED, but you have to account for the unpredictable crash factor. Using WordPad for this purpose is a more convenient way for some community members. You can quickly and easily change all your messages if you want to without needing to open your Mission Event Edit window and modify one message at a given time.

With WordPad, you can have multiple messages on your screen (depending on the resolution you are using). You can also change the font type/size to match your preferences, which helps a lot.

Beware of changing American spellings into British ones. The word behavior is part of the $AI Behavior command. FreeSpace will not be able to understand if "AI Behaviour" is used instead of "AI Behavior." There may be other such words, so don't use the Substitute --> Change All automatically.

Mass renaming

You can use the Substitute (Ctrl-H) feature to change all instances of Word A to Word B in a few clicks all through the mission. You can apply this trick to change names of characters or ships, or all instances of a given misspelling to its correct form.

It is advised that you use the Substitute option moderately at first. You can use the Search function beforehand to discover in what contexts Word A can be found in. A general rule is that if an instance of Word A can be found between two double quotation marks (" "), changing it will not break the mission's code. (But remember to avoid using another double quotation mark or a semicolon.)

Changing certain real misspellings like invencible to invincible will not break the mission.

Importing mission backgrounds

If your mission should have the same background as another mission, you can easily copy/paste the "#Background bitmaps" section of the mission that is exporting its background. Copy everything ranging from "#Background bitmaps" until "#Asteroids". Then find your mission's "#Background bitmaps" section and overwrite it.

You can also import Command and Mission Briefings this way without much of a risk. Other parts of the mission are more risky, because if they refer to ships or Events that are not in your destination mission, they will produce an error message.

Also, it is impossible to set the number of stars in the background equal to zero using FRED alone. You must use Notepad to do this. Make sure you do this if you are using a skybox as the normal retail stars will look quite ugly on top of it.

Fixing Special Hits

FRED has a peculiar way of storing and accessing custom hitpoints (set in the Special Hits window). Instead of storing it in the ship's entry, custom hitpoints are in reality variables that are assigned an identification number. As the mission starts using more and more variables, these identification numbers might get mixed up. This might result in a Colossus-size vessel having 500 hitpoints and a Myrmidon 2,500,000. An entry looks like this:

92		"GVD Hedret"		"0"		"block"
93		"GVD Hedret"		"200000"	"block"

The first value (92) is the amount of shield the ship is set to have. Even if this is a Hatshepsut destroyer that has no shields, FRED requires both the shield and the hitpoint value (93). The heart of the problem is this line from the ship's entry:

+Special Hitpoint index: 94

This line is near the bottom of the ship's entry. This value isn't what it should be. 94 and 95 belong to another ship (a bomber), that has 1100 shields and 700 hitpoints. This results in the GVD Hedret having 700 hitpoints altogether. The solution is simple.

Replace the wrong value with the right one, and test. Give the shield's value, because otherwise the engine will look for the next value to determine the ship's custom hitpoint. It's very likely that it is 0 again. Now that you're at it, make sure that there are no other such inconsistencies. Jump to the Variables section (Search "$Variables") and check each ship one by one. Save, but don't touch FRED yet. Test the mission and see if it works. It may not work still, but keep trying.

In case of emergency or desperation, give up using Special Hits. Start by canceling all the Special Hits in FRED, save, and open the mission in WordPad. Delete all the outdated variables that used to belong to the old Special Hits values (if they are still there). Set all the values again and test.

Repairing broken missions

Remember to test every change that you think might break the mission. If it does, try to repair it immediately. The more you delay it, the more you will forget about what you had done to the mission. The error must always be found somewhere around the changes you have applied. Use juxtaposition to see if the part you modified matches the code. If it doesn't, use the unaltered parts of your mission as a base of your repair attempts. Your clipboard might still contain the bit you copied, you can use that as a reminder as to what you have changed.

If all you did was edit messages, try to remember if you have used a semicolon or a double quotation mark as they break the mission. If you connected two sentence clauses by a semicolon, you have found the source of the problem. Use the "period and new sentence" formation to circumvent the semicolon or use $semicolon instead of the actual punctuation mark.

Scroll down your mission and see if there are big empty spaces anywhere. If you find any, remove them. Do not remove anything else but enters and spaces.

Under the most desperate of circumstances, retrieve an older version by renaming the mission's .bak file to .fs2, or seek the help of a more experienced FREDder.