Add first version of philosophy document.

1 files changed, 157 insertions, 0 deletions

diff --git a/PHILOSOPHY b/PHILOSOPHY
new file mode 100644
index 00000000..d1d89f4a
--- /dev/null
+++ b/PHILOSOPHY
@@ -0,0 +1,157 @@
+
+Chocolate Doom has been designed around a careful and deliberate
+philosophy that attempts to recreate the original ("Vanilla") DOS
+executables for Doom, Heretic, Hexen and Strife. This document
+describes some of that philosophy and the reasoning behind it.
+
+This document is descriptive, not proscriptive.
+
+== Vanilla behavior ==
+
+Ideally Chocolate Doom aims to recreate the behavior of the Vanilla
+binaries, but different aspects of Vanilla behavior are held to
+varying degrees of importance. It can be imagined as different "tiers"
+of compatibility:
+
+ * The game and gameplay itself is of central importance. Here, the
+   Vanilla behavior ought to be maintained as accurately as possible.
+   This includes the look, feel and sound, and things like demo
+   compatibility.
+ * The surrounding aspects of the game that aren't part of the central
+   gameplay experience can be extended as long as there's a good
+   reason and Vanilla behavior is respected.
+ * The setup tool is not required to reproduce the behavior of the
+   Vanilla setup tool, even though it reproduces its look and feel.
+
+"Vanilla" is defined as:
+
+ * DOS Doom 1.9 (although there are actually multiple "1.9"s).
+ * DOS Heretic 1.3.
+ * DOS Hexen 1.1.
+ * DOS Strife 1.31.
+
+"Vanilla" does not include ports (either official or unofficial), such
+as console ports, Doom 95 or Doom 3: BFG Edition.
+
+== DOS tools ==
+
+Chocolate Doom includes some features that aren't part of Vanilla Doom
+but exist for compatibility with DOS tools that interact with it.
+These are considered part of the Vanilla experience and ought to be
+treated as such. Some examples are:
+
+ * The novert setting, which reproduces the functionality of
+   novert.exe.
+ * The -deh parameter, which loads Dehacked patches like dehacked.exe
+   does under DOS. Chocolate Doom imposes the same limitations that
+   Vanilla Dehacked does.
+
+== Exceptions ==
+
+Chocolate Doom differs from Vanilla Doom in a number of ways. In most
+cases these are subtle, minor differences. Nonetheless they deserve
+some explanation and justification. Here are some examples of
+situations where changes are considered acceptable:
+
+ 1. Vanilla behavior can be broken that is harmful, eg. can damage the
+    player's computer, or is just outright misleading. For example:
+
+    - Vanilla uses unbounded sprintf and strcpy (security issue).
+    - Vanilla has crashes that force the user to reboot the machine.
+    - Vanilla has an out of memory message that recommends tweaking
+      CONFIG.SYS. As Chocolate Doom doesn't run under DOS, reproducing
+      this message would not be helpful.
+
+ 2. Subtly extending behavior is okay where it's not clear what the
+    Vanilla behavior is anyway. For example:
+
+    - Opening the menu releases mouse grab in Chocolate Doom.
+    - Chocolate Hexen's graphical startup screen runs in a window.
+
+ 3. Supporting obsolete technology is not a goal: it's considered
+    acceptable that Chocolate Doom does not support every type of
+    hardware from 1993. However, Chocolate Doom should aim to recreate
+    the functionality in a modern way. Examples of technology that
+    isn't supported are:
+
+    - No support for IPX networks, but TCP/IP is instead.
+    - No support for dial-up/serial connections; modern operating
+      systems have features that do that for you.
+    - No MS-DOS version.
+
+ 4. Changes are permitted that allow the player to be able play the
+    game. For example:
+
+    - There are new key bindings for actions that can't be rebound with
+      Vanilla Doom, because it's useful for portability to machines
+      that don't have a full keyboard.
+    - There are additional mouse or joystick key bindings that let you
+      perform actions with them that can only be done with the keyboard
+      in Vanilla Doom.
+    - Chocolate Doom includes some hacks to support the Doom 3: BFG
+      Edition IWAD files. The assumption is that being able to at least
+      play is better than nothing, even if it's not Vanilla behavior.
+
+ 5. Adding extra options to Vanilla functionality is permitted as long
+    as the defaults match Vanilla, it doesn't change gameplay and
+    there's a good reason for it. For example:
+
+    - PNG screenshots are supported because PCX is an obsolete format.
+    - Chocolate Doom has the vanilla_keyboard_mapping option that
+      allows the user to use the native keyboard mapping for their
+      computer, rather than always assuming a US layout.
+
+ 6. Changing configuration file defaults is permitted where there's a
+    very good reason. For example:
+
+    - Vanilla Doom defaults to no sound or music if a configuration
+      file is not found. Chocolate Doom defaults to having sound
+      effects and music turned on by default, because modern computers
+      support these; there's no need to configure hardware IRQ settings
+      to get sound working.
+
+ 7. Things can be changed if they're really just inconsequential. For
+    example:
+
+    - The startup messages in Chocolate Doom are not identical to
+      Vanilla Doom and are not necessarily in the same order.
+    - Vanilla Doom has command line options named -comdev, -shdev and
+      -regdev used by id internally for development; these have been
+      removed.
+
+A good litmus test of when it's acceptable to break from Vanilla
+behavior is to ask the question: "Although this is Vanilla behavior,
+is there anyone who would want this?".
+
+For example, emulating Vanilla bugs like the visplane overflow bug is
+something that is useful for people making Vanilla format maps. On the
+other hand, painstakingly emulating Vanilla Doom by starting with no
+sound or music by default is not helpful to anyone.
+
+== Other philosophical issues ==
+
+Chocolate Doom aims for maximal portability. That includes running on
+different CPUs, different operating systems and different devices (ie.
+not just a desktop machine with a keyboard and mouse).
+
+Chocolate Doom is and will always remain Free Software. It will never
+include code that is not compatible with the GNU GPL.
+
+Chocolate Doom aims to be minimalist and straightforward to configure;
+in particular, the setup tool should have a sane interface. Part of
+the inspiration for Chocolate Doom came from Boom's complicated maze
+of options menus (and a desire to avoid them). Too many preferences
+lead to a bad user interface; see Havoc Pennington's essay on Free
+Software UI:
+
+  http://ometer.com/free-software-ui.html
+
+Chocolate Doom has some options that are quite obscure and only really
+of interest to a small number of people. In these cases, the options
+are hidden away in configuration files and deliberately not exposed in
+the setup tool. The assumption is that if you care enough about those
+obscure features, editing a configuration file by hand should not be a
+huge problem for you.
+
+# vim: tw=70
+