Editing a mission in a text editor

From FreeSpace Wiki
Revision as of 18:04, 2 October 2008 by TopAce (talk | contribs) (New page: 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 "...)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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) 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.

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.