109 lines
3.9 KiB
Markdown
109 lines
3.9 KiB
Markdown
# GitHug Android
|
|
|
|
Native Android adaptation of the GitHug learning game, built with **Kotlin + Jetpack Compose** and designed for **mobile-first usability** while preserving a **CLI-first play style**.
|
|
|
|
## Current MVP scope
|
|
|
|
This repository contains a starter Android app with:
|
|
|
|
- Kotlin + Jetpack Compose project scaffolding
|
|
- CLI-first gameplay shell
|
|
- Optional hideable visualization panel
|
|
- A native-Git runtime scaffold with in-memory fallback while no bundled Git binary is present
|
|
- Full official Githug level catalog, split into dedicated Kotlin level files
|
|
|
|
## Product direction
|
|
|
|
The app supports three modes:
|
|
|
|
- **CLI ONLY**: hide all visualization and play with terminal-style input only
|
|
- **HYBRID**: command line with optional repo panels
|
|
- **VISUAL**: repo panels visible by default, still backed by the same command engine
|
|
|
|
## Building
|
|
|
|
You will need a local Android SDK installation and either Android Studio or SDK command line tools.
|
|
|
|
Typical next step once the SDK is installed:
|
|
|
|
```bash
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
## Android project tooling
|
|
|
|
This repo includes a root-level tooling script:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh
|
|
```
|
|
|
|
It is designed to be idempotent and uses project-relative paths to:
|
|
|
|
- install a project-local JDK into `./jdk`
|
|
- install Android command-line tools into `./android-sdk`
|
|
- restore `gradle/wrapper/gradle-wrapper.jar` if missing
|
|
- install required Android SDK packages
|
|
- write `local.properties`
|
|
|
|
To also build the debug APK without leaving Gradle running in the background:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --build
|
|
```
|
|
|
|
The script and project are configured to prefer non-daemon Gradle usage.
|
|
|
|
It also avoids depending on the system Java version by provisioning a project-local **JDK 17**, which is required by current Android SDK command-line tools.
|
|
|
|
To avoid repeated expensive SDK verification, the script writes a small state file named:
|
|
|
|
`./.android-project-tooling.state`
|
|
|
|
If all required components were verified successfully, the script will skip SDK verification/reinstallation for the next **24 hours** unless required directories are missing.
|
|
|
|
When you run:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --build
|
|
```
|
|
|
|
the script will also attempt to create a **git commit after a successful build** if there are source changes to commit.
|
|
|
|
It will also automatically bump the Android app version in `app/build.gradle.kts` before each build by:
|
|
|
|
- incrementing `versionCode` by 1
|
|
- incrementing the patch component of `versionName` (for example `0.1.0` → `0.1.1`)
|
|
|
|
To run the JVM unit test suite after ensuring the local toolchain is ready:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --test
|
|
```
|
|
|
|
## Native Git prototype status
|
|
|
|
The app now includes a **filesystem-backed runtime scaffold** for moving from the custom Kotlin Git emulator toward a real native Git backend.
|
|
|
|
Current prototype behavior:
|
|
|
|
- the app prepares per-level sandbox directories in app-private storage
|
|
- terminal commands are routed through a runtime abstraction instead of directly calling the old in-memory engine
|
|
- if a bundled native Git binary is available at runtime, Git commands are executed against a real repository sandbox
|
|
- if no bundled native Git binary is present yet, the app automatically falls back to the existing in-memory sandbox so development can continue
|
|
|
|
Planned native Git packaging path:
|
|
|
|
- cross-compile Git for Android ABIs with the NDK
|
|
- bundle one binary payload per ABI
|
|
- extract the correct executable into app-private storage on first launch
|
|
- keep helper shell-like commands (`ls`, `pwd`, `cat`, `touch`, `mkdir`, `rm`, `echo`) implemented in Kotlin
|
|
|
|
## Next steps toward full GitHug parity
|
|
|
|
- Replace the fallback in-memory Git engine with a packaged native Git binary
|
|
- Tighten advanced real repository-backed validation across the full Githug catalog
|
|
- Continue refining per-level setup fidelity for the remaining advanced scenarios
|
|
- Add richer validation rules and per-level explanations
|
|
- Add onboarding, accessibility polish, icons, tests, and Play Store assets
|