Modding, Mission Design, and Coding > FS2 Open Coding - The Source Code Project (SCP)

[Master Sticky] The "Read Me First" Posts

(1/2) > >>

Zacam:
This is the consolidation of previous sticky posts to help provide the "One Stop Shopping" sort of starting point for folks.

So, lets begin the journey, shall we?

* Post #2: Reporting Bugs: The HOW-TO
  Details Mantis, our bug reporting system and where it is and how to use it.
  (modified from the original post created by Inquisitor)
* Post #3: Getting the Code: SVN and You
  Takes you through how and where to go to check out the source code.
  (copied from the original post created by Karajorma)
  Sign up for email summaries of all SVN commits by joining the FS2Source Google Group
* Post #4: RE: "Hi, I'd like to code for you, where do I start?"
  Whether you are new or you've been around, the question is "How can I get started with helping or coding for the SCP?", this post will hopefully provide some answers. New original Post by Zacam.
* Post #5: What to do when SCP coders cannot reproduce your fs2_open crashes?
  You've got a bug, you've reported it, but it doesn't seem to want to show itself to a coder. This post will help you out with how you can help us help you.
  (copied from the original post created by Fury)
  You can also call this the "How do I Compile My own FSO Exec?"
* Post #6: How to write new Sexps. A guided tour, by The E.
* Post #7: How to enable multiplayer support for new sexps. A guide by Karajorma.
* Post #8: How to use gdb to get debug information on Linux. In case the guide in post #5 is not usable for you. Written by niffiwan.
* Post #9: How to transfer patches from svn to git
As time progresses, the following posts may change, or new ones added, this post will serve as a changelog for that.

Zacam:
(modified from the original post created by Inquisitor)

We use a bug-tracking system called Mantis, and it is located here.
This is used to track bug reports only. It's highly recommended that you give a read to Karajormas wonderful article: "How to report bugs - A Coder's Perspective" before starting.
Additionally, give a read to this article on how to submit bugs. It will save both you and us a substantial amount of grief.

Here are the Guidelines to adhere to when using Mantis:

* Look before you leap - make sure there isn't a similar bug before you post a new one. If there is a similar bug, post info on your particular circumstance.
* Give the bug an intelligible title.  Nothing is worse than "it's broke" or "weird problem".  Help us make sense of it.
* Provide as much information as you can.  What you think is unimportant could actually be very important in finding out what's causing the bug.  It's better to have too much than too little.
* ALWAYS post what build you're using.  Usually it will have the date in the file name.  If it's just named something like "fs2_open_r", post where you got it from and what date it was posted.
* ALWAYS post what command lines you're using, and whether removing them makes the problem go away.
* ALWAYS post whether you're using any of the mediaVPs, and whether removing them makes the problem go away.
* ALWAYS run a debug build and post any errors you get with it (Not all builds have a debug build with them though)
* ALWAYS keep track of any bugs you report.  Check them regularly, provide reminders to the coders if necessary, and make sure your Mantis emails aren't getting eaten by the spam filter.  If we can't reproduce your bug, and we can't get in touch with you, we WILL remove your bug report.
* If you haven't done so already, READ THIS ARTICLE.  Seriously.
If you must browse without registering, please use these credentials:

Username: SCPGuest
Password: password

However, note that you will not be able to report bugs as a guest. To be fully involved, please take the time to register. We do not allow anonymous bug reporting: the reason we require registration is so that we can keep in touch with our bug reporters.  Again, bug reporting is not fire-and-forget. We will usually need to ask you to do something to help us fix the bug.

Help us help FreeSpace. You guys are as important to this process as any of the developers.

Zacam:
(copied from the original post created by Karajorma)

Here's how you set things up:

NOTE: For Windows 7 folks, you may need/want to install hotfix KB982927 first to prevent issues.
(copied from Fury's Guide)


* Go to the Tortoise SVN homepage and download the latest version
* Install it. You'll have to restart your PC afterwards
* Make a new folder on your HD where you'd like to install the code. You'll need a fair bit of space for the code + the intermediate files created when building it.
* Press right mouse in the new folder and choose SVN Checkout from the list.

* An new window will open up. Cut and paste this into the URL of repository box svn://svn.icculus.org/fs2open/trunk/fs2_open
* By default the HEAD revision will be selected. You probably don't want to change this. Your screen should now look like this

* Press OK to begin downloading from the repository. The process shouldn't take long if you have a reasonably fast connection.
Additionally, for Window Users:
(copied also from Fury's Guide)

* Create a new user environment value where variable name is FS2PATH and variable value is full path to your Freespace 2 folder, by default C:\Games\FreeSpace2. This applies too all Windows OS', not just XP.
* Restart your computer. This step is REQUIRED for the environment variable above to take effect!
* Follow instructions in this guide to optimize TortoiseSVN caching, which reduces disk activity significantly. As per instructions in the linked guide, include your Freespace2 folder and don't forget the asterisk, for example C:\Games\Freespace2\*

Zacam:
So, you're new here (or maybe you've been around for awhile) and now you want to code, but you don't know what, where or how to get started.

Welcome aboard! And firstly, thanks for taking the time to be here, we hope you will enjoy your stay, and it's my personal hope that you will find the following information useful.

Yes, there is quite a bit of it, no you don't need that tazer, trust me.

Not knowing where to get started with something can be really daunting.
Especially if you've just done a code checkout (for whatever reason) and you're trying to make sense of it all.

Here are some basic bullet points:

* The Cardinal Rule: At the end of the day, the engine MUST be able to load AND use in retail fashion the original Retail FS2 data.
  Everything else added or done to the engine (for a Total Conversion, MOD X or "Just because it's cool") is permitted, but it cannot break that rule.
  This means that any new feature should be turned off by default if it changes retail behavior.

* SCP/FSO is Multi-Platform. We operate on Windows, OS X and Linux.
  There are probably quite a few additional platforms, but we're mostly after the 3 Amigo's
  We are probably heaviest on Windows platform coder-wise right now, so more OS X and Linux people are VERY much Welcome

* Our Graphics Engine is in OpenGL. We do use GLSL Shaders (currently at a minimum of Shader Model 2.0)

* FRED2 is still currently Windows Only, and will not compile on Express editions of MSVC.
  wxFRED is looking to change that, but needs more work to get off the ground.

* The Cardinal Rule (Redux): At the end of the day, the engine MUST be able to load AND use in retail fashion the original Retail FS2 data.
  Everything else added or done to the engine (for a Total Conversion, MOD X or "Just because it's cool") is permitted, but it cannot break that rule.
  This means that any new feature should be turned off by default if it changes retail behavior.

Don't forget to read the "Getting the Code: SVN and You" post.
As well, ensure you have (at a minimum) a working FreeSpace 2 Install. Anything else after that (TC's, MediaVPs, etc) is completely optional. Recommended install path on Windows is "C:\Games\" or anywhere -OTHER- than "Program Files" or "Program Files (x86)"

What We Are Looking For, Can Use and NEED:

-+People who can Profile/Optimize/Analyze and Debug:
(speaking from MSVC experience here, but there are many tools on other OSes to accomplish this)
Being able to step through Asserts/Warnings/etc and find out how/why and being able to Profile or run Analysis (run-time OR Compiler level) on where the code spends the most of it's time and finding out why.

EVEN IF you are not an excellent or strong coder, don't despair! We still need (what Karajorma affectionately calls) Spaders.
If you can compile the code and run it in a debugger, you can help find (and maybe even fix!) existing issues.
Finding the bugs (and reporting what you found) goes a HUGE mile to helping us improve the engine, especially when some issues can be hard to reproduce. And the best part about it is, again, you don't necessarily need to be a strong coder to do it, and it can provide a GREAT place to start, especially with getting familiar to the state the code is in currently.
(More details here)


-+Resolving Mantis Issues!
We get a lot more New Features or Feature requests worked on than we ever see in resolved Mantis Issues.
Even just a simple "Can this still be reproduced" test and comment on the ticket will go a long way to helping us really know what needs working on.
ALSO: Do check out the FreeSpace & FreeSpace Open Support board on a regular basis. Not to provide support, but to know about User interaction issues and their resolutions.
It's also a great way to see common mistakes and I like to (mentally) resolve issues and see how close I came when the final solution is reached.


Additional Things We Are Looking For:

-+Network Coders:
Aside from taylor/Karajorma, we don't have any.
Multi (and the ability to do really cool things in Multi) is kind of suffering from this. Being able to have stableserver/client connections, SEXPs over Multi, Asteroid/Nebula Online, persistent Multi Campaigns, etc.


-+Graphics API (preferably OpenGL) Coders:
Even DirectX people can help in this area so long as your C/C++ is strong.
Knowing how a graphics API work-flow and pipeline works is what we need, especially if it can be translated well into being usable in OpenGL.


-+Documentation and Standardization:
We're still an intermix of C and C++ and this can get rather interesting at times.
A lot of things can stand to be better outlined so that we can find weak areas, or redundant (unnecessarily so) portions and address them.
As well, being able to follow data from point A all the way to Z (and see what it does along the way) can be made a lot easier with better thread_safe and documented code, especially if we can have reliable "mangers" to handle passing the data around.
(Currently Echelon9 has undertaken being the Point Person for the Documentation Project)


-+People familiar with cross-platform portability issues:
We ESPECIALLY need more dedicated OS X/Linux people.
If you can compile on more than one platform, that is an awesome bonus, but the more people we have in any one platform that can resolve compiler warnings or code issues, the better. Being able to address 64bit expansion would also be nice.


-+Optimizations:
Such as: SSE/SSE2 is done with MSVC at a compiler level, there is nothing run-time wise that takes advantage of of the performance
available by enabling/using these extensions.
This is just one example, I'm sure there are many more places where we can have optimizations.


-+External Transparency:
FRED compiles the same CODE dir as FSO, but it has it's own needs as well as to have the things it can or cannot use explicitly defined with it.
Being able to have the code ONCE and usable multiple times or to multiple places would be the best thing since sliced bread.
The ability to have SEXPs, LUA and accurate external Table/Data parsers that can validate data (outside of either the engine or FRED) can help make modding people happy, and happy modders make more content.


Current Hangups:

Collision Detection: The code spends more time here than anywhere else.

Asteroid Code: It needs better data structures and better algorithms for tossing rocks at ships.

Rendering: Modern graphics cards should be able to render high-detail models much faster than they do in FSO. Smarter understanding/reworking of the rendering code could possibly fix that, and give us some major FPS increases

More Modular Tables: Not everything that is Tabled by Retail currently has modular extendability. This would include being able to use a 'mod.tbl' for settings that are generally mod specific or "Global" settings that don't have a place anywhere else.


Other things that would be nice (aka: Some somewhat more specific examples):

-+Converting/Updating the VP format to allow for Compressed (non-solid) Archives (LINK):
As described in the link, the ability to compress VP files (or distribute them compressed and leave them that way) would be much appreciated as Mods/TC's get larger.


-+Native usage of OpenCollada DAE as an in-game model format.
Failing that, implement and expand the POF format as much as possible.
(Being able to generate and store IN the POF the Cache file, for instance.
Would probably require collaboration with PCS2 to make happen)


-+wxFRED:
Since FRED2 Open is a Windows only application (and will not compile under Express Editions of MSVC), wxFRED's objective is manifest as:

* Replicate all of the existing (or at least, Retail to start) functionality of FRED
* Be available to users on the Big 3: OS X, Linux, Windows. Preferably with a consistent UI
* Where possible, address the short comings of FREDs UI and ease of use, enhance the systems scalability

-+LUA & SEXP Organization and Management:
Sort of ties in with the Transparency noted above, but this is also about making sure that we can have a scalable method for controlling these and adding new ones.


-+Interface Overhaul:
Similar to the HUD Overhaul, this would allow for customization to take place with being able to create, define and layout new Interface elements instead of relying on limited fixed-functionality or specific image formats.
(One idea: An expanded "Advanced" Options screen, possibly in the Pilot Select screen (as the Game State hooks are not set yet) where options currently controlled by the launcher can be set)


-+People to Fulfill or Test feature Requests:
Cause we can get a lot of them. Especially in the public forum. At some point, should you be granted an SCP Badge, you'll find we have an Internal Forum for Hosted Projects Collaboration. These are Feature Requests being made because a MOD/TC is actively finding them necessary to continue their project, so those will get TOP priority.


-+Feedback and Testing on other Projects:
Aside from FSO itself, we have the wxLauncher, a cross-platform Installer, PCS2 and any other number of tools that can use help. Many of the original FS (Descent Manager) Tools haven't seen an update in AGES.


How This Will Work:

Alright, so you've gotten some feedback or you have found something to work on, and you want access or the ability to commit it. And hey, you've probably done an awesome job on it, so why shouldn't you?

Well, we are an at will community. This is our free time, for the largest part. And we've had a lot of in's and outs in our coder base as well as our code base. So, we need to make sure that changes that happen are understandable and maintainable. We can't make anybody stay, but those that are here need to be able to continue maintaining the code. So here is how the process works.

* Find your Feature/Bug that you want to work on and work it, test it, refine it, get it to where you think it's ready for the lime light.
* Generate a .diff or a .patch for your code changes. Create a topic (or respond to an existing one) or the Mantis Issue (we also like seeing Topic Posts for updates to Mantis Issues, so we can be sure they don't get missed) and attach your diff/patch to that.
* An SCP coder (possibly several) will take a look at it. And no, it won't happen automagically. We don't don't have a bat signal or Spidey Sense, it may take us a while, so relax.
* Feedback will take place from whomever grabs and compiles/tests your code. EVEN IF the person responding to you isn't a Coder, some key words to watch for in ANY response is "causing warnings in the compiler" or "getting an error 'X" in testing it". Follow up and own those and resolve them if they happen.
* Stay positive and communicative. Even if you think it should be obvious to everybody, provide clarification when asked for it. We all walk different paths and have different skills, this is what makes us great, but can also cause the greatest discord when we don't communicate well.Once the code has undergone peer review, it will initially be contributed to our SVN by an SCP coder (with all appropriate credits given). There is no hard and fast "Do 'X' number of things, Get a Badge, do 'Y' more after that, get Write Access". It's all about the quality of the work and the commitment to getting it done, and done well and rightly the first time through.

Code can also be an art as much as it's a science. It's easy to get frustrated. But we're here to help those who -want- to help themselves so that we can all be better. We're open to any idea, but be aware that liking and wanting an Idea done is not the same thing as everybody dropping everything and doing it right then and there. We're not a fast paced, high volume code-fest (though there are times where we have our moments!), so be assured that Patience is not only highly valued, but also well rewarded.

Communications with Coders can take place here, in these forums, or you can hit us up on #SCP channel on Esper.Net IRC. (that's a link to go there using Mibbit, a browser based IRC). And unless other wise suggested by another coder, don't just go PM'ing somebody in regards to something.

Zacam:
(Note: If you already have gone through the above posts for checking out the code, or already have an established IDE, you can skip to step 25. This guide is meant to be a 'absolute zero' start to finish for people to be able to follow)

(copied from the original post created by Fury)

So you have encountered frequent problems with fs2_open that leads to crashes? You have already provided debug log for support people and coders, but it wasn't enough and no coder can reproduce these crashes to fix the problem? Don't worry, you can help the coders out by providing important information needed to track it down.

This however involves downloading and installing Visual C++ 2013 Express, TortoiseSVN and fs2_open repository. All of this has been instructed in detail below, so be sure to follow them to letter and ask for help when needed. It's not hard at all, but it does require some time and effort.

What you however can't do is track down non-crash related problems. Such problems will require more or less knowledge about the code and coding itself. In addition these instructions cannot be used to solve crashing problems in fred2_open, as fred2_open cannot be compiled in Visual C++ 2010 Express.

1. Download Visual C++ 2013 Express and install it.
2. Check Microsoft Update for software updates.
3. If you use Windows 7, install hotfix KB982927, click the "View and request hotfix downloads" link in top of the page. Or install Service Pack 1. TortoiseSVN is likely to trigger this Windows bug.
4. Download TortoiseSVN and installl it.

5. Create a new user environment value where variable name is FS2PATH and variable value is full path to your Freespace 2 folder, by default C:\Games\FreeSpace2. This applies too all Windows OS', not just XP.
6. Restart your computer. This step is REQUIRED for step 5 to take effect!

7. Follow instructions in this guide to optimize TortoiseSVN caching, which reduces disk activity significantly. As per instructions in the linked guide, include your Freespace2 folder and don't forget the asterisk, for example C:\Games\Freespace2\*

8. Create a new folder to your Freespace2 folder called fs2_open.
NOTE: If you need or want to use antipodes FSO builds instead, then create a folder called fs2_open_antipodes.
9. Right click on the folder and select SVN Checkout.
10. Copy this to "URL of repository": svn://svn.icculus.org/fs2open/trunk/fs2_open
NOTE: If you need or want to use antipodes FSO builds instead, then use following url: svn://svn.icculus.org/fs2open/branches/antipodes
11. Make sure "checkout folder" is the folder you created in step 8. Make sure "checkout depth" is set to "fully recursive". And finally, make sure "HEAD" is selected in "revision". Then click OK.

NOTE: Steps 12-15 are optional steps and should only be done if instructed so by a coder. Skip to step 16 if you're unsure.
12. If you have received a patch-file from a coder, make copy of the folder created in step 8 and call it something like fs2_open_patchname where patchname is name of the patch you've been provided.
13. Place the patch file in fs2_open_patchname folder. Then right-click on the patch file and select TortoiseSVN --> Apply patch.
14. Two windows will open, the smaller window lists files that the patch modifies. Right click on the small window and select "Patch all".
15. If there are no errors of any kind, you can close these windows now. Otherwise, ask the coder who provided your patch for assistance.

16. Go to fs2_open folder (or the copy of it if you followed steps 12-15), open projects\MSVC_2013 folder. From there open file called Freespace2.sln. Select Visual C++ Express 2013 as the application to open it in if asked to choose an application.

17. On left side you see a small window called solution explorer. Right click on "Freespace2" and select Properties.
18. Again on left of the newly opened window you see "common properties" and "configuration properties", under "configuration properties" select "debugging".
19. Change "Command" to: $(FS2PATH)\$(TargetFileName)
20. Click OK.

NOTE: If a coder advises you to do a clean build, you can do this by following steps 16-20. Make sure Visual C++ 2013 Express window is active, press Ctrl + Alt + F7. Then follow instructions from step 21 onwards. If this is your first time doing this, you can safely skip straight to step 21. Even if this is not your first time, normally clean build is not needed.

21. Look up to the toolbar row. Under "Help" you see a green triangle and to right a dropdown menu. Select "Debug Inferno SSE2" from the dropdown menu.
22. Press F7 on your keyboard. A small "Output" window opens. Wait until it finishes, this probably takes a few minutes on most computers.

23. When text in the "Output" window stops rolling, last three lines should be more or less as follows:

--- Code: ---6>  Freespace2.vcxproj -> C:\Games\FreeSpace2\fs2_open\projects\MSVC_2010\Debug SSE2\fs2_open_3_7_2_SSE2.exe
6>          1 file(s) copied.
========== Build: 6 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

--- End code ---
In third to last line you will see name of the exe file that has been copied to your Freespace2 folder. If a file of same name already existed, it has been overwritten.

In second to last line you will see whether copying has been succeeded or failed, this needs to say succeeded for us to continue. If this says failed, seek assistance on the forums or irc, alternatively browser based irc link.

In the last line you will see outcome of your build. Normally you will see one failed because Visual Studio Express cannot compile fred2_open. This is fine and we can continue. If you have more than one failed, seek assistance on the forums or irc, alternatively browser based irc link.

NOTE: If you need to seek assistance, select the "Output" window and then press Ctrl + A, this selects all text from the window. Now, copy and paste the text to Pastebin and include a link to your pasted text for coders to read.

24. From your Freespace2 folder, open launcher. We need to run FSO in windowed mode, so first lower your resolution from video tab. Then go to features tab, select dev tool from under list type. Select windowed mode. Also ensure other settings such as active mod are suitable for your bug hunting. Click OK.

25. Go back to Visual C++ 2013 Express window and make sure it is active. Press F5.
26. In a moment you will see FSO window opening up. Note that running FSO in this mode is significantly slower than it would be normally, you just have to bear with it.
27. Now play FSO normally until you encounter the crash bug.

NOTE: If you missed something in the launcher, like selected wrong mod or your resolution is too large or too small for windowed use, exit FSO. Change required settings in the launcher, then select window of Visual C++ 2010 Express to activate it. Press F5 again.

28. You have encountered the crash you were looking for. Now, there are two types or crashes. First is straight crash to desktop (CTD) which doesn't produce anything more than regular Windows error message about "this application has closed". Second is an error or assert message given by fs2_open and it gives you two options - OK and Cancel. Click OK.
29. Now regardless of whether you got a CTD or fs2_open error/assert message, you should now have "fs2_open_3_7_2_DEBUG_SSE2.exe has triggered a breakpoint" message in your Visual C++ 2013 Express window. Click Break.
30. You see a small window in lower right corner, it has three tabs - call stack, break point and output. Select call stack.
31. After selecting call stack tab, make sure the small window is active. Press Ctrl + A to select all text, then copy and paste that text to Pastebin.
32. Now you need to give a link to your pastebinned text to a coder, either in the forums or irc, alternatively browser based irc link.
33. Follow instructions a coder may give you to further troubleshoot your crash if it is needed.


NOTE: To repeat these steps at a later date:
- Right click on the folder created in step 8, select SVN Update.
- Once update is done, click OK.
- Continue from either step 12 or 16. Steps 12-15 are optional steps and should only be done if instructed so by a coder. Skip to step 16 if you're unsure.

Navigation

[0] Message Index

[#] Next page