An open-source lower-screen game assistant built for AYN Thor.

Download Alpha · Setup Guide · 简体中文设置指南 · Report an issue

English | 简体中文

Heimdall keeps the game on Thor's upper screen while the lower screen becomes a persistent control and reference console: Profiles, macros, touch controls, translation, hardware status, maps, guides, local-media Canvases, Portals, recording, and Quick Actions stay within thumb reach.

Alpha software: Heimdall targets AYN Thor. Compatibility is not guaranteed for every Thor firmware, controller mode, game, emulator, or other dual-screen device.

Active play: Precision Aim and circular magnification	Profile controls: Portal, touchpad, and Macros
Reference: a local Guide without covering the game	Execution: Canvas move list and structured Macros

Play view: controls stay glanceable on the lower screen	Edit view: drag modules and resize from visible corners

Installing Heimdall does not require root or Developer options. Developer options are needed only if you want to start Shizuku for advanced controller features.

You do not need to enable every permission during first launch. Start with one Profile and one route, test it, then add features as needed.

1. Open the Heimdall Releases page.
2. Open the newest versioned Alpha release.
3. Download the file named like heimdall-vX.Y.Z-alpha.N.apk. The same release also includes SHA256SUMS.txt for file verification.
4. Open the APK with Thor's file manager.
5. If Android asks, allow that file manager to install unknown apps, return to the installer, and finish installation.
6. Open Heimdall.

Install only immutable, versioned releases from this repository. The mutable private-development debug-latest channel is not a public release, and re-signed APKs from unknown sources should not be trusted.

Official Alpha updates signed with the same release identity can normally install over the previous public Alpha. Do not uninstall first unless the release notes explicitly require it: uninstalling removes local Profile data and imported assets.

Older test packages and new Debug builds may be separate Apps and do not share data with the public package com.mastercook777.heimdall.

Before moving from an older test build:

1. Open Profile management in the old build.
2. Export all Profiles and keep the exported file somewhere easy to find.
3. Install and open the public Alpha.
4. Re-authorize the services you use.
5. Import the exported file and confirm the important Profiles before deleting the old build or backup.

Older builds export configuration-only JSON, which remains importable but cannot recover missing external assets. Current builds export a self-contained .heimdall-profile bundle containing Profile data plus supported Profile icons, maps, file Guides, user Macro icons, and Canvas media.

1. Open Settings > Profile management.
2. Create a Profile for one game or emulator.
3. Start the target App on the upper screen, then bind it from Heimdall's recent-App selector.
4. Choose a Grid preset. Balanced is the easiest starting point; Controls reserves more room for touch controls, and Macros shows more actions.
5. Add only the modules you want now.
6. Tap Save at the bottom of Settings.
7. Switch back to the game and confirm Heimdall selects the expected Profile.

Save boundary: Grid and several Profile settings use preview/draft state. Seeing the preview does not mean it has been stored; save before leaving the editor or Settings.

Basic Touch sends compatible taps, holds, swipes, and touchpad drags to the upper screen through Android Accessibility. It does not require Shizuku or Developer options.

1. Open Settings > Connections in Heimdall.
2. Choose Basic Touch and tap its enable action.
3. In Android Accessibility settings, find Heimdall, read the system warning, and enable the service.
4. Return to Heimdall and confirm Basic Touch is available.
5. Test one simple tap macro or touchpad movement before building a longer macro.

Basic Accessibility touch and Thor's built-in mapper use separate touch streams and may cancel each other when used simultaneously. If coexistence is required, use the mapping-compatible Enhanced Touch route only when Heimdall reports it as available.

Shizuku is needed for physical-controller recording/replay, Virtual Right Stick, Precision Aim, and mapping-compatible Enhanced Touch. Heimdall does not require root.

• Shizuku official releases
• Shizuku official setup guide

Android menu names can vary slightly by Thor firmware. If a named page is hard to find, use the search box in Android Settings for Build number, Developer options, or Wireless debugging.

1. Open Thor's Android Settings.
2. Open About device, About handheld, or a similarly named page.
3. Find Build number. On some firmware it may be inside a software/version details page.
4. Tap Build number seven times.
5. Enter the screen-lock PIN if Android asks. A message should confirm that Developer options are enabled.
6. Go back to System > Developer options, or search Settings for Developer options.
7. Enable USB debugging.
8. Open Wireless debugging and turn it on.

Developer options are now available. You normally do not need to repeat these eight steps.

1. Install and open Shizuku.
2. Choose Start via wireless debugging, then start pairing.
3. Return to Android's Wireless debugging page.
4. Choose Pair device with pairing code.
5. Enter the displayed code in Shizuku's notification or pairing screen.
6. Return to Shizuku, tap Start, and wait for it to report that Shizuku is running.
7. Open Heimdall > Settings > Connections > Advanced Controls.
8. Tap the authorize/connect action and allow Heimdall in the Shizuku permission dialog.
9. Return to Heimdall and confirm Advanced Controls are available.

After restarting Thor, check Shizuku before using controller features. If it is no longer running, start it again; pairing normally does not need to be repeated.

If Shizuku stays on "Searching for pairing service," allow it to run in the background, enable its notifications, keep local networking and wireless debugging available, and try turning wireless debugging off and on once. See the official Shizuku troubleshooting guide for current platform-specific advice.

Open the visual Grid editor to add, drag, resize, or remove modules. Modules snap to the 12 x 8 Grid. Preview first, then save the Grid and Profile explicitly. Layouts from earlier Alpha releases migrate forward; review the result before saving further edits.

1. Add a Macro module to the Grid.
2. Hold a Macro button for about 1.8 seconds to open the structured editor.
3. Add tap, hold, swipe, or wait steps.
4. When capturing coordinates, act directly on the upper-screen target.
5. Save the Macro, return to Main, and tap the button to run it.

Controller recording and replay require Shizuku and an available Advanced Controls route. Thor's built-in mapper may hide already-mapped physical buttons from Heimdall's recording stream. If this happens, begin recording, temporarily return to Android Home to press the button, then return to Heimdall to review and save the sequence.

Enhanced Touch protects Thor's built-in mapping by default and rejects Macros containing physical-controller steps before replay. If the mapper is off, you may disable that protection for the current Profile; screen steps still use the strict mapping-compatible touch route and never fall back to Accessibility.

• Touch drag converts lower-screen finger movement into an upper-screen drag.
• Virtual Right Stick emits Thor right-stick input through Advanced Controls and should return to neutral immediately after release.
• Precision Aim is for small camera corrections. Start with low sensitivity and keep the physical stick for large turns.

• Add up to two Portals to a Profile's Grid. Each Portal has its own upper-screen region, zoom, shape, frame rate, and View Only or Interactive mode. Both share one screen-capture session. Interactive mode sends one-finger input through the available Shizuku Enhanced Touch route; only one Portal gesture can be active at a time. Portal and screen recording cannot run together. Choose the region in Portal Settings, then press Save; Grid placement has its own Save.
• Open Community Profiles from Profile management to browse the curated catalog. A download is checked against its catalog size and SHA-256, validated as a .heimdall-profile bundle, and imported as a new Profile. Existing Profiles are not replaced. The catalog and bundles come from the community repository.
• Maps and guides belong to the current Profile and may reference local images, PDFs, text, or an Interactive Map URL.
• Canvas accepts local JPG, PNG, GIF, WebP, and MP4 media. GIF and animated WebP require Android 9 or newer; MP4 is always muted and loops. A Profile can contain multiple independent static Canvases, while GIF, animated WebP, and MP4 share a limit of one dynamic Canvas. Files are limited to 50 MiB; images may be up to 4096 × 4096 and MP4 video up to 2048px on its longest side. APNG is not supported. Double-tap a Canvas for full-screen viewing and hold it to replace its media or adjust composition.

• Add one Translation module to a Profile, hold it to choose the upper-screen region, OCR script, and target language, then save the component. The runtime region shortcut commits only the confirmed region; it does not save unrelated Grid placement changes.
• Translation uses Heimdall Accessibility screenshots and bundled on-device ML Kit OCR. It does not acquire MediaProjection. Only recognized text is sent over HTTPS to the configured SiliconFlow or custom OpenAI-compatible /chat/completions endpoint.
• Provider settings and the API key are App-global. The API key is encrypted with Android Keystore and is not included in Profile JSON or .heimdall-profile exports.
• Test connection checks the current Settings draft. Press the Settings footer Save after a successful test to make that provider configuration active.
• Add one Hardware Monitor per Profile to show CPU temperature and used/total RAM. It needs no Shizuku permission and shows unavailable rather than guessing when Thor's verified CPU sensor cannot be read uniquely.

Choose a registered Heimdall or Freya colorway under Appearance. A Profile can use its own saved theme or follow the App default. The experimental Match joystick lighting switch is App-global and off by default; on supported Thor firmware it applies the resolved theme color and one shared brightness to both joystick rings. Heimdall does not use Shizuku, root, polling, animation, or game events for this feature, and theme changes remain usable if the firmware lighting call is unavailable.

Quick Actions can capture the upper screen. Recording uses Android MediaProjection and Android Audio Playback Capture rather than microphone input. The upper App may still forbid its game audio from being captured.

Use Profile management to export the current Profile or all Profiles after completing an important layout or Macro setup. The .heimdall-profile bundle is self-contained for supported Profile-owned assets and is validated before import. Heimdall also keeps bounded recovery snapshots for some destructive Profile changes, but these do not replace an export stored outside the App. See the Profile bundle format.

Android platform backup is disabled for this Alpha. Uninstalling the App removes its local data.

• Android streaming clients do not reliably forward external Meta/Win input from Heimdall's uinput keyboard. Full Keyboard shows disabled Win keys and Keypad does not offer Win bindings; use the streaming client's built-in keyboard when Win is required.
• Mapping-compatible Shizuku Touch is verified only on tested Thor firmware, game, and mapper combinations. Other firmware may report it unavailable.
• Basic Accessibility touch and Thor's built-in mapper may cancel each other during simultaneous operation.
• Thor's mapper may hide mapped controller buttons from the Macro recorder.
• A Profile supports at most two live Portals. Interactive input is one finger and one active Portal gesture at a time. Portals cannot share MediaProjection with recording.
• After a lower-screen Tab round trip, a frozen Portal's Stop marker can occasionally be missing; stopping can also leave the final retained frame visible. These are known presentation-state issues, not proof that the frame is still live.
• Translation quality, latency, and service availability depend on the selected OCR script, network, model, and provider. SiliconFlow China with Hunyuan-MT-7B is the owner-tested route; other listed or custom OpenAI-compatible endpoints are protocol-compatible but not all are Thor-validated.
• Hardware Monitor reports CPU temperature only when Thor exposes one unique readable cpu-0-1 thermal source to the ordinary App process. It intentionally does not substitute battery temperature or estimate fan speed.
• Theme-matched joystick lighting remains optional and off by default. It uses the Thor stock-lighting protocol; if firmware behavior differs, use Thor's system lighting controls to restore or disable the lights.

Read the v0.4.0-alpha.1 release notes for the new scope and known limitations. The visually reviewed 0.2.0 English and Simplified-Chinese PDF guides remain archived references; this README is the current setup guide.

Use GitHub Issues and include:

• Heimdall version and Thor firmware version.
• Controller mode: native or Xbox.
• Game or emulator name.
• Active route: Basic Touch or Shizuku.
• Whether Thor's built-in mapper is enabled.
• Exact reproduction steps and frequency.
• Screenshot or recording when possible.
• Whether restarting Heimdall, restarting Shizuku, or re-authorizing changes the result.

./gradlew :assistant:assembleDebug --no-daemon

./gradlew :assistant:lintDebug --no-daemon

Profile data stays on the device unless the player explicitly imports or exports it. Internet access is used for player-configured Interactive Map pages and optional Translation requests. Translation OCR runs locally, but recognized text is sent to the provider selected by the player. See docs/PRIVACY.md.

Read CONTRIBUTING.md before submitting a change. Native input, cross-display routing, MediaProjection, performance, and physical ergonomics require clearly scoped AYN Thor evidence.

Heimdall source is licensed under the Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.

AYN and Thor are trademarks of their respective owner. Heimdall is a community project and is not presented as an official AYN application.