= Freedoom

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.

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*:: Four chapters, nine levels each, totalling 36
levels.  This game aims for compatibility with _The Ultimate Doom_
mods, 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_ mods.
*FreeDM*:: A 32-level game designed for competitive deathmatch play.

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

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].

One particularly recommended by the _Freedoom_ project is
https://zdoom.org/[GZDoom].  This engine offers good support for
single-player, multi-player, and the majority of mods created for both
_Doom_ and _Freedoom_.

On Windows, you should place _Freedoom_'s data files (those ending
with +.wad+) alongside the engine (eg, +odamex.exe+).  On Unix-like
systems, these data files should go in either +/usr/share/games/doom+
or your home directory.  If _Freedoom_ comes packaged as part of your
operating system distribution, it should already be installed into the
proper location.

If you wish to venture outside of GZDoom, beware that _Phase 1_ and
_Phase 2_ require a https://doomwiki.org/wiki/Limit_removing[limit
removing] engine, which is thankfully the majority of them, but
not all.  _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 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+, +tnt.wad+, or
       +plutonia.wad+
    ** +freedm.wad+ can be renamed to +doom2.wad+, +tnt.wad+, or
       +plutonia.wad+

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.

== 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.

== Contributing to Freedoom

Contributions to _Freedoom_ are always welcome, however there are a
few guidelines that should be followed:

=== Intellectual property

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 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:

  * 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_ must be compatible with any limit
removing engine.  This means that you may exceed the limits of the
original _Doom_, but do not depend on any additional mapping features.
Levels should be in _Doom_'s original format, not in “Hexen”-format.

It is a goal that future versions of _Freedoom_ will be entirely
vanilla-compatible, not even allowing expanded limits.  Keeping this
in mind while mapping may make it easier for your level to be
preserved.  Levels requiring large amounts of modification to fit into
vanilla limits may be discarded entirely in favor of a less complex map.

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
visplane overflows and other such problems in the vanilla engine.
This ensures the maximum compatibility with all _Doom_-derived
engines.

It is sensible to also heed the following guidelines:

  * Make sure that skill levels are implemented, and that all
    multiplayer start points, both cooperative 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.
  * While unrestricted by limits, 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 your levels in
    http://fabiangreffrath.github.io/crispy-doom[Crispy Doom], which
    is an engine that is limit removing but does not introduce mapping
    features to accidentally exploit.
  * 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.

=== Graphics

Graphics should generally have the same color and size as the original
_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_.

=== Documentation

_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
    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).

=== Submitting your work

The most common, and a fairly simple method, to submit your work is by
posting it on the http://www.doomworld.com/vb/freedoom/[Freedoom
forum] on Doomworld Forums.  This allows a great number of people to
review the contribution and provide feedback, although the
registration process is known to be cumbersome.

An alternative to using the forum, is to post your submission on the
https://github.com/freedoom/freedoom/issues[issue tracker], which may
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 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
to use when you need a location to upload files.  Sites and services
such as https://www.dropbox.com/[Dropbox] and
https://mega.co.nz/[Mega], as well as others, are common and should be
simple to use.

==== Crediting information

_Freedoom_ is made up of submissions from many people all over the
globe.  All of them, and you, deserve credit!  Please do not forget to
provide your name and email when submitting resources.

==== Using Git

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 style commonly seen in distributed
version control systems, adopted by projects such as Linux and Git.
For an explanation of this style, see
https://chris.beams.io/posts/git-commit/[How to Write a Git Commit
Message].

The commit `2017-02-20T01:52:35Z!mikeonthecomputer@gmail.com` is a
good example of a properly-written commit.

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 (February 2017), 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 generating them.