diff --git a/README.rst b/README.rst index ee4134171a..4e829946ec 100644 --- a/README.rst +++ b/README.rst @@ -1,131 +1,155 @@ -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. +About Taisei Project +^^^^^^^^^^^^^^^^^^^^ + +Taisei Project is an open source fan-game set in the world of +`Tōhō 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. + +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. + +For gameplay screenshots, see +`our website `__. + +For gameplay instructions, read `this `__. + +For the story, read `this `__. (Spoiler warning!) + +About Tōhō Project +^^^^^^^^^^^^^^^^^^ + +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 `__ +which allows for indie derivative works such as Taisei Project to legally exist. + +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. + +For more information on dōjin culture, +`click here `__. Installation ------------ -Dependencies -^^^^^^^^^^^^ +You can find precompiled binaries of the complete game on the +`Releases `__ page on +GitHub, available for Windows (x86/x64), Linux, and macOS. + +An experimental build for Nintendo Switch (homebrew) also exists (use at your +own risk). + +You can also play our experimental WebGL build through your web browser +`here `__. (Chromium-based browsers and +Firefox supported.) + +Source Code & Development +------------------------- -- OpenGL >= 3.3 or OpenGL ES >= 3.0 or OpenGL ES >= 2.0 (with some extensions) -- `cglm `__ >= 0.7.8 +Basic Dependencies +^^^^^^^^^^^^^^^^^^ + +Run-Time Dependencies +_____________________ + +Required +******** + +- OpenGL >= 3.3, or OpenGL ES >= 3.0 - SDL2 >= 2.0.10 -- freetype2 +- cglm >= 0.7.8 - libpng >= 1.5.0 - libwebpdecoder >= 0.5 or libwebp >= 0.5 - libzip >= 1.5.0 (>= 1.7.0 recommended) - libzstd >= 1.4.0 +- freetype2 - opusfile - zlib -Optional: +Optional +******** - 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 - `__ integration) +- `ANGLE `__ (useful for platforms with + flaky/non-existent OpenGL support, such as Windows) +- GameMode headers (Linux only; for automatic + `GameMode `__ integration) -Build-only dependencies -^^^^^^^^^^^^^^^^^^^^^^^ +Build-Time Dependenices +_______________________ -- Python >= 3.6 +- ``gcc`` or ``clang`` - meson >= 0.53.0 -- [python-zstandard](https://github.com/indygreg/python-zstandard) - -Optional: - -- docutils (for documentation) - -Obtaining the source code -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Stable releases -""""""""""""""" - -You can find the source tarballs at the -`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: - -:: - - git submodule init - git submodule update - -This step needs to be done just once, and can be skipped if you specified the -``--recursive`` or ``--recurse-submodules`` option when cloning. - -**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. +- Python >= 3.6 +- `python-zstandard `__ >= 0.11.1 +- `python-docutils `__ (optional, for generating documentation) -Compiling from source +Obtaining Source Code ^^^^^^^^^^^^^^^^^^^^^ -To build and install Taisei on \*nix, just follow these steps: +Source +______ -:: - - cd /path/to/taisei/source - 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 -maintainer’s choice. Alternatively you may want to add -``-Dinstall_relative=true`` to get a relative structure like +We recommend fetching the source code using ``git``: :: - $prefix/taisei - $prefix/data/ - -``install_relative`` is always set when building for Windows. + git clone --recurse-submodules https://github.com/taisei-project/taisei -The OpenGL ES 3.0 backend is not built by default. To enable it, do: +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. -:: +Archive +_______ - meson configure -Dr_gles30=true -Dshader_transpiler=true +⚠️ **NOTE**: Due to the way GitHub packages source code, the ``Download ZIP`` +link on the main repo *does not work*. -See `here `__ for information on how to activate it. -Alternatively, do this to make GLES 3.0 the default backend: +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 `__ page. -:: +Compiling Source Code +^^^^^^^^^^^^^^^^^^^^^ - meson configure -Dr_default=gles30 +Currently, we recommend building Taisei on a POSIX-like system (Linux, macOS, +etc). -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: +While Taisei is highly configurable, the easiest way to compile the code for +your host machine is: -- ``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/ -Where are my replays, screenshots and settings? ------------------------------------------------ +Replays, Screenshots, and Settings Locations +-------------------------------------------- Taisei stores all data in a platform-specific directory: @@ -137,80 +161,16 @@ 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 `__ utility, - which `comes with SDL source code - `__. -- 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 - `__. 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 - `__ 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 `__, -`SDL_GameControllerDB `__, -and `us `__, 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. +Feel free to +`open up an issue `__ if you +run into any issues with compiling or running Taisei. Contact ------- - https://taisei-project.org/ -- `#taisei-project on Freenode `__ - - `Our server on Discord `__