- π Overview
- π¦ Installation
- βοΈ Project Configurations
- ποΈ How to Use
- π Reporting Issues
- π€ Contributions
Experience a user-friendly open-source π Gradle plugin π designed to simplify your DevOps journey while developing with LibGdx.
This plugin empowers you to effortlessly develop, run, and distribute simulations and games using LibGdx across multiple platforms. With automation at its core, you can bid farewell to complex configurations and project structure.
Harnessing the power of the core OIS library, this plugin provides a straightforward approach to implementing graphic simulation and games. Paired with the OIS runners, distributing your projects across platforms becomes a breeze, all while maintaining a clean project structure.
Embark on your project journey within your preferred IDE, without the hassle of learning new tools to develop simulations or games in Java. Simplify development and distribution and embrace a more streamlined process.
- Java version
15
or a more recent release. - Gradle version
7
or a newer version.
The plugin is not yet available in Maven Central and must be installed locally.
Manual installation
To install the OIS core library locally:
- Clone the core library repository:
git clone https://github.com/attiasas/open-interactive-simulation-core.git
- Navigate to the cloned directory and publish the library to Maven Local:
./gradlew publishToMavenLocal
To install the plugin locally:
- Clone this repository:
git clone https://github.com/attiasas/open-interactive-simulation-deployer.git
- Navigate to the cloned directory and publish the library to Maven Local:
./gradlew publishToMavenLocal
Download the installation bash script and execute it:
./installOIS.sh [-d <deployer_tag>] [-c <core_tag>] [-h]
The script can be used to install the OIS core library and the deployer plugin. It accepts the following options:
-d <deployer_tag>
: Specify the deployer tag (default: master).-c <core_tag>
: Specify the core tag (optional, determined automatically if not specified).-h
: Display this help message.
- Add at the top of your
settings.gradle
the following snippetpluginManagement { repositories { mavenLocal() } }
- Add the following repositories to the
buildScript
in your projectbuild.gradle
buildscript { repositories { mavenLocal() mavenCentral() gradlePluginPortal() maven { url "https://oss.sonatype.org/content/repositories/snapshots/" } google() } }
- Apply the plugin in your project
build.gradle
plugins { id 'org.attias.open.interactive.simulation.deployer' version '1.0-SNAPSHOT' }
- [Optional, Recommended] Add the core library dependency in your project
build.gradle
dependencies { implementation group: 'org.attias.open.interactive.simulation', name: 'open-interactive-simulation-core', version: '0.1' }
In order to utilize the plugin and execute OIS projects, it is necessary to set up the configurations or Generate
a file known as simulation.ois
. This file will contain all the essential project configurations required for running your project.
The file follows a JSON format and comprises the subsequent attributes:
Attribute | Description |
---|---|
title | The designated title of your simulation project. |
initialState | The state that will be activated upon initiating the simulation. |
states | A mapping of all implemented IState classes within your project, along with their corresponding keys. |
publish | The configurations for publishing your OIS project and facilitating its distribution. |
publish.platforms | The designated platforms on which the simulation will operate, with at least one platform defined. |
publish.publishedName | [Optional, default is the project name] The name of the resulting artifacts upon publishing. |
publish.publishNumber | [Optional default is 1] the publishing version number (typically incremented with each release). |
publish.iconsDir | [Optional] The directory housing all project icons, must follow the configurations. |
publish.generateMissingIcons | [Optional, default is false] try to generate missing icons base on iconsDir attribute content. |
For instance (minimal, only required attributes):
{
"title" : "OIS simulation",
"initialState" : "Green",
"states" : {
"Blue" : "org.example.BlueState",
"Red" : "org.example.RedState",
"Green" : "org.example.GreenState"
},
"publish" : {
"platforms" : [ "Desktop", "Android" ]
}
}
For seamless development, the option to override specific project simulation.ois
or plugin configurations is available.
This can be achieved by specifying the oisDeployer
extension within your build.gradle
file:
oisDeployer {
// Instead of resolving the runner based on its version in simulation.ois,
// Run the runner project from this directory.
runnerPath = 'path-to-dir-of-specific-runner'
// Instead of retrieving the project configurations from the `simulation.ois` file in the project root directory,
// Obtain project configurations from this file.
configPath = 'path-to-your-simulation-config-file'
// Rather than resolving the assets directory from your project resources
// Resolve it from this path.
assetsPath = 'path-to-your-resources-dir'
// Rather than resolving the Android Sdk location from the environment variable 'ANDROID_HOME'
// Resolve it from this path.
androidSdkPath = 'path-to-android-sdk-dir'
}
You have the opportunity to tailor your own custom icons for the project. A designated directory should be provided to accommodate these icons. You are not obliged to provide a complete set of icons; any missing icons will be substituted with default counterparts, or generated from the existing subset.
The directory must contain only one item per combination of dimensions and extensions. If multiple items exist, only one will be considered.
Desktop Platform Icons
The valid extensions for icons are:
- Windows:
png
,ico
(optional). - Linux:
png
. - Mac:
icns
.
Acceptable icon dimensions include: 128x128
, 32x32
.
Android Platform Icons
The icon that will be shown as the app has to be in xml
format and be generated by following this steps:
-
Generate your Icon.
- Must be in
svg
/psd
format. - Colors must be in black and white (can color shapes later).
- Must be
108x108
, the logo should be centered, must be at least48x48
dp; it must not exceed72x72
dp because the inner72x72
dp of the icon appears within the masked viewport.
- Must be in
-
Open, in intellij, any
Android
project (or use the runner project cloned to theois
plugin directory in your$HOME
directory).2.1. On the Project tab, right click:
New
->Vector Asset
2.2. Chose
Asset type
value toLocal file (SVG, PSD)
the path and the target name.2.3. Chose
108dpx108dp
as the value forSizw
.2.4. Continue and generate the
xml
file and copy it to youriconsDir
. -
[Optional] Color the generated icon shapes (
paths
tag) by editing thexml
file and changing theirfillColor
values.
In addition, you can provide png
icons for specific dpi,
Acceptable icon dimensions include: 48x48
, 72x72
, 96x96
, 144x144
, 192x192
.
The plugin offers Gradle tasks that facilitate both the execution and distribution of your project across various platforms.
These tasks are grouped under the ois
category.
To establish the foundation of your OIS project and generate essential files, use the following command:
gradlew initializeProject
If you wish to make modifications to your project's structure, files, or attributes and ensure the correctness of your configuration, execute:
gradlew validateProject
For implementing your OIS project, consider utilizing LibGdx or consult the user guide for insights into leveraging the core library effectively.
To plugin will create running tasks to debug your project for each value you input at publish.platforms
attribute in the configurations.
Desktop Platform
After applying the configurations, you can run your project locally on your Desktop
by executing:
gradlew runDesktop
Android Platform
After applying the configurations, you can run your project on a virtual/physical Android
device by executing:
- Make sure there is an active device connected (can use Intellij).
- Run the following gradle command:
gradlew runAndroid
Some changes may require to uninstall the application before rerunning.
Once you've implemented your project, you can deploy it to generate the necessary production files. These files are essential for running your project on the designated platforms. Use the following command:
gradlew deployProject
The artifacts intended for distribution will be created within your project's build
directory.
Inside this directory, you'll find a folder named OIS
containing zip files tailored for each platform configuration specified in your project's configuration file.
Publishing to Desktop Platform:
Note that the generated zip files are specific to the platform they were built on. For instance, generate the distribution task on a Windows machine for Windows distribution and on a Linux machine for Linux distribution.
Publishing to Android Platform:
Note that the generated apk is unsigned and should be signed before distribution.
When encountering problems during your build process,
we recommend using the -d
option when running Gradle for detailed debug information.
If you face issues with running or deploying your project, start fresh by cleaning the runners:
gradlew cleanRunners
To contribute to the library's improvement, please report encountered issues. Your input is valuable to us.
We welcome pull requests from the community. To help us improve this project, please read our Contribution guide.