BumpDesk is an experimental 3D launcher for Android that reimagines the traditional home screen as a physical workspace. Inspired by the classic "BumpTop" desktop metaphor, it treats applications, widgets, and notes as physical objects that can be moved, stacked, pinned to walls, and interacted with in a natural way.

• Physics-Based Workspace: Objects collide, bounce, and have "weight". Move items naturally around the room.
• Surface Organization: Use the floor for active work and walls for pinning important apps or widgets.
• Smart Piles: Gather items into piles by "lassoing" them. Piles can be fanned out for quick scanning or expanded into an organized grid.
• Immersive Widgets: Android widgets are rendered as 3D panels. Interact with them directly in the 3D scene.
• Recent Tasks Carousel: A dedicated 3D view on the back wall showing live snapshots of your recently used applications.
• Dynamic Themes & Procedural Shaders: Fully customizable workspace appearance. Themes like BumpDesk Animated feature real-time procedural caustics and underwater effects.
• SVG Vector Support: High-fidelity rendering across all surface textures and icons using sharp vector graphics.
• Contextual UI: Intuitive radial menus provide quick access to advanced launch modes (Freeform, Pinned, Fullscreen) and item properties.

BumpDesk is in an Advanced Beta state.

• Stability: High. Recent infrastructure refactors (VBOs, LRU Texture Caching, and Synchronized Concurrency) have significantly improved frame rates and memory reliability.
• Performance: Optimized for O(n log n) physics scaling and batched rendering.
• Persistence: Desktop layouts, widgets, and theme preferences are fully saved via Room DB.

The easiest way to try BumpDesk is to download the latest APK from the Releases page.

1. Download the app-debug.apk or signed app-release.apk from the latest release.
2. Install it via ADB:

   adb install app-debug.apk

3. Launch the app and follow the Onboarding Wizard.

Obtainium: For automatic updates from GitHub tags, add this repo in Obtainium and filter releases to app-release.apk. See docs/distribution.md for F-Droid vs Obtainium details.

If you are a developer and want to contribute or customize:

1. Open the project in Android Studio Koala (or newer).
2. Connect an Android device or emulator (Android 12+ recommended).
3. Run the :app:assembleDebug task to build the APK.
4. Deploy to your device using the Run button in Android Studio.

• Android device running Android 12 (API 31) or higher.
• Support for OpenGL ES 2.0.

For the best experience, several system-level settings should be configured via ADB:

1. Enable Usage Statistics (Required for Recent Apps):

   adb shell appops set com.bass.bumpdesk GET_USAGE_STATS allow

2. Enable Freeform Windowing (For "Open As > Freeform"):

   adb shell settings put global enable_freeform_support 1
   adb shell settings put global force_resizable_activities 1
   adb reboot

3. Grant Snapshot Permissions (Optional - Requires Root/AOSP Privileges): To see live app snapshots in the Recents carousel instead of icons:

   adb shell pm grant com.bass.bumpdesk android.permission.REAL_GET_TASKS

4. Wallpaper floor (Flat floor mode) — Android 13+ / Waydroid: Enabling Use system wallpaper as floor in Settings requests Photos and videos access first. That permission can be granted in the runtime dialog or in App Settings.

   On Android 13 and 14, the live system wallpaper API still checks legacy Storage (READ_EXTERNAL_STORAGE) at the system binder. Sideloaded builds cannot self-grant Storage from App Settings — use ADB (or pick the same image manually).

   # Grantable in App Settings as "Photos and videos" (Android 13+)
   adb shell pm grant com.bass.bumpdesk android.permission.READ_MEDIA_IMAGES
   
   # Live system wallpaper on API 33–34 (required on Waydroid; not shown in App Settings UI)
   adb shell pm grant com.bass.bumpdesk android.permission.READ_EXTERNAL_STORAGE

   Alternative: when prompted, choose Pick Image and select the same wallpaper from Photos — no legacy Storage grant needed.

   Filter wallpaper diagnostics in logcat:

   adb logcat -s "BumpDesk:Wallpaper"

   Log lines include permission state, e.g. READ_MEDIA_IMAGES=… READ_EXTERNAL_STORAGE=… canReadFile=….

BumpDesk is built using:

• OpenGL ES 2.0: For high-performance 3D rendering using Vertex Buffer Objects (VBOs).
• Custom Physics Engine: Optimized with Spatial Grid Partitioning for high item counts.
• Modular Shader Engine: Supports theme-local GLSL injection for custom procedural effects.
• Kotlin & Coroutines: For efficient thread-safe state management.
• Room Persistence: To save your desktop layout across reboots.

This project leverages a strict AI Workflow & Reward System:

• Test-First: Verification tests are created before major logic changes.
• Build-After-Edit: Automated builds verify every iteration to prevent regressions.
• Lead Developer Agent: The development is guided by an AI agent that maintains a detailed dev_plans.md and earning points for verified completions.

• BumpTop: This project is a spiritual successor to the original BumpTop software.
• BumpTop Open Source: Significant inspiration and logic references were drawn from the BumpTop Windows Source Code.
• Themes: Default assets and theme logic are designed to be compatible with legacy BumpTop theme formats.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.