diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4c02f4ec..ad0897b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,17 +4,22 @@ Thanks for your interest in opsu! This document provides basic guidelines for contributing to the repository. If you plan on making major changes, consider [opening an issue][issues] first to discuss your ideas. -[issues]: https://github.com/itdelatrisu/opsu/issues/new +[issues]: https://github.com/clonewith/opsu/issues/new + +## Reporting problems + +We are happy to see the problems you reported! You can do as belows: + +1. Make sure the problem is not about the device itself, and deal with it when necessary. +2. Look through the issues list, and see if your issue was reported before by others. +3. Provide relevant details. The issue template can help you. ## Making a Change -1. [Fork the repository][fork] and set up your build environment, as described - in the [README][buildenv]. +1. [Fork the repository][fork] and set up your build environment, as described in the [README][buildenv]. 2. Make your desired code changes in your fork. -3. Test your change. There are no automated tests, so just do this manually. - Read the [testing tips](#testing-tips) below for some suggestions. -4. Commit your change and create a [pull request][PR]. Follow up with any - requested changes as needed. +3. Test your change. We have automated CIs that can help check your code, but changes in gameplay and interface still need manual checks. Read the [testing tips](#testing-tips) below for some suggestions. +4. Commit your change and create a [pull request][PR]. Follow up with any requested changes as needed. [fork]: https://help.github.com/articles/fork-a-repo/ [buildenv]: README.md#building @@ -22,34 +27,26 @@ contributing to the repository. If you plan on making major changes, consider ## Guidelines -* A pull request should only contain one feature or bug fix. If you want to make - multiple changes, create branches and open separate pull requests. -* Don't change more than you need to. In particular, don't change the coding - style or move existing blocks around. -* In general, follow the same coding style as the file that you're editing. -* Write comments in your code as needed. At minimum, [Javadoc][Javadoc] comments - are expected on all classes, methods, and global variables. +- An issue or a pull request should only contain one feature or bug fix (at least, one exact part of the game). If you want to make multiple changes, create branches and open separate issues or pull requests. +- Don't change more than you need to. In particular, don't change the coding style or move existing blocks around. +- In general, follow the same coding style as the file that you're editing. The `.editorconfig` can help set up your IDE. +- Write comments in your code as needed. At minimum, [Javadoc][Javadoc] comments are expected on all classes, methods, and global variables. [Javadoc]: https://en.wikipedia.org/wiki/Javadoc#Technical_architecture ## Coding Style -* Use tabs for indenting, not spaces. -* Indentation and brace placement follow [Java conventions][indent]. Braces are - usually not used for single-statement `if`, `while`, and `for`. -* There is no maximum line length; break long lines (or not) for readability. -* For now, avoid using features of Java 8 or higher (e.g. streams, lambdas). +- Use tabs for indenting, not spaces. +- Indentation and brace placement follow [Java conventions][indent]. Braces are usually not used for single-statement `if`, `while`, and `for`. +- There is no maximum line length; break long lines (or not) for readability. +- For now, avoid using features of Java 8 or higher (e.g. streams, lambdas). [indent]: https://en.wikipedia.org/wiki/Indent_style#Variant:_Java ## Testing Tips -* **Gameplay changes:** Depending on the change, consider playing through a - regular or [2B][2B] beatmap, watching a replay, pausing/resuming the game, - enabling/disabling experimental sliders, etc. -* **UI changes:** Be sure to try different client resolutions (such as - 800x600 and widescreen) and different skins (if applicable). -* **Graphics/audio changes:** Test on different operating systems if you can, - especially if your change could break Linux audio in any way. +- **Gameplay changes:** Depending on the change, consider playing through a regular or [2B][2B] beatmap, watching a replay, pausing/resuming the game, enabling/disabling experimental sliders, etc. +- **UI changes:** Be sure to try different client resolutions (such as 800x600 and widescreen) and different skins (if applicable). +- **Graphics/audio changes:** Test on different operating systems if you can, especially if your change could break Linux audio in any way. [2B]: https://osu.ppy.sh/s/90935 diff --git a/CREDITS.md b/CREDITS.md index 39d96694..2c47bfdc 100644 --- a/CREDITS.md +++ b/CREDITS.md @@ -1,13 +1,12 @@ -Credits -======= +# Credits -This software was created by Jeffrey Han ([@itdelatrisu](https://github.com/itdelatrisu/)). +This software was created by Jeffrey Han ([@itdelatrisu](https://github.com/itdelatrisu)). [@CloneWith](https://github.com/clonewith) made further changes on it. -All game concepts and designs are based on work by [osu!](https://osu.ppy.sh/) +All game concepts and designs are based on work by [osu!](https://osu.ppy.sh) developer Dean Herbert ([@ppy](https://github.com/ppy)). -Images ------- +## Images + The images included in opsu! belong to their respective authors. * XinCrin - "Fantasy's Skin" @@ -20,27 +19,27 @@ The images included in opsu! belong to their respective authors. * Misaki Louize - "Yukino II" * Alic1a - "AL's IA -Blue-" * Xiaounlimited - "Nexus Ivory" -* noClue - "Vocaloid Project Skin [LIGHT]" +* noClue - "Vocaloid Project Skin \[LIGHT\]" * pictuga - "osu! web" * sherrie__fay * kouyang * teinecthel -* Teddy Kelley - https://unsplash.com/photos/weuWmzv7xnU (main menu background) -* User icons designed by Freepik - https://www.freepik.com/ - * https://www.freepik.com/free-vector/flat-lovely-animal-avatar-collection_845660.htm - * https://www.freepik.com/free-vector/wild-and-marine-animal-collection_845661.htm -* Font Awesome by Dave Gandy - http://fontawesome.io - -Projects --------- +* Teddy Kelley - [Source](https://unsplash.com/photos/weuWmzv7xnU) (main menu background) +* User icons designed by Freepik - [Main Website](https://www.freepik.com/) + * [Flat lovely animal avatar collection](https://www.freepik.com/free-vector/flat-lovely-animal-avatar-collection_845660.htm) + * [Another link](https://www.freepik.com/free-vector/wild-and-marine-animal-collection_845661.htm) +* Font Awesome by Dave Gandy - [Website](http://fontawesome.io) + +## Projects + The following projects were referenced in the initial creation of opsu!: -* "Wojtkosu" - Wojtek Kowaluk (https://osu.ppy.sh/forum/t/97260) -* "osu-parser" - nojhamster (https://github.com/nojhamster/osu-parser) -* "osu! web" - pictuga (https://github.com/pictuga/osu-web) +* "Wojtkosu" - Wojtek Kowaluk [Forum link](https://osu.ppy.sh/forum/t/97260) +* "osu-parser" - nojhamster [Github repo](https://github.com/nojhamster/osu-parser) +* "osu! web" - pictuga [Github repo](https://github.com/pictuga/osu-web) + +## Theme Song -Theme Song ----------- Rainbows - Kevin MacLeod (incompetech.com) Licensed under Creative Commons: By Attribution 3.0 License -http://creativecommons.org/licenses/by/3.0/ +[Creative Commons BY 3.0](http://creativecommons.org/licenses/by/3.0/) diff --git a/README.md b/README.md index 38bad21a..cd70e83b 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,86 @@ -# [opsu!](https://itdelatrisu.github.io/opsu/) -**opsu!** is an unofficial open-source client for the rhythm game -[osu!](https://osu.ppy.sh/), written in Java using -[Slick2D](http://slick.ninjacave.com/) and [LWJGL](http://lwjgl.org/) -(wrappers around OpenGL and OpenAL). +# [opsu!](https://github.com/clonewith/opsu) -opsu! runs on Windows, OS X, and Linux. -A [libGDX port](https://github.com/fluddokt/opsu) also supports Android devices. +**opsu!** is an unofficial open-source client for the rhythm game [osu!](https://osu.ppy.sh/), written in Java using [Slick2D](http://slick.ninjacave.com/) and [LWJGL](http://lwjgl.org/) (wrappers around OpenGL and OpenAL). + +opsu! runs on Windows, Linux and Android (libGDX port). For Android releases, there is also a [separate repo](https://github.com/clonewith/opsu-droid) and one to [build apks](https://github.com/clonewith/opsu-ABuild). + +Take a look at the original project if you would like to do so: + +- [itdelatrisu/opsu](https://github.com/itdelatrisu/opsu) +- [fluddokt's Android port](https://github.com/fluddokt/opsu) + +Specially, you may hope to read [relevant wiki articles](https://osu.ppy.sh/wiki) as well. ## Getting Started -Get a copy of opsu! from the [releases](https://github.com/itdelatrisu/opsu/releases) -page. APK releases can be found [here](https://github.com/fluddokt/opsu/releases). + +- Get a copy of opsu! from the [releases](https://github.com/clonewith/opsu/releases) page. +- APK releases can be found [here](https://github.com/clonewith/opsu-droid/releases). ### Java Setup -The Java Runtime Environment (JRE) 7 or higher must be installed in order to run -opsu!. The download page is located [here](https://www.java.com/en/download/). + +For desktop versions, the Java Runtime Environment (JRE) 7 or higher must be installed in order to run opsu!. The download page is located [here](https://www.java.com/en/download/). ### Beatmaps -opsu! requires "beatmaps" to run, which contain the songs and gameplay data. -These can be downloaded directly through opsu! in the downloads menu, or -manually from the [osu! website](https://osu.ppy.sh/p/beatmaplist) (requires -registration) and mirror sites like [Bloodcat](http://bloodcat.com/osu/). -Place any manually downloaded beatmaps (in .osz format) in the `Import/` -directory for opsu! to unpack them automatically. -If osu! is installed, opsu! will attempt to read beatmaps from the osu! -installation location. The beatmap directory can also be changed by setting -the "BeatmapDirectory" value in the generated configuration file. +opsu! requires "beatmaps" to run, which contain the songs and gameplay data. These can be downloaded directly through opsu! in the downloads menu, or manually from the [osu! website](https://osu.ppy.sh/p/beatmaplist) (needs an available osu! account) and mirror sites. +Place any manually downloaded beatmaps (in .osz format) in the `Import/` directory for opsu! to unpack them automatically. Currently opsu! only supports **osu!(standard) mode** beatmaps! + +If osu! is installed, opsu! will attempt to read beatmaps from the osu! installation location. The beatmap directory can also be changed by setting the "BeatmapDirectory" value in the generated configuration file `opsu.cfg`. ### First Run -opsu! will parse all beatmaps when launched, which can take a while for the -first time. If no beatmaps are found, the game will prompt you to download some -to get started. -Game settings can be changed in the options menu, accessed by clicking the -"Other Options" button in the song menu. The "Music Offset" value will likely -need to be adjusted initially, or whenever hit objects are out of sync with the -music. +opsu! will parse all beatmaps and update the database when launched, which can take a while for the first time. If no beatmaps are found, the game will prompt you to download some to get started. + +Game settings can be changed in the options menu, accessed by clicking the "Other Options" button in the song menu. The "Music Offset" value will likely need to be adjusted initially, or whenever hit objects are out of sync with the music. ### Directory Structure + The following files and folders will be created by opsu! as needed: -* `.opsu.cfg`: The configuration file. Most (but not all) of the settings can - be changed through the options menu. -* `.opsu.db`: The beatmap cache database. -* `.opsu_scores.db`: The scores and player database. -* `.opsu.log`: The error log. All critical errors displayed in-game are also - logged to this file, and other warnings not shown are logged as well. -* `Songs/`: The beatmap directory (not used if an osu! installation is detected). - The parser searches all of its subdirectories for .osu files to load. -* `Skins/`: The skins directory. Each skin must be placed in a folder within - this directory. Any game resource (in `res/`) can be skinned by placing a - file with the same name in a skin folder. Skins can be selected in the - options menu. -* `Replays/`: The replay directory. Replays of each completed game are saved - as .osr files, and can be viewed at a later time or shared with others. -* `Import/`: The import directory. All beatmap packs (.osz) and skin - packs (.osk) are unpacked to the proper location. All replays (.osr) are - moved to the replay directory, and their scores saved to the scores database. -* `Screenshots/`: The screenshot directory. Screenshots can be taken by - pressing the F12 key. -* `Natives/`: The native libraries directory. -* `Temp/`: The temporary files directory. Deleted when opsu! exits. + +- `.opsu.cfg`: The configuration file. Most (but not all) of the settings can be changed through the options menu. +- `.opsu.db`: The beatmap cache database. +- `.opsu_scores.db`: The scores and player database. +- `.opsu.log`: The error log. All critical errors displayed in-game are also logged to this file, and other warnings not shown are logged as well. +- `Songs/`: The beatmap directory (not used if an osu! installation is detected). The parser searches all of its subdirectories for .osu files to load. +- `Skins/`: The skins directory. Each skin must be placed in a folder within this directory. Any game resource (in `res/`) can be skinned by placing a file with the same name in a skin folder. Skins can be selected in the options menu. +- `Replays/`: The replay directory. Replays of each completed game are saved as .osr files, and can be viewed at a later time or shared with others. +- `Import/`: The import directory. All beatmap packs (.osz) and skin packs (.osk) are unpacked to the proper location. All replays (.osr) are moved to the replay directory, and their scores saved to the scores database. +- `Screenshots/`: The screenshot directory. Screenshots can be taken by pressing the F12 key. +- `Natives/`: The native libraries directory. +- `Temp/`: The temporary files directory. Deleted when opsu! exits. ## Building + opsu! is distributed as both a [Maven](https://maven.apache.org/) and [Gradle](https://gradle.org/) project. ### Maven + Maven builds are built to the `target` directory. -* To run the project, execute the Maven goal `compile`. -* To create a single executable jar, execute the Maven goal `package -Djar`. - This will compile a jar to `target/opsu-${version}.jar` with the libraries, - resources and natives packed inside the jar. - * Setting the "XDG" property (`-DXDG=true`) will make the application use XDG - folders under Unix-like operating systems. - * Setting the "exclude" property to "ffmpeg" (`-Dexclude=ffmpeg`) will exclude - FFmpeg shared libraries from the jar. + +- To run the project, execute the Maven goal `compile`. +- To create a single executable jar, execute the Maven goal `package -Djar`. This will compile a jar to `target/opsu-${version}.jar` with the libraries, resources and natives packed inside the jar. + - Setting the "XDG" property (`-DXDG=true`) will make the application use XDG folders under Unix-like operating systems. + - Setting the "exclude" property to "ffmpeg" (`-Dexclude=ffmpeg`) will exclude FFmpeg shared libraries from the jar. ### Gradle + Gradle builds are built to the `build` directory. -* To run the project, execute the Gradle task `run`. -* To create a single executable jar, execute the Gradle task `jar`. - This will compile a jar to `build/libs/opsu-${version}.jar` with the libraries, - resources and natives packed inside the jar. - * Setting the "XDG" property (`-PXDG=true`) will make the application use XDG - folders under Unix-like operating systems. - * Setting the "excludeFFmpeg" property (`-PexcludeFFmpeg`) will exclude - FFmpeg shared libraries from the jar. + +- To run the project, execute the Gradle task `run`. +- To create a single executable jar, execute the Gradle task `jar`. This will compile a jar to `build/libs/opsu-${version}.jar` with the libraries, resources and natives packed inside the jar. + - Setting the "XDG" property (`-PXDG=true`) will make the application use XDG folders under Unix-like operating systems. + - Setting the "excludeFFmpeg" property (`-PexcludeFFmpeg`) will exclude FFmpeg shared libraries from the jar. ## Contributing -See the [contributing guidelines](CONTRIBUTING.md). + +See the [contributing guidelines](CONTRIBUTING.md) for details. ## Credits -This software was created by Jeffrey Han -([@itdelatrisu](https://github.com/itdelatrisu/)). All game concepts and -designs are based on work by [osu!](https://osu.ppy.sh/) developer Dean Herbert -([@ppy](https://github.com/ppy)). Other credits can be found [here](CREDITS.md). + +This software was created by Jeffrey Han ([@itdelatrisu](https://github.com/itdelatrisu/)). All game concepts and designs are based on work by [osu!](https://osu.ppy.sh/) developer Dean Herbert ([@ppy](https://github.com/ppy)). Other credits can be found [here](CREDITS.md). ## License + **This software is licensed under GNU GPL version 3.** You can find the full text of the license [here](LICENSE).