archives/freedoom
2
0
Fork 0
mirror of https://github.com/freedoom/freedoom.git synced 2025-09-01 04:25:45 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

README: rewrite/revisement of many sections

Browse source 
The introduction uses wording mostly copied from the web site to
maintain consistency within the project, and the usage of the term
"IWAD" is greatly reduced.  I still define it, but only so that
someone might become familiar with the term when other people use it,
rather than as a primary term.  Like wise, "port" and "source port"
are largely replaced with "engine," but while defining the former so a
newbie can understand what community members are speaking of.

"How to play" has some additional information about how to actually
get an engine to play the game.  It was previously lacking.  Odamex is
the only port actually outright named as a recommendation, but I try
to keep from sounding like it's the _only_ choice.

The "general rules" to follow has been reduced from four to three, the
first one heavily rewriting so as to not imply that derived works are
completely forbidden.

The "Using Git" section also had a major reworking.  I don't really
like the section entirely myself.  Either needs more revisement or
ejected entirely.

Quite a few linguistic tweaks in all of the sections.

Game names are more consistently italicized.
This commit is contained in:
Mike Swanson 2015-07-20 22:03:54 -07:00
parent 5b716f8376
commit 7b303f22dc
1 changed files with 176 additions and 135 deletions
Download patch file Download diff file Expand all files Collapse all files

311
README.adoc
View file

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