1Taisei
2======
3
4.. contents::
5
6Introduction
7------------
8
9Taisei is an open clone of the Tōhō Project series. Tōhō is a one-man project of
10shoot-em-up games set in an isolated world full of Japanese folklore.
11
12Installation
13------------
14
15Dependencies
16^^^^^^^^^^^^
17
18- OpenGL >= 3.3 or OpenGL ES >= 3.0 or OpenGL ES >= 2.0 (with some extensions)
19- `cglm <https://github.com/recp/cglm>`__ >= 0.7.8
20- SDL2 >= 2.0.6
21- SDL2_mixer >= 2.0.4
22- freetype2
23- libpng >= 1.5.0
24- libwebpdecoder >= 0.5 or libwebp >= 0.5
25- libzip >= 1.2
26- opusfile
27- zlib
28
29Optional:
30
31- OpenSSL (for a better SHA-256 implementation; used in shader cache)
32- SPIRV-Cross >= 2019-03-22 (for OpenGL ES backends)
33- libshaderc (for OpenGL ES backends)
34- GameMode headers (Linux only; for automatic `GameMode
35 <https://github.com/FeralInteractive/gamemode>`__ integration)
36
37Build-only dependencies
38^^^^^^^^^^^^^^^^^^^^^^^
39
40- Python >= 3.5
41- meson >= 0.48.0 (build system; >=0.49.0 recommended)
42
43Optional:
44
45- docutils (for documentation)
46
47Obtaining the source code
48^^^^^^^^^^^^^^^^^^^^^^^^^
49
50Stable releases
51"""""""""""""""
52
53You can find the source tarballs at the
54`Releases <https://github.com/taisei-project/taisei/releases>`__ section on
55Github. **Do not** grab Github's auto-generated source archives, those do not
56contain the required submodules. This only applies for versions v1.3 and above.
57
58Latest code from git
59""""""""""""""""""""
60
61If you cloned Taisei from git, make sure the submodules are initialized:
62
63::
64
65 git submodule init
66 git submodule update
67
68This step needs to be done just once, and can be skipped if you specified the
69``--recursive`` or ``--recurse-submodules`` option when cloning.
70
71**Important:** You should also run ``git submodule update`` whenever you pull in
72new code, checkout another branch, etc. The ``pull`` and ``checkout`` helper
73scripts can do that for you automatically.
74
75Compiling from source
76^^^^^^^^^^^^^^^^^^^^^
77
78To build and install Taisei on \*nix, just follow these steps:
79
80::
81
82 cd /path/to/taisei/source
83 mkdir build
84 cd build
85 meson --prefix=$yourprefix ..
86 ninja
87 ninja install
88
89This will install game data to ``$prefix/share/taisei/`` and build this
90path *statically* into the executable. This might be a package
91maintainer’s choice. Alternatively you may want to add
92``-Dinstall_relative=true`` to get a relative structure like
93
94::
95
96 $prefix/taisei
97 $prefix/data/
98
99``install_relative`` is always set when building for Windows.
100
101The OpenGL ES 3.0 backend is not built by default. To enable it, do:
102
103::
104
105 meson configure -Dr_gles30=true -Dshader_transpiler=true
106
107See `here <doc/ENVIRON.rst>`__ for information on how to activate it.
108Alternatively, do this to make GLES 3.0 the default backend:
109
110::
111
112 meson configure -Dr_default=gles30
113
114The OpenGL ES 2.0 backend can be enabled similarly, using ``gles20`` instead of
115``gles30``. However, it requires a few extensions to function correctly, most
116notably:
117
118- ``OES_depth_texture`` or ``GL_ANGLE_depth_texture``
119- ``OES_standard_derivatives``
120- ``OES_vertex_array_object``
121- ``EXT_frag_depth``
122- ``EXT_instanced_arrays`` or ``ANGLE_instanced_arrays`` or
123 ``NV_instanced_arrays``
124
125
126Where are my replays, screenshots and settings?
127-----------------------------------------------
128
129Taisei stores all data in a platform-specific directory:
130
131- On **Windows**, this will probably be ``%APPDATA%\taisei``
132- On **macOS**, it's ``$HOME/Library/Application Support/taisei``
133- On **Linux**, **\*BSD**, and most other **Unix**-like systems, it's
134 ``$XDG_DATA_HOME/taisei`` or ``$HOME/.local/share/taisei``
135
136This is referred to as the **Storage Directory**. You can set the environment
137variable ``TAISEI_STORAGE_PATH`` to override this behaviour.
138
139Game controller support
140-----------------------
141
142Taisei uses SDL2's unified GameController API. This allows us to correctly
143support any device that SDL recognizes by default, while treating all of them
144the same way. This also means that if your device is not supported by SDL, you
145will not be able to use it unless you provide a custom mapping. If your
146controller is listed in the settings menu, then you're fine. If not, read on.
147
148An example mapping string looks like this:
149
150::
151
152 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,
153
154There are a few ways to generate a custom mapping:
155
156- You can use the
157 `controllermap <https://aur.archlinux.org/packages/controllermap>`__ utility,
158 which `comes with SDL source code
159 <https://hg.libsdl.org/SDL/file/68a767ae3a88/test/controllermap.c>`__.
160- If you use Steam, you can configure your controller there. Then you can add
161 Taisei as a non-Steam game; run it from Steam and everything should *just
162 work™*. In case you don't want to do that, find ``config/config.vdf`` in your
163 Steam installation directory, and look for the ``SDL_GamepadBind`` variable.
164 It contains a list of SDL mappings separated by line breaks.
165- You can also try the `SDL2 Gamepad Tool by General Arcade
166 <http://www.generalarcade.com/gamepadtool/>`__. This program is free to use,
167 but not open source.
168- Finally, you can try to write a mapping by hand. You will probably have to
169 refer to the SDL documentation. See `gamecontrollerdb.txt
170 <misc/gamecontrollerdb/gamecontrollerdb.txt>`__ for some more examples.
171
172Once you have your mapping, there are two ways to make Taisei use it:
173
174- Create a file named ``gamecontrollerdb.txt`` where your config, replays and
175 screenshots are, and put each mapping on a new line.
176- Put your mappings in the environment variable ``SDL_GAMECONTROLLERCONFIG``,
177 also separated by line breaks. Other games that use the GameController API
178 will also pick them up.
179
180When you're done, please consider contributing your mappings to
181`SDL <https://libsdl.org/>`__,
182`SDL_GameControllerDB <https://github.com/gabomdq/SDL_GameControllerDB>`__,
183and `us <https://github.com/taisei-project/SDL_GameControllerDB>`__, so
184that other people can benefit from your work.
185
186Also note that we currently only handle input from analog axes and digital
187buttons. Hats, analog buttons, and anything more exotic will not work, unless
188remapped.
189
190Troubleshooting
191---------------
192
193Sound problems (Linux)
194^^^^^^^^^^^^^^^^^^^^^^
195
196If your sound becomes glitchy, and you encounter lot of console messages like:
197
198::
199
200 ALSA lib pcm.c:7234:(snd_pcm_recover) underrun occurred
201
202it seems like you possibly have broken ALSA configuration. This may be fixed by
203playing with parameter values of ``pcm.dmixer.slave`` option group in
204``/etc/asound.conf`` or wherever you have your ALSA configuration.
205Commenting ``period_time``, ``period_size``, ``buffer_size``, ``rate`` may give
206you the first approach to what to do.
207
208Contact
209-------
210
211- https://taisei-project.org/
212
213- `#taisei-project on Freenode <irc://irc.freenode.org/taisei-project>`__
214
215- `Our server on Discord <https://discord.gg/JEHCMzW>`__
216