/REGISTER

From HEWIKI
(Redirected from Technical:/REGISTER)
Jump to: navigation, search

/REGISTER <action> <command> <SCRIPT=""> [+/-WORLD] [DESCRIPTION=""]

Arguments

<action> 
One of the following options:
  • ADD - Link a new command to a server-side script
  • MODIFY - Modify an existing command
  • REMOVE - Unlink an existing command from a script
  • LIST - Lists all currently registered commands, in order
  • FIND - Gives info on the selected command
  • MOVE - Manually sorts the verb into the list
  • CHECK - Checks all commands to ensure that their scripts are still valid
<command> 
No spaces. Must start with a forward slash, and be at least three-characters long. Not case-sensitive.
SCRIPT="<script>" 
The name of the script to connect to the verb. Must be contained within double-quotes
+/-WORLD 
(optional) Specifies that the script will be used on the World Server, as opposed to an Area Server. If not specified, the default is Area Server
+/-PLAYER 
(optional) Indicates if the command can be used by players. For commands that cannot be used by players, a call is made to $PERMISSIONS._isAccountDeveloperCommandUser to verify the user is allowed to access the command.
DESCRIPTION="<description>" 
(optional) for internal use only, will not be displayed to players. Must be contained within double-quotes

Description

/REGISTER adds a command to the registry (if it doesn't already exist). Command strings in this system must meet the criteria of starting with "/" and being at least 3 characters long. The script given must be valid and must contain two or more of the appropriate shared functions:

shared function ProcessWorldInput(rci as Class RemoteCallIn)
  //  This is the shared function which commands should use if they are processed on the world.
.
 
shared function HE_ProcessCommandInput(account as NodeRef, input as String)
  //  This is the shared function which commands should use if they are processed in the area.
.
 
shared function HE_CommandUsage(account as NodeRef, input as String)
  //  This is to be used for giving usage to a player.
.

The quickest way to create a command script is to create it using the template script cmdTemplate, either by copy and pasting the code from that script into your own or by choosing it as a template when you create your script.

NewScriptTemplateDialog.gif

If you do not have a templates option when you create a new script, you can add it by creating a folder in the Server and Client Script Organizers called Templates and then add any template scripts to it.

The first function, ProcessWorldInput, is only required if you set the command +world, which means a remote call is made and the script is called on the world server instead of in the current area server (current being the one the player that sent the command is connected to). If the command is set to -world (which is the default), then the second function, HE_ProcessCommandInput, is required instead. All commands are required to have the HE_CommandUsage function.

Creating a new command

/REGISTER ADD <command> <script=""> [+/-world] [+/-player] [description=""]

To create a new command:

1) Using template code defined in the cmdTemplate script, create a new server-side script for your command with an appropriate name. (For example, use the command name with a prefix of "CMD", like the /GO command's script could be CMDgo.)

2) The script should include one or more of the following shared functions depending on which server it will be running on:

Area Server level 
Include the shared function HE_ProcessCommandInput(player as NodeRef, input as String)
World Server level 
Include the shared function ProcessWorldInput(rci as class RemoteCallIn). rci should have its fields set as follows:
  • args - a lookuplist indexed by string of string, with "player" and "input"
  • player - set to the ID of the player who typed the command
  • input - set to the input string that was typed (including the command name)

3) (Both Area and World Server levels) Include the shared function HE_CommandUsage(player as NodeRef, input as String). This is used to display usage to the player, if appropriate. Details are up to individual licensees, but one way to handle this would be to link it to a /HELP system.

4) Compile the script.

5) Register the command using /REGISTER ADD <command> <script> +world. The server should generate a response that the command was created, or that it was already in use (in which case it'll be necessary to choose a different command).

Note that any new command should always generate output; otherwise the user won't know that their command went through.

Currently, when you add a command, it gets added to the end of the list for matching on input. There is a single sorted list of commands so that when a user enters a command only partially, the correct command can be matched. You can use /REGISTER list to see the sorted list, and you can use /REGISTER MOVE <command> BEFORE|AFTER <otherCommand> to shuffle its place in the list around. Full commands will always get matched before a partial match, however, so for example /who will always match on /who and not /whoall.

Listing commands

/REGISTER LIST [ALPHA] 

This outputs a parse-ordered list of all commands to the Chat window.

The optional parameter ALPHA puts the list in alphabetical order.

Modifying a command

/REGISTER MODIFY <command> [SCRIPT="<script>"] [+/-WORLD] [+/-PLAYER] [DESCRIPTION="<description>"]

This modifies an existing command. The same restrictions as adding a command apply. If you wish to modify the actual name of the command, you should instead use the REMOVE option and then ADD it back again with the new command string.

Find/Display a command

/register FIND <command>

This finds and displays the command's info (accepts partial match). It also finds the command, in parsing order. This can help you determine what command comes before another in the case of similarly named commands.

Move a command

/REGISTER MOVE <command> BEFORE|AFTER <otherCommand>

This moves the command in the list, which affects parse order. By default, commands are simply added to the end of the command list, which means all other commands will have a chance to be matched by parsing first. So if you have a command, "/sweet" already in the list, and you add the command "/swell", if someone enters "/swe" it will match against "/sweet" first. If you need to change that so that "/swell" is matched first (because it's a more commonly used command, or whatever) then use the MOVE option.

Example

/REGISTER MOVE /swell BEFORE /sweet 

is the same as:

/REGISTER MOVE /sweet AFTER /swell

Check commands

/REGISTER CHECK

This action checks all commands to ensure their scripts are still valid, and that the scripts have all of the required shared functions.

Note: It is possible that, if a script has been deleted, then checking its scriptref will throw a script error that the script code could not be loaded. In that case, it's usually best to undelete the script, completely comment it out and recompile/resubmit it. Once all scripts are in that state, and the CHECK option runs successfully, you will see a list of all commands that have invalid scripts or scripts with missing functions. For freshly undeleted scripts, you can probably REMOVE the command, then delete the script again. This is purely a maintenance function.

Removing a Command

/REGISTER REMOVE <command> 

This removes the command from the list of registered commands. It does not, however, delete the script. The command can be added again later, though it may be sorted differently when it is added anew.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox