[karajorma]

As part of the work I've been doing on Diaspora, I've been rewriting the FRED Documentation so that when we get newbie FREDders they'll have something as useful for them as the original FREDdocs were for me when I got started.

I've uploaded my WIP version here since I saw no point on sitting on this until Diaspora is out. I'd like opinions on the content (not the actual HTML, I know that sucks! If anyone wants to fix that, let me know). I'd especially like to hear from newbie FREDders if it's useful to them.

[jg18]

I'll look at this more closely later this week.

Might there eventually be an FS2 version of this documentation as well?

All I know about BSG is that it's a TV show that takes place in outer space.

[karajorma]

I'm basically going to release the final version under Creative Commons so it wouldn't be that hard for someone to convert it from BSG to Freespace. In general about 95% of the documentation was common to both Diaspora and FS2 anyway. Only a few things like shields and jump nodes are FS2 specific.

[jg18]

First, thanks for taking the time to update the FREDdocs. Sadly, I don't know CSS, so I can't help you with making it prettier.

Some things I've noticed so far, bearing in mind that this is still a WIP and assuming that the long-term intent is for this new version of the FREDdocs to replace the retail version:

In general

- Are you planning to include the material from the original FREDdocs' Basic Concepts anywhere? Things like how to move the camera using the keyboard and the difference between selection and marking would be useful.

- You might want to take specific pieces of information that are particularly important and then separate them from the rest of the text as a "Caution:", "Note:", or "Tip:", where the difference between Caution and Note is that failing to pay heed to a Caution can either cost you hours of work or frustration or cause your mission to have serious problems, while failing to pay heed to a Note can cause a bit of confusion or hampered productivity later. An example from the Quick Start would be

Note: Mission titles can be at most 26 characters long.

(Just wondering, what happens if the title is longer than that?)

I suppose there's also "WARNING:", although I don't think there's anything in the FREDdocs that really merits that.

Quick Start

- Just curious, why did you decide to make the new quick start a bit more complex than the original quick start, adding in enemy wings and multiple waves? I suppose the extra complexity doesn't hurt; it makes the quick start more substantive.

Toolbar

- Could you put an image of each button near its description, like in the retail FREDdocs?

- Any chance that you could redo the image of the ships used to explain local vs. non-local rotation? The ships are a bit, well, dark and hard to see.

Menus

View Menu

- For completeness, it'd be good if you covered the entries in this menu that you haven't yet covered, as well as what those entries are useful for, such as Hide Marked Objects.

- For Show Outlines, it'd be good to explain what each wireframe color means, like the table in the retail FREDdocs, although there might be fewer colors of importance in Diaspora, I dunno.

Speed Menu

- I didn't know it was little used. I've had to use it when moving the camera around with the keyboard in the default camera view mode (that is, not Current Ship).

Misc Menu

- Same thing as with View Menu, it'd be good to explain the menu entries that you haven't yet covered and what they're useful for, although maybe you just haven't gotten there yet. [Maybe you can borrow text from the retail FREDdocs? Under what license are they copyrighted?]

- A bit more detail about what Level Object and Align Object do would be good, since I had a really hard time finding information about them, and I still don't fully understand how they work. Is it squaring off the gridlines somehow? I don't have a FRED-capable machine nearby and as such can't check.

- About Mark Wing, I thought that multiple ships can be marked, but only one ship can be selected at a time, right? The wording of this explanation left me unsure.

Editors

- Personally, I really liked having all of the editors explained on one web page, like in the retail FREDdocs. I guess giving certain editors their own page is OK, although it means you can't be immediately sure which page to look at to learn about a particular editor.

- I recommend having some kind of link(s) to the editors on the main page, like in the retail FREDdocs, for quick access.

Ships Editor

- About Special Explosion, what values of Blast are considered large or small? Also, what are the units for Shockwave Speed? Is it meters per second?

- You might want to say something about what are reasonable values for Escort Ship, and that ships listed in the escort list are sorted by priority in descending order (I think).

- What does the Primitive Sensors flag do? Ditto for any ship flag not yet described, although admittedly some of them might not be useful to Diaspora (and thus not covered), I dunno.

- In Initial Status, is Velocity in m/s, or is it in percent of the ship's maximum velocity?

- Also under Initial Status, when it comes to weapons, do "Won't Fire" and "Locked" mean the same thing? I'm especially wondering since I think the relevant SEXPs are called lock-*/unlock-*.

- How does the priority threshold of 89 mentioned in the Initial Orders window work? I assumed/imagined that player-issued orders had a priority somewhere in the 90s, but the text in your description leaves me uncertain.


Well, this is a start. I'll post more later covering the other parts of the documentation.

Hope that helps, and thanks for soliciting feedback.

[karajorma]

First, thanks for taking the time to update the FREDdocs. Sadly, I don't know CSS, so I can't help you with making it prettier.

Not a problem. Besides, at this point my interest is really in getting the content down.

- Are you planning to include the material from the original FREDdocs' Basic Concepts anywhere? Things like how to move the camera using the keyboard and the difference between selection and marking would be useful.

Yeah, I guess I'll have to include those somewhere.

- You might want to take specific pieces of information that are particularly important and then separate them from the rest of the text as a "Caution:", "Note:", or "Tip:", where the difference between Caution and Note is that failing to pay heed to a Caution can either cost you hours of work or frustration or cause your mission to have serious problems, while failing to pay heed to a Note can cause a bit of confusion or hampered productivity later. An example from the Quick Start would be

Note: Mission titles can be at most 26 characters long.

(Just wondering, what happens if the title is longer than that?)

That's a pretty good idea. I have included warnings but it might be an idea to clearly label them as such. In this case it's not the title that was the problem, it's the file name. Anything longer than that with the .fs2 extension ends up being too long to be read by CFILE. So you end up with a mission that FS2 can't see.

I suppose there's also "WARNING:", although I don't think there's anything in the FREDdocs that really merits that.

I'll probably use Note for minor pieces of useful information, Caution for warnings of places where you must be careful and Warning for ones where you can end up spending hours confused.

- Just curious, why did you decide to make the new quick start a bit more complex than the original quick start, adding in enemy wings and multiple waves? I suppose the extra complexity doesn't hurt; it makes the quick start more substantive.

I liked the FS2 quickstart but it really didn't cover much at all. Adding wings is such a basic feature of mission design that I thought it was worth going into. Technically the quickstart gives you all you need to start making a few gauntlet style missions yourself. Secondly I wanted the quickstart to be useful not just to FREDders but also to coders who need to make a simple mission and don't want to learn FRED. They can go through that quickstart in 5 rather than 2 minutes and they'll find it a lot more useful.

- Any chance that you could redo the image of the ships used to explain local vs. non-local rotation? The ships are a bit, well, dark and hard to see.

Yeah, I never noticed the Bolithos were quite that dark. I can easily redo that one. 

- I didn't know it was little used. I've had to use it when moving the camera around with the keyboard in the default camera view mode (that is, not Current Ship).

I've very rarely heard it mentioned. I generally move the camera around by rotating or selecting ships or groups of ships and I find that much quicker than doing it manually. Maybe other FREDders do use it and I'm the outlier. "First rule of Speed Menu is you don't talk about Speed Menu"

- Same thing as with View Menu, it'd be good to explain the menu entries that you haven't yet covered and what they're useful for, although maybe you just haven't gotten there yet. [Maybe you can borrow text from the retail FREDdocs? Under what license are they copyrighted?

I believe they belong to Volition same as everything else does with Interplay having the rights to publish them. I did actually obtain permission from Peter Drake to alter the original docs (although he can't do anything about Volition or Interplay's ownership), but since my plan is to release this version under creative commons, I'd rather they were clean.

- About Mark Wing, I thought that multiple ships can be marked, but only one ship can be selected at a time, right? The wording of this explanation left me unsure.

I reversed my explanation from the one in the original FREDdocs. It actually makes more sense given the way the terms are used in the editor and is more consistent with the way someone not used to working with FRED would expect them to be.

- Personally, I really liked having all of the editors explained on one web page, like in the retail FREDdocs. I guess giving certain editors their own page is OK, although it means you can't be immediately sure which page to look at to learn about a particular editor.

Only 3 editors got their own page. Ships Editor and Events Editor are huge. Both require quite a bit of information. Campaign Editor is so far divorced from the others that I wanted to reinforce that by sticking it on another page.

- Also under Initial Status, when it comes to weapons, do "Won't Fire" and "Locked" mean the same thing? I'm especially wondering since I think the relevant SEXPs are called lock-*/unlock-*.

That was an issue caused partly by and partly by myself. "Won't fire" means that the weapons won't fire in-game. "Locked" means that you can't alter the weapon from the loadout screen. The sexps are somewhat confusingly named until you realise that there is no way a SEXP could affect "Won't fire" anyway.
 I will make the explanation clearer though. I'll probably change Turrets/Afterburner Locked to "Turrets/Afterburner Won't Fire" in code to keep the names consistent while I'm at it.

- How does the priority threshold of 89 mentioned in the Initial Orders window work? I assumed/imagined that player-issued orders had a priority somewhere in the 90s, but the text in your description leaves me uncertain.

Player orders have values between 90 and 100 (I forget the exact values). As a mission designer you can give the AI order with a higher priority but you must balance this against the fact that if a player gives an order, the AI will ignore it and carry on doing the one you gave it.

Hope that helps, and thanks for soliciting feedback.

No problem, thanks for taking the time to write it all out. I didn't respond to all your points cause some I simply agreed with and will fix in the next iteration.

[General Battuta]

Do you mean there's no way a SEXP could affect 'Locked'?

[mjn.mixael]

I read through it. It's quite good and detailed. Definitely would be able to learn from it. I think jg18 summed up what most of my feedback would be, so I won't retype it all.

One thing I'd like to do when it's all done is convert it to be FS centric. (Literally just change words and recapture pictures). So that new FS players don't dismiss the tut as being only for Diaspora.

EDIT: A good warning for the SEXP section is to make sure readers know that SEXPs can't return strings. Period. Ever. (I think this is good because I found myself thinking they could for a while, or.. forgetting that they can't.)

[karajorma]

Do you mean there's no way a SEXP could affect 'Locked'?

Yes, my bad.

Locked is a flag that means the player can't change their loadout or ship class. There's no way to get at that from in the mission since by the time you start the mission you are already past that point, you're already in the mission. The mission designer can alter the loadout or even jury-rig a system allowing the player to do it, but there's no way to go back to the loadout and have the player do it.

That said, while writing that I realised I was wrong, there is a way, Goober added the Perform-Actions SEXP very recently that allows you to call change operators from within the mission briefing. So now all you'd need would be a SEXP allowing you to unlock the loadout. However, when I wrote the SEXPs, I was right. If you knew want "locked" did, there was no way you should mistake the Primaries/secondaries-locked SEXP as having anything to do with it. 

[jg18]

Some more comments:

Screenshots

- Ensure that your screenshots contain realistic content, rather than being blank, such as the screenshots of the Debriefing Editor and Voice Acting Manager currently are. The content doesn't have to come from real missions; it can just be made up for the purposes of the screenshot (i.e., a mock-up). Even if Diaspora doesn't currently use an editor, such as the Fiction Viewer, you might want to make up some plausible phony data to use in the screenshot for illustration purposes.

Some more examples of this idea would be expanding the sexp trees for the goals in the Mission Objectives Editor, using a dockpoint in Initial Status, adding a few orders in Initial Orders, and using more complex (but realistic) SEXPs in the arrival/departure cues in Ships/Wings Editors.

Doing these things will help maximize the amount of information that you communicate in each screenshot.

- Consider using the "window snip" feature from Windows 7's snipping tool to take screenshots of specific windows. You can access the window snip using the arrow next to "New" in the snipping tool's menu bar. It'd likely be easier than using click-and-drag to grab rectangular screenshots, which is what it looks like you're currently doing.

Toolbar

- In the Ship Selection List, describe what the All/Clear/Invert buttons do, as well as the difference between the top list and the bottom list. Changing the screenshot to one in which both lists had at least one entry would be helpful.

Editors

Ships editor

- In Initial Orders, note that orders 6 through 10 are permanently disabled, but you can always use the add-goal SEXP to add more orders.

Wings editor

- Change Wing Threshold to Wave Threshold.

Events Editor

- Good explanation of trigger count vs. repeat count. I think I finally get it now. One thing: will trigger count trigger the event, regardless of whether the event trigger is actually true?

- How is it determined when directives are displayed? The event for a directive seems primarily about determining when the directive is completed/failed. There are some directives in my first mission that I had trouble getting to display when I wanted them to.

- On that point, could you expand a bit on the use of is-event-true/false-delay in directives? Am I reading it right that those SEXPs are used to determine when the directive appears unless the optional third argument is supplied, in which case they're used to determine whether the directive has been completed?

- Consider visually showing the difference between Add/Replace/Insert Operator, maybe with four screenshots of a SEXP, with the leftmost being the original one, and each of the other screenshots showing the result of performing one of the three operations (add/replace/insert). Granted, it's something you don't really get until you try it out (and most likely screw it up).

- Maybe also include something about how Add Operator is used to make logical SEXPs (particularly and/or/etc.) have more than two arguments, since this fact wasn't obvious from the retail FREDdocs.

- Maybe note that reordering events tends to cause problems and as such isn't recommended.

Background Editor

- Maybe describe what the skybox flags do. Alternatively, is this a case of "if you need to change these, either you'll know what to do or someone will tell you what to do"?

Mission Specs Editor

- Include an overview sentence about what the mission specs editor is for.

- As mentioned before about the View Menu and Ship Flags Editor, please include descriptions for what all of the checkboxes do and what they're for.

- Are badges the same as medals in "disallow promotions/badges"?

- What image formats do squadron logo and loading screen accept?

Custom Wing Names

- I don't understand what this is for. What does it do that the Wings Editor doesn't?

SEXPs

- An explanation of how individual boolean SEXPs can only return true or false, but triggers for events may return true, false, or incomplete, as well as why an event trigger would return incomplete, would be helpful, since I'm not sure I fully understand this myself. The retail FREDdocs touch on this issue, but they don't explain it as thoroughly as I'd like.

- Similarly, it might be worth noting that not is-event-true-delay != is-event-false-delay.

Other stuff

- If you're going to redefine selection and marking, you might want to change the text in FRED's status bar from "Marked" to "Selected", assuming that people even look at the (woefully underutilized) status bar.


That's all I have for now. I might have a follow-up post later with additional comments, but this should cover just about everything.

Hope that helps.

Also:

One thing I'd like to do when it's all done is convert it to be FS centric. (Literally just change words and recapture pictures). So that new FS players don't dismiss the tut as being only for Diaspora.

Just to note, in order to keep the document compatible with Creative Commons, someone'll need to come up with a new mission to use for the extended walkthrough, or we could adapt an existing community-made mission for it if the FREDder in question is okay with that.

EDIT: Clarification.

[karajorma]

Updated with most of jp18's suggestions. Some of the Editors.html changes are still pending cause Amaya keeps crashing on me whenever I try to edit that file. If anyone knows a good WYSIWYG HTML editor for free, please tell me about.

Since I've either not clarified these yet, or cause they're buried in the docs.....

- Good explanation of trigger count vs. repeat count. I think I finally get it now. One thing: will trigger count trigger the event, regardless of whether the event trigger is actually true?

No, the trigger must still evaluate to true. Basically Trigger Count means the game waits the Interval and then starts testing the trigger every frame like it would with a non-repeating event.

- How is it determined when directives are displayed? The event for a directive seems primarily about determining when the directive is completed/failed. There are some directives in my first mission that I had trouble getting to display when I wanted them to.

Directives by default will appear as soon as the mission starts. If you chain a directive to another event however the directive must wait for that event to be true + the chain delay before appearing. FS2 however is fairly smart when it comes to directives, if the directive mentions wings or ships not currently in the mission the directive might not appear. This is probably the reason why some of your directives worked and some didn't.

Custom Wing Names

- I don't understand what this is for. What does it do that the Wings Editor doesn't?

By default the player must be in Alpha wing. Beta through Epsilon are the wingmen that will be displayed on the Wingman Status Gauge. Custom Wing Names allows you to change those wing names.

[Sheridan_37]

Well I'm a newbie fredder, been fredding just over a year now and after reading your updated documentation i have already learned something new. I think this will be of great use to all like me, i certainly could have done with this when starting out (and will keep referring to it) but with the good people on HLP sharing their knowledge and looking at how other people built their missions through opening them up in fred i am learning fast. a definite

[Scourge of Ages]

Bump! Because I just learned something that should definitely be recorded:

- In Initial Status, is Velocity in m/s, or is it in percent of the ship's maximum velocity?

It is... a percentage of $Max velocity!

I was having real trouble figuring out why I had to set the speed way higher than I actually wanted it in my mission, and finally figured it out for myself. I don't think it's actually noted anywhere that I could find that it's a percentage.

I makes a lot of sense, and I don't know why I didn't realize sooner, but that's what it is. And it needs to be recorded.

P.S. fs2downloads.com is down

some search term seeding for future reference: initial status velocity initial velocity initial speed

[jr2]

http://www.downforeveryoneorjustme.com/fs2downloads.com

Yup. 

[karajorma]

I know it's down, it's hosted in the same place as the FSO installer.