Project Standards

This page is to serve as the definitive authority on standards for the Starflight III project.

Performance Goals
The game is meant to be designed as a single-player, non-web-based game, with no provisions at this time to add either a multiplayer or web-based elements. Minimum target hardware requirements are:
 * 2 GHz single-core P4 processor (or equivalent)
 * 1 GB memory
 * <500 MB HDD space (this one must be flexible, as we have no idea how big the finished product will be at this time.)
 * GeForce FX 5200 video card.

Most systems built since the mid-2000s should fulfill these requirements. Provisions for other platforms (Linux, MacOS) will be made as needed, but the initial product will be designed targeting users of Windows XP, Windows Vista and Windows 7.


 * Update - Capi3101 (talk) 14:45, February 17, 2016 (UTC)

What will the system requirements be? We do not have a good answer on this, yet. Theoretically, it shouldn't take much, but I'm simply going to say that it will take what it will take, and we won't really know that until we're closer to finished.

What platforms will the game run on? We're targeting Windows. If Linux or Mac compatibility happens, thanks to Unity, it will be a bonus, but it will not be an explicit goal from the outset. We do not have the resources to dedicate to ensuring compatibility between multiple platforms.

Software
As of February 2011, Panda3D has been selected for the core 3D engine for the game. While most of the game will only require 2D capabilities, some of the desired featues of the game (Starport and Planetary Exploration in particular) will need 3D engines. Historically, the selection of a new underlying engine has caused substantial setbacks in development; while it is hoped that this will be the final decision made for the 3D engine, the author of this design document recognizes that there may come a point where it needs to be changed yet again, should a sufficient number of coders more familiar with another system (such as C#/XNA) be recruited to work on the project. In the meantime, however, all portions of this document will be written with Panda in mind. Version 1.6.2 is the most current stable release of Panda as of this writing; migration to future versions of Panda may be made as new stable releases come out. Panda utilizes one of the BSD open game licenses; SF3 will strive to use this same license, unless something comes up during development which would necessitate the choice of a different one. Panda is a free download, available from their official site.

Pyglet will also be utilized in the project, mainly for audio support. This is owing to the relative ease of use of the module for sound, as well as its support of the MP3 file format standard (of which many of the currently extant music utilize; most of the others are still in MIDI format and will have to be reformatted). Panda's own audio module, FMOD, is proprietary and would (if I understand correctly) require the game to have some monetary cost to offset its use, which is against the aforementioned requirement that the game be freeware. Pyglet is also a free download, available here.


 * Update - Capi3101 (talk) 14:45, February 17, 2016 (UTC)

What language is the game written in? C#

What engine does the game use? Unity. Currently, version 5.3.2, which is the most up to date release as of this writing.

Will the game be 3D? Starflight 3 will be a top-down 2D interface, just like the originals. Any elements of 3D will be purely for effect and will not have an impact on actual game mechanics. The graphics/models themselves may be 3D, but there will be no 3D coordinate system used in the game for any practical game mechanics purposes.

Blender is the preferred utility used for the creation of 3D models by most members of the project, though any program that can export to a Panda-compatible format that our art team is comforable using is acceptable. Panda utilizes .egg and .bam files, and relies on translators to import files from other programs into one of those two formats. The translators for Blender, Maya and Max are well-developed and reliable as of this writing; Panda also has translators for .lwo, .dxf, .flt, .vrml, .x2, and .x file formats, though these are not as well developed and should be avoided if possible. Blender is freeware; it's home site is at www.blender.org. A word of caution for the uninitiated when it comes to Blender: it has a particularly steep learning curve.

Finally, GIMP is the preferred utility used for the creation of 2D images, such as interfaces and shaders, though once again any program that can produce standard 2D file formats (.png in particular) is acceptable (Photoshop is another good example of an acceptable program). GIMP's home page is at www.gimp.org.

Code Conventions
For all languages, code files should be in Unicode UTF-8 or UTF-16 encoding, with DOS-style (CRLF) line endings.

Python
All code for the game will be written in the Python programming language, utilizing the version of Python required by the current version of Panda3D (as of this writing, this is Python 2.6). Where possible, code written for the project should follow the Python Enhancement Proposal Document 8 Style Guide (this file has been hard-copied and will be added to the Documents sub-directory in the svn repository, in the Project_2011 folder. In the unlikely event that this document is removed from the official Python website, team members are directed to look there for these guidelines.)


 * Update - Capi3101 (talk) 14:45, February 17, 2016 (UTC)

''As per above, the project is now using C#. This design document was written during a time when Python was the language of choice; references to the Python programming language in this document will be updated as necessary and possible. The previously existing link to the aforementioned Style Guide rotted; the project still has this guide though that should be a moot point at this juncture.''

Please comment gratuitously on anything you do that isn't in-your-face obvious. Historically, this project has had high developer turnover (and what looks nice to you might take three weeks for someone else (or yourself) to decipher three months from now). While we hope this trend will not continue, it's only wise to assume that it will do so for the foreseeable future. Heavy commenting will also assist those members of the programming team with less experience.

Optimization
Please DO NOT carry out unnecessary premature optimization. If your routine is slow or could perform better, mark it for later optimization. Only make optimization changes if it will not obfuscate the code you are optimizing or otherwise make it harder to understand. Feel free to document and comment on optimizations you would like to see happen in the code, either in comments or in the General Procedures and Notes section of the corresponding module page on the private wiki. Alternatively, a note can be made to the Fleet Command forums at ICC (though this method does not guarantee that the concern will be readily addressed; it's probably better to put a comment in the code.)

Images
"Images" refers to pre-rendered content in file formats understood by programs such as the GIMP or Photoshop. They are used in the project for reference and as game content. As a general rule, pre-rendered images are to be in 32-bit PNG format with 8-bit alpha channel and no interlacing. Bitmaps will not be included in the game unless there is a technical reason for it; any non-PNG image submitted for use in the project will need to be converted over to the aforementioned standard.

Images utilized for reference purposes may appear in the subversion repository, the FTP repository, and the wikis. If an image is to be posted on a wiki, please keep sizes sane, if possible and try to keep a minimal number of large images on each page (sane meaning not much larger than half a megabyte and no more than three to a page, unless absolutely necessary). If it is necessary to have more numerous large images on a single page, consider uploading them and linking to them via the buttons in the editor. If an image is to be stored in the SVN, please do whatever you can to make the file size small. Again, we recognize the fact that some images cannot help but be large; all we're asking is that these instances be kept to as much of a minimum as possible.

Images utilized for game content will need to be as large as necessary to perform their in-game function. No restrictions on their size will be imposed at this time, but the aforementioned pre-rendering standard must be adhered to regardless of all other considerations.

Animations
"Animations" refers to motion video that has been pre-rendered in file formats understood by such programs as Windows Media Player or Winamp. They are used in the project mainly for purposes of cut-scenes and plot advancement. As a general rule, pre-rendered animations are to be in .AVI format, with a 128 kps bit rate, 113 kps data rate and 30 fps frame rate. Any audio associated with the animations should follow the game's MP3 standard.

Animations may appear in the subversion repository or the FTP repository. We ask that animations not be loaded on the wiki unless absolutely necessary, and then no more than one to a page. If an animation is to be stored in the SVN, please do whatever you can to make the file size small. Again, we recognize the fact that some animations cannot help but be large; all we're asking is that these instances be kept to as much of a minimum as possible.

Animations utilized for game content will need to be as large as necessary to perform their in-game function. No restrictions on their size will be imposed at this time, but the aforementioned pre-rendering standard must be adhered to regardless of all other considerations.

XML
XML will be used as the primary data storage format during the initial design and non-public alpha testing portions of the game, to provide easy change paths. By the time public alpha testing is in place, all XML code should be included in the game's "Toybox" object, which will act as an in-game data repository. Data saved in the Toybox will be saved via pickling (use of cPickle, unfortunately, will not be allowed due to incompatibilities across OS platforms). This combination of techniques is designed to prevent cheating; at some point, the utility used to create the Toybox object may be made available to the general public for purposes of modding.

All XML must conform to the XML 1.1 specifications and must be able to validate against the W3C XML validator.

Schemas
All modules described in this design document will have a section devoted to any XML required by the module. Details about all XML files and their schema should be included on these pages whenever possible. Coders are welcome to use their best judgment as to the page under which to place their description. An XSD of the XML document, while not strictly necessary, may help other team members to more fully understand the intended usage of the file; team members are asked to generate XSDs of their documents whenever possible, and especially if their XML file is particularly complex (and its description verbose).

Element Usage
All objects are elements. Basically, if an object is represented in code by a class or struct, it should be made into an element. Elements should not be used for trivial properties such as dimensions, names, and so forth; attributes should be used for that purpose.

Attribute Usage
All direct properties of an object should be made as attributes. If an object is made up of other objects or contains other objects, those other objects should be made as elements, with their respective direct properties created as attributes.

Numeric Data
Numeric data should be stored as an appropriate type, as specified in the XML's description or XSD file. Coders are reminded that it will be necessary to re-cast the data into appropriate Python numeric type in order for the information to be used as intended. For integral data, use integral types (such as int and long). For floating-point values, always use float.

Comments
Comments should be used when possible, but not so much that implementation of them in code is cumbersome or so much that they obfuscate the file to an unnecessary degree.

File Size/Optimization
Team members are asked not to be blatantly wasteful when it comes to file size and optimization, though file size really isn't that big of a concern. Team members are encouraged not to try to over-optimize their XML if it isn't necessary to do so.

Jargon/Terminology

 * SVN - Subversion. A version control application.  Refers to the software or to the repository, depending on context.
 * Repo - Repository. Generally referring to the Subversion repository, but also sometimes used to refer to the (now defunct) FTP repository, depending on context.
 * Editor - Generally refers to the Universe Editor. This is intended as an amalgamation of several smaller editors, which will be used to generate all data for use in the game and ultimately create the Toybox object.
 * Tortoise - TortoiseSVN. A useful free Windows shell extension to interface with Subversion.  HIGHLY recommended.
 * PWiki - The private wiki. This wiki. Located at private.starflight3.org.
 * Wiki - Generally refers to the public wiki, but may also refer to this wiki depending on context. This wiki.

Standards Page Status
This page as of this writing should cover all of the necessary standards to proceed with the project. However, as the project progresses, additional decisions may need to be made regarding coding aspects. When a decision is reached by the team members on a particular matter, this document will be updated to reflect that decision and its implications towards coding.

The following additional standards have been added since this document was initially completed (on February 15, 2011):

(No additional standards have been added at this time).

NEXT: Plot PREVIOUS: Introduction TOP