archives/freedoom
2
0
Fork 0
mirror of https://github.com/freedoom/freedoom.git synced 2025-08-30 08:16:54 -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 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.