A game framework written with osu! in mind.
keii.dev
1<p align="center">
2 <img width="500px" src="assets/o!f Logo Large FC.svg">
3</p>
4
5# osu!framework
6
7[](https://github.com/ppy/osu-framework/actions/workflows/ci.yml)
8[](https://github.com/ppy/osu-framework/releases/latest)
9[](https://www.codefactor.io/repository/github/ppy/osu-framework)
10[](https://discord.gg/ppy)
11
12A game framework written with [osu!](https://github.com/ppy/osu) in mind.
13
14## Developing a game using osu!framework
15
16If you are interested in **creating a project** using the framework, please start from the [getting started](https://github.com/ppy/osu-framework/wiki/Setting-up-your-first-project) wiki resources (or jump straight over to the [project templates](https://github.com/ppy/osu-framework/tree/master/osu.Framework.Templates). You can either start off from an empty project, or take a peek at a working sample game. Either way, full project structure, cross-platform support, and a testing setup are included!
17
18The rest of the information on this page is related to working *on* the framework, not *using* it!
19
20## Objectives
21
22This framework is intended to take steps beyond what you would normally expect from a game framework. This means things like basic UI elements, text rendering, advanced input handling (textboxes) and performance overlays are provided out-of-the-box. Any of the osu! code that is deemed useful to other game projects will live in this framework project.
23
24- Anywhere we implement graphical components, they will be displayed with a generic design and will be derivable for further customisation.
25- Common elements used by games (texture caching, font loading) will be automatically initialised at runtime.
26- Allow for isolated development of components via a solid testing environment (`VisualTests` and `TestCases`). Check the [wiki](https://github.com/ppy/osu-framework/wiki/Development-and-Testing) for more information on how these can be used to streamline development.
27
28## Requirements
29
30- A desktop platform with the [.NET 5.0 SDK](https://dotnet.microsoft.com/download) or higher installed.
31- When running on linux, please have a system-wide ffmpeg installation available to support video decoding.
32- When running on Windows 7 or 8.1, *[additional prerequisites](https://docs.microsoft.com/en-us/dotnet/core/install/windows?tabs=net50&pivots=os-windows#dependencies)** may be required to correctly run .NET 5 applications if your operating system is not up-to-date with the latest service packs.
33- When working with the codebase, we recommend using an IDE with intellisense and syntax highlighting, such as [Visual Studio 2019+](https://visualstudio.microsoft.com/vs/), [Jetbrains Rider](https://www.jetbrains.com/rider/) or [Visual Studio Code](https://code.visualstudio.com/).
34
35### Building
36
37Build configurations for the recommended IDEs (listed above) are included. You should use the provided Build/Run functionality of your IDE to get things going. When testing or building new components, it's highly encouraged you use the `VisualTests` project/configuration. More information on this provided [below](#contributing).
38
39- Visual Studio / Rider users should load the project via one of the platform-specific .slnf files, rather than the main .sln. This will allow access to template run configurations.
40
41### Code analysis
42
43Code analysis can be run with `powershell ./InspectCode.ps1` or `InspectCode.sh`.
44
45## Contributing
46
47Contributions can be made via pull requests to this repository.
48
49If you're unsure of what you can help with, check out the [list of open issues](https://github.com/ppy/osu-framework/issues) (especially those with the ["good first issue"](https://github.com/ppy/osu-framework/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) label).
50
51Before starting, please make sure you are familiar with the [development and testing](https://github.com/ppy/osu-framework/wiki/Development-and-Testing) procedure we have set up. New component development, and where possible, bug fixing and debugging existing components **should always be done under VisualTests**.
52
53Note that while we already have certain standards in place, nothing is set in stone. If you have an issue with the way code is structured; with any libraries we are using; with any processes involved with contributing, *please* bring it up. We welcome all feedback so we can make contributing to this project as pain-free as possible.
54
55For those interested, we love to reward quality contributions via [bounties](https://docs.google.com/spreadsheets/d/1jNXfj_S3Pb5PErA-czDdC9DUu4IgUbe1Lt8E7CYUJuE/view?&rm=minimal#gid=523803337), paid out via paypal or osu! supporter tags. Don't hesitate to [request a bounty](https://docs.google.com/forms/d/e/1FAIpQLSet_8iFAgPMG526pBZ2Kic6HSh7XPM3fE8xPcnWNkMzINDdYg/viewform) for your work on this project.
56
57## Licence
58
59This framework is licensed under the [MIT licence](https://opensource.org/licenses/MIT). Please see [the licence file](LICENCE) for more information. [tl;dr](https://tldrlegal.com/license/mit-license) you can do whatever you want as long as you include the original copyright and license notice in any copy of the software/source.
60
61The BASS audio library (a dependency of this framework) is a commercial product. While it is free for non-commercial use, please ensure to [obtain a valid licence](http://www.un4seen.com/bass.html#license) if you plan on distributing any application using it commercially.
62
63## Projects that use osu!framework
64
65[osu!](https://github.com/ppy/osu) – rhythm is just a *click* away!
66
67[GDEdit](https://github.com/gd-edit/GDE) - A third-party Geometry Dash editor.
68
69[Vignette](https://github.com/vignette-project/vignette) - An OpenCV-based facial recognition software for Live2D
70
71[IWBTM](https://github.com/EVAST9919/iwbtm) - A platform game with level editor based off of "I Wanna..." games
72
73<!--
74We love to see people using our framework! Add your project here via a PR!
75
76Conditions:
77 - Must be a GitHub link (i.e. your project is open source)
78 - Must be actively developed (and have executable releases)
79-->
80