diff --git a/README.adoc b/README.adoc index 76c763a2..fe717c37 100644 --- a/README.adoc +++ b/README.adoc @@ -1,67 +1,99 @@ = Freedoom -Freedoom is a project to create a complete Doom engine-based game -which is free software, in addition to maintaining compatibility with -Doom modifications (``mods'') that have been released by the -continually-active community since 1993. +The Freedoom project aims to create a complete, free content first +person shooter game, but _Freedoom_ by itself is just the raw material +for a game. It must be paired with a compatible _Doom_ engine to be +played. -Freedoom aims to create three ``IWAD'' files for the engine, each of -these is an independent sub-project representing different aims towards -game design and compatibility with Doom mods: +There is a massive http://doomwiki.org/wiki/Idgames_archive[back +catalog], spanning over two decades, containing thousands of _Doom_ +levels and other modifications (``mods'') made by fans of the game. +_Freedoom_ aims to be compatible with these and allows most to be +played without the need to use non-free software. + +_Freedoom_ is actually three games in one, consisting of two +single-player oriented campaigns and one set of levels designed +exclusively for multiplayer deathmatch: [horizontal] -*Freedoom: Phase 1*:: A four-chapter game, nine levels each, totalling -36 levels. This project aims for compatibility with The Ultimate Doom -(also known as plain Doom or Doom 1). -*Freedoom: Phase 2*:: A 32-level chapter featuring extra monsters and -a double-barrelled shotgun. This project aims for compatibility with -Doom II. -*FreeDM*:: 32 levels designed for competitive deathmatch play. +*Freedoom: Phase 1*:: Four chapters, nine levels each, totalling 36 +levels. This game aims for compatibility with _The Ultimate Doom_, +also known as plain _Doom_ or _Doom 1_. +*Freedoom: Phase 2*:: 32 levels in one long chapter, featuring extra +monsters and a double-barrelled shotgun. This project aims for +compatibility with _Doom II_ and _Final Doom_. +*FreeDM*:: A 32-level game designed for competitive deathmatch play. -An ``IWAD'' file is used by the Doom engine, which contains all the -game data such as graphics, sound effects, music, and so on. While the -Doom engine source code is free, you would normally still need one of -the proprietary IWAD files from id Software in order to play -Doom. Freedoom aims to create a free alternative; combined with the -GPL-licensed Doom source code, results in a completely free -Doom-based game. +The engine uses a single file, such as +freedoom2.wad+, that contains +all the game data such as graphics, sound effects, music, and so on. +This file is often called an ``IWAD'' by those in the _Doom_ and +_Freedoom_ communities. While the _Doom_ engine source code is free, +you would normally still need one of the proprietary data files from +http://www.idsoftware.com/[id Software] to play _Doom_. _Freedoom_ +aims to create a free alternative: combined with the GPL-licensed +_Doom_ source code, this results in a completely free game. For more information, see http://freedoom.github.io/. == How to play -Hopefully, your engine of choice should already be capable of running -Freedoom without extra configuration. This may not be the case, -however, if the engine does not recognize any of the filenames for -Freedoom, and might require manual intervention to make it so. One of -the following options should do the trick: +Since _Freedoom_ is only the game data, you will still need to +download an engine separately. These are also often termed ``source +ports'' by the community. There are an overwhelming number of choices +available, a lengthy list of which is available on the +http://doomwiki.org/wiki/Source_port[Doom Wiki]. - * Use the +-iwad+ command line parameter. For example, to play Phase - 2, you can enter +-iwad freedoom2.wad+ either from a command - prompt/terminal, or adding it to an application shortcut. - * Use the +DOOMWADPATH+ environment variable. Many engines support - this variable to add directories and/or IWADs to their search - path. The exact syntax matches your operating system's normal +One in particular that is highly recommended by the Freedoom project +is http://odamex.net/[Odamex]. This engine offers good support for +both single-player and multiplayer games. + +If you wish to venture outside of Odamex, beware that _Phase 1_ and +_Phase 2_ require a Boom-compatible engine, which is thankfully the +majority of them, but without compatibility, some aspects of the game +may not run properly. _FreeDM_, on the other hand, is intended to be +playable by all variants of the _Doom_ engine. + +Hopefully, your engine of choice should already be capable of running +_Freedoom_ without extra configuration. This may not be the case, +however, if the engine does not recognize any of the filenames for +Freedoom, and might require manual intervention to make it so. One of +the following options should solve it: + + * Use the +-iwad+ command line parameter. For example, to play + Phase 2, you can enter +-iwad freedoom2.wad+ either at a command + line, or adding it to an application shortcut. + * Use the +DOOMWADPATH+ environment variable. Many engines support + this variable to add directories and/or files to their search + path. The exact syntax matches your operating system's normal +PATH+ environment variable. - * Rename the game IWADs. This may be a bit crude, but you can rename - the files to match those of Doom's. This is often the easiest - quick-fix, although it is normally desirable to use one of the - above methods if possible. + * Rename the game files. This may be a bit crude, but you can + rename the files to match those of _Doom_'s. This is often the + easiest quick-fix, although it is normally desirable to use one of + the above methods if possible. ** +freedoom1.wad+ can be renamed to +doom.wad+ - ** +freedoom2.wad+ can be renamed to +doom2.wad+ - ** +freedm.wad+ can be renamed to +doom2.wad+ + ** +freedoom2.wad+ can be renamed to +doom2.wad+, +tnt.wad+, or + +plutonia.wad+ + ** +freedm.wad+ can be renamed to +doom2.wad+, +tnt.wad+, or + +plutonia.wad+ -== What ``free software'' means +Additionally, for Unix-like operating systems, such as GNU/Linux or a +BSD variant, _Freedoom_ may be packaged and installed with programs +named +freedoom1+, +freedoom2+, and +freedm+ that automatically run an +engine for proper play. Desktop files may also be installed so that +you can start the game using a graphical interface and avoid the +command line altogether. -When we speak of free software, we refer to the software movement in -which your freedoms to use, copy, modify, and study it are ensured. For -example, you may freely use Freedoom for any purpose you see fit, you -may redistribute it to anyone without needing to ask for permission, you -may modify it (provided you keep the license intact, see `COPYING`), and -you may study it -- for example, to see how a Doom IWAD is built. To -facilitate this, you can get the full source code (here, in the form of -a DeuTex tree) for Freedoom. +== What ``free'' means + +When we speak of free content or software, we refer to the movement in +which your freedoms to use, copy, modify, and study a work is not +infringed. For example, you may freely use _Freedoom_ for any purpose +you see fit, you may redistribute it to anyone without needing to ask +for permission, you may modify it (provided you keep the license +intact, see `COPYING`), and you may study it--for example, to see how +an ``IWAD'' is built. To facilitate this, you can get the full source +code for Freedoom, in this case, in the form of a DeuTex tree. You may read more about free software at the http://www.gnu.org/[GNU] and http://www.fsf.org/[Free Software Foundation] websites. @@ -77,74 +109,77 @@ We know people hate legalese, but this is important. This applies to *everything* which is submitted. You must be incredibly careful when basing on existing graphics or -sounds. Most Doom projects are incredibly lax on reusing intellectual -property -- there are plenty of WADs out there which contain modified -Doom sprites, for example. However, due to the nature of this project, -we do not have the same liberty to rip as we please. +sounds. Most _Doom_ projects are incredibly lax on reusing +intellectual property--there are many mods which contain modified +_Doom_ sprites, for example. However, due to the nature of this +project, we do not have the same liberty to rip as we please. The general rules go as follows: - * Everything you submit must be 100% your own work. You must not base - upon resources from Doom or any other game. You may not even rip - textures from WADs you have downloaded (if you find a WAD with - textures in which look useful, let us know -- that way, we can - contact the author). - * Do not simply copy the original resources. Where possible, try to - make an effort to make the new versions look visibly different from - the originals. - * Be especially careful of ``free texture'' (or ``free sound'' or - ``free graphic'') sites. Although these would appear at first to - be okay to use, many are free for ``non-commercial use only''. One - of the things we want to be able to do is put this on GNU/Linux CDs - (which are sold -- ``a commercial use''). - * The main exception is that you may of course reuse anything in the - Freedoom source tree. In fact, this is encouraged, as reusing - material will give the WAD a more consistent feel. + * You must have permission for everything you submit. If you make + your own resources, do not base on resources from _Doom_ or any + other restricted work. If you take work from other places, please + make sure that the work is freely-licensed or that you obtain + permission to include it in the _Freedoom_ project. They may not + place additional restrictions compared to the normal _Freedoom_ + license. + * Do not try to emulate _Doom_ resources exactly. Where possible, + put effort to make new versions look visibly different from + _Doom_. This is a tough call, because our compatibility with + _Doom_ mods limits how far we can deviate, but it is feasible. + * Be especially careful of ``free textures'' (or ``free sounds'' or + ``free graphics'') sites. Although these would appear at first to + be okay to use, many are free for ``non-commercial use only.'' + One of the things we want to be able to do is put this in + GNU/Linux distributions (which can be sold or developed + commercially). === Levels -Levels for Phase 1 and Phase 2 should be compatible with Boom 2.02: a -Doom-derived engine which is a common ancestor for many engines -today. Its extensions are even commonly reimplemented by engines which -are not descended from Boom. This means that you may exceed the limits -of vanilla Doom and use features introduced in Boom. However, do not -use features that are not supported by Boom 2.02 and compatible -engines. Levels should be in Doom's original format, not in -``Hexen''-format. +Levels for _Phase 1_ and _Phase 2_ should be compatible with Boom +2.02: a _Doom_-derived engine which is a common ancestor for many +engines today. Its extensions are even commonly reimplemented by +engines which are not descended from Boom. This means that you may +exceed the limits of the original _Doom_ and use features introduced +in Boom. Do not use features that are not supported by Boom 2.02 and +compatible engines. Levels should be in _Doom_'s original format, not +in ``Hexen''-format. -Levels for FreeDM must strictly be vanilla-compatible, that is, they +Levels for _FreeDM_ must strictly be vanilla-compatible, that is, they must run in the original +doom2.exe+ engine for DOS and not cause any -VPOs and other such problems in the vanilla engine. This ensures the -maximum compatibility with all Doom-derived engines, including those -that do not descend from nor support Boom features. +visplane overflows and other such problems in the vanilla engine. +This ensures the maximum compatibility with all _Doom_-derived +engines, including those that do not descend from nor support Boom +features. It is sensible to also heed the following guidelines: * Make sure that skill levels are implemented, and that all - multiplayer start points are present. - * Make levels appropriately difficult for their position within the - progression of the game. Also bear in mind that not all players may - be as skilled a player as you. - * Do not use tricks that exploit Doom's software renderer; some source - ports, especially those that use hardware accelerated rendering, may - not render it properly. Examples of tricks to avoid include those used - to simulate 3D bridges and ``deep water'' effects. + multiplayer start points, both coöperative and deathmatch, are + present. + * Try to make levels appropriately difficult for their position + within the progression of the game. Also bear in mind that not + all players may be as skilled a player as you. + * Do not use tricks that exploit _Doom_'s software renderer; some + engines, especially those that use hardware accelerated rendering, + may not render it properly. Examples of tricks to avoid include + those used to simulate 3D bridges and ``deep water'' effects. * Boom removes almost all of the limits on rendering; however, do not make excessively complicated scenes. It is desirable that Freedoom levels should be playable on low-powered hardware, such as phones and old computers. - * For Phase 1 and Phase 2, try to test in + * For _Phase 1_ and _Phase 2_, try to test in http://www.teamtnt.com/boompubl/boom2.htm[Boom] towards the end of - your level creation process, before submission. Incompatibilities + your level creation process, before submission. Incompatibilities will usually be discovered before a release, but it will help to - be sure yourself. Since using DOS-compatible operating systems is - uncommon these days, you may need to use + be sure yourself. Since using a DOS-compatible operating system + is uncommon these days, you may need to use http://www.dosbox.com/[DOSBox] or similar virtual machine software to run Boom. - * For FreeDM, while you can test in the original +doom2.exe+ engine - with DOS or an emulator, this original engine is not free software - and not legally obtainable without Doom itself, in addition to the - hassle of merely running it. + * For _FreeDM_, while you can test in the original +doom2.exe+ + engine with DOS or an emulator, this original engine is not free + software and not legally obtainable without _Doom_, in addition to + the hassle of merely running it. http://www.chocolate-doom.org/[Chocolate Doom] is a free software, highly-portable, and strictly-vanilla-compatible engine without any extra features for levels, suitable for testing FreeDM. @@ -152,30 +187,31 @@ It is sensible to also heed the following guidelines: === Graphics Graphics should generally have the same color and size as the original -Doom graphics, as to remain compatible with PWADs. Otherwise, such -levels may end up looking like a nightmare in design. They may be -thematically different as long as it still fits. +_Doom_ graphics, as to remain compatible with mods. Otherwise, levels +may end up looking like a nightmare in design. They may be +thematically different as long as it doesn't clash. -Doom uses a fictional corporation abbreviated as ``UAC'': this is -trademarked by id Software and cannot be used in Freedoom. Instead, -use the initials ``AGM'' for Freedoom. +_Doom_ uses a fictional corporation abbreviated as ``UAC:'' this is +trademarked by id Software and cannot be used in _Freedoom_. Instead, +use the initials ``AGM'' for _Freedoom_. === Documentation -Freedoom always needs help with the documentation, so please send your +_Freedoom_ always needs help with documentation, so please send your patches, but keep in mind: * We use http://asciidoc.org/[AsciiDoc] for writing the - documentation. AsciiDoc is a simple plaintext-based format which + documentation. AsciiDoc is a simple plaintext-based format which is simple to read and write in its source form, and can generate nice HTML documents out of them. * Headers are formated in a wiki-style format, this makes it easier for Vim (perhaps other editors, too) to automatically re-format text. - * Text is kept at 72 characters wide. In Vim, you can set the editor - to automatically insert line breaks as you're typing by performing - `set textwidth=72`. Special exceptions to the width rule might be - allowed when necessary (for example, inserting long URLs). + * Text is kept at 72 characters wide. In Vim, you can set the + editor to automatically insert line breaks as you're typing by + performing `set textwidth=72`. Special exceptions to the width + rule might be allowed when necessary (for example, inserting long + URLs). === Submitting your work @@ -191,8 +227,7 @@ also be peer-reviewed and provide a feedback cycle. Lastly, it is possible to get work submitted by joining the official irc://irc.oftc.net/freedoom[#freedoom] IRC channel, although this -poses the greatest risk of being lost in the scrollback history and -forgotten. +poses the greatest risk of being lost and forgotten. Unfortunately, the Freedoom project cannot provide hosting space in the form of a web page nor FTP, however there are many free file hosts @@ -203,12 +238,12 @@ simple to use. ==== Using Git -You can also use commit directly off of a clone of the Freedoom -repository, although this tends to be a highly technical task and it -is okay to allow other Freedoom maintainers to do it instead: that is -our normal mode of operation! Pull requests may come from anywhere, -you need not use GitHub if you wish not to, however GitHub usually -makes this sort of thing very simple. +You can also commit on a clone of the _Freedoom_ repository, although +this is a technical task and it is okay to let other _Freedoom_ +maintainers to do it instead: that is our normal mode of operation. +However, pull requests are much appreciated and you may submit them in +any manner you wish, with GitHub's direct pull requests being the +simplest, but by far not the only means. Freedoom uses the commit message format commonly seen in distributed version control systems, and adopted by high-profile projects such as @@ -216,26 +251,32 @@ Linux and Git. The first line of a message needs to be a short summary, preferably at a 72-character limit. The summary usually begins with a short component name followed by a colon, this can be a directory name (eg, `musics:`), a resource name (eg, `map17:`), or a -more generic component (eg, `build system:`). The summary line should -never bleed into a second line, and should never be the start of a -lengthy explanation. If the commit needs further explanation (and -they often do), use extra paragraphs and write in plain-English what -the commit is about. The commit -`2014-08-24T22:42:37Z!fraggle@gmail.com` is a good example. +more generic component (eg, `build system:`). The summary line must +not bleed into a second line, and should not be the start of a lengthy +explanation. If the commit needs further explanation (and they often +do), use extra paragraphs and write in plain English what the commit +is about. The commit `2014-08-24T22:42:37Z!fraggle@gmail.com` is a +good example. -Additionally, use either simple pointers to other commits, such as -``my previous commit'', or use http://esr.ibiblio.org/?p=3872[action -stamps], which can improve the meaningfulness of commit identifiers if -the repository is rewritten at an early point in, or if the repository -is ever converted to another DVCS. At the time of writing (November -2014), core Git does not yet have a mechanism to output this format, -but you may use a +Additionally, do not use commit hashes to refer to other commits. Use +other kinds of pointers, simple ones like ``my previous commit'' might +suffice, or use http://esr.ibiblio.org/?p=3872[action stamps], which +can improve the meaningfulness of commit identifiers if the repository +history is rewritten (this has happened at least twice!), or if the +repository is converted to another VCS (this happened once before). +At the time of writing (July 2015), core Git does not yet have a +mechanism to output this format, but you may use a https://gist.github.com/chungy/195f53bfb9253584e596[shell script] and -place it in your `$PATH` to achieve some ease in doing them. +place it in your `$PATH` to achieve some ease in generating them. -You should commit often; each important change should get its own -commit, but minor changes need not. Take advantage of git's ability to -rewrite history, don't use `git revert` on your private copy of the -repository, just remove (`git reset`) or amend (`git commit --amend`) -the faulty commit as necessary. Leave all the interesting and important -history bits, leave out stupid mistakes like spell check errors. +You should commit at each logical step. Do not bundle up many +unrelated changes into the same commit, and definitely do not write a +commit message like ``changed some stuff.'' Best judgment should be +used for what constitutes a logical step. It may be just a single +file, or it may be a group of files representing a monster in the +game. If you are finding yourself needing to repair previous commits' +blunders in your private repository, try to take advantage of Git's +ability to rewrite history , don't use `git revert`, just remove (`git +reset`), amend (`git commit --amend`), or rebase (`git rebase`) as +necessary. Leave all the interesting and important history bits, +leave out stupid mistakes like spell check errors if you catch them.