muOS System Information - joneavila/aesthetic GitHub Wiki

muOS Theme Structure

Custom themes must follow the muOS theme structure to ensure compatibility. For details, see the muOS Themes documentation.

muOS System Scripts

muOS uses various scripts to perform system actions on the fly. For example, extract.sh extracts archives and installs packages.

Available scripts in /opt/muos/script/mux/:

|-- extract.sh
|-- find.sh
|-- frontend.sh
|-- hotkey.sh
|-- idle.sh
|-- launch.sh
|-- metacut.sh
|-- migrate.sh
|-- playbgm.sh
|-- quit.sh
|-- screenshot.sh
|-- sdl_map.sh
|-- sync.sh
|-- track.sh
`-- tweak.sh

Environment Variables

You can set environment variables in your launch script and access them in your application. This is useful, for example, for setting directories or reading device information.

# Get screen dimensions from device configuration
SCREEN_WIDTH=$(GET_VAR device mux/width)
SCREEN_HEIGHT=$(GET_VAR device mux/height)

To view all available environment variables:

printenv | sort

Configuration Files

muOS uses two main configuration files, one for device-specific settings and one for global settings.

DEVICE_CONFIG=/opt/muos/device/rgcubexx-h/config.ini
GLOBAL_CONFIG=/opt/muos/config/config.ini

Input System

  • SDL (Simple DirectMedia Layer) is a library that provides hardware abstraction for gamepad controllers and other input devices

  • LÖVE uses SDL for controller input handling and standardizes button names through its GamepadButton API (e.g., a, b, x, y, leftshoulder, rightshoulder)

  • The SDL_GameControllerDB project maintains a database of gamepad mappings to translate physical controller inputs to these standardized buttons, stored in a convinient text file

  • muOS uses this database file, stored in /usr/lib/gamecontrollerdb.txt, to map physical gamepad buttons to virtual buttons

  • Aesthetic's launch script exports the environment variable SDL_GAMECONTROLLERCONFIG_FILE="/usr/lib/gamecontrollerdb.txt" to specify the mapping database

  • In the example gamepad mapping entry below, b0, b1, etc. refer to physical buttons on the gamepad, and entries like a:b0 map the virtual button a to physical button b0.

    030000007e0500000920000011810000,Nintendo Switch Pro Controller,a:b0,b:b1,back:b9,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b11,leftshoulder:b5,leftstick:b12,lefttrigger:b7,leftx:a0,lefty:a1,rightshoulder:b6,rightstick:b13,righttrigger:b8,rightx:a2,righty:a3,start:b10,x:b3,y:b2,platform:Linux,

  • Buttons such as a, b, x, y are digital inputs that report either pressed (1) or not pressed (0), checked using LÖVE joystick:isGamepadDown.

  • Axes are analog inputs that report a range of values from -1.0 to 1.0, accessed using LÖVE joystick:getGamepadAxis.

    • Triggers (e.g., triggerleft, triggerright) are considered axes since they report a range of values from 0.0 (not pressed) to 1.0 (fully pressed)
    • Joysticks provide two axes each: leftx/lefty and rightx/righty, where 0.0 is neutral position and -1.0/1.0 represent extremes

  • Related files

    • Aesthetic: src/input.lua, mux_launch.sh
    • muOS system: /opt/muos/device/current/control/hotkey.json