8-Puzzle (Sliding Puzzle)

8-Puzzle is a sliding puzzle game that features a walkthrough of the optimal solution and allows users to customize the tiles using photos selected from their Gallery. In finding the optimal path from the current puzzle state to the goal state, the system employs the informed search algorithm A* and uses Manhattan distance as an admissible and consistent heuristic to estimate the cost.

Inspired by an exercise in our Mobile Development class, I started creating this app during our university break, after finishing my second year of undergraduate studies. As one of my first personal projects, working on this was an opportunity to synthesize concepts and practices that I learned from our sophomore courses, such as:

Exploration of language features (Advanced Programming and Theory of Programming Languages)
Program optimization (Algorithms and Complexity)
Artificial intelligence and search algorithms (Introduction to Intelligent Systems)
Quality assurance and unit testing (Introduction to Software Engineering)

This project also utilizes a continuous integration/continuous delivery (CI/CD) pipeline — which is the focus of our third-year class Advanced Software Engineering.

The API documentation can be viewed at https://memgonzales.github.io/sliding-puzzle/

Project Structure

The project consists of the following folders:

Folder	Description
`.github`	Contains the YML files defining the workflows that are included in the CI/CD pipeline
`.idea`	Contains files used by Android Studio to load project-specific configurations
`app`	Contains all the source code and resource files, the markdown file for the app- and package-level documentation, and files defining the module-specific dependencies, project-specific ProGuard rules, and developer credentials related to Google services
`gradle`	Contains files used by Gradle to run build automation tasks

Several Gradle-related files are also included in its root directory.

Running the Application

The minimum SDK supported is Android Lollipop (API Level 21), and the target SDK is Android 11 (API Level 30).

Using the APK

Download and install the APK file from the latest release. You may have to modify the security settings of your device to allow the installation of third-party apps from unknown sources.

Using the Source Code

Create a copy of this repository:
- If git is installed, type the following command on the terminal:
```
git clone https://github.com/memgonzales/sliding-puzzle
```
- If git is not installed, click the green Code button near the top right of the repository and choose Download ZIP. Once the zipped folder has been downloaded, extract its contents.
Run the app using Android Studio (or any IDE that supports Android development). Alternatively, Android also provides a guide on how to build the app from the command line.

Dependencies

This project uses the following project dependencies:

Dependency	Version	Description	License
`com.android.tools.build:gradle`	4.2.2	Gradle build automation tool	Apache License 2.0
`org.jetbrains.kotlin:kotlin-gradle-plugin`	1.5.0	Gradle plugin for Kotlin/JVM compilation tasks	Apache License 2.0
`org.jetbrains.dokka:dokka-gradle-plugin`	1.5.0	Gradle plugin for Dokka documentation engine	Apache License 2.0
`com.google.gms:google-services`	4.3.10	Plugin for processing the `google-servies.json` file	Apache License 2.0

It also uses the following module-specific dependencies:

Dependency	Version	Description	License
`org.jetbrains.kotlin:kotlin-stdlib`	1.5.0	Kotlin standard library for JVM	Apache License 2.0
`androidx.core:core-ktx`	1.6.0	Core module providing Kotlin extensions for common framework APIs and several domain-specific extensions	Apache License 2.0
`androidx.appcompat:appcompat`	1.3.1.	Library allowing access to new APIs on older API versions of the platform	Apache License 2.0
`com.google.android.material:material`	1.4.0	Library for using APIs that provide implementations of the Material Design specification	Apache License 2.0
`androidx.constraintlayout:constraintlayout`	2.1.1	Library for positioning and sizing widgets in a flexible way with relative positioning	Apache License 2.0
`junit:junit`	4.13.2	Unit testing framework for Java	Eclipse Public License 1.0
`androidx.test.ext:junit`	1.1.3	AndroidX unit testing framework for Java	Eclipse Public License 1.0 Apache License 2.0
`androidx.test.espresso:espresso-core`	3.4.0	Framework for writing Android user interface tests	Apache License 2.0

The descriptions are taken from their respective websites.

Built Using

This project uses the following languages and technologies:

Logic: Kotlin, a statically typed language endorsed by Google as the preferred language for Android development
Layouts: XML, a lightweight markup language that is both human- and machine-readable

GitHub Actions serves as the CI/CD platform for automating these workflows (triggered by a push or pull request):

Linting, testing, and building the APK
Generating the HTML version of the API documentation from KDoc comments via Dokka
Publishing the API documentation with GitHub Pages

Author

Mark Edward M. Gonzales
mark_gonzales@dlsu.edu.ph
gonzales.markedward@gmail.com

Assets (such as images and XML resource files) are properties of their respective owners. Attribution is found in the credits file. Technical references used in the implementation of algorithms are cited in the API documentation of the pertinent methods.

memgonzales/sliding-puzzle