ANDROID / ARM64 ENGINEERING NOTES
A mouse-and-keyboard game needs more than new button bindings on a handheld. Explore the control, text-entry and audio decisions behind the port.
Choose a topic below. The repository contains the full development records and their technical context.
01 / PRACTICAL LESSONS
Entries retain their repository identifiers. Historical experiments are labelled separately from the stable release.
KB-SS-001 / Automation
A launch helper used names that differed only by case. PowerShell treated them as the same variable and corrupted the launch component.
Use distinct variable names. Separate launcher failures from faults in the game or build.
KB-SS-002 / Android lifecycle
Android overlays can take focus or change the SDL surface during startup. A disappearing surface therefore needs lifecycle and focus diagnostics.
Check which component owns the surface before redesigning rendering code.
KB-SS-003 / Audio
Raw SDL audio and SDL_mixer competed for the same physical device. The Android design routes music, effects and other streams through one mixer-owned device.
Share the mixer instead of opening a separate device for each subsystem.
KB-SS-004 / Text input
Player-name fields use the Android keyboard through SDL text input. Committed characters arrive through SDL_TEXTINPUT; navigation and editing keys keep their own path.
Avoid reconstructing text from controller events. Diagnostics record state and counts, not the entered name.
KB-SS-005 / Controls
The right stick controls camera look by default. View/Select switches to a fine cursor for the original mouse-oriented interface. Touch is optional.
Preserve both interaction modes instead of forcing one control model onto every task.
KB-SS-006 / Music timing
After a scheduling delay, overdue XMI events could play in a rapid burst. The Android timing path uses a monotonic clock and shifts active layer origins together.
Rebase delayed playback rather than replaying the delay at maximum speed. The subsequent manual music check passed.
KB-SS-007 / Presentation
Version 1.0.0 presents the game at 1024×768 in 4:3 without stretching. The widescreen prototype was not selected.
Choose presentation against the preservation goal, not simply because another layout is technically possible.
KB-SS-008 / Historical research
The renderer uses indexed colours. Scale4x can select existing palette colours; bicubic scaling creates intermediate colours that need quantisation.
Judge an image in the renderer that must display it. The HD experiments are outside version 1.0.0.
KB-SS-009 / Resource identity
A resource reference can recur in separate files. Matching therefore needs the relevant file or namespace, plus type and geometry where required.
Check where an identifier is unique before using it as a global key. Ambiguous matches retain original resources.
KB-SS-010 / Build checks
The verifier checks package identity, architecture, native libraries, signing and obvious embedded commercial data. Device behaviour is tested separately.
Match each check to its purpose: producing an APK does not test its controls, image or sound.
KB-SS-011 / Dependency setup
The first clean pre-release bootstrap cloned SDL_mixer with --no-tags, then tried to check out release-2.8.1. The tag was unavailable locally.
The helper now fetches unresolved tags explicitly. A fresh v0.1.0-pre.2 checkout completed dependency bootstrap without an existing cache.
KB-SS-012 / Preservation scope
Version 1.0.0 retains original content and 4:3 presentation. Android-specific work covers access, input, audio, data import and release operation.
Keep HD, widescreen and font experiments separate from the preservation release. A full Retroid Pocket 5 playthrough was accepted before release.
Read the full knowledge records · Follow the development history
02 / GAME-DATA IMPORT
The early data-copy process needed Android debugging tools. A normal signed APK needed a user-facing installation path.
The importer opens Android's folder picker. Players select their own compatible res folder; the app copies it into private storage.
A staging directory keeps incomplete copies separate. If activation fails, the importer attempts to restore the previous data.
The pre-release test copied 56 data files and 96 sound files. Its separate non-debuggable QA package launched the game and passed the recorded smoke check.
The test installation was then removed without changing the baseline installation.
REL-SS-004: importer record · Folder layout and import process
03 / REUSE THE LESSONS
Check the platform, source revision and test conditions before adapting a change. Use a separate working copy and retain the earlier result for comparison.
Keep ownership clear: Android manages the physical surface, one mixer owns the audio device, and committed text follows the text-input path.
Build checks and hands-on testing answer different questions. Record what was exercised and what remains untested.
04 / OPEN QUESTIONS
Retroid Pocket 5 is the tested reference device. Other Android 13+ ARM64 devices still need their own control, display, audio and installation checks.
HD graphics and font work are historical research, not pending features of version 1.0.0. That font research covered 36 fonts and 5,696 glyphs.
05 / CONTRIBUTE
Report the device, Android version, release and steps used. Mark unchecked behaviour as “not tested”.
For a documentation correction, include the article ID and the unclear passage. Do not attach commercial game data or personal information.