Scripting is always enabled. To activate it, you simply have to place a file called main.js in the Scripts folder within your main PinballY folder. The program checks automatically for this file; there are no extra options to set. At startup, PinballY checks to see if Scripts\main.js exists, and if so, PinballY loads and executes the file.
If you wish, you can organize your code into multiple files. This is particularly useful if you want to share your code or use modules written by other people. See How to use multiple script files later in this section.
The main thing that the top-level code in your main.js file will usually do is set up event listeners. An event listener is a function you write that will be called when a specific event occurs. Once an event listener is set up, PinballY will call it whenever the associated event occurs.
Instead of using timing loops or waits, use a timeout or interval. That'll let PinballY run the UI while waiting for the scheduled time. If you have a long-running, CPU-intensive task to perform, try to break it up into smaller tasks, and use intervals to spread the subtasks out over time.
Most of the code you write for PinballY will be there to handle events. An event is something like "the user pressed a key" or "a game is being launched".
A function you write to handle an event is called an event listener. PinballY notifies you that something is happening by calling your event listeners for that particular event.
You set up an event listener by calling a function to add the listener to the event target object that generates the events of interest. An event target represents a PinballY user interface element that's associated with one or more events. The primary event target for most events is the mainWindow object, which represents the main playfield window. Most UI events are handled in this window, even when other windows (such as the backglass or DMD) are open.
To attach an event listener to an event target, you use the on() method of the event target object:
You can attach a listener to more than one event with a single "on" call, by separating the event names with spaces:
on() adds a listener. It doesn't replace or remove existing listeners for the same event. If there's already another event listener on the same object, the old listener and the new listener will both be called when the event occurs. You can add any number of listeners this way. This is especially useful if you're mixing packages written by different people, because it lets listeners from different packages co-exist peacefully, without having to know about each other.
There's variation of on() called one(), which adds a listener that only runs a single time. The first time a "one" handler is called, it runs normally, then the system automatically removes it.
You can remove an event listener explicitly via the off method:
Calling off() with an event name simply removes all listeners for the given event name. You can remove a specific listener by passing in the same function you used to set up the listener in the first place with on():
You can specify a "namespace" with each event created with on(). A namespace is specified after the event name, separated with a period (.).
The point of a namespace is to identify the listener for later removal. When you call off(), you can use the same namespace qualifier to remove only the listener(s) created with that namespace:
Remember, the normal off() removes all listeners for the named event. Using a namespace qualifier removes only listeners with the same namespace. This is especially useful for sharing code, because it lets you make nicely isolated code that won't interfere with other people's code that it's combined with.
Using a namespace also lets you easily remove every event listener of every type that you installed under the namespace. Just call off() with the namespace qualifier alone, with no event name:
PinballY provides access to the program environment through a number of pre-defined system objects. These are analogous to the system objects in a Web browser ("window", "document", etc), but are tailored to the PinballY environment instead of a browser environment. See System Objects for details.
The easiest is to use FileSystemObject, a standard Windows scripting component. You can access this using PinballY's OLE Automation support. FileSystemObject provides simple scripting access to basic file functions, such as getting directory listings and reading and writing text files.
If you need lower-level access, or more advanced functions beyond what FileSystemObject provides, you can call most native Windows API functions directly via the DLL Import system.
The import system is specifically designed to make it easy to combine code written by different people, by letting you say exactly which symbols (and only those) are shared among modules. That avoids all sorts of problems that usually come up when people try to share code, such as when two people both used the same names for their variables and functions.
You can import multiple symbols from the module by listing them inside the braces, separated by commas.
PinballY's system scripts are in the Scripts\System folder within your PinballY program folder. These files are automatically loaded when PinballY starts up (or, in some cases, later on when needed), so there's no need to copy any of these files into your own .js files or to load them explicitly with "import" or any other means. You can simply expect these files to be available at all times.
A quick summary of the files: