kitty-gridlock/ReadMe.org

#+title: Kitty Gridlock

This is a project for V. She loves [[https://en.wikipedia.org/wiki/Rush_Hour_(board_game)][Rush Hour]] puzzles. For her birthday (April 2021), I have a goal to make a Rush Hour player for her Android phone, using my [[https://macoy.me/code/macoy/cakelisp/][Cakelisp]] and [[https://macoy.me/code/macoy/gamelib][GameLib]] tools.

I am using [[https://www.michaelfogleman.com/rush/][Michael Fogleman's Rush Hour database]] ([[https://web.archive.org/web/20201101044241/https://www.michaelfogleman.com/rush/][archive.org]]) in order to provide her tons of puzzles.

* Setup
** Linux
Clone the repository and its dependencies:
#+BEGIN_SRC sh
git clone https://macoy.me/code/macoy/kitty-gridlock.git
git submodule update --init --recursive
#+END_SRC

Build:
#+BEGIN_SRC sh
./Build.sh
#+END_SRC
** Android
See [[file:Dependencies/gamelib/Dependencies/SDL/docs/README-android.md][SDL's README-android.md]] for instructions I followed for setting up Android. You need to download Android Studio. (You could get away with only the SDK and build tools, but you'll probably want the debugger when things don't work out of the box anyways.)

*** Building
Run ~Setup_Android.sh~ to create the proper files and symlink to SDL.

Then, run ~Build_Android.sh~. This will fail if you don't have an Android device connected via USB (and in Developer mode). Once it succeeds, the connected Android device will have Kitty Gridlock installed!

You can also open Android Studio, browsed to the Android directory, and hit Debug, Run, etc.
*** Per-user setup
Open ~Android/local.properties~ and set these variables to the ones you have set up (mine, for reference):
#+BEGIN_SRC properties
sdk.dir=/home/macoy/Android/Sdk
ndk.dir=/home/macoy/Android/Sdk/ndk/21.4.7075529
#+END_SRC
Follow SDL Readme, get NDK from SDK Manager, etc.
*** Known working version(s)
My local build was tested the following software versions:

| Component       | Version           |
|-----------------+-------------------|
| Android         | 10                |
| SDK Build-Tools | 29.03, 28.03, 26¹ |
| NDK             | 21.4.7075529²     |
¹= I'm not actually sure which SDK version is being used, because I didn't explicitly specify one.

²= I had to downgrade from version 22 due to ~platforms~ folder missing. See below section.
*** Fix ~SDL_main()~ not found in ~libmain.so~ error
- Ensure you have ~main()~ defined *with* its full signature: ~int main(int numArgs, char* args[])~
- Note that SDL defines ~main()~ as a macro to be ~SDL_main()~, which is a bit confusing, but works okay as long as you have the full signature
*** Fix no ~platforms~ folder in NDK
I had to downgrade from version 22 due to ~platforms~ folder missing. To do so:
- Open Android Studio
- ~Tools -> SDK Manager~
- Switch to tab ~SDK Tools~
- Check ~Show Package Details~
- Expand the NDK tree and check ~21.4.7075529~, then click OK
*** Building from the command line
Follow the [[file:Dependencies/gamelib/Dependencies/SDL/docs/README-android.md][SDL README-android.md]] for using ~androidbuild.sh~, which is how I got the first version going. For reference, here is the command sequence:
#+BEGIN_SRC sh
cd Dependencies/gamelib/Dependencies/SDL/build-scripts

export ANDROID_HOME=/home/macoy/Android/Sdk
export ANDROID_NDK_HOME=/home/macoy/Android/Sdk/ndk/21.4.7075529/

./androidbuild.sh org.libsdl.testgles ../test/testgles.c

cd ../build/org.libsdl.testgles
# Note: This will only succeed if you have an Android device plugged in to USB, with Developer mode enabled
./gradlew installDebug
#+END_SRC

All I had to do for my project was copy some files as the Readme instructs, then edit ~SDL/build/org.libsdl.testgles/app/jni/src/Android.mk~, to add the files and flags, e.g.:
#+BEGIN_SRC makefile
# Work around "bug" in cakelisp where there are extraneous parens
LOCAL_CFLAGS += -Wno-parentheses-equality

# Copied straight from cakelisp_cache
LOCAL_SRC_FILES := Main.cake.cpp Math.cake.cpp SDL.cake.cpp
#+END_SRC
*** Fix Android Studio not knowing how to build/debug project
Click ~File -> Sync Project files with Gradle files~.
* Target device
V has a OnePlus 6T Android phone with the following specifications (from [[https://www.gsmarena.com/oneplus_6t-9350.php][here]]):

| Thing              | Value                                                           |
|--------------------+-----------------------------------------------------------------|
| Display Type       | Optic AMOLED                                                    |
| Display Size       | 6.41 inches, 100.9 cm2                                          |
| Display Resolution | 1080 x 2340 pixels, 19.5:9 ratio (~402 ppi density)             |
| CPU Chipset        | Qualcomm SDM845 Snapdragon 845 (10 nm)                          |
| CPU                | Octa-core (4x2.8 GHz Kryo 385 Gold & 4x1.7 GHz Kryo 385 Silver) |
| GPU                | Adreno 630                                                      |
| RAM                | 8GB                                                             |
| Android Version    | 10                                                              |

The two main specs I need to care about are Android Version and Display Resolution. Additionally, AMOLED hints that pure black is going to look nice.
* Database format
/(The following text is copied from  [[https://www.michaelfogleman.com/rush/][Michael Fogleman's Rush Hour database]] ([[https://web.archive.org/web/20201101044241/https://www.michaelfogleman.com/rush/][archive.org]]), for easier reference)/
#+BEGIN_QUOTE
The database is a simple text file with just a few columns. There is one row for every valid (solvable, minimal) cluster. The columns are: number of moves, board description, and cluster size (number of reachable states).

The board description is a 36-character string representing the state of the unsolved board. It is a 6x6 2D array in row-major order. The characters in the description follow these simple rules:

- o empty cell
- x wall (fixed obstacle)
- A primary piece (red car)
- B - Z all other pieces

I used lowercase ~o~ instead of periods ~.~ for the empty cells in the database so that the entire board description can be selected with a double-click.
#+END_QUOTE

An example board:
#+BEGIN_SRC C
60 IBBxooIooLDDJAALooJoKEEMFFKooMGGHHHM 2332
#+END_SRC
* Licensing and 3rd party
Kitty Gridlock is copyright (C) 2021 Macoy Madson. Licensed under ~GPL-3.0-or-later~. Art made by Macoy and V.

Kitty Gridlock uses the following 3rd-party code:
- [[http://libsdl.org/][SDL2]], [[https://www.libsdl.org/license.php][Zlib license]]
- [[https://github.com/HandmadeMath/Handmade-Math][Handmade Math]], public domain

During build time only:
- [[http://www.landley.net/code/][bunzip]] by Rob Landley, under LGPL v2
- [[https://www.michaelfogleman.com/rush/][Michael Fogleman's Rush Hour database]] is used to generate a list of puzzles. The code to generate the database is MIT Licensed, but the database itself is ambiguously licensed as far as I can tell (which I should reach out and get clarification on, but have yet to do so)

Kitty Gridlock is built atop my [[https://macoy.me/code/macoy/cakelisp/][Cakelisp]] and [[https://macoy.me/code/macoy/gamelib][GameLib]] tools, both ~GPL-3.0-or-later~.