A library made in kotlin for native android that exposes a view for a virtual joystick. Customizable and simple to use.
To use the library you can install it from github packages or locally. But before installation, make sure that your project meets the requirements.
- Android minSdk >= 21
- Android minCompileSdk >= 21
- Inside you GitHub account:
- Settings -> Developer Settings -> Personal Access Tokens -> Generate new token
- Make sure you select the following scopes ("read:packages") and Generate a token
- After Generating make sure to copy your new personal access token. You won’t be able to see it again!
- Create a github.properties file within your root Android project
- In case of a public repository make sure you add this file to .gitignore for keep the token private
- Add properties gpr.usr=GITHUB_USERID and gpr.key=PERSONAL_ACCESS_TOKEN
- Replace GITHUB_USERID with personal / organisation Github User ID and PERSONAL_ACCESS_TOKEN with the token generated in #Step 1
Alternatively you can also add the GPR_USER and GPR_API_KEY values to your environment variables on you local machine or build server to avoid creating a github properties file
-
KTS
Load you credentials before apply it after the pluginManagement config.
pluginManagement { // ..... } // .... val githubPropertiesFile: File = rootProject.projectDir.resolve("github.properties"); val githubProperties = Properties() githubProperties.load(FileInputStream(githubPropertiesFile)) // .....Add a new repository inside the dependencyResolutionManagement config.
// ...... dependencyResolutionManagement { // ...... repositories { // ...... maven { name = "GitHubPackages" url = uri("https://maven.pkg.github.com/yoimerdr/AndroidVirtualJoystick") credentials { username = githubProperties.getProperty("gpr.usr") ?: System.getenv("GPR_USER") password = githubProperties.getProperty("gpr.key") ?: System.getenv("GPR_API_KEY") } } } }
You can read more about how to install a github packages library with KTS here
-
Groovy
Load you credentials before apply it after the pluginManagement config.
// .... pluginManagement { // ..... } // .... def githubPropertiesFile = Paths.get(rootProject.projectDir.toString(), "github.properties").toFile() def githubProperties = new Properties() githubProperties.load(new FileInputStream(githubPropertiesFile)) // .....
Add a new repository inside the dependencyResolutionManagement config.
// ...... dependencyResolutionManagement { // ...... repositories { // ...... maven { name = "GitHubPackages" url = uri("https://maven.pkg.github.com/yoimerdr/AndroidVirtualJoystick") credentials { username = githubProperties['gpr.usr'] ?: System.getenv("GPR_USER") password = githubProperties['gpr.key'] ?: System.getenv("GPR_API_KEY") } } } }
You can read more about how to install a github packages library with groovy here
-
-
KTS
// .... dependencies { // .... implementation("com.yoimerdr.android:virtualjoystick:1.0.0") }
-
Groovy
// .... dependencies { // .... implementation("com.yoimerdr.android:virtualjoystick:1.0.0") }
- You can see all the releases here
- After downloading the package, unzip it to the libs folder of the application module. The path is usually: path_to_project/app/libs.
- KTS
// .... dependencies { // .... implementation(files("libs/yoimerdr/android/virtualjoystick/1.0.0/virtualjoystick-1.0.0.aar")) }
- Groovy
You can read a litter more about how to install an aar library here
// .... dependencies { // .... implementation files('libs/yoimerdr/android/virtualjoystick/1.0.0/virtualjoystick-1.0.0.aar') }
After installing the package, you can use it by adding the JoystickView view to the layout of your activity or view.
<!--.........-->
<com.yoimerdr.android.virtualjoystick.views.JoystickView
android:id="@+id/vJoystick"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_marginStart="16dp"
android:layout_marginBottom="16dp"
app:arcControlDrawer_sweepAngle="100"
app:controlDrawer_accentColor="#FFFFFF"
app:controlDrawer_primaryColor="#FF0000"
app:controlType="circle"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintStart_toStartOf="parent" />
<!--.........-->And use it.
- Kotlin
// ....
val joystick = findViewById<JoystickView>(R.id.vJoystick)
joystick.setMoveListener {
}
// ....If you use the JoystickView view in a layout (xml), you could place values to some attributes that the view uses
-
background
Is a reference to a drawable resource that the view will use as background.
-
moveInterval
It is an interval (integer) of time (ms) for which passed, to consider the touch on the joystick as maintained. For now, it has a bad name, it will be changed in future versions.
-
invalidRadius
It is a dimension value to be taken into account when obtaining control direction. In other words, if the distance between the touch made by the user and the center of the JoystickView does not exceed this value, the joystick direction is considered as NONE.
-
controlType
It is an enum that determines that the already defined ControlDrawer will be used as the initial drawer of the joystick. For now, it can be any of the following values:
-
arc
The drawer to be used will be CircleControlDrawer
-
arc
The drawer to be used will be ArcControlDrawer
-
circe_arc
The drawer to be used will be CircleArcControlDrawer
-
-
directionType It is an enum that determines how many directions the joystick will be able to pass to its listener. For now, it can be any of the following values:
-
complete
The directions that the joystick will be able to pass, apart from NONE, are UP, UP_LEFT, UP_RIGHT, DOWN, DOW_LEFT, DOWN_RIGHT, LEFT and RIGHT
-
simple The directions that the joystick will be able to pass, apart from NONE, are UP, DOWN, LEFT and RIGHT
-
-
controlDrawer_primaryColor
A reference to a color that the initial drawer will use as the primary color.
-
controlDrawer_accentColor
A reference to a color that the initial drawer will use as the accent color.
-
arcControlDrawer_sweepAngle
It is a float value that will determine, if the initial drawer is of type arc or circle_arc, what sweep angle the arc will make.
-
arcControlDrawer_strokeWidth
It is a float value that will determine, if the initial drawer is of type arc or circle_arc, how wide the arc will be.
-
circleControlDrawer_radiusProportion
It is a floating value that will determine what proportion of the JoystickView radius to take as the radius of the circle to draw.
To know more about the ControlDrawer's, joystick direction and other library stuff, you can read the latest library docs here
To see how the joystick looks like with different configurations you could clone this repository, modify the joystick configuration, and run the application, but if you don't want to do that, here is a video that will show you how it looks like with some configuration changes.
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
If you encounter any problems or bugs while using the script, please open an issue in the GitHub repository. If you have any questions or suggestions, feel free to contact me.