Actions

Functions: Difference between revisions

From Iron Realms Nexus Client Documentation

No edit summary
 
(31 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Functions and scripts are the most powerful option that the client has to offer, but also one that is most difficult to use. Functions and scripts are programmed in the Javascript language. While this documentation contains a few hints to get you started, describing this language to any details is beyond its scope.
<table>
<div class="row">
<div class="large-8 columns">
Functions and scripts represent the pinnacle of what the Nexus client can provide in terms of power and customization, albeit with higher complexity. These functionalities are programmed using [[Javascript]], a versatile and widely-used language.


Functions are created as any other reflex type. Each function must have a name, otherwise it will not work. Once created, you can invoke functions simply by entering its name as a command - for this reason, you should be careful not to give your functions names that would conflict with the actual game commands.
In this section, we will not delve into the details of coding in [[Javascript]]. However, we will introduce you to some of the built-in functions and guide you through creating your own custom code. This will empower you to enhance and refine your skill set for more intricate and responsive interactions.


Scripts are similar to functions, but are attached to a particular trigger, and are only ever invoked when the trigger matches.
==== Scripts vs. Functions ====
* Scripts are specific code blocks that are fired as a result of a reflex being fired. This can be a trigger, alias, or keybind.
* Functions are reusable code blocks that can be called from scripts or directly from the client's input.  


Scripts and functions consist of commands, separated by a semicolon (;). One important command is '''client.send_direct''', which lets you send commands from the script. For example: <code>client.send_direct("look");</code>
==== Calling functions ====
Functions can be called from scripts by using '''run_function(name, args, package)'''. As mentioned above, they can also be called directly from the client's input, so you'll want to make sure your functions are named in such a way that they do not overlap with in-game commands you may wish to use.


Scripts can use their own private variables, defined using '''var name = value;'''. For example, <code>var number = 5;</code> It is important to keep in mind that these are NOT the client variables, but separate ones entirely. It is also possible to perform various calculations on the variables. For example: <code>number = 4 * 5;</code> would assign the result of 4 * 5 to the local variable number. <code>number = number * 5</code> would multiply the value stored in variable number by 5, then assign the result back to variable number, overwriting the previous value.
==== Variables ====
Scripts and functions are generally self-contained, variables are local to the code block and are cleared when the script or function finishes. To interact with variables used in the [[3.0_Simplified_Scripting|Simplified Scripting]] system, you'll want to use the built-in modules: get_variable, set_variable etc.
* Functions called in a trigger receive information about the match: '''args.text, args.match, args.prefix, args.suffix, args.backrefs[1] ...'''
* Scripts receive the backrefs ('''args[0]., args[1],. args[2], ...''') and the current_package variable indicating the active package.


Scripts can access and set the client variables as well - use '''client.get_variable''' to retrieve the value of a variable, and '''client.set_variable''' to set it. For example, this script increases the client variable called amount by one:
==== Built-in modules ====


<code>var a = client.get_variable('amount') + 1; client.set_variable('amount', a);</code>
===== Commands =====
* '''send_command(input, no_expansion)''' - Send a command to the game. Set no_expansion to 1 to send the exact string to the game without expansion.
* '''display_notice(text, fgcolor, bgcolor)''' - display a notice on the output screen.


Functions and scripts receive some additional variables depending on how they are called.
===== Variables =====
* '''get_variable(name)''' - Retrieve the value of a variable from the client's simplified scripting system.
* '''set_variable(name, val)''' - Set a variable for the client's simplified scripting system.
* '''delete_variable(name)''' - Delete a variable from the client's simplified scripting system.
* '''inc_variable(name, by)''' - Increment a variable from the client's simplified scripting system.
* '''dec_variable(name, by)''' - Decrement a variable from the client's simplified scripting system.
* '''mul_variable(name, by)''' - Multiply a variable from the client's simplified scripting system.
* '''div_variable(name, by)''' - Divide a variable from the client's simplified scripting system.


Functions called by a command receive an args variable, which contains the individual words used after the function name, accessed using args[0], args[1],. ....
===== Reflex Manipulation =====
* '''reflex_find_by_name(type, name, case_sensitive, enabled_only, package))''' - Search for a specific reflex.
** ''type'' - Type of reflex: 'alias', 'trigger', 'keybind', ...
** ''name'' - Name to search for
** ''case_sensitive'' - Whether the name needs to match case exactly
** ''enabled_only'' - Set if disabled reflexes (including reflexes in disabled groups) should be ignored
** ''package'' - Name if a package to search in; omit if searching in the main list
* '''reflex_enable(reflex)''' - Enable a reflex (reflex is as returned by reflex_find_by_name above).
* '''reflex_disable(reflex)''' - Enable a reflex (reflex is as returned by reflex_find_by_name above).


Functions called in a trigger receive information about the match - args.text, args.match, args.prefix, args.suffix, args.backrefs[1], ...
===== Output Manipulation (Trigger Scripts)=====
Scripts receive the backrefs (args[0]., args[1],. args[2], ...) and the current_package variable indicating the active package (see below).
* '''current_text()''' - An unformatted version of the line that fired the trigger.
Another example of what scripts can do are conditional triggers, using the if statement. For example: <code>if (client.get_variable('count') >= 5) client.send_direct('say count is ' + client.get_variable('count'));</code> In this example, the + operator is used to join two strings.
* '''gag_current_line()''' - Hide the line that fired the trigger from the output window.
You can call functions in scripts using run_function(name, args, package).
* '''colorize_current_line(start, length, fgcolor, bgcolor)''' - Colorize/highlight a specified part of the line that fired the trigger.
* '''replace_current_line(start, length, newtext, fgcolor, bgcolor)''' - Replace a party of the current line with the specified text and color.


=== Manipulating reflexes in functions or scripts ===
===== UI Manipulation =====
* '''client.register_custom_tab(tab,container_id)''' - Make a custom UI tab. ''Please note, this is unsupported.''


The client allows you to fetch information about reflexes, and to modify it in various ways.
===== Tab Display =====
* '''set_custom_tab_html("tab_name", "html")''' - Display output in a tab.
* '''append_custom_tab_html("tab_name", "html")''' - Display output in a tab.


First, you need to fetch the desired refles, using client.reflex_find_by_name(type, name, case_sensitive, enabled_only, package). The last three parameters are optional. For example: var el = client.reflex_find_by_name('alias', 'drop'); The name is entered into the Alias name / Trigger name / ... field that you haven't been using so far.
===== Buttons =====
* '''buttons_set_label(id, text)''' - Set the text label on a button.
* '''buttons_set_commands(id, cmds)''' - Sets the command sent to the game when the button is pressed.
* '''buttons_set_highlight(id, on_off)''' - Set whether the button is highlighted or not.
* '''buttons_set_default(id)''' - Reset a button to the default value.


The most useful option that this function provides is the ability to enable and disable various types of reflexes (including groups) in a script. To do this, you can use the '''client.reflex_enable''' and '''client.reflex_disable''' functions. For example: <code>var el = client.reflex_find_by_name('alias', 'drop'); client.reflex_disable(el);</code>. You can use el.enabled in conditions to check if a particular reflex is enabled.
===== Misc. =====
* '''to_number(val)''' - Convert a string number to a value.
* '''send_GMCP(message, arguments)''' - Sends a GMCP message to the game. Arguments are an object or string, depending on the GMCP call used - see the GMCP documentation for more information.


This functionality allows you to easily implement functionality such as one-time triggers. Simply use '''reflex_enable''' when you need to enable the trigger, and '''reflex_disable''' in the trigger itself, using the trigger's name so that the trigger disables itself.
==== Default functions ====
 
There are three functions which are called automatically by the client. These are '''onLoad''', called when the settings are loaded, '''onGMCP''', called upon receiving a GMCP message, and '''onBlock''', called upon receiving each text block, allowing you to perform manipulations on it, or kickstart functionality that you want to execute on every prompt.
=== Output text manipulation in trigger scripts and functions ===
 
In trigger scripts and functions called by triggers, you have access to the client.current_line, which can be used to modify the line that will be shown on the screen, similarly to how the built-in functionality operates. This functionality is suitable for more complicated cases, such as only highlighting if a certain condition is met, or displaying a result of some calculation.
 
To hide a line of text, simply set its gag property to true - client.current_line.gag = true;.
 
To colorize or change a portion of the text, you need to access the parsed line, using '''client.current_line.parsed_line''' or '''client.current_line.parsed_prompt''' (if the line is actually a prompt; note that prompts are not displayed by default). You can then use the '''colorize(start, end, color, background)''' and '''replace(start, end, newtext, color, background)''' functions to modify the line. "end" is the first index that is not colorized or replaced. For example, <code>client.current_line.parsed_line.colorize(10, 12, 'red', null);</code> would colorize the 10th and 11st character red.
 
'''client.current_line.parsed_line.text()''' allows you to retrieve the line text without any formatting - useful to determine the appropriate positions for the replacements.
 
=== Default functions ===
 
There are three functions which are called automatically by the client. These are onLoad, called when the settings areloaded, onGMCP, called upon receiving a GMCP message, and onBlock, called upon receiving each text block, allowing you to peform manipulations on it, or kickstart functionality that you want to execute on every prompt.
The function does not receive any data.
The function does not receive any data.


Line 50: Line 73:


The onBlock function can make use of the current_block variable, which holds the individual lines (current_block[0] is the first one, current_block[1] is the second one, and so on). The manipulation methods described with triggers are all applicable on these as well.
The onBlock function can make use of the current_block variable, which holds the individual lines (current_block[0] is the first one, current_block[1] is the second one, and so on). The manipulation methods described with triggers are all applicable on these as well.
*Nexus 3 uses nexusclient.current_block instead of current_block


=== Examples ===
==== Examples ====
[[GMCP Data|GMCPData]]: This example reads some data coming over via [[GMCP]] and assigns it to variables.
For some examples of functions, read the [[3.0_Examples|examples]] page.
</div>
<div class="large-4 columns">
{{Nexus_3_Sidebar}}
</div>
</div>
</table>

Latest revision as of 02:14, 21 June 2023

Functions and scripts represent the pinnacle of what the Nexus client can provide in terms of power and customization, albeit with higher complexity. These functionalities are programmed using Javascript, a versatile and widely-used language.

In this section, we will not delve into the details of coding in Javascript. However, we will introduce you to some of the built-in functions and guide you through creating your own custom code. This will empower you to enhance and refine your skill set for more intricate and responsive interactions.

Scripts vs. Functions

  • Scripts are specific code blocks that are fired as a result of a reflex being fired. This can be a trigger, alias, or keybind.
  • Functions are reusable code blocks that can be called from scripts or directly from the client's input.

Calling functions

Functions can be called from scripts by using run_function(name, args, package). As mentioned above, they can also be called directly from the client's input, so you'll want to make sure your functions are named in such a way that they do not overlap with in-game commands you may wish to use.

Variables

Scripts and functions are generally self-contained, variables are local to the code block and are cleared when the script or function finishes. To interact with variables used in the Simplified Scripting system, you'll want to use the built-in modules: get_variable, set_variable etc.

  • Functions called in a trigger receive information about the match: args.text, args.match, args.prefix, args.suffix, args.backrefs[1] ...
  • Scripts receive the backrefs (args[0]., args[1],. args[2], ...) and the current_package variable indicating the active package.

Built-in modules

Commands
  • send_command(input, no_expansion) - Send a command to the game. Set no_expansion to 1 to send the exact string to the game without expansion.
  • display_notice(text, fgcolor, bgcolor) - display a notice on the output screen.
Variables
  • get_variable(name) - Retrieve the value of a variable from the client's simplified scripting system.
  • set_variable(name, val) - Set a variable for the client's simplified scripting system.
  • delete_variable(name) - Delete a variable from the client's simplified scripting system.
  • inc_variable(name, by) - Increment a variable from the client's simplified scripting system.
  • dec_variable(name, by) - Decrement a variable from the client's simplified scripting system.
  • mul_variable(name, by) - Multiply a variable from the client's simplified scripting system.
  • div_variable(name, by) - Divide a variable from the client's simplified scripting system.
Reflex Manipulation
  • reflex_find_by_name(type, name, case_sensitive, enabled_only, package)) - Search for a specific reflex.
    • type - Type of reflex: 'alias', 'trigger', 'keybind', ...
    • name - Name to search for
    • case_sensitive - Whether the name needs to match case exactly
    • enabled_only - Set if disabled reflexes (including reflexes in disabled groups) should be ignored
    • package - Name if a package to search in; omit if searching in the main list
  • reflex_enable(reflex) - Enable a reflex (reflex is as returned by reflex_find_by_name above).
  • reflex_disable(reflex) - Enable a reflex (reflex is as returned by reflex_find_by_name above).
Output Manipulation (Trigger Scripts)
  • current_text() - An unformatted version of the line that fired the trigger.
  • gag_current_line() - Hide the line that fired the trigger from the output window.
  • colorize_current_line(start, length, fgcolor, bgcolor) - Colorize/highlight a specified part of the line that fired the trigger.
  • replace_current_line(start, length, newtext, fgcolor, bgcolor) - Replace a party of the current line with the specified text and color.
UI Manipulation
  • client.register_custom_tab(tab,container_id) - Make a custom UI tab. Please note, this is unsupported.
Tab Display
  • set_custom_tab_html("tab_name", "html") - Display output in a tab.
  • append_custom_tab_html("tab_name", "html") - Display output in a tab.
Buttons
  • buttons_set_label(id, text) - Set the text label on a button.
  • buttons_set_commands(id, cmds) - Sets the command sent to the game when the button is pressed.
  • buttons_set_highlight(id, on_off) - Set whether the button is highlighted or not.
  • buttons_set_default(id) - Reset a button to the default value.
Misc.
  • to_number(val) - Convert a string number to a value.
  • send_GMCP(message, arguments) - Sends a GMCP message to the game. Arguments are an object or string, depending on the GMCP call used - see the GMCP documentation for more information.

Default functions

There are three functions which are called automatically by the client. These are onLoad, called when the settings are loaded, onGMCP, called upon receiving a GMCP message, and onBlock, called upon receiving each text block, allowing you to perform manipulations on it, or kickstart functionality that you want to execute on every prompt. The function does not receive any data.

The onGMCP function receives two arguments - args.gmcp_method is the GMCP message name, args.gmcp_args are the parameters (if any).

The onBlock function can make use of the current_block variable, which holds the individual lines (current_block[0] is the first one, current_block[1] is the second one, and so on). The manipulation methods described with triggers are all applicable on these as well.

  • Nexus 3 uses nexusclient.current_block instead of current_block

Examples

For some examples of functions, read the examples page.

Important Links

Nexus 3.0 Documentation

The following links describe how to use the Nexus Client.

The Basics

Client Settings

Scripting

Retrieved from "https://nexus.ironrealms.com/index.php?title=Functions&oldid=1665"