Upgrading campaigns

Upgrading a campaign means editing someone else's work. This means that the changes a FREDder can make are somewhat restricted.

Unless the original campaign creator is available to assist, radical changes are to be kept to a bare minimum.

Guidelines

Generic

Purpose

The upgrade is to make an old campaign compatible with FSO or, if it was already compatible with FSO, to make it compatible with recent builds developed by the SCP.

This means that the FSCRP's upgrades are not intended to be compatible with Retail FreeSpace. Generally, upgrades are not intended to fully replace the original versions - the original releases are the only official ones in existence and therefore should remain available. It's worth noting that people who don't make use of FSO have the ability to play the original campaigns.

Team

Upgrading a campaign is usually the result of the work of many members who decide to use their free time. For this reason, it'd be polite to keep a reasonable behavior and respect for the other members of the upgrade team.

No one should be ashamed of making mistakes, so don't flame.

Contacts

The ability to contact is a necessary in upgrades. Although instant messaging programs, personal messages, e-mails, and any other form of communication are possible, using private forums is recommended.

As evidenced here, coordinating work of notable complexity requires a private forum that can be used to post questions, proposals, reports, etc.

One of the main disadvantages in using anything other than private forums is that posts will not be available for everyone to read. Members whose addresses/nicknames aren't included as additional recipients in e-mails/personal messages wouldn't have any notifications. Also, members joining the upgrade team later wouldn't have any chances of getting acquainted with the progress made so far.

Upgraders

See also: Mission pre-release checklist

Finding the problems

Although most of the bug-hunting job is up to the testers, FREDders are also encouraged to playtest campaigns in need of upgrades at least once.

There are several benefits: first, it's very important to get acquainted with the original campaign creator's FREDding style so that the upcoming changes can fit with the previous work. It's also extremely important when trying to supplement a tester's work and propose significant changes - testers with poor or nonexistent FREDding experience are focused on mission bugs and balancing while a FREDder may also analyze the campaign and decide whether or not cutscenes and/or other special effects should be added.

Proper naming conventions

Naming conventions are of the utmost importance. There's nothing worse than making hard-to-guess edits with vague info. New events, for example, need to have comprehensive names. It's also important to track the FREDder who made the changes should problems arise.

Example:

• MBS - Destroy Transports Directive

In this example, the event has been created by Mobius and it's intended to show up a specific directive: "Destroy Transports".

Changelogs

Changelogs are necessary to track edits and undo them should problems arise. Each upgrader working on a project is supposed to attach a .txt file with the changes he made. The document needs to be extensive.

It's also recommended to post the contents of the changelogs in the forums. Do not attach the .txt to a post, since attachments are deleted at regular intervals.

Testers

See also: Testing

Compiling initial reports

Initial reports mark the beginning of an upgrade. During this phase, the most noticeable bugs and problems are found and discussed with the rest of the upgrade team.

Problems are various and aren't all FREDding-related. Certain campaigns are, in fact, old enough to give problems with recent builds of FreeSpace Open (or worse, with FreeSpace Open in general) so immediate edits are needed to test the campaign properly.

The basic formula to create a report is the following:

<Mission Name>

Command Briefing:

<Stage N>

Text

Briefing:

<Stage N>

Text

Icon placement

Usage formula (eventually)

Mission:

<Arrival of ship X>

<Message X>

<Time-elapsed particular event>

Other

Debriefing:

<Stage N>

Usage formula

Text

Mission-related problems are harder to point out. This happens mainly because of the fact that a problem can occur because of a certain event becoming true or false anytime (or, at least, in a wide time window) during the mission. Even "easily understandable" events like the ones connected to the destruction or the arrival of a ship may result in problems if the conditionals are complex.

When compiling a report, it's worth reminding that a) it should be comprehensive for FREDders and b) it should respect the "One line per problem" rule, meaning that all reported bugs/problems shouldn't be mixed in the text file.

This:
- Ship Y departs too soon, one of its messages is sent by Command instead;
- Bomber wing Z, tasked to destroy Ship Y, remains immobile if the ship departs and the bombers are unsuccessful at destroying it;

Is much more appropriate than this:
- Ship Y departs too soon and bomber wing Z remain immobile instead of engaging the player and/or other friendly ships. One of the messages Ship Y is supposed to send is sent by Command instead;

Playthroughs

To be filled in later.

Compiling further reports

To be filled in later.

Sanity check

Sanity check is the last phase of the upgrade. It consists of one or more playthroughs whose objective is testing additional changes and making sure that the campaign is in good conditions. Sanity checks shouldn't be disregarded, and there should be a coherent approach during this phase.

Basic edits

Backgrounds

Adding backgrounds

See also: Background Emporium

A considerable number of custom-made missions lack or feature minimal backgrounds. Most, if not all, campaign upgrades involve the improvement of backgrounds. It's actually possible to create several backgrounds from scratch, but the existence of several shortcuts makes thing easier.

Thanks to the efforts of several FREDders, most canon systems have their specific backgrounds. If a mission takes place in a given system, it's possible to copy and paste that background via Notepad. The operation is not hard at all, but eventual errors could result in certain mission corruption. Be careful when using Notepad to alter mission files, and don't forget to open the modified mission in FRED to verify if the new background is properly set and/or to check if your Notepad edits somewhat compromised critical mission lines.

If several missions take place in different sectors of the same system, it would be a nice idea to make every sector unique with a series of minimal (but effective) edits. The apparent magnitude of stars depend on the distance to those stars, so if you're upgrading a mission that takes place in a remote section of the system it may be a good idea to reduce the star's dimensions in FRED to minimal values (0.3-0.1 or even 0.05). Additionally, each sector may feature different planets and even satellites (thus adding variety). Even the same sector might change: it's plausible to add satellites that previously did not appear because they were covered by a planet.

If you decide to create a background from scratch, it would be a nice idea to post it to the Background Emporium. Both alternate versions of existing system backgrounds and background for exclusive systems are accepted and should be made public.

Stars

Older campaigns were tested using FRED Retail. Back then, no starfield skyboxes were available, so the only ways to improve a background were to add nebulae and set the number of stars to the max value, 2,000.

Many fans complain about the presence of those stars because their usage results in certain render oddities, like the "distortion effect". A recent change to the code has made sure that the skybox overwrites auto-generated stars, but it's always a safer to change the number of stars to 0:

Editors ---> Background ---> Misc ---> Number of stars ---> Set the value to 0.

Skybox

Skyboxes are graphical enhancements introduced by the FreeSpace Upgrade Project. Needless to say, as fan-made effects, skyboxes are missing from old campaigns.

Adding them is a must during the upgrade—they're the easiest and most effective way to show a good background even without any nebula. The standard skybox model released with the Media VPs is called "starfield". Adding it is easy:

Editors ---> Background ---> Misc ---> Skybox Model ---> Type "starfield.pof" without the quotes. There's no need to browse the model.

Generic mission management

Timings

To be filled in later.

Weird warship battles

Often, FREDders order ships to engage each other in a fight by simply ordering them to attack each other. This is known to cause oddities—ships engaged in some sort of "dance" and/or involved in multiple collisions aren't worth watching. Obviously, this edit isn't necessary if all warships involved in the battle are supposed to remain immobile.

The most common solution is to create waypoints for the warships to follow. If the warships are too fast and/or their starting distance is too short, it may be a good idea to reduce their speed. All of this can be easily done:

Removing orders:
Normal orders:
Editors ---> Ships ---> Initial Orders ---> Remove the order to attack the opposing ship.

SEXP-triggered orders:
Editors ---> Events ---> Find the event ---> Remove the add-goal SEXP. It may be a good idea to delete the whole event as long as it's not in the middle of a chain and/or there are other SEXPs other than add-goal.

Waypoints:
Creating waypoint paths:
Interface Shiplist ---> Choose Waypoint ---> Press Ctrl + Left bt. on mouse to add ---> Create, if necessary, a waypoint path ---> Name the waypoint path ---> Repeat this process for the other ships.

New orders:
Normal orders:
Editors ---> Ships ---> Initial Orders ---> Fly the selected waypoint.

SEXP-triggered orders:
Editors ---> Events ---> Find the event ---> Use the add-goal SEXP to order ships to follow their specified waypoints.

Speed:
Editors ---> Events ---> Find the warship's arrival event ---> Add the cap-waypoint-speed SEXP to set a reduced speed. It can be reset by choosing a speed of "-1". This may be necessary if a ship involved in a battle is successively supposed to fly through waypoints at max speed or, at least, at a speed different from the one showed during the battle.

If there are no events related to the warship's arrival and/or to the beginning of the battle, it's a good move to create at least one for better handling.

Grammar/spell-checking

To be filled in later.

Inappropriate names

To be filled in later.

Order-related issues

Ships

Among the FREDding mistakes that can screw up a mission, order-related issues deserve its own section. In many campaigns, it's possible to issue orders to transports, freighters, cruisers, and corvettes which are supposed to fly through waypoints and/or to follow certain orders. Ordering to attack a ship and/or to capture a given target can lead to unpredictable results, like freezing the progress of a mission.

Unless it is clearly specified that the player is supposed to issue orders to such ships, it's very important to make sure that those ships will do only what they're supposed to:

Editors ---> Ships ---> Player Orders ---> Unmark all orders that the player can issue. The white boxes need to be unchecked.

Spacecraft

Even spacecraft can cause trouble because of their initial orders. The player, even in the role of squadron leader, should not always be capable of issuing orders to all spacecraft. There might be fighters and/or bombers that he has no authority over as well as units which are supposed to behave according to the original campaign creator's will without any interference (kamikaze runs, waypoints, suicide attacks, ignore certain allied ships, etc). It's also possible that certain spacecraft may need to receive orders by the player, but that should be rare.

It's also worth noting that in missions featuring characters, it shouldn't be possible to order those characters to depart anytime during the mission. If the player orders them to depart, all messages they were supposed to send will be sent by Command, instead.

Choosing the orders the player can issue is very easy:

Use the mouse or the Select List button on the interface (or, alternatively, press H) ---> Choose the spacecraft whose player orders need to be changed ---> OK (if using Select List, otherwise jump this step) ---> Player Orders ---> Mark/unmark the orders. Pay a lot of attention to characters.

Wings management

Although waved wings are rare in main campaigns, their use in custom campaigns is notable. For several reasons, an upgrader may have to change the number of waves and/or the delay between waves according to the reports compiled by testers.

Names-related problems

See also: Friendly wing names, Enemy wing names

It's not rare to deal with misspelled or repetitive wing names. Although it's normal to have an Alpha wing in virtually every single mission, it's not possible to say the same thing if every mission of a campaign features a Cancer and/or Aries wing. Misspelled names, like Beema (Bheema) or Sagitarious (Sagittarius), are also unacceptable.

Because renaming a wing in FRED resets that wing's orders and also leads to event/cue conflicts, not to mention the possibility of altering the contents of messages, the easiest way to change wing names is using Notepad. Use the program to open the mission and scroll down the file until you find the list of wings. Take note of the repetitive and/or misspelled names and then decide which names you're going to use instead. Use the search function of Notepad to ensure that no ships/messages have the name you're willing to add (read below for more info about this possible conflict) and then use the same function to find each reference to the wing name that is in dire need of changes. The search function should point you to: each ship of the wing, the wing's entry in the list of wings, eventual directives related to the wing, eventual arrival cues/event conditions that are related to the wing, message names and the content of some messages. Changing the name via Notepad will effectively do the job. Be careful when editing a mission via Notepad, though - any errors could result in certain mission corruption.

Please note how it's not that hard to have individual ships with names that match perfectly those used for wings. It's the case of transports and freighters, which usually have conventional names like Capricorn 1 or Iota 2 without being part of any wings. For this reason, before replacing a wing's name with another, it's extremely important to use the search function of Notepad to verify whether or not that name is used for another ship - FRED won't tolerate both a combat spacecraft and a transport/freighter with the same name like Capricorn 1.

Random protection

For pure balance issues, the upgrade might involve additional changes to allied wings' survivability. Thanks to random protection, it's possible to make sure that a friendly wing will not be completely destroyed during the mission.

In order to represent the effect, create an event for the wing you want the random protection to have effect on. In this event, use percent-ships-destroyed with any reasonable value (like 50) and ship-guardian-threshold (with rand) for every spacecraft of the wing. ship-guardian would work, but it won't randomize anything (the minimum value will be 1% for every spacecraft). Additionally, it's strongly suggested to use ship-subsys-guardian-threshold to prevent the spacecraft from being disabled. Here's an example:

Condition that will trigger the event (with when):

 percent-ships-destroyed
 50
 Epsilon

To protect the hull:

 ship-guardian-threshold
 rand
    5
    15
 Epsilon 1

[...]

 ship-guardian-threshold
 rand
    5
    15
 Epsilon 4

To protect the engines:

 ship-subsys-guardian-threshold
 rand
    20
    40
 Epsilon 1
 engine/engines/<<all engines>>

[...]

 ship-subsys-guardian-threshold
 rand
    20
    40
 Epsilon 4
 engine/engines/<<all engines>>

Finally, it's also possible to AI-protect the spacecraft. It's not highly recommended, but it's a valid option:

 protect-ship
 Epsilon 1

[...]

 protect-ship
 Epsilon 4

Depending on the mission, it's also possible to protect the spacecraft from beams:

 beam-protect-ship
 Epsilon 1

[...]

 beam-protect-ship
 Epsilon 4

Waves-related problems

A bad management of waves oftentimes results in serious balance problems. One of the most common things testers notice is how some enemy wings respawn too quickly and/or their number of waves is exaggerated. Thanks to simple and effective edits, those issues can be solved. One of the main advantages is the fact that, unlike many other changes, this has minimal to nonexistent effects on storytelling.

Number of waves:
Editors ---> Wings ---> Edit the value placed near # of Waves.

Delay between waves:
Editors ---> Wings ---> Arrival ---> Delay between waves ---> Edit the Min and/or Max value.

Weapons management

Shivan weapons

With Media VPs, the Shivans now have a large variety of specific weapons. They're the same as the weapons used by the player, but their mesh and their color fits for Shivan use.

In order to add those weapons, the FSU Team has modified the default table entries of Shivan craft. This kind of change, although entirely appropriate, has its drawbacks: it has no effect on weapon configurations which have been modified manually in FRED. Because getting an idea of the difference is hard during the game, it's highly suggested to. Doing this is very important if, for example, missions feature the SB Nephilim: the bomber's default configuration has no heavy weaponry - it's very likely that the mission designer changed the configuration manually, meaning that during the mission the Nephilims will not make use of new Shivan weapons.

Related Links

• FreeSpace Campaign Restoration Project
  • Public board | Hard Light Productions.net