Application Development - joneavila/aesthetic GitHub Wiki

Aesthetic can be tested locally on macOS and Linux with LÖVE installed (download). Set up your development environment as follows:

# Clone the repository
git clone http://github.com/joneavila/aesthetic
cd aesthetic

# Make the launch script executable
chmod +x dev_launch.sh

# Run the script with default window size
./dev_launch.sh
# Or specify a custom window size
#   ./dev_launch.sh 720x720

The script creates a .dev directory in the root of the repository to simulate a muOS environment. This directory, combined with environment variables set by the script, allows you to generate themes locally. The .dev directory has the following structure:

• .dev/logs/ - Log files
• .dev/opt/muos/config/version.txt – Simulated muOS version file
• .dev/opt/muos/device/current/script/led_control.sh – Simulated muOS LED control script
• .dev/run/muos/storage/themes/ – Simulated muOS themes storage (generated themes are stored here)

1. Connect your handheld to your network via Configuration > Wi-Fi Network and note its IP address.

2. Enable SFTP access via Configuration > Web Services > SFTP + Filebrowser. The default credentials are root for both username and password.

3. Enable SSH access via Configuration > Web Services > Secure Shell.

4. Generate your private key

   ssh-keygen -t ed25519 ~/.ssh/id_ed25519
   
   # Optionally, specify filename with `-f` and a passphrase with `-N`
   ssh-keygen -t ed25519 -f ~/.ssh/my_key -N "my_passphrase"

5. Find your handheld's IP address via Configuration > Connectivity > Wi-Fi Network

6. Upload the public key to the remote machine (handheld) to enable passwordless authentication:

   ssh-copy-id -i ~/.ssh/id_ed25519.pub root@<HANDHELD-IP>

7. Run the build script to package the application and optionally deploy to your handheld (if you provide path to private key and handheld IP) and optionally clean files from previous installation before deploying. See build script documentation for more information. Usage:

   ./build.sh [--clean] [<PRIVATE_KEY_PATH>] [<HANDHELD_IP>]
   
   # Examples
   ./build.sh
   ./build.sh ~/.ssh/id_ed25519 192.168.68.123
   ./build.sh --clean ~/.ssh/id_ed25519 192.168.68.123

Use scp to transfer files between your local machine and the handheld:

scp root@<DEVICE-IP>:/remote/path/to/file /local/destination/path

When installing a new version of the application, old files are not automatically removed from the handheld. While this typically does not cause issues (as the new code no longer references these files), you can perform a clean installation using the --clean flag with the build script, e.g.:

./build.sh --clean ~/.ssh/id_ed25519 192.168.68.123

The files to be deleted during clean installation are specified in the build script, covering both SD1 and SD2 locations.

To manually identify most files from previous installations, SSH into the handheld and use find to list all files and directories containing aesthetic in their name (case-insensitive):

find / \( -type f -o -type d \) -iname "*aesthetic*" 2>/dev/null

Aesthetic uses a modular architecture of self-contained Lua modules, each exporting a table of functions and managing its own state. These modules communicate via a global state. A screen state machine manages transitions between views. Reusable UI components and utility functions help with common tasks.

• 📂 .github/ - Assets used for the GitHub repository
• 📂 assets/ - Static resources used in the application and generated themes
  • 📂 fonts/
  • 📂 icons/
  • 📂 images/
  • 📂 sounds/
• 📂 bin/ - Binary executables, specifically the LÖVE executable
• 📂 lib/ - Shared libraries, specifically the LÖVE and LuaJIT libraries
• 📂 src/ - Application source code
  • 📂 presets/ - Theme presets
  • 📂 screens/ - Application views
  • 📂 template/ - Theme templates
  • 📂 tove/ - Vector graphics library
  • 📂 ui/ - Reusable UI components
  • 📂 utils/ - Helper functions for common operations
  • 📄 colors.lua - Color scheme definitions used throughout the application
  • 📄 conf.lua - LÖVE configuration
  • 📄 controls.lua - Control mappings
  • 📄 error_handler.lua - Error handling
  • 📄 input.lua - Input processing, handles user input from gamepad and keyboard
  • 📄 main.lua - Application entry point, initializes the state, loads screens, and sets up the application lifecycle
  • 📄 paths.lua - File system path management, manages file system paths for assets and configuration files
  • 📄 screens.lua - Screen state machine
  • 📄 state.lua - Application-wide state management, storing configuration and theme parameters
  • 📄 theme_creator.lua - Theme creation functionality, core functionality for theme creation and export
  • 📄 tween.lua - Animation utilities
  • 📄 version.lua - Version information
• 📂 utils/ - Development utilities and scripts
• 📄 build.sh - Build script for packaging
• 📄 dev_launch.sh - Development launch script
• 📄 mux_launch.sh - muOS launch script

• Lua Language Server – IDE/text editor integration
• Luacheck – Static analysis, linting
• Stylua – Code formatting

Add libraries to .luacheckrc to ignore these files and keep them as-is. You can also add ---@diagnostic disable: <warning-name> to specific files to suppress language server warnings.

The application sets up logging by redirecting output to a text file, this is done in the launch script. To print the latest log:

ssh root@<DEVICE-IP> "cd /mnt/mmc/MUOS/application/Aesthetic/.aesthetic/logs && cat \"\$(ls -t | head -n1)\""