Freespace 2 Modding

One of the most excellent elements of the game Freespace 2 Open (or of course the original, Volition's Freespace 2) is the capacity for modifications. It is possible to develop an entire campaign of missions which string together into a story, to modify or create ships and weapons, to script FS2 in Lua, and to do any number of other fairly amazing things with it. But by far the most common is to create new missions. In this article I'll give a brief explanation of some details of modding that I learned developing my first non-simple mission.

Freespace Modding

Freespace 2 is modded by laying files down someplace it can see them. In fs2_open, you can load content from multiple directories. Whether it's the Open or retail version, data can be loaded from VP files, files simply placed in the data directory, or both. The loose files take precedence, so it's easy to modify the game from its base content incrementally. In the modern day, we normally use fs2_open and we use it with the Media VPs, so just to play the ordinary game we load the MVPs, then the retail game content. Files loaded first are not replaced, so anything in the MVPs which replaces retail game content "wins", and the game is changed.

FRED2

If what you want to change is missions, which is the most common thing to mod in Freespace 2 because it is one of the most accessible activities, then you use FRED2. There are two versions; There's FRED2 Retail, and FRED2 Open. The Retail version creates missions which work with both Freespace 2 Retail and Freespace 2 Open. The Open version does too, but it can also use some functionality that is not present in the retail version. If you do that, your mission won't work in the retail game. For that reason it's probably smarter to use the original FRED2 if you want to create missions that work with the retail version. If you intend for it to be played only on FS2 Open, then you can make the step up. Note however that FRED2 currently only runs on Windows (wxFRED2 is seriously unfinished) and that it requires OpenGL 1.2. That means the Windows software OpenGL won't work and the SGI free reference software OpenGL also won't work because both provide OpenGL 1.1. You need the multitexture extension, so you need a video card with accelerated OpenGL support. I've heard of people being able to run it in Wine, but the OpenGL portion had problems on my Linux system (with wine 0.9.41 and the latest NVIDIA drivers for my QuadroFX) so I'm running the original version under vmware. On the down side, I therefore lack access to some of the nice new functionality. On the up, my missions will work with retail Freespace 2 as well.

Taking a look at FRED2

Let's take a look at the mission I'm going to use to illustrate principles here, as a means of an introduction to FRED2.

A shot of the FRED2 Event Editor

Across the top we have some buttons that do various things I'm mostly not going to talk about. In general they let you manipulate things and choose which things to manipulate. There are some menus, which we'll also ignore - I'm not providing a tutorial on using FRED2, just talking about some of the things the documentation doesn't help you with. In the window is a map of my level. This is a truly three-dimensional map which can be displayed in a number of styles to match your system capabilities. Nearly everyone these days will be turning all the options (except perhaps the background, which can look like a mess here) on so that they can see all the ships and such, but you can show them as outlines, textures, or just a dot.

In this map you can see the entire area of my mission, because I've flown the viewpoint well above everything. The big brown box is an asteroid field, and the green box is an area inside of it that is free from asteroids. The three-pronged green thing is a jump node - we'll fly in closer to it in a moment. You can kind of see a couple of solid items in the green box; let's take a closer look at what's going on there, and at the jump node.

In the jump node (left) you can see a wing of four ships, designated Alpha. Alpha 1 is the player ship (which could be named anything.) The purple dot is a waypoint. In the asteroid-free zone (right) you can see a Shivan communications node and a Terran corvette. Note that all these ships are fully modeled and textured, which is a great help in determining relationships between things and vaguely what they will look like.

Missions

In Freespace 2, a "mission" is a single flight. It has (or may have) a command briefing, a mission briefing, an actual mission, and a debriefing in which mission goals are reviewed. The entire game is governed by scripting (aside from AI, which in the loosely remembered words of one author is a big mess of code.) In general, there are various "when" events which instruct the game engine as to when things should happen. When the conditions of the when event are met, it occurs. Things whose condition are set to a logical true simply happen as soon as possible. Some objects have events attached to them; for example there are conditions for warp-in and warp-out for every fighter save for the player, and by default these are set to true and false respectively, so that if you place a ship or shiplike object in the mission, by default it will be present in the mission and it will not warp out.

Events and the Event Editor

This is all well and good, but beyond this you have the ability (with the Events Editor) to create new events, which also typically start with a when statement. Here's an example event that prevents the player from warping out.

This is the first event which occurs in my mission. It sets Alpha 1 to be unable to jump. There is a different event which breaks the jump engines, but it's possible to fix them by calling in a support ship so if you want the player to be unable to jump for plotline purposes, this is what you do. In my case I want them to not be able to jump until they accomplish some things and then return to the jump node.

You'll notice that this event occurs when true. Let's take a look at a slightly more complicated example:

In this example we use the logical operator for less than ( < ) which in this case is a functionIn programming as well as math, a function is a statement or series of statements which has zero or more input values, and one or more output values. which takes two numerical arguments.An argument is an input to a function. The output of the less than operator, like most functions, is either true or false. If we provide it to the when statement instead of true, then the when statement will happen (we often say an "event" will "fire") only when that function's output is "true". The distance function's output — or its "return value", which it "returns" to the function which called it, which is logically enough known as the "calling function" — is a number indicating the number of meters between the two objects specified. In this case it's a Deimos-class corvette (the GTCv Watchword) and a navigation point which I've placed at the center of the jump node. We use this nav point to determine when ships are close to it, and to give them something to fly toward in order to get there.

A when statement has two parts; a condition to be met, and an action to be taken. The action, in this case, is a send-message. Messages are written in the event editor as well. Any wingman will send the message referenced when the Watchword approaches the navigation point. This is necessary because all ships require some run-up room when they jump out. For fighters this might be a hundred meters or something; for this ship it's in the vicinity of 1.7 km! They also require some room when they jump in, so if you want a ship to come to rest in a certain position you have to take both that and their inertia coming out of jump into account. It's best to have them jump a bit short, then come to rest at a waypoint.

Hints and Tips

Here's some things I wish someone had told me when I started, or obvious mistakes that I made anyway. Some of it is things I did learn before I started, but they're important so I'm echoing them here. FRED2 comes with very little documentation, just enough to get you into trouble. As always, take apart the original game files and look at the missions with the editor (I used VPVIEW32 2 beta to read the VP files, which worked great) to see how the original developers did things.

Using FRED2

• FRED2 retail Uses Direct3D 8 or so. FRED2 Open uses OpenGL 1.2. If you can't run FRED2, this may be why.
• FRED2 Open is rumored to run on Linux under Wine, but it doesn't work for me. I have to run FRED2 retail in a virtual machine because both editors botch graphics under WINE on my system.
• Moving the viewpoint around FRED2 is done with the default keyboard movement keys. Number keys 1-8 set the speed of movement, which you can also do from a menu, but why? A moves you forward and Z moves you back, keypad 1 and 3 strafe left and right. Keypad 8, 4, 6, and 2 control pitch and yaw. Just think of it like you're flying.
• The lock button (looks like a padlock) in the toolbar is your bestest friend, and it's next to the "select units from list" button for a reason. If you want to fiddle with a obscured object (e.g. a ship inside a warp node, or perhaps whose starting point overlaps a larger ship) you can click the padlock, then select the object with the select list. The move button will now move the object around regardless of where you click.

Events

• You can move events up and down the hierarchyOrder. In this case the hierarchy is mostly tree-structured, although it is possible to jump from branch to branch. by copying and pasting. For example, if you have an "and" statement and you want to replace it with one of the statements under the and, just copy the lower statement and paste it on top of the "and". Similarly, this is a great way to make duplicate (or very similar) events quicker. After copying the when statement from the event you want to copy to the one you want to copy it to, just change the actors (the ships etc specified) and your event is finished.
•  
• A directive is marked as satisfied when the when-condition for the event to which it is attached is met. This leads to events being listed in rather odd orders because the directive appears as soon as the event is interpreted. For example, let's say you want a directive to destroy a ship to appear after that ship warps in. You'd create an event which says that when the ship has arrived, you do nothing (or play a message, or what ever you would like to do.) This event is followed by an event which is set to do-nothing - but only when the target ship is destroyed.
  Now let's say you want to give a notice when the ship's been half-damaged. If you put that event in between the two events we talk about before then you won't get your "destroy" directive until the ship's down to 50% hull. So instead, the event to display the message should be unchained.
• When you want to start an unrelated (or at least unsynchronized) chain of events from an existing chain, link the new chain by setting the first event's when condition to is-event-true-delay with a delay of whatever you like — since you won't have a chain delay for this event, which begins a new chain. Set the event for is-event-true-delay to the previous event in the "chain" — the place at which this other chain forks. Then chain the rest of the related events off this new, unchained event.
• To tell an AI unit to warp out, just set the ai-warp-out goal (provided their warp engine isn't broken or disabled.) To warp the player out, you can do a red-alert (for red alert missions) or an end-mission SEXP (the nicer way to do it). You also use end-mission for handling players docking with a station, ship, et cetera; Just invoke it when the player's distance to subsystem is less than a sufficiently low number. I like about fifty to sixty meters.
• Ships take a certain amount of run-up distance to warp out. Experiment with different values to get the jump point to form at the center of a jump node. You need to place a waypoint at the center of the jump node, because for some bizarre reason a jump node is not an object (at least not a proper one) and you can't measure distance to it. I like to give this waypoint a unique name (like "Jump Out") and have it not be a chain. You can always give multiple waypoints-once ai goals to a ship, with each later waypoint set at a lower priority, to get a ship to follow multiple waypoint chains in sequence. Have a ship follow one or more waypoints to move towards the node, then move to your single waypoint.

Goals

• If you want a goal to appear only after the player does something, then set the checkbox for "Invalidate Goal" and it will not appear on the list until you use the validate-goal function (you can invalidate it again later if you like, although in most cases it would make more sense to fail the goal than to make it disappear.) Just don't forget to validate it later, especially if your debriefing takes its completion (or lack thereof) into account.

Some Ideas

Here's some ideas for things I think belong in every mission. This is pure opinion so if you don't like it, I don't care.

More later!

1. Any time you are the leader of a wing you should be made responsible for bringing them all home. Obviously this is horribly hard to do in many cases because your wingmen are very stupid, so it shouldn't necessarily be a condition of victory. But when it is possible, the CO should be berating you for failing to do so. When it is not, they should be consoling you for the loss of your wingmen.
2. Corollary: If no reinforcements are available, and command is in a position to monitor the condition of the player's ship, send them home when their ship is sufficiently damaged. Fail the mission on them, or don't - but if you don't you're probably going to have to branch to an alternate mission to preserve continuity. The game allows you to check if an event or goal was completed in the previous mission, which in retail is the only way to pass information from mission to mission. FS2 Open has persistent variables, and FRED2 Open supports them.
3. Every primary mission goal should have different text whether you succeed or fail it (unless it is not possible to do one or the other.) The player should always get a recommendation as to what they should have done if they fail a goal which is possible. Telling them "you failed the goal, dumbass" is not helpful though - you should tell them what they could do in order to achieve it. By chaining together events you can make this as complicated as you like, and display different (or additional) recommendation text if the player does part of what they told you, but not all. For example, if the player has a goal to destroy a capital ship, there might be events which detect the weapons subsystem and the beam turrets. If the player fails to destroy the ship and has destroyed neither of these systems, then you show text telling them to destroy the weapons system and then the turrets. If they destroy the weapons system, you might tell them to destroy the turrets after the weapons system. This kind of thing makes the mission significantly more complicated but also makes it look much more finished and polished. In the really real world (where we don't have fighter space ships and jump drives, but anyway) humans make complicated, multi-level decisions about situations. Making your mission do as much of this as possible makes it seem more real and increases replay value.