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. The single most important thing to consider is your program of choice's ability to save in a pure text format.

The most popular text editor in the community is Notepad++.

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 (Retail FS, and very old FSO)

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.

Miscellaneous mass importing of data

You can copy/paste any data, such as objects, mission events, or messages, from one mission to another. For example, you created a test mission specifically to test a complex scenario that would otherwise take place later in the main mission, and you decided you are now satisfied with the scenario, and you want to apply those changes to the main mission. There are lots of things missing from the main mission simply because you built that scenario in your test mission. The time has come to add those missing data batches by batches to the main mission file by meticuluosly copy/pasting everything from the test mission to the main mission.

Usually, these are the parts of the missions' data files you'll be interested in:

• #Variables
• #Objects
• #Wings
• #Events
• #Goals
• #Waypoints
• #Messages

Note on variables

Be very careful with copy/pasting variables. The number IDs (indexes) of your variables are critical and your variables must be numbered according to the alphabetical order of their names. It is more than likely that your variable "turret-count" is number 10 in your test mission, but is number 3 in the main. You cannot simply edit the variable's index number to 10 and be done with it, otherwise the game will not be able to load your mission because its file is now damaged. You can copy/paste your variables one by one in alphabetical order first, then changing their numbers second.

This method is quite volatile and prone to human error. The most reliable way is to add the variables to the main mission in FRED's Mission Event Editor. Once you have all the variables you need, you can safely copy/paste the mission events that refer to those variables.

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.

During copy/pasting text data, you might accidentally remove/forget to add (, ), or " characters and break the mission.

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.

Working with Notepad(++) and FRED simultaneously

You can have your mission open in Notepad++ and FRED at the same time without risking any edit conflicts between the two. There are only two scenarios that you must learn to handle.

Since Notepad is an auxiliary tool, the scenario you will encounter is this: You are in FRED and realize you're better off doing some edits in your text editor. Say, you need to make a long list for your when-argument. Save the mission, refresh your Notepad's .fs2 file, make the changes, save. Notepad++ is one of the more advanced plain text editors out there that lets you refresh your opened files in a matter of a click because the program is sophsticated enough to detect if the one of its opened files changes. Usually, a confirmation window will come up asking whether you want to refresh your file. Click yes. If it's not there, simply open another tab, then get back to your mission's tab, and the window will pop up.

Once you've made sure both Notepad and FRED have the same version of the mission loaded, make your edits in Notepad and save. Alt-Tab to FRED, move your camera around a little bit, then click File --> Revert (no hotkey) and wait until your camera jumps back to its original position. You needn't move the camera, it's just a convenient way to recognize when your reload is complete.

Continue your FREDding as normal. If you need the text editor again, jump back to step one.

The pitfalls are the usual. While editing the text data, you may spawn some errors that FRED would not let you make or an error message would pop up on save. For example, you remove a mission event/message/waypoint that you thought was unused but wasn't. You can then use either your text editor's Find tool to track down all the references to it or follow where the error messages in FRED point to and fix them one by one.

Long story short: Save your mission, reopen/refresh your .fs2 in your text editor, make the changes, save, get back to FRED, click File --> Revert.