From 6a20573dfa21d4f61be4b1c60d67f3a455c892cd Mon Sep 17 00:00:00 2001 From: Paul Breugnot Date: Sat, 11 Jan 2025 09:21:57 +0100 Subject: [PATCH] :memo: Init README.md --- README.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b800c04 --- /dev/null +++ b/README.md @@ -0,0 +1,185 @@ +``` + ______ _________ ____ ____ + / |/ \ \ / \ / \ + / | ___\ \ /\ / /\ \/ /\ \ + / /| | \ \ / \ / / \ / \ \ + / / | |\___ \ \/ \/ / \__/ \__\ + / / | |/ /\ /\ / + /___/ |___|________/ \___/ \__/ +``` + +# :joystick: Arcade Station Window Manager + +**ASWM** is an Arcade Station Window Manager, optimised to control Linux application +windows (including games and game launchers) with your favorite gamepad. It is +designed to be minimalist, robust, flexible, and compatible with old hardware +and existing arcade environments such as Emulationstation. It is based on the +good old [X Window System](https://en.wikipedia.org/wiki/X_Window_System) and +not written in Rust. + +## Why this project? + +The main motivation for this project is that I have fun coding it and reading +legacy X.org specifications, for reasons I do not understand myself. If you want +rational arguments anyway, they are provided below, but you can directly go to +[Features](#features) if you are not interested in technical details. + +If you are building your custom arcade system, you probably heard about projects +such as [Emulationstation](https://emulationstation.org/) (legacy), +[EmulationStation Desktop Edition](https://www.es-de.org/) (modern and active +fork), [Retroarch](https://www.retroarch.com/), +[Batocera](https://batocera.org/), [Retropie](https://retropie.org.uk/) or even +[Recalbox](https://www.recalbox.com/). **Emulationstation** and its derivative +are customisable gamepad compatible graphic frontends that help you organise and +launch games. **Retroarch** is a unified and generic library to run many retro +gaming systems emulators. It is particularly adapted to be used as a backend for +**Emulationstation**, even if it provides its own [gamepad compatible +UI](https://www.retroarch.com/?page=interface) to launch games. +**Emulationstation** is however not limited to **Retroarch**, and can actually +be used to launch any software. Projects like **Retropie**, **Batocera** or +**Recalbox** (and probably many others) basically adapt and bundle altogether +those software as Linux distributions more or less specialised to specific +hardware. + +Despite the awesomeness of all those projects, they are all focus on retro +systems, and quickly become limiting if you want to run applications that do not +fit the **Emulationstation + Retroarch** scheme. + +The most known issue is probably to integrate a decent +[Steam](https://store.steampowered.com/) launcher to **Emulationstation**, as +the **Steam** client tends to spawn many windows that can mess up the interface +(on the other end, **Retroarch** only spawn a single fullscreen window for each +game). Game launchers such as **Steam** can also require some user login, that +can be impossible to provide with only a gamepad as input. The excellent [Steam +Bigpicture](https://store.steampowered.com/bigpicture) mode (`steam -bigpicture` +on Linux) already solves many problems, for example providing a virtual keyboard +to log in and a gamepad compatible UI to launch games. But you might still have +issues to automatically take back input focus on the **Emulationstation** +interface when you realise that Mega Man X Legacy Collection wasn't worth $20 +and want to seamlessly go back to the SNES edition of Mega Man X without even +rebooting your system. + +Moreover, some games might not even be available from any game launcher and do +not necessarily fit the "single fullscreen window" principle. For example, you +might face issues to launch [patchers of Touhou +16](https://www.thpatch.net/wiki/Touhou_Patch_Center:Main_page) without a mouse +and keyboard. + +It is also not possible to simultaneously run several applications from +**Emulationstation** if you do not have any possibility to navigate currently +opened windows. So if I want to integrate a Spotify or Bandcamp client to my +arcade system to listen the awesome [MyNewSoundtrack's Spark Mandrill +remix](https://mynewsoundtrack.bandcamp.com/album/limitless-x) while making my +way to an epic fight against Vile to attempt to save Zero, I'm stuck. And if I +want to keep a [FreeTube](https://freetubeapp.io/) application opened to watch +[Something About Mega Man X](https://youtu.be/GYD2O23hfJ4) for the hundredth +time between two levels, I can't either. + +In short, the potential of a custom Linux based arcade system goes far beyond +what the **Emulationstation + Retroarch** combo can currently do, and I'm not +completly satisfied with existing project. + +## Why a Window Manager? + +A **Window Manager** is an optional software that organise windows on your +screen. If you only have a single fullscreen window, you don't need a window +manager: that's why **Emulationstation** based arcade system traditionnaly don't +need a window manager. On your daily system, the window manager allows you to +display multiple windows and navigate, resize and move them. + +The purpose of **ASWM** is not to reimplement a yet another flavor of +**Emulationstation**, but to provide a generic solution compatible with existing +projects. As an intermediary software between hardware and your applications, a +custom window manager is thus a smart way to extend features of existing +**Emulationstation** based arcade systems (and others) without altering them. + +As an example, running **Emulationstation** under **ASWM** won't make any +visible change to the user, as the window manager will simply display the single +fullscreen window as requested. The window manager can however provide new +features to navigate windows with a gamepad to improve compatibility with +applications other than **Retroarch**. + +Moreover, a gamepad compatible window manager allows to easily build custom +arcade systems that are not necessarily based on **Emulationstation**, due to +the flexibility of the _game launcher_ concept. + +## Features (:warning: work in progress) + +**ASWM** handles several tasks in your custom arcade system: +1. display and navigate game and game launcher windows in the most intuitive way + using a gamepad +2. perform virtual mouse and keyboard inputs using a gamepad + +### Window management + +The daily usage of a custom arcade system must be as simple as booting the +system, select a game, launch a game, play. The fact that you might need to +manage several windows (for example to log in to the game launcher, or because +several windows about news or the download of updates are displayed) compromise +this objective. But we cannot make much expectations about how each game +launcher will spawn windows in which order, nor hard code specific rules such as +"if the launcher is **Steam**, display this window here and hide this other one" +(at least not at the **ASWM** core level, but this is acceptable as user +configuration: see [Custom layouts](#custom-layouts)). + +In order to build a flexible window manager, **ASWM** is based on the abstract +concept of _game launcher_. A _game launcher_ is an application that is used to +launch other _game launchers_ or _games_. A _game_ can actually be any kind of +application. A _game launcher_ can be **Emulationstation**, the native UI +provided by **Retroarch**, the **Steam** client, or even a terminal emulator +where you type the name of a game to launch it. + +When a _game_ or _game launcher_ is closed, it is expected to automatically get +back to the _game launcher_ that launched it. + +#### Structure + +**ASWM** organize windows using the following structure: +1. A _desktop_ is a fullscreen window that can contain other windows. _Desktops_ + are organized in sequence subject to left/right navigation. +2. Each _desktop_ contains: + 1. a _tiled_ background where resizeable windows are organised to try to fit + all the space available on the screen. This is typically where windows + associated to a _game launcher_ are displayed (e.g. the main **Steam** + client window + the **Steam** news window). + 2. on top of the _tiled_ background, a _stack_ of windows centered on the + screen. All the stack is always above _tiled_ windows, and only the top + level _stack_ window can be fully visible on the screen. _Stacked_ windows + are allowed to be fullscreen. They are typically not resizeable _game_ + windows launched from the _game launcher_ in the background. + 3. a fixed _taskbar_, common for all _desktops_, can optionally be displayed + as part of the _tiled_ background, to display information about + applications, system status, and navigation reminders. + +**ASWM** will try to guess where it is more appropriate to place each window to +obtain the most intuitive and pleasant arcade user interface. However, as it is +generic and cannot make strong assumptions about how each application is +behaved, _hints_ and _rules_ can be provided to implement custom layouts that +are sure to fit your specific needs. See [Custom layouts](#custom-layouts) for +configuration instructions. + +#### Controls + +Commands are provided in terms of +[RetroPad](https://docs.libretro.com/guides/input-and-controls/#what-is-a-retropad) +inputs. + +| Command | Action | +|---------|--------| +| TODO | | + +### Virtual mouse and keyboard inputs + +> TODO + +## Installation + +> TODO + +## Configuration + +> TODO + +### Custom layouts + +> TODO