Translators - UA-ScriptEase/scriptease GitHub Wiki

I am C-3PO, human-cyborg relations.

-- C-3PO

Translators are one of the core features of ScriptEase II - a modular system for generating code for any game and then writing the compiled code to the game data directly. Translators are composed of the following:

• Translator Description File named translator.ini
• API Dictionary file
• Language Dictionary file
• Implementation of the GameModule interface for IO
• Optional relevant data Translators are stored in a subdirectory of the translators/ directory. Specific translator directory names must be lower-case. Each sub-component is detailed in its own section on this page. See the page for each specific translator for details.

#Translator Description File

##Overview Every translator must have a text Description file named translator.ini that details the locations or values of both the translator's mandatory, suggested and optional components. Mandatory components include a name string and both API & Language Dictionary locations. Suggested components are keys that will be regularly requested by ScriptEase, but are not absolutely required for operation. Optional components can be any key-value string pair that the translator author wishes to include. Mandatory and Suggested properties can be accessed with specialized methods in the Translator class, while optional properties can be access via Translator's getProperty() or getPathProperty() methods.

The file format is that of Java Properties files, and all keys are are case-sensitive. By convention we use underscore-separated UPPERCASE for all keys. Values can be any string, but file path values must follow the Java standard (as seen in File or equivalent) and relative paths are considered to be relative to the location of the Translator Description file.

##Mandatory and Suggested Keys

Mandatory	Suggested	Key	Type
X		NAME	String
X		API_DICTIONARY_PATH	Path
X		LANGUAGE_DICTIONARY_PATH	Path
X		GAME_MODULE_PATH	Path
	X	INCLUDES_DIR	Path
	X	SUPPORTED_FILE_EXTENSIONS	Comma Separated String
	X	COMPILER_PATH	Path, or false for no compiler
	X	GAME_DIRECTORY	Path
	X	ICON_PATH	Path
	X	SUPPORTS_TESTING	Boolean string for Boolean.parseBoolean(String)

More keys can be specified as needed by the Translator author. Below is an example Translator file based off of a fictional game.

# ==========================================================
#    Adventures of Sherlock Holmes Translator Definition
# ==========================================================

# --- Required data--- 
NAME=Adventures of Sherlock Holmes
API_DICTIONARY_PATH=resources/apidictionary.xml
LANGUAGE_DICTIONARY_PATH=resources/languageDictionary.xml
GAME_MODULE_PATH=io/SherlockAdventureReader.class

# --- Suggested Data ---
INCLUDES_DIR=resources/includes
SUPPORTED_FILE_EXTENSIONS=adv
COMPILER_PATH=C:/Program Files/Sherlock Holmes/utils/compiler.exe
GAME_DIRECTORY=C:/Program Files/Sherlock Holmes
ICON_PATH=resources/SherlockIcon_Small.gif
SUPPORTS_TESTING=true

# --- Optional Data ---
GAME_DIRECTORY=C:/Program Files/Sherlock Holmes

#API and Language Dictionaries See the specific pages for more.

#GameModule Implementation An implementation of the GameModule interface must be provided so that ScriptEase has access to all of the game data required to be able to generate scripts.

The GameModule implementation must:

1. be loadable as a Java class that implements GameModule.class
2. never contradict the interface as defined in GameModule's documentation.

Aside from those conditions, the Translator author is allowed to perform whatever actions they feel necessary to access game information and convert it to ScriptEase data as well as writing generated data back to the game (if possible). This could include reading and writing from files or connecting to a database.

GameConstant: The GameConstant interface will need to be implemented in order to fully implement the GameModule interface.

#Optional Relevant Data Translators may include whatever they want in the package; after all, it's just a zip file. A common addition, for example, is a translator icon (16x16 GIF or PNG), usually derived from the game's logo or icon. See the table under Translator Description File for commonly used keys, but you may also use any key you like.