Take On Helicopters: Java Scripting

Overview

Patch 3 (1.04) for Take On Helicopters introduces the ability to use Java scripting in the Real Virtuality engine. It is currently available for testing in beta patch rev. 89707.

Arma 3 will also have Java scripting available, so its introduction in TKOH is to ensure the implementation can mature before that game is released.

This documentation will need to be expanded with more details, guides for other IDEs and comparisons to SQF scripting.

Limitations

• Classes can only be loaded from mission, campaign and user profile folders.

Setup - Eclipse

Installation

• Download and install Java SE 1.7
• Download and install Eclipse (Indigo)
  • You are free to use other IDEs, but this guide deals with Eclipse only
• Download and install the TKOH Beta Patch rev. 89707 (or later)

Sample mission

• Create a new mission in the editor on Oil Platform
• Insert a player pilot character
• Save the mission as JavaSample (which will create the JavaSample.Intro_Island_H folder in your user profile Missions folder)

New IDE project

• In Eclipse, create a new Java Project (File > New)
  • Enter a name (e.g. JavaSample)
  • Untick Use default location, and browse to the mission you've just created
  • Select Next
• We'll want the .java sources and compiled .class files in the root of the mission for now (alternatively you can organize your data using packages)
  • Right-click the default src folder and select Remove from Build Path
    • If you want, manually delete the src folder from your mission folder
  • Select the root JavaSample folder, right-click, and select Use as Source Folder
  • Set Default output folder to just JavaSample (remove \bin)
• Go to the Libraries tab
  • Select Add External JARs..
  • Select from your game installation folder: JRE\lib\ext\JNIScripting.jar
• Select Finish

New Java class

• Right-click the JavaSample project and create a new Class
  • Enter as Name: Sample
  • Superclass: empty (remove the default java.lang.Object)
  • Select Finish
• Change the Sample.java file to:

import com.bistudio.JNIScripting.RVEngine;

/**
 * Sample Java class 
 * @author Bohemia Interactive
 */
public class Sample {
	/** 
	 * Show a hint passed to jCall.
	 * @param args Method parameters
	 */	
	public static Object showHint(Object[] args) {
		if (!(args[0] instanceof String)) return null;		
		RVEngine.hint((String)args[0]);
		return null;
	}
}

• Save the file

Debugging

• Run TKOH with start-up parameter -jDebugPort=8008 (or another suitable port number)
• Open the mission in the editor
  • In the player's Initialization-field add:

BIS_Sample = jLoad "Sample"; BIS_Result = BIS_Sample jCall ["showHint", ["Take On World!"]];

• In Eclipse, go to the Run menu and select Debug Configurations..
  • Double-click Remote Java Application
  • Change the port number to the one you launched TKOH with (8008)
  • In the Common tab, tick to show this configuration in the Debug favorites menu for ease of use
  • Select Apply and Close
• Place a breakpoint on the following line (double-click the grey column on the left):

RVEngine.hint((String)args[0]);

• Start the debugger from the Debug favorites menu (by default named Sample (1))
• In TKOH, preview the mission
  • It is recommended to run TKOH windowed to make switching between Eclipse and the game easier (-window)
  • Eclipse's debugger will take focus almost immediately to show the breakpoint
    • If Eclipse does not show the source code it is paused at, make sure the project and JNIScripting.jar are listed under the Source tab in the debug configuration (Source Lookup Path)
  • Press F8 to resume
  • Return to TKOH to see the hint displayed
• Welcome to Take On Java!