Configure Your Simulation Project

This page provides step-by-step instructions for setting up a minimal OIS project.

1. Create a Minimal Java Library Project with Gradle

To get started, create a new directory for your project and navigate into it:

mkdir my-simulation-project
cd my-simulation-project

Next, initialize a new Gradle project:

gradle init --type java-library

2. Configure your project to OIS ecosystem

Update Your build File

Open the build.gradle file generated in the project root directory and add the following configuration to apply the OIS simulation plugin:

plugins {
    id 'org.ois.simulation' version '1.0-SNAPSHOT'
}

Configure Plugin Management

Next, you need to modify the settings.gradle file to specify where to find the OIS simulation plugin since it is not publicly available. Open the settings.gradle file and add the following configuration:

pluginManagement {
    repositories {
        mavenLocal()
    }
}

This configuration tells Gradle to look for plugins in your local Maven repository.

3. Create your first IState class

In a simulation, there are various phases or "states" (e.g., menus, gameplay, pause screens) that can occur. The IState interface allows you to define how these states behave when they are entered, updated, or exited, among other lifecycle methods.

The core methods in the IState interface include:

• enter: Invoked when entering the state.
• exit: Invoked when exiting the state.
• pause: Pauses the state.
• resume: Resumes the state after a pause.
• resize: Handles resizing the state (e.g., when the window changes size).
• render: Handles drawing the state.
• update: Updates the state logic.
• dispose: Releases resources when the state is no longer needed.

create a class that implements the IState interface. Each method in the interface must be implemented, even if some methods are left empty

package org.mypackage;

import org.ois.core.state.IState;

public class MyState implements IState {
    
    @Override
    public void enter(Object... parameters) {
        // Logic when entering the state.
        // Optional: Handle any parameters passed to this state.
    }

    @Override
    public void exit() {
        // Logic when exiting the state.
    }

    @Override
    public void pause() {
        // Logic when the application is paused at the state.
    }

    @Override
    public void resume() {
        // Logic when the application is resume at the state.
    }

    @Override
    public void resize(int width, int height) {
        // Logic to handle state resizing.
    }

    @Override
    public void render() {
        // Logic to render the state (e.g., drawing elements on screen).
    }

    @Override
    public boolean update(float dt) {
        // Update the state logic (e.g., physics, game events).
        // Return true to keep the state active, or false to exit the state.
        return true;
    }

    @Override
    public void dispose() {
        // Clean up resources when the state is no longer needed.
    }
}

4. Add a simulation configuration directory to the project

🗂️ Simulation directory

Create a directory named simulation in your project root directory, this directory will hold all of your project configurations and assets.

---

⚙️ Simulation configuration file

The simulation.ois file is a JSON configuration file used to define the settings for your simulation. This file allows you to specify the title, initial state, available states, target platforms, and screen dimensions for the simulation. A file named simulation.ois

Key Elements

1. title (Optional): The title of your simulation, which may be displayed in the window title bar or launcher, depending on the platform.
2. states: A map of all of the project implementations of IState mapped to a unique key to identify them.
3. initialState: Specifies the state in which the simulation should start. This must correspond to one of the states defined in the states section.
4. runner (Optional): Defines the simulation runner configurations such as the intended platform for the simulation and its screen dimensions.
   • platforms: An array of platforms on which the simulation can run. If no platforms are specified, the simulation will run on all available platforms by default.
   • screenWidth: The width of the simulation screen. A value of 0 means the screen will dynamically fill the available space (this is the default behavior).
   • screenHeight: The height of the simulation screen. A value of 0 means the screen will dynamically fill the available space (this is the default behavior).

Here is the structure of a typical simulation.ois file:

{
    "title": "My Simulation Title"
    "initialState": "MyState",
    "states": {
        "MyState": "org.mypackage.MyState"
    },
    "runner": {
        "platforms": [ "Html", "Desktop", "Android" ],
        "screenWidth": 0,
        "screenHeight": 0
    }
}

Minimal Configurations

The minimal required fields in the simulation.ois file are initialState and states. These fields define the starting point and the available states for your simulation. The other fields are optional, and if not provided, default values will be used.

{
    "initialState": "MyState",
    "states": {
        "MyState": "org.mypackage.MyState"
    }
}

---

🎨 Assets directory

To use assets in your simulation you need to place them inside the assets directory. The OIS infrastructure will know to include them with the simulation.

---

📑 Reflection configuration file

For HTML supported project that needs to use Reflection. You can specify the package that will be reflected inside (Optional) reflection.ois JSON configuration file.

[
   "org.mypackage.ClassToReflect",
   "org.mypackage.OtherClassToReflect"
]

---

You are done configuring your OIS project!

After making these changes, your project structure should look like this:

my-simulation-project/
├── build.gradle
├── settings.gradle
├── simulation
│   ├── assets
│   └── simulation.ois
└── src
    └── main
        └── java
            └── org
                └── mypackage
                    └── MyState.java

Continue to Running and Debugging the Simulation