common
Standard library of commonly used functions.
Predefined Global Constants and Variables
useLibrary( library )
exit()
Error.error( [exception] ) static
Error.warn( [message], [stackFrame] ) static
Error.deprecated( [message], [stackFrame] )
Error.handleUncaught( exception ) static
prompt( [promptMessage], [initialValue] )
confirm( promptMessage, [title] )
confirm.confirm( promptMessage, [title] ) static
confirm.yesno( promptMessage, [title] ) static
confirm.choose( promptMessage, title, option1, [option2], ... ) static
alert( message, [isErrorMessage] )
sleep( [msDelay] )
Console
Console.print() static
Console.println() static
Console.printf( formatStirng, [values...] ) static
Console.printImage( image ) static
Console.printComponent( component ) static
Console.printHTML( html ) static
Console.clear() static
Console.history() static
Console.visible static
Console.queue() static
Console.flush() static
Console.out static read-only
Console.err static read-only
print( obj )
println( obj )
string( key, [args...] )
gstring( key, [args...] )
sprintf( formatString, [args...] )
printf( formatString, [args...] )
useSettings( source )
$( key ) static
useInterfaceLanguage( [language] )
@( key ) static
useGameLanguage( [language] )
#( key ) static
Patch
Patch.apply( [key1, value1], [key2, value2], ... ) static
Patch.restore( [key1], [key2], ... ) static
Patch.temporary( [key1, value1], [key2, value2], ... ) static
Patch.card( component, [key1, value1], [key2, value2], ... ) static
Patch.cardFrom( component, resource ) static
Patch.cardRestore( component, key1, [key2], ... ) static
| Global | a reference to the global scope of the script; sometimes needed to specify a global variable when a local variable has the same name, but can also be used to look up global variable programmatically, e.g.: println( Global['$recent_file_' + 1] ); |
| Eons | a reference to the main application |
| Editor | a reference to the active editor |
| Component | a reference to the component currently edited by Editor, if any |
| PluginContext | a reference to the plugin context instance for this script |
| sourcefile | the source file of the script being executed |
Import the objects, functions, and variables defined by a library into the
current script. The value of library may either be the simple name
of a built-in library or the URL of a script file. Libraries may safely
be imported multiple times; subsequent calls to uselibrary with
the same library argument will be ignored.
Examples:
useLibrary( 'markup' );
useLibrary( 'res://myname/myplugin/mylib.js' );
The common library is automatically imported into every script.
| library | the built-in library name or a URL |
Stops executing the script running in the current thread.
Indicates an error condition by throwing an exception. The argument can be
a JavaScript or Java excpeption.
| exception | a message string, JavaScript Error, or Java Throwable object to throw |
If script warnings are enabled, issues a warning with message
as the warning text. The optional stackFrame parameter indicates
the relative stack frame to indicate as the location (file and line number)
of the warning. The default is -1, which reports the line of the direct caller
to warn.
| warning | a warning message string to be printed as a script warning |
| stackFrame | the optional relative stack frame position to report as the source |
If script warnings are enabled, warns that a deprecated feature has been
used. Marking a feature as deprecated warns that it may be removed in a
future version. The optional stackFrame parameter indicates
the relative stack frame to indicate as the location (file and line number)
of the warning. The default is -1, which reports the line that called
deprecated.
| message | an optional message describing the deprecated feature |
| stackFrame | the optional relative stack frame position to report as the source |
Prints a standard error message to the console to describe an exception.
This function can be called to handle uncaught script errors in script code
that "escapes" the execution of the script that defined it, such as a
Java interface implementation.
When a script is executed, exceptions that are thrown are caught and displayed
in the console as if the entire script were surrounded by a special
try-catch pair. However, when you implement a Java class
or interface with script code, the function(s) that implement the Java object
"escape" from this try-catch. For example, suppose you create an
ActionListener, add it to a JButton, and then add the
button to the application window with Eons.addCustomComponent.
The script ends, but the listener still exists because it is attached to the
button and the button still exists. If the listener function throws an exception,
you will not see the error message. To get an error message from this listener,
surround the listener code with a try/catch and call this
function with the thrown exception. For example:
let button = new swing.JButton( 'Press Me!' );
button.addActionListener( function listener() {
try {
println( 'You pressed me!' );
} catch( ex ) {
Error.handleUncaught( ex );
}
});
Eons.window.addCustomComponent( button );
Note: Although you could use an anonymous function to create this
listener (function(){...}), if you give it a name then that that name
will appear in the stack trace of any error messages.
Prompts the user for input and returns the result.
This function displays a dialog box with a text field in which the user
may enter text. If the user presses OK, the entered text is returned.
If the user cancels the dialog, null is returned.
| promptMessage | an optional prompt to display |
| initialValue | an optional default value to fill in the text field |
returns the string entered by the user, or null if the dialog
is cancelled
Displays a dialog box containing the promptMessage text along with OK and Cancel
buttons. Returns true if the user selects OK, or false otherwise.
The confirm() function is commonly supported by Web browsers with
JavaScript support. To complement this functionality, two additional
variants are available: confirm.yesno for Yes/No questions,
and confirm.choose to choose from a set of custom options.
These are both described in detail below.
| promptMessage | the prompt text to display |
| title | an optional title for the prompt window |
returns true if user selects OK
This is equivalent to confirm( promptMessage, title ). It is
provided as a parallel to confirm.yesno and
confirm.choose.
Display a dialog box containing the promptMessage text along with Yes and No
buttons. Returns true if the user selects Yes, or false otherwise.
| promptMessage | the prompt text to display |
| title | an optional title for the prompt window |
returns true if user selects Yes
Display a dialog box with buttons for each of option1, option2,
and so on.
If the user chooses one of the options, the index of the option is returned
(0 for option1, 1 for option2, and so on).
If the user closes the dialog without making a selection, -1
is returned instead.
| promptMessage | the prompt text to display |
| title | a title for the prompt window (may be null) |
| options | a list of one or more options to display |
returns the selected option's index, or -1
Displays a message in a dialog box. The user must press the OK button
to continue. This is not generally a user-friendly act and should only
be used if the user must acknowledge something before being allowed to
continue using the application.
The message dialog is normally formatted as a warning message.
If the isErrorMessage flag is true, it will be
formatted as an error message instead. (Exactly what this means
depends on the platform and selected theme, but typically the
resulting dialog box will feature a different
icon for warnings than for errors.)
| message | the message to display |
| isErrorMessage | an optional flag; if true, an error dialog is displayed |
Pauses script execution for a period of time. Returns true if you interrupt()
the thread from another thread while it is sleeping, otherwise returns false.
| delay | the length of time to pause, in milliseconds (default is 1000) |
The console object allows you to interact with the Script Output
Console window.
Prints an object to the script console. This is identical to the global
print function.
Prints an object to the script console. This is identical to the global
println function.
Prints a formatted string to the script console. This is identical to the global
printf function.
Prints an image or icon (subclass of
java.awt.Image
or
java.awt.Icon)
to Console.out.
| image | an image or icon object to be inserted into the console text |
Prints a user interface component (a subclass of
java.awt.Component)
to Console.out.
| image | an image or icon object to be inserted into the console text |
Prints a string of HTML markup to the console as formatted text. The level
of HTML support is equivalent to that provided by Swing JLabels.
| html | a string of HTML markup to be parsed, formatted, and inserted |
Clears the script console.
Returns the current text of the script console history
Boolean property that controls whether the console window is visible.
Buffers output to Console.out until a matching call to flush().
This method should be surrounded with a try...finally block
to ensure that the matching call to flush() is always performed.
Immediately flushes pending writes to Console.out. If output is
currently being buffered due to a call to queue(), buffering ends
and the accumulated output is written to the console.
A java.io.PrintWriter that can be used to write to the
console window's output stream.
A java.io.PrintWriter that can be used to write to the
console window's error stream.
Prints an object to the script console. You may pass multiple arguments
to this function; the arguments will be printed in sequence as if they
printed by multiple print statements.
This is a cover for Console.print.
| obj | an object for which a string representation should be printed |
Prints an object to the script console, followed by a newline.
You may pass multiple arguments to this function; the arguments
will be printed in sequence as if by multiple print calls,
then followed by a newline.
This is a cover for Console.println.
| obj | an object for which a string representation should be printed |
Returns the localized user interface string for a string key.
If the key is undefined an error message string is returned
instead.
If the user interface string is a format string, it may be formatted by
passing additional arguments. Note that Number arguments are converted
to java.lang.Doubles; to fill %d format arguments you
must explicitly convert the Number to a Java Integer
or Long (you can use n.toInt()).
| key | a user interface text key |
| args | zero or more arguments used to format the string |
returns the formatted, localized string mapped to by the key
Returns the localized game string for a string key.
If the key is undefined an error message string is returned
instead.
If the user interface string is a format string, it may be formatted by
passing additional arguments. Note that Number arguments are converted
to java.lang.Doubles; to fill %d format arguments you
must explicitly convert the Number to a Java Integer
or Long (you can use n.toInt()).
| key | a user interface text key |
| args | zero or more arguments used to format the string |
returns the formatted, localized string mapped to by the key
Returns a string formatted using C-style printf syntax.
See Formatter Syntax
for details. Note that Number arguments are converted to java.lang.Double.
| formatString | the string to be formatted using the arguments |
| args | a list of zero or more arguments used to format the string |
returns a formatted string using the specified format string and arguments.
Print a formatted string to the console using C-style printf syntax.
See Formatter Syntax
for details. Note that Number arguments are converted to java.lang.Double.
If you wish to use the %d format, convert the number to java.lang.Integer
using its toInt() function.
| formatString | the string to be formatted using the arguments |
| args | a list of zero or more arguments used to format the string |
Sets the Settings object that will be used to get and set
settings using the $setting_name syntax. Starting
with Strange Eons 2.00.5, script code may read and write settings
using global variables that start with a dollar sign ($) followed
by the setting name. Setting names that include the hyphen character
should use an underscore instead of a hyphen since hyphens are not
legal in JavaScript identifiers. For example, to print the value of
stamina-text-region, one would write:
println( $stamina_text_region );
By default, a script that uses this syntax will read and write the
global (shared) settings, except for DIY scripts
which use the private settings of their DIY game component object.
This function allows you to choose a different Settings
object to use. The value of source can either be a
Settings object, which will be used directly, or
else a game component, in which case the private settings of that
component will be used. If source is null or
undefined, then shared settings will be used.
| source | the settings to use for $ script variables |
Looks up the value of a key named by the string argument in the current
$-notation settings. This allows you to describe a key
algorithmically using consistent notation.
| key | a string whose value is the desired setting key |
Sets the Language used
to look up interface strings with the @key_name
syntax. By default this is Language.getInterface().
The @-syntax is the same as the $-syntax for
settings, except that it looks up localized interface strings.
| language | the localized string source to use |
Looks up the value of an interface string key in the current @-notation
language. This allows you to describe a key algorithmically while
still using consistent notation.
| key | a string whose value is the desired interface language key |
Sets the Language used
to look up game strings with the #key_name
syntax. By default this is Language.getGame().
The #-syntax is the same as the $-syntax for
settings, except that it looks up localized game strings.
| language | the localized string source to use |
Looks up the value of a game string key in the current #-notation
language. This allows you to describe a key algorithmically while
still using consistent notation.
| key | a string whose value is the desired game language key |
The Patch object contains static helper methods that modify
(or restore) settings.
This can be used to fix user issues or to modify program behaviour at
runtime, and to create new card types based on existing cards.
Writes zero or more pairs of settings values to user settings and then
saves user settings to disk. The new values will override the default
values for the application and game language.
The arguments must be a sequence of key, value pairs. If the number of
arguments is not even, an exception is thrown.
For example:
Patch.apply( 'encounter-bright-adjust', '1' )
| key1, value1, ... | pairs of key and value strings that name the keys to be modified and their new values |
Deletes zero or more user settings and then writes user settings to disk.
| key1, ... | the names of the keys whose values should be restored |
Changes zero or more pairs of settings values until the end of the current
session. The settings will return to their previous value the next time
the application runs.
The arguments must be a sequence of key, value pairs. If the number of
arguments is not even, an exception is thrown.
Assigning a value to a setting using the $-notation is normally
equivalent to calling this function unless the script is a DIY component
or usesettings has been called.
| key1, value1, ... | pairs of key and value strings |
Modifies the private settings of a component.
These settings apply only to component and are saved and loaded
with it.
This can be used by extensions to create custom components based on
existing card types by modifying their images, text, regions, and so on.
| component | the game component to modify |
| key1, value1, ... | pairs of key and value strings |
Modifies the private settings of a component by merging in all of the settings
stored in a resource file.
| component | the game component to modify |
| resource | the path to a resource file from which settings will be read |
Removes one or more private settings from a component, restoring them to
their default value.
| component | the game component to modify |
| key1, ... | the names of the keys whose values should be restored |
Contents