{"id":20367508,"url":"https://github.com/regb/scala-game-library","last_synced_at":"2025-04-15T17:34:48.144Z","repository":{"id":145158125,"uuid":"59868379","full_name":"regb/scala-game-library","owner":"regb","description":"Scala library for cross-platform 2D game development","archived":false,"fork":false,"pushed_at":"2024-09-23T23:32:02.000Z","size":8655,"stargazers_count":155,"open_issues_count":3,"forks_count":9,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-21T00:01:41.747Z","etag":null,"topics":["game","game-2d","game-engine","scala","scala-android","scala-library","scala-native","scalajs"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/regb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-27T23:31:28.000Z","updated_at":"2025-02-04T07:00:47.000Z","dependencies_parsed_at":"2024-11-15T00:32:50.303Z","dependency_job_id":"bae93b0a-b29e-4223-9849-4dbe43843446","html_url":"https://github.com/regb/scala-game-library","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regb%2Fscala-game-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regb%2Fscala-game-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regb%2Fscala-game-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/regb%2Fscala-game-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/regb","download_url":"https://codeload.github.com/regb/scala-game-library/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246112661,"owners_count":20725300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game","game-2d","game-engine","scala","scala-android","scala-library","scala-native","scalajs"],"created_at":"2024-11-15T00:32:39.237Z","updated_at":"2025-03-28T23:07:22.836Z","avatar_url":"https://github.com/regb.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SGL: Scala Game Library\n\n![Scala CI](https://github.com/regb/scala-game-library/workflows/Scala%20CI/badge.svg)\n\nScala Game Library (SGL) is a library for developing cross-platform 2D video\ngames in Scala. It provides a high-level API for building games, and can export\ngames to the Desktop, Android, and the web. More platforms, including iOS and\nconsoles, are on the roadmap.\n\nSGL is still in development, but is intended to provide an extensive toolkit to\nfacilitate game development in Scala, with a layer of abstraction on top of the\nplatform-specific functionalities, and an out-of-the-box implementation for\nmany common features needed in games, such as physics, collision detection,\ntilemaps, and scenes management.\n\n## Objectives\n\nSGL aims at providing a generic and cross-platform 2D game API. The API provides\nsome layers of abstraction on top of the underlying systems, and a game written\nusing the API should be able to get compiled and run on each platform with very\nlitle platform-specific code. However, there are several non-goals of SGL:\n\n  * The exported API hides the non-game specific features of each system,\n    however it will export an API that ressembles the underlying systems, with\n    a slight Scala stylisation when possible. What that means is that the API will\n    be imperative as this is the prevalent system architecture, and it will look\n    familiar to people used to write games directly on some of these systems.  In\n    case you are interested in writing games with a fully functional style, you\n    will need to either build an abstraction on top of this API, or you can check\n    out [Indigo](https://indigoengine.io/), another Scala game engine but with an\n    explicit goal of providing a purely functional API for game developers.\n  * SGL is not an opiniated way of building games. It's trying to provide the\n    most simple yet general API that is cross-platform and enable programmers\n    to create any 2D game. The design decisions are centered around what to export\n    in the API, in the best possible style without losing low-level control. SGL\n    can be thought of as a [libGDX](https://libgdx.badlogicgames.com/) in pure\n    Scala and optimized for 2D games. Another source of inspiration for the\n    design of SGL is the [Simple DirectMedia Layer](https://www.libsdl.org/), and\n    the name SGL was chosen partly because it tries to be a sort of SDL for Scala.\n  * Although SGL is currently providing a lot of extra toolkit library (scene\n    management, game screen management, tiled maps, etc) to facilitate building\n    games, internally there's a relatively clear distinction between what is the\n    core cross-platform API and what are the components built on top of that. A\n    lot of thoughts goes into desiging these core APIs, but components are kind\n    of piled on top of each other quickly, mostly as the need arise in an actual\n    game development project. In the long term, it's possible that SGL will be split\n    between the core layers of abstraction, and the components that are built on top.\n    The objective of SGL is to build the correct core abstraction, while the components\n    are one possible take on a game engine API, it should be eventually possible to\n    replace all the components and choose a totally different programming style\n    (including functional reactive programming) and still share the same\n    underlying platform abstractions.\n\n## Features\n\nThe main selling point of SGL is to provide a platform-independent Scala game\nframework to build games, and then deploy them to any platform. You can get\nstarted by writing a core generic game implementation, and then configure any\nbackend with just a few lines of Scala.  You can iterate on your game by\nrunning the AWT backend from `sbt`, which, depending on your configuration, is\nas straighforward as:\n\n    sbt mygame-awt/run\n\nThus, you can quickly iterate on your game locally, without the need to waste a\nlot of time deploying to your target platforms, such as mobile or console.\n\nThe current implementation provides the following backends:\n\n  * *Desktop* with JVM and AWT. This is mostly convenient during development,\n    but can also serve as a final release if you are able to distribute your\n    game to people that have a JVM. It will be cross-platform across Windows,\n    Mac, and Linux.\n  * *Android*. The Android backend is implemented with the native Android SDK\n    for Java, which means that SGL supports Android natively.\n  * *Web* with Scalajs. The web backend is implemented with scalajs\n    and uses the HTML5 canvas for graphics, the HTML5 audio tag for audio, and\n    other standard web features.\n  * *Native (Experimental)*. The native backend implemented with scala-native\n    is able to generate a native executable that can then be run on the target\n    platform without a JVM.  The support for native is not complete yet, but\n    the current implementation is a proof of concept. Further extensions to\n    this backend should enable SGL to eventually target iOS and various\n    consoles.\n  * *iOS* while we do not yet support iOS natively, it is possible to use the\n    web backend combined with a tool like Cordova, to make an iOS app. This\n    has been proven with [this game](https://apps.apple.com/us/app/fish-escape-lite/id1515164224).\n\n## Alternatives\n\nIf you want to write games in Scala, you have a few alternatives. Here's a\nbiased opinion on how SGL compares with these alternatives. But first a\ndisclaimer: SGL is not production-ready and is under heavy development, so if\nyou want to limit your interaction with the game engine, you probably should\nlook somewhere else for now.\n\n* [libGDX](https://libgdx.badlogicgames.com/) is an extremely mature game library\n  written in Java and thus fully useable in Scala. It provides solid support for\n  many platforms, and it supports 3D and you can make full use of OpenGL with it.\n  You can't really compare SGL to libGDX, as they are just not playing in the same\n  league. Today, if you decide to use SGL, you are betting on the future. You are\n  betting on a future where SGL will get to feature-parity with libGDX, and where\n  the Scala-first approach will pay off for your game.\n\n  I do think there are fundamental technical advantages with having the engine written\n  in Scala, which might eventually justify using SGL over libGDX:\n  * Scala is a better language than Java (biased opinion, but I think it's true).\n  * Scala opens up extremely powerful design pattern for the core engine and the\n    plugins built arount it.\n  * SGL leverages Scala Native and Scala.js to provide a high-level of control on each\n    target platform, which I think is superior to what can be done with traditional\n    cross-platform development offered by libGDX.\n\n* [Indigo](https://indigoengine.io/) is a pure Scala game engine with a design\n  focused on developer productivity. It offers a purely functional way of writing\n  games, which is likely to appeal more to Scala developers. By contrast, SGL\n  does not emphasize the funcitonal programming style, it limits itself at\n  abstracting away multiple platforms into a consistent API. Indigo is currently in\n  development so the set of features is constantly moving (just like SGL), so it's\n  hard to truly compare them. Given the current state of the engines, I think it's\n  fair to say that Indigo invested a lot of work into building the right API for\n  the developer, while SGL invested a lot of work into supporting multiple platforms\n  in a very native way (Android, AWT, Native, HTML5 are supported, while today Indigo\n  runs only with Scala.js).\n\n## Work in Progress\n\nThis is a work in progress, so please don't hesitate to get in touch if you are\ninterested in writing a game in Scala.  This is not production ready yet and\nthings will need to be tweak in order to make them work, but I'm putting this\nproject out there as I think it has a good potential, and I'm looking for\nfeedback from people interested in such a library.\n\nI'm developing new features on a need basis. I'm working on some Android games,\nand I started to use this library as it was much nicer to build and test the\ngame on my Linux desktop, and only deploy to the phone for the final tests. I'm\nconstantly adding new features to the library based on my needs for my games,\nbut if you miss some other features, please let me know and I will add them!\nYou're also very welcome to contribute :)\n\nIf you check out the latest master branch, and find out that some stuff is not working\nas expected, please understand that the project is evolving rapidly and I'm\nlikely just breaking existing stuff to try to improve the overall design. The\nlibrary does truly help in building actual games, and I successfully developed\none published [Android\ngame](https://play.google.com/store/apps/details?id=com.regblanc.winsmash) with\nit. The library helped tremendously, by being entirely Scala-based and by\nallowing for transparent porting from the Desktop to the Android platform.\n\n## How to Write a Game with SGL\n\nSGL is split across several sub-projects so that games built by the framework\nonly pack the necessary dependencies. The organization is to provide a `core`\nproject, which defines all the APIs, and roughly one backend per platform. A\ngame should then depend on both the core abstraction and the platform on which\nit will deploys. Cross-platform games can be further split into smaller units,\nwith a cross-platform core logic that will only depends on the core SGL\nabstractions and various platform-specific implementations. The small\n[snake](examples/snake) project demonstrates how you can organize a game to be\ncross platform. A more advanced example can be found by looking at the sources\nof [Scalavator](https://github.com/regb/scalavator).\n\nSGL is currently splited into the following sub-projects:\n\n  * coreJVM, coreJS, coreNative (the core abstractions compiled for JVM,\n    scalajs, and scala-native).  The [core](core/) project contains the\n    abstract API for the platform as well as all the features that are\n    platform-agnostic.\n  * desktopAWT, depends on coreJVM and provide window and graphics with AWT.\n  * desktopNative, depends on coreNative and use scala-native and OpenGL to\n    build a native executable.\n  * html5, depends on coreJS and use scala.js to generate a javascript game.\n  * coreAndroid and android, for the android platform.\n  * jvmShared, some non-core utilities shared by all JVM-based platform.\n\nThese projects are defined in the [built.sbt](build.sbt) file and have their\nsources in each corresponding subdirectory. Android definitions are in a\n[sub-directory](android/build.sbt) because the Android plugins does not\nwork with the most recent sbt version.\n\n## Understanding the Versioning\n\nFor a long time, the only way to use SGL was to declare direct source\ndependencies. That proved relatively unsuccessful and most of the Scala\ncommunity seems to believe that binary dependencies is the way to go. Since SGL\nis still an early prototype, I wasn't very keen on publishing a stable version\nas a binary that people could just depend on through Maven.\n\nNevertheless, to make SGL easier to use, I will soon start officially releasing\non Maven. The first release will be `0.0.1`, with the intent to be clear that\nthis is a highly experimental version. Future versions will simply increase the\nlast digit, i.e. `0.0.2` and then `0.0.3`. As long as SGL stays in the `0.0`\nversion line, there will be no guarantee on backward compatibility, and each\nnew version could break absolutely everything the previous version introduced.\nThis is all in the name of velocity and innovation, of course. If you do give a\nchance to SGL `0.0.X`, just be aware that there will be bugs, and updates will\nlikely break your code. You must be willing to actively engage with the\ndevelopers of SGL.\n\nThe eventual goal is to reach the `0.1` version line, which at that point will\nbe a more stable release and future updates would hopefully better respect\nbackward compatibility.\n\nAt the current time, version `0.0.1` is not yet released on Sonatype. Most of\nthe build config and code is there, but I want to make a few adjustments before\npublishing.  Until then, you can use `publishLocal` to publish the version\nlocally and use it on your own games.\n\n### Roadmap to 0.0.1\n\nI would like to ensure that the artifact for 0.0.1 is good enough to write interesting\ngames without constantly requiring tweaking SGL. Currently, as I'm working on\nmy games, I constantly need to go back and tweak SGL a little bit in order to\nget something working as I would expect. That tells me that the library is not\nquite stable enough to reach the highly unstable and experimental version 0.0.1.\nOf course, 0.0.1 should not be perfect, but we should have a reasonable chance\nto be able to complete a game without requiring an update to the library. There are\na few things that I would like to get done before getting there:\n\n1. Get a commercial game published. Fish Escape fits the bill here and is already\npublished on iOS and Android. There are still extra features that I want to implement\nto tweak the games (ads on iOS, analytics on iOS, iAP on both platforms), so these\nshould be implemented and deployed (although maybe iAP can wait for 0.0.2).\n\nThis would prove that SGL can get the job done and make a feature-complete game.\n\n2. Make sure that Desktop, Web, Android, and iOS (through Cordova) have\ncomplete support for the core providers. It's ok to be missing some addon\nproviders (ads, analytics, etc) on some of the platforms, but we should at\nleast be able to get a game with the fundamental providers on each of these\nplatforms. We can ship with the experimental native backend, but we need to be\nclear that this is not supported and is still a PoC.\n\n3. Provide a basic tutorial.\n\n4. Provide a demo game. Scalavator is good for that, but it needs updating.\nThis also doubles as another proof that the library can build games.\n\n5. We probably don't need a website, but we should publish the scaladoc\nsomehow.\n\n6. Expand the scaladoc. In particular, we should have a starting point in the\nsgl root package, where we explain the high level design of the library and\nhow to put a game together with the cake. Ideally this would serve as the\ndocumentation until we have a proper documentation (like an actual system\nmanual, much more verbose).\n\n7. Review the core API and make sure most of the obvious mistakes have been\nfixed. Examples that have already been fixed are using int coordinates in the\ncanvas. Another one that is in the process of being addressed is the weird\nbehavior when loading multi-dpi bitmaps. There are probably many more such stupid\nmistakes, and I should do a pass to make sure we aren't releasing something that's\nobviously bad. There will be plenty more design mistakes, and that's fine we\ncan fix them later, but let's at least fix the ones we know today.\n\n## Getting Started\n\nYou can start with [a step-by-step tutorial on writing a game with\nSGL](https://regblanc.com/blog/cross-platform-game-development-in-scala-natively/).\nThe tutorial explains some of the concept of the library.\n\nIf you feel ready to start a project from scratch, you can fork the [starter\nproject](https://github.com/regb/sgl-starter-project) as a mostly blank slate.\nYou can check out the [examples](examples/) projects for how to use some of the\nfeatures of SGL.\n\nIf you want to see how a small, but complete, game looks like, I developed [an\nopen-source game](https://github.com/regb/scalavator) with SGL.  The game is\nintended to demonstrate some of the features of the library. \n\n## Some Design Principles\n\n* Games and only games. This is not a general media toolkit. The only things\n  that should be build with this library are games. Yes, there's a feeling like\n  we can do more with this cross-platform style, and that's probably true, but\n  this is better left to other frameworks.\n\n* Pure and true Scala library. We want to expose a Scala-like library a much as\n  possible. No compromise for compatibility with other languages, everything is\n  done in Scala.\n\n* Entirely cross-platform, no cheating. The core library should abstract\n  everything and only exposes features that are truly cross-platform. Any\n  platform-specific extensions should be provided in a type-safe way.\n\n* Generic but pragmatic. We try to remain as generic as possible, in the sense\n  that only features that would be useful for at least two different games\n  would be integrated. However, we want to provide a very effective toolkit, so\n  almost anything that is remotely useful for building games should be made\n  available. Whenever a problem has many alternative implementations, we should\n  try to provide an abstract interface, with each alternative implementation\n  available and let the user select the one they prefer.\n\n* 2D only. The library does not target 3D games. I believe there are an\n  infinite number of wonderful games that can be build entirely in 2D, and I\n  would rather focus on getting a great library to build 2D games than an\n  average library to do everything.\n\n* No building magic. Everything is explicitly implemented in Scala. No\n  additional code generator to handle the different platforms. Setting up a\n  deployment platform should be simple enough to be done manually. That said,\n  eventually a good sbt plugin would come in handy, as long as it is a light,\n  and optional, layer on top.\n\n* Try to be as native as possible. We want to always use the platform native\n  and standard APIs. We should try to map the SGL API as directly as possible\n  to each system API. For example on Android, we want to try to map to the\n  drawable-Xdpi built-in system to handle multiple pixel densities, instead of\n  building a custom asset loading code. By mapping directly into the platform\n  behavior, we get more optimized apps, and can take advantage of future\n  evolution of the system (like app bundles on Android, which requires to use\n  the standard drawable-xdpi layout).\n\n## Gallery\n\nSGL has been used so far to produce mobile-friendly games, usually cross-published\nto Android, iOS, and the web. That said it could be used to make more classic\nindie titles for Steam, it just hasn't been done yet.\n\nThe most ambitious game created with SGL is the cross-platform commercial game\n[Fish Escape](https://www.limetalesgames.com/press/fish-escape.html), available\non:\n* [Android](https://play.google.com/store/apps/details?id=com.limetalesgames.fishescape)\n  ([free lite version](https://play.google.com/store/apps/details?id=com.limetalesgames.fishescapelite))\n* [iOS](https://apps.apple.com/us/app/fish-escape/id1519111295)\n  ([free lite version](https://apps.apple.com/us/app/fish-escape-lite/id1515164224))\n* the web with [Kongregate](https://www.kongregate.com/games/limetales/fish-escape)\n  and [Facebook](https://www.facebook.com/games/fish-escape/)\n\nAdditionally, a small number of experimental games have been published with\nSGL:\n* [WinSmash](http://regblanc.com/games/winsmash/), available for\n[Android](https://play.google.com/store/apps/details?id=com.regblanc.winsmash)\n* [Scalavator](http://regblanc.com/games/scalavator/), available for\n[Android](https://play.google.com/store/apps/details?id=com.regblanc.scalavator)\nand for the [Web](http://regblanc.com/games/scalavator/play.html). Code source\navailable on [GitHub](https://github.com/regb/scalavator).\n\nIf you are using SGL for your commercial game, please contact me and I'll be\nhappy to mention you in this section.\n\n## Code Organization\n\nI heavily use the cake pattern as a means to abstract the different backends\nand to correctly modularize the system. A good article to introduce using the\ncake pattern for dependencies injection is [this\none](http://jonasboner.com/real-world-scala-dependency-injection-di/). There\nis also a [great talk](https://www.youtube.com/watch?v=yLbdw06tKPQ) that\ndescribes how to use the cake pattern, which closely ressembles our usage here.\n\nMore recent articles seem to criticise the Cake pattern and many people seem\nto have drop it. The choice of using the cake pattern was made more than 4\nyears ago and I still haven't reached the point where I think the drawbacks\noutweight the benefits.\n\n## Developing\n\nIn order to run the tests for scala-native, you will need to follow the\ninstallation instructions on the Scala Native\n[website](https://scala-native.readthedocs.io/en/v0.3.9-docs/user/setup.html#installing-clang-and-runtime-dependencies)\nif you have not done so already. Additionally, you will need to have development\nlibraries to link against OpenGL, SDL2, and SDL2 Image.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregb%2Fscala-game-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fregb%2Fscala-game-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fregb%2Fscala-game-library/lists"}