Documentation Improvements (collected)

README.rst

@@ -1,131 +1,118 @@
-Taisei
-======
+Taisei Project
+==============
+
+.. image:: misc/icons/taisei.ico
+   :width: 150
+   :alt: Taisei Project icon
 
 .. contents::
 
 Introduction
 ------------
 
-Taisei is an open clone of the Tōhō Project series. Tōhō is a one-man project of
-shoot-em-up games set in an isolated world full of Japanese folklore.
-
-Installation
-------------
-
-Dependencies
-^^^^^^^^^^^^
+About Taisei Project
+^^^^^^^^^^^^^^^^^^^^
 
--  OpenGL >= 3.3 or OpenGL ES >= 3.0 or OpenGL ES >= 2.0 (with some extensions)
--  `cglm <https://github.com/recp/cglm>`__ >= 0.7.8
--  SDL2 >= 2.0.10
--  freetype2
--  libpng >= 1.5.0
--  libwebpdecoder >= 0.5 or libwebp >= 0.5
--  libzip >= 1.5.0 (>= 1.7.0 recommended)
--  libzstd >= 1.4.0
--  opusfile
--  zlib
+Taisei Project is an open source fan-game set in the world of
+`Tōhō Project <https://en.wikipedia.org/wiki/Touhou_Project>`__.
+It is a top-down vertical-scrolling curtain fire shooting game (STG), also known
+as a "bullet hell" or "danmaku. It is a fast-paced game focused around pattern
+recognition and mastery through practice.
 
-Optional:
+Taisei Project is highly portable, and is written in C11, using SDL2 with an
+OpenGL renderer. It is officially supported on Windows, Linux, macOS, and
+through WebGL-enabled browsers such as Firefox and Chromium-based browsers
+(Chrome, Edge, etc). It can also be compiled for a number of other operating
+systems.
 
--  OpenSSL (for a better SHA-256 implementation; used in shader cache)
--  SPIRV-Cross >= 2019-03-22 (for OpenGL ES backends)
--  libshaderc (for OpenGL ES backends)
--  GameMode headers (Linux only; for automatic `GameMode
-   <https://github.com/FeralInteractive/gamemode>`__ integration)
+For gameplay screenshots, see
+`our website <https://taisei-project.org/media>`__.
 
-Build-only dependencies
-^^^^^^^^^^^^^^^^^^^^^^^
+For gameplay instructions, read `this <doc/GAME.rst>`__.
 
--  Python >= 3.6
--  meson >= 0.53.0
--  [python-zstandard](https://github.com/indygreg/python-zstandard)
+For the story, read `this <doc/STORY.txt>`__. (Spoiler warning!)
 
-Optional:
+About Tōhō Project
+^^^^^^^^^^^^^^^^^^
 
--  docutils (for documentation)
+Tōhō Project is an indie game series (also known as "doujin" in Japanese)
+known for its ensemble cast of characters and memorable soundtracks.
+It is produced by and large by a single artist known as ZUN, and has a
+`permissive license <https://en.touhouwiki.net/wiki/Touhou_Wiki:Copyrights#Copyright_status.2FTerms_of_Use_of_the_Touhou_Project>`__
+which allows for indie derivative works such as Taisei Project to legally exist.
 
-Obtaining the source code
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Taisei is *not* a "clone" of Tōhō, and tells an original story with its own
+music, art, gameplay mechanics, and codebase. While some familiarity with Tōhō
+is helpful, the gameplay can be enjoyed on its own without prior knowledge of
+the series.
 
-Stable releases
-"""""""""""""""
+For more information on dōjin culture,
+`click here <https://en.wikipedia.org/wiki/D%C5%8Djin>`__.
 
-You can find the source tarballs at the
-`Releases <https://github.com/taisei-project/taisei/releases>`__ section on
-Github. **Do not** grab Github's auto-generated source archives, those do not
-contain the required submodules. This only applies for versions v1.3 and above.
-
-Latest code from git
-""""""""""""""""""""
-
-If you cloned Taisei from git, make sure the submodules are initialized:
+Installation
+------------
 
-::
+You can find precompiled binaries of the complete game on the
+`Releases <https://github.com/taisei-project/taisei/releases>`__ page on
+GitHub, available for Windows (x86/x64), Linux, and macOS.
 
-    git submodule init
-    git submodule update
+An experimental build for Nintendo Switch (homebrew) also exists (use at your
+own risk).
 
-This step needs to be done just once, and can be skipped if you specified the
-``--recursive`` or ``--recurse-submodules`` option when cloning.
+You can also play our experimental WebGL build through your web browser
+`here <https://play.taisei-project.org/>`__. (Chromium-based browsers and
+Firefox supported.)
 
-**Important:** You should also run ``git submodule update`` whenever you pull in
-new code, checkout another branch, etc. The ``pull`` and ``checkout`` helper
-scripts can do that for you automatically.
+Source Code & Development
+-------------------------
 
-Compiling from source
+Obtaining Source Code
 ^^^^^^^^^^^^^^^^^^^^^
 
-To build and install Taisei on \*nix, just follow these steps:
+Source
+______
 
-::
+We recommend fetching the source code using ``git``:
 
-    cd /path/to/taisei/source
-    mkdir build
-    cd build
-    meson --prefix=$yourprefix ..
-    ninja
-    ninja install
+.. code:: sh
 
-This will install game data to ``$prefix/share/taisei/`` and build this
-path *statically* into the executable. This might be a package
-maintainer’s choice. Alternatively you may want to add
-``-Dinstall_relative=true`` to get a relative structure like
+    git clone --recurse-submodules https://github.com/taisei-project/taisei
 
-::
+You should also run ``git submodule update`` whenever you pull in
+new code, checkout another branch, or perform any ``git`` actions. The ``./pull``
+and ``./checkout`` helper scripts can do that for you automatically.
 
-    $prefix/taisei
-    $prefix/data/
+Archive
+_______
 
-``install_relative`` is always set when building for Windows.
+⚠️ **NOTE**: Due to the way GitHub packages source code, the ``Download ZIP``
+link on the main repo *does not work*.
 
-The OpenGL ES 3.0 backend is not built by default. To enable it, do:
+This is due to the fact that GitHub does not package submodules alongside source
+code when it automatically generates ``.zip`` files. We've instead created those
+archives manually, and you **MUST** download the archive from
+`Releases <https://github.com/taisei-project/taisei/releases>`__ page.
 
-::
-
-    meson configure -Dr_gles30=true -Dshader_transpiler=true
-
-See `here <doc/ENVIRON.rst>`__ for information on how to activate it.
-Alternatively, do this to make GLES 3.0 the default backend:
+Compiling Source Code
+^^^^^^^^^^^^^^^^^^^^^
 
-::
+Currently, we recommend building Taisei on a POSIX-like system (Linux, macOS,
+etc).
 
-    meson configure -Dr_default=gles30
+While Taisei is highly configurable, the easiest way to compile the code for
+your host machine is:
 
-The OpenGL ES 2.0 backend can be enabled similarly, using ``gles20`` instead of
-``gles30``. However, it requires a few extensions to function correctly, most
-notably:
+.. code:: sh
 
-- ``OES_depth_texture`` or ``GL_ANGLE_depth_texture``
-- ``OES_standard_derivatives``
-- ``OES_vertex_array_object``
-- ``EXT_frag_depth``
-- ``EXT_instanced_arrays`` or ``ANGLE_instanced_arrays`` or
-  ``NV_instanced_arrays``
+    meson setup build/
+    meson compile -C build/
+    meson install -C build/
 
+See the `Building <./doc/BUILD.rst>`__ doc for more information on how to build
+Taisei, and its list of dependencies.
 
-Where are my replays, screenshots and settings?
------------------------------------------------
+Replays, Screenshots, and Settings Locations
+--------------------------------------------
 
 Taisei stores all data in a platform-specific directory:
 
@@ -137,80 +124,19 @@ Taisei stores all data in a platform-specific directory:
 This is referred to as the **Storage Directory**. You can set the environment
 variable ``TAISEI_STORAGE_PATH`` to override this behaviour.
 
-Game controller support
------------------------
-
-Taisei uses SDL2's unified GameController API. This allows us to correctly
-support any device that SDL recognizes by default, while treating all of them
-the same way. This also means that if your device is not supported by SDL, you
-will not be able to use it unless you provide a custom mapping. If your
-controller is listed in the settings menu, then you're fine. If not, read on.
-
-An example mapping string looks like this:
-
-::
-
-    03000000ba2200002010000001010000,Jess Technology USB Game Controller,a:b2,b:b1,back:b8,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:,leftshoulder:b4,lefttrigger:b6,leftx:a0,lefty:a1,rightshoulder:b5,righttrigger:b7,rightx:a3,righty:a2,start:b9,x:b3,y:b0,
-
-There are a few ways to generate a custom mapping:
-
--  You can use the
-   `controllermap <https://aur.archlinux.org/packages/controllermap>`__ utility,
-   which `comes with SDL source code
-   <https://hg.libsdl.org/SDL/file/68a767ae3a88/test/controllermap.c>`__.
--  If you use Steam, you can configure your controller there. Then you can add
-   Taisei as a non-Steam game; run it from Steam and everything should *just
-   work™*. In case you don't want to do that, find ``config/config.vdf`` in your
-   Steam installation directory, and look for the ``SDL_GamepadBind`` variable.
-   It contains a list of SDL mappings separated by line breaks.
--  You can also try the `SDL2 Gamepad Tool by General Arcade
-   <http://www.generalarcade.com/gamepadtool/>`__. This program is free to use,
-   but not open source.
--  Finally, you can try to write a mapping by hand. You will probably have to
-   refer to the SDL documentation. See `gamecontrollerdb.txt
-   <misc/gamecontrollerdb/gamecontrollerdb.txt>`__ for some more examples.
-
-Once you have your mapping, there are two ways to make Taisei use it:
-
--  Create a file named ``gamecontrollerdb.txt`` where your config, replays and
-   screenshots are, and put each mapping on a new line.
--  Put your mappings in the environment variable ``SDL_GAMECONTROLLERCONFIG``,
-   also separated by line breaks. Other games that use the GameController API
-   will also pick them up.
-
-When you're done, please consider contributing your mappings to
-`SDL <https://libsdl.org/>`__,
-`SDL_GameControllerDB <https://github.com/gabomdq/SDL_GameControllerDB>`__,
-and `us <https://github.com/taisei-project/SDL_GameControllerDB>`__, so
-that other people can benefit from your work.
-
-Also note that we currently only handle input from analog axes and digital
-buttons. Hats, analog buttons, and anything more exotic will not work, unless
-remapped.
-
 Troubleshooting
 ---------------
 
-Sound problems (Linux)
-^^^^^^^^^^^^^^^^^^^^^^
+Documentation for many topics, including development and game controller
+support, can be found in our `docs section <./doc/README.rst>`__.
 
-If your sound becomes glitchy, and you encounter lot of console messages like:
-
-::
-
-    ALSA lib pcm.c:7234:(snd_pcm_recover) underrun occurred
-
-it seems like you possibly have broken ALSA configuration. This may be fixed by
-playing with parameter values of ``pcm.dmixer.slave`` option group in
-``/etc/asound.conf`` or wherever you have your ALSA configuration.
-Commenting ``period_time``, ``period_size``, ``buffer_size``, ``rate`` may give
-you the first approach to what to do.
+Feel free to
+`open up an issue <https://github.com/taisei-project/taisei/issues>`__ if you
+run into any issues with compiling or running Taisei.
 
 Contact
 -------
 
 -  https://taisei-project.org/
 
--  `#taisei-project on Freenode <irc://irc.freenode.org/taisei-project>`__
-
 -  `Our server on Discord <https://discord.gg/JEHCMzW>`__