Configure.js (Config pack)

From Moondust Wiki
Jump to navigation Jump to search

configure.js - is a special JavaScript-coded module for an integrational configuration package that contains a script to initialize the configuration package and change its settings.

Specification

The configure script should contain the "onConfigure()" call that returns a boolean value:

function onConfigure()
{
    return true;
}

The "true" return will indicate successful configuration, causing the Editor to continue loading. Otherwise, config pack loading is stopped and will instead lead back to the config pack selecting dialog.

The Editor will call it at start-up in a condition when the config pack settings file does not contain the "application-path-configured" fieldset with "true" at its "[main]" section. So if you wish to mark the configuration package as configured and tell the Editor to stop calling this function, you need to set the field at main.ini to something such as:

function onConfigure()
{
    // ....
    var ini = INI.open(FileIO.configSettingFile());
    ini.beginGroup("main");
    ini.endGroup();
    ini.setValue("application-path-configured", true);
    ini.close();
    // ....
    return true;
}

Available JS API

PGE

Common calls.

// Show information message box dialog
PGE.msgBoxInfo(string title, string message);
// title - A title of the message box
// message - A message text
// Show warning message box dialog
PGE.msgBoxWarning(string title, string message);
// title - A title of the message box
// message - A message text
// Show error message box dialog
PGE.msgBoxError(string title, string message);
// title - A title of the message box
// message - A message text

FileIO

File I/O API.

// Get a full path to the directory where this script is placed
var path = FileIO.scriptPath();
// Get a full path to the local settings for the configuration package. Use it to store all config pack specific settings you want to write.
var path = FileIO.configSettingFile();
// Get a full path to the application directory
var path = FileIO.appPath();
// Start the file open dialog and return the path. On cancel, the empty string is returned.
var path = FileIO.getOpenFilePath(string caption, string dir = "", string filter = "All files (*)");
// caption - the title of a file selection dialog
// dir - a path to the initial directory
// filter - a file selection filter (see the documentation of Qt's QFileDialog)

// path - the path to the selected file. Empty string if file selection was canceled.
// Start the directory open dialog and return the path. On cancel, the empty string is returned.
var path = FileIO.getOpenDirPath(string caption, string dir = "");
// caption - the title of a directory selection dialog
// dir - a path to the initial directory

// path - the path to the selected directory. Empty string if directory selection was canceled.
// Check the existence of a file
var ret = FileIO.isFileExists(string filePath);
// filePath - The path to a file to check it's existence

// ret - true if given file exist
// Check the existence of a directory
var ret = FileIO.isDirExists(string filePath);
// filePath - The path to a directory to check it's existence

// ret - true if given directory exist
// Copy one file to another
var ret = FileIO.copy(string src, string dst, bool override = false);
// src - source file
// dst - tatget file path
// override - override file if target already exist

// ret - true when file was successfully copied


INI

INI file read and write API.

// Open INI file
var ini = INI.open(string filePath);
// filePath - the full path to an INI file to open

// ini - an interactable object that contains the file instance
// Make the volatile configuration from the scratch
var ini = INI.make();

// ini - an interactable object that contains the file instance

INIFile

INIFile is a class that holds the opened INI file and allows to change it.

// Open existing INI file with the current instance
ini.open(string filePath);
// filePath - the full path to an INI file to open
// Close currently opened INI file
ini.close();
// Open the section of INI file by name
ini.beginGroup(string groupName);
// groupName - the name of a section to open
// Quit the current section
ini.endGroup();
// Get the existing value from a current section
var value = ini.value(string name, string defaultValue);
// name - the field name
// defaultValue - the default value given instead of non-exist fileds

// value - the final value
// Change the value of a field by name at current section
ini.setValue(string name, string value)
// name - the field name
// value - the value data to write

Example script

A very simple example (API 42 and newer):

function onConfigure()
{
    // Show the message box
    PGE.msgBoxInfo("It works!", "Welcome to my config pack! Enjoy!");
    
    // Mark the config pack as "configured". 
    // This mean, the message box above will be shown once on the first startup
    // of this config pack
    var ini = INI.open(FileIO.configSettingFile());
    ini.beginGroup("main");
    ini.endGroup();
    ini.setValue("application-path-configured", true);
    ini.close();
    
    // Confirm that configure was a success    
    return true;
}

This is a big example of a configure script example that was taken from the TheXTech SDK configuration package to illustrate the work of the script:

/*
 * A configure script required for the TheXTech SDK configuration package working
 */

/**
 * The main function called by Moondust Editor to request configuring process
 */
function onConfigure()
{
    var smbxPath = FileIO.scriptPath();
    var SMBXExeName = "smbx.exe";

    if(!FileIO.isFileExists(FileIO.scriptPath() + "/main.ini"))
    {
        PGE.msgBoxError( "ERROR OF INI FILE!",
                               "Configuratiog package seems damaged.\n"+
                               "Impossible to find main.ini!");
        return false;
    }

    var ini = INI.open(FileIO.configSettingFile());

    while(1)
    {
        smbxPath = FileIO.getOpenDirPath("Select TheXTech-compatible assets directory...", smbxPath);
        if(smbxPath === "")
        {
            PGE.msgBoxWarning("Configuring has been canceled",
            "You was canceled a configuring of the\n'TheXTech SDK configuration package'!\n"+
            "To take able use it, you should choose the path to your installed TheXTech.\n\n"+
            "TheXTech SDK config pack was not configured!" );
            return false;
        }

        try
        {
            //Attempt to detect SMBX directory
            if(!FileIO.isDirExists(smbxPath + "/graphics"))
                throw("'" + smbxPath + "/graphics" + "' directory not exists");

            if(!FileIO.isDirExists(smbxPath + "/graphics/npc"))
                throw("'" + smbxPath + "/graphics/npc" + "' directory not exists");

            var smbxEXENames = [
                "smbx",
                "thextech",
                "advdemo",
                "a2xtech",
                "a2xtech-bin",
                "smbx.exe",
                "smbx-win64.exe",
                "thextech.exe",
                "advdemo.exe"
            ];

            for(var i = 0; i < smbxEXENames.length; i++)
            {
                if(FileIO.isFileExists(smbxPath + "/" + smbxEXENames[i]))
                {
                    SMBXExeName = smbxEXENames[i];
                    break;
                }
            }

            ini.beginGroup("main");
            ini.setValue("application-path", smbxPath);
            ini.setValue("smbx-exe-name", SMBXExeName);
            ini.setValue("application-dir", 1);

            ini.setValue("graphics-level", "graphics");
            ini.setValue("graphics-worldmap", "graphics");
            ini.setValue("graphics-characters", "graphics");
            ini.setValue("application-path-configured", true);
            ini.close();
        }
        catch(e)
        {
            PGE.msgBoxWarning( "TheXTech SDK configuration error",
                               "This is a not TheXTech directory!\nPlease try again!\n" + e);
            continue;
        }
        break;
    }

    PGE.msgBoxInfo( "TheXTech SDK configured",
                    "Integration configuration pack successfully configured!\n\n"+
                    "TheXTech assets path is: " + smbxPath + "\n" +
                    "Default executable name (can be changed at test settings): " + SMBXExeName);

    return true;
}

Deprecated examples

OOjs UI icon notice-destructive.svg DEPRECATED: This is an old example of deprecated behavior at API 41 and lower. Unlike the modern variant, this requires you to modify the main.ini at the config pack itself. That makes the config pack require the writable file system to be placed.


A very simple example (API 41):

function onConfigure()
{
    // Show the message box
    PGE.msgBoxInfo("It works!", "Welcome to my config pack! Enjoy!");
    
    // Mark the config pack as "configured". 
    // This mean, the message box above will be shown once on the first startup
    // of this config pack by overriding the main.ini. 
    // This is a deprecated logic since API 42 that means you shouldn't write config pack files at all
    var ini = INI.open(FileIO.scriptPath() + "/main.ini");
    ini.beginGroup("main");
    ini.endGroup();
    ini.setValue("application-path-configured", true);
    ini.close();
    
    // Confirm that configure was a success    
    return true;
}