From 093f4cf507194ea134e01be4aa997258e30f9e29 Mon Sep 17 00:00:00 2001 From: kichikuou Date: Tue, 29 Aug 2023 11:26:20 +0900 Subject: [PATCH] Improve documentations With the help of ChatGPT. --- README.md | 141 +++++++++++++++++++++++++++----------------- android/README.md | 47 +++++++++------ system3.ini.example | 30 +++++----- 3 files changed, 130 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index f472a7d..d6eec6c 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,90 @@ # System3 for SDL2 -This is a SDL2 port of [System3 for Win32](http://takeda-toshiya.my.coocan.jp/alice/) by Takeda Toshiya that supports multiple platforms, including Android and Emscripten. +This is an SDL2 port of +[System3 for Win32](http://takeda-toshiya.my.coocan.jp/alice/) by Takeda +Toshiya. It supports multiple platforms, including Android and Emscripten. ## Building ### Linux (Debian, Ubuntu) - $ git submodule update --init - $ sudo apt install g++ cmake libsdl2-dev libsdl2-ttf-dev libsdl2-mixer-dev - $ mkdir -p out/debug - $ cd out/debug - $ cmake -DCMAKE_BUILD_TYPE=Debug ../../src/ - $ make - $ sudo make install +```bash +$ git submodule update --init +$ sudo apt install g++ cmake libsdl2-dev libsdl2-ttf-dev libsdl2-mixer-dev +$ mkdir -p out/debug +$ cd out/debug +$ cmake -DCMAKE_BUILD_TYPE=Debug ../../src/ +$ make +$ sudo make install +``` ### MacOS - $ git submodule update --init - $ brew install cmake pkg-config sdl2 sdl2_ttf sdl2_mixer - $ mkdir -p out/debug - $ cd out/debug - $ cmake -DCMAKE_BUILD_TYPE=Debug ../../src/ - $ make - $ sudo make install +```bash +$ git submodule update --init +$ brew install cmake pkg-config sdl2 sdl2_ttf sdl2_mixer +$ mkdir -p out/debug +$ cd out/debug +$ cmake -DCMAKE_BUILD_TYPE=Debug ../../src/ +$ make +$ sudo make install +``` ### Windows (MSYS2 mingw64) - $ git submodule update --init - $ pacman -S make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_ttf - $ mkdir -p out/debug - $ cd out/debug - $ cmake -G"MSYS Makefiles" -DCMAKE_BUILD_TYPE=Debug ../../src/ - $ make +```bash +$ git submodule update --init +$ pacman -S make mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_ttf +$ mkdir -p out/debug +$ cd out/debug +$ cmake -G"MSYS Makefiles" -DCMAKE_BUILD_TYPE=Debug ../../src/ +$ make +``` ### Windows (Microsoft Visual Studio) -- Visual Studio 2019 can be used to clone this repository. It will automatically clone submodules too. - - If you're using an older version of Visual Studio, install Git and clone this repository with `--recurse-submodules` option. -- Install [CMake](https://cmake.org/download/). (Visual Studio's CMake integration doesn't work.) -- In the CMake GUI, press "Browse Source..." button and select the `src` folder of this repository. -- Press "Browse Build..." button. Create a new folder (e.g. `out`) under the top folder of the repository, and select it. -- Press "Configure" button. Specify the generator for your version of Visual Studio, and hit "Finish". -- Press "Generate" button. -- `System3.sln` file should be generated in the build folder. Open it with Visual Studio. + +- Visual Studio 2019 can be used to clone this repository and will + automatically clone submodules as well. + - If you're using an older version of Visual Studio, install Git and clone + this repository using the `--recurse-submodules` option. +- Install [CMake](https://cmake.org/download/). (The CMake integration in + Visual Studio does not work.) +- In the CMake GUI, press the "Browse Source..." button and select the `src` + folder of this repository. +- Press the "Browse Build..." button. Create a new folder (e.g., `out`) under + the top-level directory of the repository and select it. +- Press the "Configure" button. Specify the generator for your version of + Visual Studio and click "Finish." +- Press the "Generate" button. +- A `System3.sln` file should be generated in the build folder. Open it with + Visual Studio. ### Emscripten - $ git submodule update --init - $ mkdir -p out/wasm - $ cd out/wasm - $ emcmake cmake -DCMAKE_BUILD_TYPE=Release ../../src/ - $ make +```bash +$ git submodule update --init +$ mkdir -p out/wasm +$ cd out/wasm +$ emcmake cmake -DCMAKE_BUILD_TYPE=Release ../../src/ +$ make +``` -To use the Emscripten build, check out https://github.com/kichikuou/web and copy `out/wasm/system3.*` into its `docs` directory. +To use the Emscripten build, check out https://github.com/kichikuou/web and +copy the `out/wasm/system3.*` files into its `docs` directory. ### Android -See [android/README.md](android/). +See [android/README.md](android/README.md). ### Nintendo Switch See [switch/README.md](switch/README.md). ## Running + Usage: -``` + +```bash system3 [options] ``` @@ -73,29 +94,38 @@ system3 [options] Disables text anti-aliasing. #### `-fontfile` _filename_ -Specifies a font file used to render text. `.ttf` and `.otf` files are supported. +Specifies the font file used for rendering text. Both `.ttf` and `.otf` files +are supported. #### `-playlist` _filename_ -_filename_ is a text file that specifies audio files to be played instead of CD audio tracks, one per line. For example: +_filename_ is a text file that lists the audio files to play in lieu of CD +audio tracks, one per line. For example: -``` +```plaintext # This line is ignored BGM/track02.mp3 BGM/track03.mp3 ... ``` -The first line is not used, because track 1 of game CD is usually a data track. +The first line is not used because track 1 on a game CD is usually a data +track. #### `-fm` -Use FM tone generator emulation. If not specified, MIDI sound is used. +Uses FM tone generator emulation. If not specified, MIDI sound is used. #### `-timiditycfg` _filename_ -Specified a specific configuration file in a [format for TiMidity](https://manpages.ubuntu.com/manpages/bionic/en/man5/timidity.cfg.5.html) to use (used in some platforms by SDL_Mixer). +Specifies a particular configuration file in a +[format compatible with TiMidity](https://manpages.ubuntu.com/manpages/bionic/en/man5/timidity.cfg.5.html) +to use (this is utilized by SDL_Mixer on some platforms). #### `-game` _game_id_ -Since System1-3 behave slightly differently depending on the game, `system3` uses fingerprint of the scenario file (ADISK.DAT) to determine which game you are playing. This option allows you to override this. This is useful when running patched games. +As System1-3 have slight variations depending on the game, `system3` uses the +fingerprint of the scenario file (ADISK.DAT) to identify the game being played. +This option allows you to override this detection, which is useful when running +patched games. + +Here is a list of available game IDs and their corresponding titles: -Here's the list of available game IDs and corresponding titles: | game_id | Title | ----------|-------- | `bunkasai` | あぶない文化祭前夜 | @@ -150,13 +180,16 @@ Here's the list of available game IDs and corresponding titles: | `ningyo` | 人魚 -蘿子- | | `mugen` | 夢幻泡影 | -### Configuration file `system3.ini` -Every option that can be set via the command line flags can also be configured -via the `system3.ini` file placed in the game folder. See -[`system3.ini.example`](system3.ini.example) for the file format and available -options. Options specified on the command line override `system3.ini`. +### Configuration File `system3.ini` -## Localizing a game -System3-sdl2 supports localization, while the original System1-3 only supported -Japanese. If you are interested in translating games, check out -[Sys0Decompiler](https://alicesoft.fandom.com/wiki/User_blog:RottenBlock/System_Programming_Resources). \ No newline at end of file +Every option that can be set via command line flags can also be configured +through the `system3.ini` file located in the game folder. Refer to +[`system3.ini.example`](system3.ini.example) for the file format and available +options. Options specified on the command line will override those in +`system3.ini`. + +## Localizing a Game + +System3-sdl2 supports localization, whereas the original System1-3 only +supported Japanese. If you're interested in translating games, check out +[Sys0Decompiler](https://alicesoft.fandom.com/wiki/User_blog:RottenBlock/System_Programming_Resources). diff --git a/android/README.md b/android/README.md index 0055356..5c3688d 100644 --- a/android/README.md +++ b/android/README.md @@ -1,7 +1,8 @@ # System3 for Android ## Download -Prebuilt APKs are [here](https://github.com/kichikuou/system3-sdl2/releases). +You can download prebuilt APKs +[here](https://github.com/kichikuou/system3-sdl2/releases). ## Build Prerequisites: @@ -9,15 +10,15 @@ Prerequisites: - Android NDK >=r15c ### Using Android Studio -Clone this repository and its submodules: +Clone this repository along with its submodules: ```sh git clone --recurse-submodules https://github.com/kichikuou/system3-sdl2.git ``` -Then open `system3-sdl2/android` directory as an Android Studio project. +Next, open the `system3-sdl2/android` directory as an Android Studio project. -### Command line build -Configure environment variables and run the `gradlew` script in this folder. +### Command Line Build +Set environment variables and run the `gradlew` script in this directory. Example build instructions (for Debian bookworm): ```sh @@ -30,36 +31,44 @@ mkdir -p $ANDROID_SDK_ROOT/cmdline-tools wget https://dl.google.com/android/repository/commandlinetools-linux-10406996_latest.zip unzip commandlinetools-linux-10406996_latest.zip -d $ANDROID_SDK_ROOT/cmdline-tools mv $ANDROID_SDK_ROOT/cmdline-tools/cmdline-tools $ANDROID_SDK_ROOT/cmdline-tools/tools -yes |$ANDROID_SDK_ROOT/cmdline-tools/tools/bin/sdkmanager --licenses +yes | $ANDROID_SDK_ROOT/cmdline-tools/tools/bin/sdkmanager --licenses $ANDROID_SDK_ROOT/cmdline-tools/tools/bin/sdkmanager ndk-bundle 'cmake;3.22.1' export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk-bundle -# Check out and build system3-sdl2 +# Clone and build system3-sdl2 git clone --recurse-submodules https://github.com/kichikuou/system3-sdl2.git cd system3-sdl2/android ./gradlew build # or ./gradlew installDebug if you have a connected device ``` -## Use +## Usage ### Basic Usage -1. Create a ZIP file containing all the game files and BGM files (see [below](#preparing-a-zip) for details), and transfer it to your device. -2. Open the app. A list of installed games is displayed. Since nothing has been installed yet, only the "Install from ZIP" button is displayed. Tap it. -3. Select the ZIP file you created in 1. -4. The game starts. Two-finger touch is treated as a right click. +1. Create a ZIP file containing all the game files and BGM files (see + [below](#preparing-a-zip) for details), and transfer it to your device. +2. Open the app. A list of installed games will be displayed. Since no games + have been installed yet, only the "Install from ZIP" button will be visible. + Tap it. +3. Select the ZIP file you created in step 1. +4. The game will start. To simulate a right-click, tap the black bars on either + the left or right, or top or bottom of the screen. ### Preparing a ZIP - Include all `.DAT` files. -- Music files (`.mp3`, `.ogg` or `.wav`) whose file names end with a number are recognized as BGM files. For example: +- Music files (`.mp3`, `.ogg`, or `.wav`) whose filenames end with a number are + recognized as BGM files. For example: - `Track2.mp3` - `15.ogg` - - `rance41_03.wav` (This shouldn't be `rance4103.wav`, because it would be treated as the 4103rd track) + - `rance41_03.wav` (Note: The filename shouldn't be `rance4103.wav`, as it + would be treated as the 4103rd track.) -Note: This form of ZIP can be used in [Kichikuou on Web](http://kichikuou.github.io/web/) as well. +Note: This ZIP format is also compatible with +[Kichikuou on Web](http://kichikuou.github.io/web/). ### Miscellaneous -- You can export / import saved files using the option menu of the game list. -- To uninstall a game, long-tap the title in the game list. -- System menu pops up with 3-finger touch during game play. +- You can export or import save files via the game list's option menu. +- To uninstall a game, long-tap its title in the game list. +- A system menu will appear when you use a three-finger touch during gameplay. ## Known Issues -- Installation from a ZIP containing multiple games (e.g. DPS series) does not work well. +- Installing from a ZIP file containing multiple games (e.g., the DPS series) + may not work correctly. diff --git a/system3.ini.example b/system3.ini.example index 3bce1c6..8174cd5 100644 --- a/system3.ini.example +++ b/system3.ini.example @@ -1,40 +1,40 @@ ; encoding: utf-8 ; System3-sdl2 configuration file. -; Lines beginning with a semicolon are comments. +; Lines starting with a semicolon are comments. [config] -; If true, turn off text anti-aliasing. +; If set to true, text anti-aliasing will be disabled. noantialias = false -; A folder to store the save files. +; Directory to store saved game files. savedir = save -; A font file used to render text. *.ttf and *.otf files are supported. +; Font file used for text rendering. Supports *.ttf and *.otf files. fontfile = custom_font.ttf -; A text file that lists audio files to be played instead of CD audio tracks, -; one per line. +; Text file listing audio tracks to be played as background music, one per +; line. playlist = bgm/playlist.txt -; Use FM tone generator emulation. If not specified, MIDI sound is used. +; Enable FM tone generator emulation. If not specified, MIDI sound will be +; used. fm = true -; The game ID. No need to specify if you use AliceSoft's original game data. -; See README.md for possible values. +; Game ID. No need to specify if using AliceSoft's original game data. +; Refer to README.md for a list of possible values. game = rance41 -; Character encoding of the game data. shift_jis or utf-8. +; Character encoding for game data. Choose between shift_jis or utf-8. encoding = shift_jis -; Text displayed in the window's title bar. If not specified, original Japanese -; game title will be used. +; Text to be displayed in the window's title bar. If not specified, the +; original Japanese game title will be used. title = Rance 4.1 ~Save the Medicine Plant!~ - -; The [string] section allows overriding Japanese text embedded in the game -; engine. The values below are original Japanese text. +; The [string] section allows you to override Japanese text embedded in the +; game engine. The values below are the original Japanese text. [string] back = 戻る next_page = 次のページ