Replace Markdown+Pandoc with RST+Docutils (#110)

This commit is contained in:
Andrei Alexeyev 2018-01-20 05:21:21 +02:00 committed by GitHub
parent 65fffdee94
commit af82877c7d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 621 additions and 399 deletions

View file

@ -1,89 +0,0 @@
# Taisei
## 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:
* SDL2 >= 2.0.5, SDL2\_ttf, SDL2\_mixer
* zlib
* libzip >= 1.0
* libpng >= 1.5.0
* OpenGL >= 2.1
* meson >= 0.39.0 (build system)
* pkg-config (build dependency)
* pandoc (build dependency, optional)
To build and install Taisei just follow these steps.
```
mkdir build
cd build
meson --prefix=$yourprefix ..
ninja
ninja install
```
This will install game data to `$prefix/share/taisei/` and build this path
_statically_ into the executable. This might be a package maintainers choice.
Alternatively you may want to add `-Dinstall_relative=true` to get a relative
structure like
```
$prefix/taisei
$prefix/data/
```
`install_relative` is always set when building for Windows.
## Where are my replays, screenshots and settings?
Taisei stores all data in a platform-specific directory:
* On **Windows**, this will probably be `%APPDATA%\taisei`
* On **macOS**, it's `$HOME/Library/Application Support/taisei`
* On **Linux**, **\*BSD**, and most other **Unix**-like systems, it's `$XDG_DATA_HOME/taisei` or `$HOME/.local/share/taisei`
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.
## Sound problems (Linux)
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.
## Contact
http://taisei-project.org/
\#taisei-project on Freenode

146
README.rst Normal file
View file

@ -0,0 +1,146 @@
Taisei
======
.. 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
^^^^^^^^^^^^
- SDL2 >= 2.0.5, SDL2_ttf, SDL2_mixer
- zlib
- libzip >= 1.0
- libpng >= 1.5.0
- OpenGL >= 2.1
Build-only dependencies
^^^^^^^^^^^^^^^^^^^^^^^
- meson >= 0.39.0 (build system)
- Python >= 3.4
- pkg-config
- docutils (optional, for documentation)
To build and install Taisei just follow these steps.
::
mkdir build
cd build
meson --prefix=$yourprefix ..
ninja
ninja install
This will install game data to ``$prefix/share/taisei/`` and build this
path *statically* into the executable. This might be a package
maintainers choice. Alternatively you may want to add
``-Dinstall_relative=true`` to get a relative structure like
::
$prefix/taisei
$prefix/data/
``install_relative`` is always set when building for Windows.
Where are my replays, screenshots and settings?
-----------------------------------------------
Taisei stores all data in a platform-specific directory:
- On **Windows**, this will probably be ``%APPDATA%\taisei``
- On **macOS**, it's ``$HOME/Library/Application Support/taisei``
- On **Linux**, **\*BSD**, and most other **Unix**-like systems, it's
``$XDG_DATA_HOME/taisei`` or ``$HOME/.local/share/taisei``
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)
^^^^^^^^^^^^^^^^^^^^^^
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.
Contact
-------
http://taisei-project.org/
#taisei-project on Freenode

View file

@ -1,124 +0,0 @@
# Taisei environment variables
## Introduction
Some of Taisei's more advanced configuration options are delegated to [environment variables](https://en.wikipedia.org/wiki/Environment_variable). This document attempts to describe them all.
Generally you don't need to set any of them. They are intended for developers and advanced users only. Therefore, familiarity with the concept is assumed.
In addition to the variables listed here, those processed by our runtime dependencies (such as SDL) also take effect, unless stated otherwise.
## Variables
### Virtual filesystem
* **TAISEI_RES_PATH** *(default: unset)*: if set, overrides the default **resource directory** path. This is where Taisei looks for game data. The default path is platform and build specific:
* On **macOS**, it will be the `Contents/Resources/data` directory inside of the `Taisei.app` bundle.
* On **Linux**, **\*BSD**, and most other **Unix**-like systems (without -DRELATIVE), it will be `$prefix/share/taisei`. This path is static and determined at compile time.
* On **Windows** and other platforms when built with -DRELATIVE, it will be the `data` directory relative to the executable (or to whatever `SDL_GetBasePath` returns on the given platform).
* **TAISEI_STORAGE_PATH** *(default: unset)*: if set, overrides the default **storage directory** path. This is where Taisei saves your configuration, progress, screenshots and replays. Taisei also loads custom data from the `resources` subdirectory in there, if any, in addition to the stock assets. The custom resources shadow the default ones if the names clash. The default path is platform specific, and is equivalent to the return value of `SDL_GetPrefPath("", "taisei")`:
* On **Windows**, it's `%APPDATA%\taisei`.
* On **macOS**, it's `$HOME/Library/Application Support/taisei`.
* On **Linux**, **\*BSD**, and most other **Unix**-like systems, it's `$XDG_DATA_HOME/taisei` or `$HOME/.local/share/taisei`.
### Resources
* **TAISEI_NOASYNC** *(default: `0`)*: if `1`, disables asynchronous loading. Increases loading times, might slightly reduce CPU and memory usage during loads. Generally not recommended unless you encounter a race condition bug, in which case you should report it.
* **TAISEI_NOUNLOAD** *(default: `0`)*: if `1`, loaded resources are never unloaded. Increases memory usage, reduces filesystem reads and loading times over time.
* **TAISEI_NOPRELOAD** *(default: `0`)*: if `1`, disables preloading. All resources are only loaded as they are needed. Reduces loading times and memory usage, but may cause stuttering during gameplay.
* **TAISEI_PRELOAD_REQUIRED** *(default: `0`)*: if `1`, the game will crash with an error message when it attempts to use a resource that hasn't been previously preloaded. Useful for developers to debug missing preloads. Doesn't affect optional resources.
### Video and OpenGL
* **TAISEI_PREFER_SDL_VIDEODRIVERS** *(default: `wayland,mir,cocoa,windows,x11`)*: List of SDL video backends that Taisei will attempt to use, in the specified order, before falling back to SDL's default. Entries may be separated by spaces, commas, colons, and semicolons. This variable is ignored if `SDL_VIDEODRIVER` is set.
* **TAISEI_VIDEO_DRIVER** *(**deprecated**; default: unset)*: Use `SDL_VIDEODRIVER` instead.
* **TAISEI_LIBGL** *(default: unset)*: OpenGL library to load instead of the default. The value has a platform-specific meaning (it's passed to the equivalent of `dlopen`). Takes precedence over `SDL_OPENGL_LIBRARY` if set. Has no effect if Taisei is linked to libgl (which is not recommended, because it's not portable).
* **TAISEI_GL_EXT_OVERRIDES** *(default: unset)*: Space-separated list of OpenGL extensions that are assumed to be supported, even if the driver says they aren't. Prefix an extension with `-` to invert this behaviour. Might be used to work around bugs in some weird/ancient/broken drivers, but your chances are slim. Also note that Taisei assumes many extensions to be available on any sane OpenGL 2.1+ implementation and doesn't test for them, so you can't disable code that uses those this way.
* **TAISEI_FRAMERATE_GRAPHS** *(default: `0` for release builds, `1` for debug builds)*: if `1`, framerate graphs will be drawn on the HUD.
### Timing
* **TAISEI_HIRES_TIMER** *(default: `1`)*: if `1`, tries to use the system's high resolution timer to limit the game's framerate. Disabling this is not recommended; it will likely make Taisei run slower or faster than intended and the reported FPS will be less accurate.
* **TAISEI_FRAMELIMITER_SLEEP** *(default: `0`)*: if over `0`, tries to sleep this many milliseconds after every frame if it was processed quickly enough. This reduces CPU usage by having the game spend less time in a busy loop, but may hurt framerate stability if set too high, especially if the high resolution timer is disabled or not available.
* **TAISEI_FRAMELIMITER_SLEEP_EXACT** *(default: `1`)*: if `1`, the framerate limiter will either try to sleep the exact amount of time set in `TAISEI_FRAMELIMITER_SLEEP`, or none at all. Mitigates the aforementioned framerate stability issues by effectively making `TAISEI_FRAMELIMITER_SLEEP` do nothing if the value is too high for your system.
* **TAISEI_FRAMELIMITER_COMPENSATE** *(default: `1`)*: if `1`, the framerate limiter may let frames finish earlier than normal after sudden frametime spikes. This achieves better timing accuracy, but may hurt fluidity if the framerate is too unstable.
* **TAISEI_FRAMELIMITER_LOGIC_ONLY** *(default: `0`)*: **EXPERIMENTAL**: if `1`, only the logic framerate will be capped; new rendering frames will be processed as quickly as possible, with no delay. This inherently desynchronizes logic and rendering frames, and therefore, some logic frames may be dropped if rendering is too slow. However, unlike with the synchronous mode, the game speed will remain roughly constant in those cases. `TAISEI_FRAMELIMITER_SLEEP`, `TAISEI_FRAMELIMITER_COMPENSATE`, and the `frameskip` setting have no effect in this mode.
### Logging
Taisei's logging system currently has four basic levels and works by dispatching messages to a few output handlers. Each handler has a level filter, which is configured by a separate environment variable. All of those variables work the same way: their value looks like an IRC mode string, and represents a modification of the handler's default settings. If this doesn't make sense, take a look at the *Examples* section.
#### The levels
* **Debug** (*d*) is the most verbose level. It contains random information about internal workings of the game and is disabled for release builds at source level.
* **Info** (*i*) logs some events that are expected to occur during normal operation, for example when a spell is unlocked or a screenshot is taken.
* **Warning** (*w*) alerts of non-critical errors, for example a missing optional resource, corrupted progress data, or failure to save a replay due to insufficient storage space or privileges.
* **Fatal Error** (*e*) is an irrecoverable failure condition. Such an event most likely signifies a programming error or a broken installation. The game will immediately crash after writing a message with this log level. On some platforms, it will also display a graphical message box.
* **All** (*a*): this is not a real log level, but a shortcut directive representing all possible log levels. See *Examples* for usage.
#### The variables
* **TAISEI_LOGLVLS_CONSOLE**: controls what goes to the console, both `stdout` and `stderr`. Defaults to *All* (`+a`). This is a master switch for the two variables below:
* **TAISEI_LOGLVLS_STDOUT**: controls what goes to standard output. Defaults to *Debug and Info* (`+di`).
* **TAISEI_LOGLVLS_STDERR**: controls what goes to standard error. Defaults to *Warning and Fatal Error* (`+we`).
* **TAISEI_LOGLVLS_FILE**: controls what goes into the log file (`{storage directory}/log.txt`). Defaults to *All* (`+a`).
* **TAISEI_LOGLVLS_BACKTRACE**: affects all outputs and controls which log levels produce a call stack trace upon printing a message. Only supported in Debug builds with glibc. Defaults to *Fatal Error* (`+e`).
#### Examples
* In release builds: print *Info* messages to stdout, in addition to *Warning*s and *Fatal Error*s as per default:
```sh
TAISEI_LOGLVLS_STDOUT=+i
```
* In Debug builds: remove *Debug* and *Info* output from the console:
```sh
TAISEI_LOGLVLS_STDOUT=-di
```
OR:
```sh
TAISEI_LOGLVLS_CONSOLE=-di
```
* Don't save anything to the log file:
```sh
TAISEI_LOGLVLS_FILE=-a
```
* Don't print anything to the console:
```sh
TAISEI_LOGLVLS_CONSOLE=-a
```
* Don't save anything to the log file, except for *Warning*s:
```sh
TAISEI_LOGLVLS_FILE=-a+w
```
* Print everything except *Debug* to `stderr`, nothing to `stdout`:
```sh
TAISEI_LOGLVLS_STDOUT=-a
TAISEI_LOGLVLS_STDERR=+a-d
```
* In Debug builds: produce a stack trace for every *Warning* message, in addition to *Fatal Error*s as per default:
```sh
TAISEI_LOGLVLS_BACKTRACE=+w
```

282
doc/ENVIRON.rst Normal file
View file

@ -0,0 +1,282 @@
Taisei Project Environment Variables
======================================
.. contents::
Introduction
------------
Some of Taisei's more advanced configuration options are delegated to
`environment
variables <https://en.wikipedia.org/wiki/Environment_variable>`__. This
document attempts to describe them all.
Generally you don't need to set any of them. They are intended for
developers and advanced users only. Therefore, familiarity with the
concept is assumed.
In addition to the variables listed here, those processed by our runtime
dependencies (such as SDL) also take effect, unless stated otherwise.
Variables
---------
Virtual filesystem
~~~~~~~~~~~~~~~~~~
**TAISEI_RES_PATH**
| Default: unset
If set, overrides the default **resource directory** path. This is
where Taisei looks for game data. The default path is platform and
build specific:
- On **macOS**, it will be the ``Contents/Resources/data`` directory
inside of the ``Taisei.app`` bundle.
- On **Linux**, **\*BSD**, and most other **Unix**-like systems
(without -DRELATIVE), it will be ``$prefix/share/taisei``. This
path is static and determined at compile time.
- On **Windows** and other platforms when built with -DRELATIVE, it
will be the ``data`` directory relative to the executable (or to
whatever ``SDL_GetBasePath`` returns on the given platform).
**TAISEI_STORAGE_PATH**
| Default: unset
If set, overrides the default **storage directory** path. This is
where Taisei saves your configuration, progress, screenshots and
replays. Taisei also loads custom data from the ``resources``
subdirectory in there, if any, in addition to the stock assets. The
custom resources shadow the default ones if the names clash. The
default path is platform specific, and is equivalent to the return
value of ``SDL_GetPrefPath("", "taisei")``:
- On **Windows**, it's ``%APPDATA%\taisei``.
- On **macOS**, it's ``$HOME/Library/Application Support/taisei``.
- On **Linux**, **\*BSD**, and most other **Unix**-like systems,
it's ``$XDG_DATA_HOME/taisei`` or ``$HOME/.local/share/taisei``.
Resources
~~~~~~~~~
**TAISEI_NOASYNC**
| Default: ``0``
If ``1``, disables asynchronous loading. Increases loading times, might
slightly reduce CPU and memory usage during loads. Generally not
recommended unless you encounter a race condition bug, in which case
you should report it.
**TAISEI_NOUNLOAD**
| Default: ``0``
If ``1``, loaded resources are never unloaded. Increases memory usage,
reduces filesystem reads and loading times over time.
**TAISEI_NOPRELOAD**
| Default: ``0``
If ``1``, disables preloading. All resources are only loaded as they
are needed. Reduces loading times and memory usage, but may cause
stuttering during gameplay.
**TAISEI_PRELOAD_REQUIRED**
| Default: ``0``
If ``1``, the game will crash with an error message when it attempts to
use a resource that hasn't been previously preloaded. Useful for
developers to debug missing preloads. Doesn't affect optional resources.
Video and OpenGL
~~~~~~~~~~~~~~~~
**TAISEI_PREFER_SDL_VIDEODRIVERS**
| Default: ``wayland,mir,cocoa,windows,x11``
List of SDL video backends that Taisei will attempt to use, in the
specified order, before falling back to SDL's default. Entries may be
separated by spaces, commas, colons, and semicolons. This variable is
ignored if ``SDL_VIDEODRIVER`` is set.
**TAISEI_VIDEO_DRIVER**
| Default: unset
| **Deprecated**
Use ``SDL_VIDEODRIVER`` instead.
**TAISEI_LIBGL**
| Default: unset
OpenGL library to load instead of the default. The value has a
platform-specific meaning (it's passed to the equivalent of ``dlopen``).
Takes precedence over ``SDL_OPENGL_LIBRARY`` if set. Has no effect if
Taisei is linked to libgl (which is not recommended, because it's not
portable).
**TAISEI_GL_EXT_OVERRIDES**
| Default: unset
Space-separated list of OpenGL extensions that are assumed to be
supported, even if the driver says they aren't. Prefix an extension with
``-`` to invert this behaviour. Might be used to work around bugs in
some weird/ancient/broken drivers, but your chances are slim. Also note
that Taisei assumes many extensions to be available on any sane OpenGL
2.1+ implementation and doesn't test for them, so you can't disable code
that uses those this way.
**TAISEI_FRAMERATE_GRAPHS**
| Default: ``0`` for release builds, ``1`` for debug builds
if ``1``, framerate graphs will be drawn on the HUD.
Timing
~~~~~~
**TAISEI_HIRES_TIMER**
| Default: ``1``
If ``1``, tries to use the system's high resolution timer to limit the
game's framerate. Disabling this is not recommended; it will likely make
Taisei run slower or faster than intended and the reported FPS will be
less accurate.
**TAISEI_FRAMELIMITER_SLEEP**
| Default: ``0``
If over ``0``, tries to sleep this many milliseconds after every frame
if it was processed quickly enough. This reduces CPU usage by having the
game spend less time in a busy loop, but may hurt framerate stability if
set too high, especially if the high resolution timer is disabled or
not available.
**TAISEI_FRAMELIMITER_SLEEP_EXACT**
| Default: ``1``
If ``1``, the framerate limiter will either try to sleep the exact
amount of time set in ``TAISEI_FRAMELIMITER_SLEEP``, or none at all.
Mitigates the aforementioned framerate stability issues by effectively
making ``TAISEI_FRAMELIMITER_SLEEP`` do nothing if the value is too high
for your system.
**TAISEI_FRAMELIMITER_COMPENSATE**
| Default: ``1``
If ``1``, the framerate limiter may let frames finish earlier than
normal after sudden frametime spikes. This achieves better timing
accuracy, but may hurt fluidity if the framerate is too unstable.
**TAISEI_FRAMELIMITER_LOGIC_ONLY**
| Default: ``0``
| **Experimental**
If ``1``, only the logic framerate will be capped; new rendering frames
will be processed as quickly as possible, with no delay. This inherently
desynchronizes logic and rendering frames, and therefore, some logic
frames may be dropped if rendering is too slow. However, unlike with the
synchronous mode, the game speed will remain roughly constant in those
cases. ``TAISEI_FRAMELIMITER_SLEEP``, ``TAISEI_FRAMELIMITER_COMPENSATE``,
and the ``frameskip`` setting have no effect in this mode.
Logging
~~~~~~~
Taisei's logging system currently has four basic levels and works by
dispatching messages to a few output handlers. Each handler has a level
filter, which is configured by a separate environment variable. All of
those variables work the same way: their value looks like an IRC mode
string, and represents a modification of the handler's default settings.
If this doesn't make sense, take a look at the *Examples* section.
The levels
^^^^^^^^^^
- **Debug** (*d*) is the most verbose level. It contains random
information about internal workings of the game and is disabled for
release builds at source level.
- **Info** (*i*) logs some events that are expected to occur during
normal operation, for example when a spell is unlocked or a
screenshot is taken.
- **Warning** (*w*) alerts of non-critical errors, for example a
missing optional resource, corrupted progress data, or failure to
save a replay due to insufficient storage space or privileges.
- **Fatal Error** (*e*) is an irrecoverable failure condition. Such an
event most likely signifies a programming error or a broken
installation. The game will immediately crash after writing a message
with this log level. On some platforms, it will also display a
graphical message box.
- **All** (*a*): this is not a real log level, but a shortcut directive
representing all possible log levels. See *Examples* for usage.
The variables
^^^^^^^^^^^^^
- **TAISEI_LOGLVLS_CONSOLE**: controls what goes to the console, both
``stdout`` and ``stderr``. Defaults to *All* (``+a``). This is a
master switch for the two variables below:
- **TAISEI_LOGLVLS_STDOUT**: controls what goes to standard output.
Defaults to *Debug and Info* (``+di``).
- **TAISEI_LOGLVLS_STDERR**: controls what goes to standard error.
Defaults to *Warning and Fatal Error* (``+we``).
- **TAISEI_LOGLVLS_FILE**: controls what goes into the log file
(``{storage directory}/log.txt``). Defaults to *All* (``+a``).
- **TAISEI_LOGLVLS_BACKTRACE**: affects all outputs and controls which
log levels produce a call stack trace upon printing a message. Only
supported in Debug builds with glibc. Defaults to *Fatal Error*
(``+e``).
Examples
^^^^^^^^
- In release builds: print *Info* messages to stdout, in addition to
*Warning*\ s and *Fatal Error*\ s as per default:
.. code:: sh
TAISEI_LOGLVLS_STDOUT=+i
- In Debug builds: remove *Debug* and *Info* output from the console:
.. code:: sh
TAISEI_LOGLVLS_STDOUT=-di
OR:
.. code:: sh
TAISEI_LOGLVLS_CONSOLE=-di
- Don't save anything to the log file:
.. code:: sh
TAISEI_LOGLVLS_FILE=-a
- Don't print anything to the console:
.. code:: sh
TAISEI_LOGLVLS_CONSOLE=-a
- Don't save anything to the log file, except for *Warning*\ s:
.. code:: sh
TAISEI_LOGLVLS_FILE=-a+w
- Print everything except *Debug* to ``stderr``, nothing to ``stdout``:
.. code:: sh
TAISEI_LOGLVLS_STDOUT=-a
TAISEI_LOGLVLS_STDERR=+a-d
- In Debug builds: produce a stack trace for every *Warning* message,
in addition to *Fatal Error*\ s as per default:
.. code:: sh
TAISEI_LOGLVLS_BACKTRACE=+w

View file

@ -1,133 +0,0 @@
# Taisei Project Game Manual
Taisei is a shoot-em-up game. Lots of bullets cover the screen and if you are hit by one, you die. To make things easier, your hitbox is very small-- much smaller than your character.
If you get hit you lose a life (displayed on the right hand side in the HUD); if you are out of lives, its Game Over, but you get a few Continues to keep playing (without scores or replays).
## Controls
| Name | Default Key |
| ----- | -------------------------- |
| Shoot | `Z` |
| Bomb | `X` |
| Focus | `Left Shift` |
| Move | `Up`,`Down`,`Left`,`Right` |
Using the Gamepad is also supported. See options to set up controls.
Users of non-qwerty keyboard layouts: Dont worry, Taiseis controls are not based on layout but key location.
## Shotmodes
The different playable characters have different shots. You start out weak and
have to raise your power meter to get stronger.
Try a few modes to find the one that fits you best.
## Focus
While pressing `Shift`, your movement is slower and the weapon will be more
focused, hence the name *Focus* to describe this mode. It is useful for
accurate dodging, but you shouldnt stay in this mode all the time.
The white circle appearing in this mode is a representation of your hitbox. As
you can see it is really small.
## HUD
The numbers in the HUD are
* **Score**
Your current score. Raise this by shooting enemies, grazing, and collecting items.
As you accumulate score, the game will reward you with life and bomb fragments. Be sure to catch those!
* **Player**
How many lives you have. Only full stars count.
* **Bombs**
How many bombs you have.
* **Power**
How strong your current weapon is. Maxes out at 4.
* **Graze**
If you are fearless and kiss bullets by going really close to them, this will increase and raise your score.
## Items
Killed enemies drop various amounts of items. They may look like bullets at first, but they are safe to touch.
These are:
* **Blue**
Increases your score.
* **Red**
Gives you more power.
* **Green Star**
Bomb. Appears either filled (full bomb) or as an empty outline (bomb
fragment). 5 fragments make up one bomb.
* **Pink Star**
Life or Life fragment.
If you fly near to the top of the screen, all the visible items will be picked up (shown as flying towards you).
## Bosses
Taisei has 6 levels (called *stages*). Each stage has a boss and a midboss in some form. They are much stronger than normal enemies and have different attacks with time limits. There are different types of Attacks:
* **Normal**
A signature move every boss has. They are a break between the other, more
fierce attacks, but some say there are Normals in the game that are way
too hard.
* **Spell Card**
This is where the Bosses concentrate their powers (resulting in a background
change) and hit you with really hard and unusual patterns.
They give a lot of extra points when you *capture* them. That means shooting
down the HP within the time limit without getting hit or using bombs.
You can revisit spellcards you have encountered in the *Spell Practice* mode
to get better at the ones you frequently die on.
* **Extra Spell**
*Capture* every Spell Card of a boss in succession and you activate their *Extra Spell*.
These are super hard, unique spells that will take all your skills and
creativity to dodge. Special safety magic has locked your Bomb and Life meters so
they cant hurt you, but you cant use your bombs either.
* **Survival Spell**
Rarely, a very strong boss can invoke a Spell Card that makes them completely
invincible-- turning their health bar blue.
You are on your own here. Try to survive somehow until the timer runs out.
## Bombs
Your characters are, of course, no less apt at magic than the bosses, so they
have Spell Cards of their own. These are called *bombs*.
You can use them to clear out bullets and enemies from the screen. However you
only get a limited amount of them, so they are best used when you are in a pinch. When
used against a boss' Spell Card, it voids your capturing bonus.
Rumor has it that if you get hit by a bullet and hit the bomb key fast enough,
you can avoid death. This is called *Death Bombing* and people who master it--
so the lore goes-- will find their bomb meter becoming a second life meter.
## Difficulty
~~If you found this guide helpful, you probably should start playing Easy mode.~~
Taisei is a very hard game, especially for newcomers to the genre. In many
modern games, *Easy* is a placeholder and *Normal* is the easy mode so people
playing it dont have to feel bad. So you might feel inclined to start at
Normal like in your other games.
This approach doesnt work for Taisei though. Easy is balanced around maybe
being not impossible for newcomers, so itll require some training. On the
positive side it still contains enough bullets to show you the beauty of all
the patterns. ;)
There is no shame in playing Easy. Some say that even the dev who initially
founded the project and wrote this section cant beat Easy…
## More info
Knowing this much should help to get you started!
If you want more tricks and hints on how to *“git gud”*, check out resources on how to play *Touhou*, the game Taisei is based on.
Enjoy playing, and if you want to contact us, visit us on Freenode IRC #taisei-project or on [Discord](https://discord.gg/JEHCMzW).

171
doc/GAME.rst Normal file
View file

@ -0,0 +1,171 @@
.. _taisei-project--game-manual:
.. role:: strike
:class: strike
Taisei Project Game Manual
============================
.. contents::
Introduction
------------
Taisei is a shoot-em-up game. Lots of bullets cover the screen and if
you are hit by one, you die. To make things easier, your hitbox is very
small-- much smaller than your character.
If you get hit you lose a life (displayed on the right hand side in the
HUD); if you are out of lives, its Game Over, but you get a few
Continues to keep playing (without scores or replays).
Controls
--------
+-------+------------------------------------------+
| Name | Default Key |
+=======+==========================================+
| Shoot | ``Z`` |
+-------+------------------------------------------+
| Bomb | ``X`` |
+-------+------------------------------------------+
| Focus | ``Left Shift`` |
+-------+------------------------------------------+
| Move | ``Up``,\ ``Down``,\ ``Left``,\ ``Right`` |
+-------+------------------------------------------+
Using the Gamepad is also supported. See options to set up controls.
Users of non-qwerty keyboard layouts: Dont worry, Taiseis controls are
not based on layout but key location.
Shotmodes
---------
The different playable characters have different shots. You start out
weak and have to raise your power meter to get stronger.
Try a few modes to find the one that fits you best.
Focus
-----
While pressing ``Shift``, your movement is slower and the weapon will be
more focused, hence the name *Focus* to describe this mode. It is useful
for accurate dodging, but you shouldnt stay in this mode all the time.
The white circle appearing in this mode is a representation of your
hitbox. As you can see it is really small.
HUD
---
The numbers in the HUD are
- **Score** Your current score. Raise this by shooting enemies,
grazing, and collecting items. As you accumulate score, the game will
reward you with life and bomb fragments. Be sure to catch those!
- **Player** How many lives you have. Only full stars count.
- **Bombs** How many bombs you have.
- **Power** How strong your current weapon is. Maxes out at 4.
- **Graze** If you are fearless and kiss bullets by going really close
to them, this will increase and raise your score.
Items
-----
Killed enemies drop various amounts of items. They may look like bullets
at first, but they are safe to touch.
These are:
- **Blue** Increases your score.
- **Red** Gives you more power.
- **Green Star** Bomb. Appears either filled (full bomb) or as an empty
outline (bomb fragment). 5 fragments make up one bomb.
- **Pink Star** Life or Life fragment.
If you fly near to the top of the screen, all the visible items will be
picked up (shown as flying towards you).
Bosses
------
Taisei has 6 levels (called *stages*). Each stage has a boss and a
midboss in some form. They are much stronger than normal enemies and
have different attacks with time limits. There are different types of
Attacks:
- **Normal**: A signature move every boss has. They are a break between
the other, more fierce attacks, but some say there are Normals in the
game that are way too hard.
- **Spell Card**: This is where the Bosses concentrate their powers
(resulting in a background change) and hit you with really hard and
unusual patterns. They give a lot of extra points when you *capture*
them. That means shooting down the HP within the time limit without
getting hit or using bombs.
You can revisit spellcards you have encountered in the *Spell
Practice* mode to get better at the ones you frequently die on.
- **Extra Spell**: *Capture* every Spell Card of a boss in succession
and you activate their *Extra Spell*.
These are super hard, unique spells that will take all your skills
and creativity to dodge. Special safety magic has locked your Bomb
and Life meters so they cant hurt you, but you cant use your bombs
either.
- **Survival Spell**: Rarely, a very strong boss can invoke a Spell Card
that makes them completely invincible-- turning their health bar
blue.
You are on your own here. Try to survive somehow until the timer runs
out.
Bombs
-----
Your characters are, of course, no less apt at magic than the bosses, so
they have Spell Cards of their own. These are called *bombs*.
You can use them to clear out bullets and enemies from the screen.
However you only get a limited amount of them, so they are best used
when you are in a pinch. When used against a boss' Spell Card, it voids
your capturing bonus.
Rumor has it that if you get hit by a bullet and hit the bomb key fast
enough, you can avoid death. This is called *Death Bombing* and people
who master it-- so the lore goes-- will find their bomb meter becoming a
second life meter.
Difficulty
----------
:strike:`If you found this guide helpful, you probably should start
playing Easy mode.`
Taisei is a very hard game, especially for newcomers to the genre. In
many modern games, *Easy* is a placeholder and *Normal* is the easy mode
so people playing it dont have to feel bad. So you might feel inclined
to start at Normal like in your other games.
This approach doesnt work for Taisei though. Easy is balanced around
maybe being not impossible for newcomers, so itll require some
training. On the positive side it still contains enough bullets to show
you the beauty of all the patterns. ;)
There is no shame in playing Easy. Some say that even the dev who
initially founded the project and wrote this section cant beat Easy…
More info
---------
Knowing this much should help to get you started!
If you want more tricks and hints on how to *“git gud”*, check out
resources on how to play *Touhou*, the game Taisei is based on.
Enjoy playing, and if you want to contact us, visit us on Freenode IRC
#taisei-project or on `Discord <https://discord.gg/JEHCMzW>`__.

View file

@ -1,57 +1,27 @@
if get_option('docs')
pandoc = find_program('pandoc', required : false)
rst2html5 = find_program('rst2html5', 'rst2html5.py', 'rst2html5-docutils', required : false)
if not pandoc.found()
error('pandoc is required to build documentation. Please install it, or disable the `docs` option if you don\'t want it.')
if not rst2html5.found()
error('rst2html5 from docutils is required to build documentation. Please install it, or disable the `docs` option if you don\'t want it.')
endif
r = run_command(pandoc, '--list-input-formats')
if r.returncode() != 0
error('Couldn\'t retrieve list of input formats supported by pandoc (error code @0@)\n\n@1@'.format(
r.returncode(),
r.stderr()
))
endif
formats = r.stdout().split()
input_format = 'gfm'
input_format_fallback = 'markdown_github'
if not formats.contains(input_format)
message('pandoc doesn\'t support the \'@0@\' format, falling back to @1@'.format(
input_format,
input_format_fallback
))
if not formats.contains(input_format_fallback)
error('pandoc supports neither \'@0@\' nor \'@1@\''.format(
input_format,
input_format_fallback
))
endif
input_format = input_format_fallback
endif
md_to_html = generator(pandoc,
arguments: [
'--from', input_format,
'--to', 'html5',
'--standalone',
'--self-contained',
'--table-of-contents',
'@EXTRA_ARGS@',
rst_to_html = generator(rst2html5,
arguments : [
'--no-datestamp',
'--no-source-link',
'--smart-quotes=yes',
'--no-compact-lists',
'--stylesheet-path=minimal.css,plain.css,@0@/doc/taisei.css'.format(meson.source_root()),
'@INPUT@',
'--output', '@OUTPUT@',
'@OUTPUT@',
],
output: '@BASENAME@.html',
output : '@BASENAME@.html',
)
md_docs = [
['ENVIRON.md', 'Environment Variables'],
['GAME.md', 'Game Manual'],
rst_docs = [
'ENVIRON.rst',
'GAME.rst',
]
txt_docs = [
@ -71,19 +41,15 @@ if get_option('docs')
)
endforeach
foreach pair : md_docs
f = pair[0]
title = pair[1]
foreach f : rst_docs
name = f.split('.')[0] + '.html'
custom_target(name,
command : [eolconv, eol, '@INPUT@', '@OUTPUT@'],
input : md_to_html.process(f, extra_args : [
'--metadata=title=@0@ - Taisei Project'.format(title)
]),
input : rst_to_html.process(f),
output : name,
install : true,
install_dir : doc_path
install_dir : doc_path,
depend_files : files('taisei.css')
)
endforeach
endif

3
doc/taisei.css Normal file
View file

@ -0,0 +1,3 @@
.strike {
text-decoration: line-through;
}