aswm/README.md

```
       ______  _________              ____    ____
      /      |/     \   \            /    \  /    \ 
     /       |    ___\   \    /\    /  /\  \/  /\  \
    /   /|   |        \   \  /  \  /  /  \    /  \  \
   /   / |   |\___     \   \/    \/  /    \__/    \__\
  /   /  |   |/        /\     /\    /                  
 /___/   |___|________/  \___/  \__/             
```

# :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