Skip to content

Common methods

The script file is the main entry point for developing a plugin.

Methods

Below are the plugin methods called automatically by A.V.A.T.A.R (at the startup or during a script execution). Some of these methods are created automatically if you create the plugin via Plugin Studio.

action(data, callback)

This mandatory method is the plugin's entry point.
It is always called by the action.<plugin>.js file, or directly if the plugin has no voice rules.
Always return the callback function.

  • data - object - The object sent from the action.<plugin>.js file.
    • client - string - The A.V.A.T.A.R client who sent the sentence.
    • toClient - string - The A.V.A.T.A.R client (real or virtual) in the sentence.
    • rawSentence - string - The untranslated sentence.
    • sentence - string - The sentence translated into English.
    • language - string - The short code of the language used on the A.V.A.T.A.R client for rawSentence.
    • tags - array - Sentence tags translated into English.
    • tokens - array - Tokens of the sentence translated into English.
    • relations - object - The relationship found between the object and the action of the sentence translated into English.
    • action - object - The object defined in the action.<plugin>.js file.
  • callback null or callback function if the plugin is called by Avatar.run() or Avatar.call() from another plugin with a callback function.

🔦 See Natural Language Processing for futher details on tags, tokens and relations objects.

export async function action(data, callback) {
    // Table of actions
    const tblActions = {
        // test (see rules table in the property file)
        doIt: () => doIt(data.client)                   
    };

    // Writes info console
    info("test:", data.action.command, L.get("plugin.from"), data.client);

    // Calls the function
    tblActions[data.action.command]();

    // Returns callback
    callback();
}

init()

This optional method is executed when the plugin is loaded during A.V.A.T.A.R initialization.
Useful for loading information required by the plugin, e.g. for loading language .pak files:

export async function init() {
    if (!await Avatar.lang.addPluginPak("myFirstPlugin")) {
        return error('myFirstPlugin: unable to load language pak files');
    }
}

cron()

  • interval: 2 hours` by default when the plugin is created by Plugin Studio.

This optional method is called at regular intervals by the application. The interval is defined more precisely in the myPlugin.prop properties file. 

export async function cron () {
    // Says Hello every 2 hours
    info ('hello from myPlugin !");
}

{
    "modules": { 
        "myPlugin": {
            "version": "1.0",
            "name": "My Plugin",
            "rules": {
                "test": ["test * (command|order)"]
            }
        }
    },
    "cron": {
        "myPlugin": { 
            "name": "myPlugin",
            "time": "0 * */2 * * *"
        }
    }
}

Syntax

- `*` Asterisks: Any value
- `1-3,5` Ranges: Ranges and individual values
- `*/2` Steps: Every two units

Range of values supported:

field          allowed values
-----          --------------
second         0-59
minute         0-59
hour           0-23
day of month   1-31
month          1-12 (or names, see below)
day of week    0-7 (0 or 7 is Sunday, or use names)


Names can also be used for the 'month' and 'day of week' fields.  
Use the first three letters of the particular day or month (case does not matter).  
Ranges and lists of names are allowed.
Examples: "mon,wed,fri", "jan-mar".

onClose()

This optional method is called just before A.V.A.T.A.R is closed or restarted.
Useful for saving plugin information, for example:

export async function onClose () {
    return new Promise(resolve => {
        let propertyFile = path.resolve(__dirname, 'credentials/' + Config.modules['myPlugin'].authorization.credentials);
        fs.writeJsonSync(propertyFile, property);
        resolve();
    });
}

mute(clientFrom, clientTo)

  • clientFrom: - string - The A.V.A.T.A.R client who sent the rule.
  • clientTo: - string - The A.V.A.T.A.R client which must execute the rule, can be identical to clientFrom or a virtual client.

This optional method is called if the client transmitting the rule is in loop mode immediately after the trigger keyword, or in question/answer (askme) mode.
Allows you to perform an action such as muting a device (TV or other) before the dialog.

🔦 Note: This method is generally associated with the unmute() method.

  • Prerequisites:
    • The Bedroom is a virtual client of Living room
    • The Living room client is in loop or askme mode
Living room rule: turn on the light in the bedroom 
* clientFrom: Living room 
* clientTo: Bedroom
  • Prerequisites:
    • The Bedroom is not a virtual client of Living room
    • The Living room client is in loop or askme mode
Living room rule: turn on the light in the bedroom 
* clientFrom: Living room  
* clientTo: Living room
  • Prerequisites:
    • The Bedroom is not a virtual client of Living room
    • The Living room client is not in loop mode
    • The dialogue is an askme
Living room rule: turn on the light in the bedroom  
* clientFrom: Living room 
* clientTo: Living room

unmute(clientFrom, clientTo)

  • clientFrom: - string - The A.V.A.T.A.R client who sent the rule.
  • clientTo: - string - The A.V.A.T.A.R client which must execute the rule, can be identical to clientFrom or a virtual client.

This optional method is called if the client transmitting the rule is in loop mode immediately after the trigger keyword, or in question/answer (askme) mode.
Allows you to perform an action such as restoring a device (TV or other) after the dialog.

🔦 Note: This method is generally associated with the mute() method.

  • Prerequisites:
    • The Bedroom is a virtual client of Living room
    • The Living room client is in loop or askme mode
Living room rule: turn on the light in the bedroom 
* clientFrom: Living room 
* clientTo: Bedroom
  • Prerequisites:
    • The Bedroom is not a virtual client of Living room
    • The Living room client is in loop or askme mode
Living room rule: turn on the light in the bedroom 
* clientFrom: Living room  
* clientTo: Living room
  • Prerequisites:
    • The Bedroom is not a virtual client of Living room
    • The Living room client is not in loop mode
    • The dialogue is an askme
Living room rule: turn on the light in the bedroom  
* clientFrom: Living room 
* clientTo: Living room

subclassSpeak()

This optional method is executed during plugin loading.
Allows you to override the Avatar.speak() method to use a sound system other than the client PC.

Note

This method is called automatically and only if the dialog redirection parameter is enabled on the client.

export async function subclassSpeak() {
    // You can save the default Avatar.speak function for your own use.  
    let defaultSpeak = Avatar.speak;

    Avatar.speak = () => {
        // Do stuff
    }
}

subclassPlay()

This optional method is executed during plugin loading.
Allows you to override the Avatar.play() method to use a sound system other than the client PC for the music and sound.

Note

This method is called automatically and only if the dialog redirection parameter is enabled on the client.

export async function subclassPlay() {
    // You can save the default Avatar.play function for your own use.  
    let defaultPlay = Avatar.play;

    Avatar.play = () => {
        // Do stuff
    }
}
Note

Other methods automatically called by A.V.A.T.A.R (at startup or when executing a script) are associated with widget creation and management. See the widget methods for more details.



The action