The $EDIT system node is designed to be the central location for gaining control of editing an area's geometry. Any changes to an area via HeroBlade's toolset, such as placing or moving an asset (such as a tree, for example), go through the $EDIT node and associated server-side script. Additionally, scripts may use the $EDIT system node to directly manipulate the geometry of the area.
What problem(s) does this solve?
- Anything where the area's geometry is changed. For example:
- Placing assets
- Moving assets
- Exposes methods to other scripts, which allows for building an area via script-control, where a human does not need to be involved.
What problem(s) does this not solve?
- It does not address dynamically-modified objects such as mobile items like ships or wagons.
Area editing passes through script
All of HeroBlade's area-editing functionality passes through the $EDIT system node, allowing you to implement game-specific extensions and/or arbitrary restrictions about what is possible.
The $EDIT system node provides a collection of HSL methods which are collectively referred to as the Edit System. These methods comprise the HSL handler for all editing requests that the HeroBlade client sends to the server. The Edit System methods provided within the _editHandlerClassMethods script are:
unique method _GotEditRequest(editor as NodeRef, cmd as String, myNodeID as ID, fields as List of String, values as List of String, rawData as RawData)
This method is called when the client sends an edit command to the server.
unique method _HandleEditingError(error as String, editor as NodeRef)
unique method _HandleEditingInfo(info as String, editor as NodeRef)
unique method _HandleAreaImportDebug(s as String)
unique method _HandleAreaImportMessage(s as String)
unique method _AreaImportMerge(root as NodeRef, imported as NodeRef, oldToNew as LookupList indexed by ID of ID)
unique method _HandleEditingFailure(playerToNotify as ID)
Adding game-specific functionality
As a required class/script, it is not permissible to make changes to the _editHandlerClassMethods script. Instead, extension/overriding the script is accomplished by the creation of a game-specific class (and class methods script) that is GLOMmed onto the EDIT prototype.
- Create a new class
- Create a class method script for the class
- GLOM the class onto the prototype
Create a game-specific class
Using the DOM Editor create a new (server|client) class. Our recommendation is that you use a class name that incorporates the _editHandler as a suffix to the name (ex. HJ_editHandler), this makes it easier to locate the pair of classes (the required script prefixed in _editHandler and your game-specific class).
Once you have created the game-specific class, create a new client class methods script for that class.
Adding a game-specific class
Adding your game-specific class to the EDIT prototype is achieved using the System Node Configuration GUI or the CLI server command \mpac or client |mpac in the Console Panel. The System Node Configuration GUI is the preferred method because it handles the communication to update any instantiations of a system node to reflect the changes you have made.
Using the System Node Configuration GUI
Opening the System Node Configuration GUI requires you to access the hidden Utilities Interface toolbox, located in the top left corner of the render window with
ctrl-shift-click (or press
F5), which will open the Interface. On the Tools tab within the menu, is an option to open the System Nodes Configuration GUI.
See also: Adapting Clean Engine
Using the CLI
It is important to recognize that modification of the prototype from which a system node is instantiated will not update any instantiations that have already been made in various local GOMs. That means your changes will not take effect until the area (in the case of server system nodes) restarts, or the client (in the case of client system nodes), restarts.
\mpac EDIT, hj_editHandler;
|mpac EDIT, hj_editHandler;
Overriding the _editHandlerClassMethods script
The following methods may be overriden to provide game-specific, custom behavior.
method HE_PreEditRequest(editor as NodeRef, cmd as String) as Boolean // Used by SYSTEM.NODE.EDIT return false .
When overriding this method, the return value indicates if the edit request should be ignored. If the game-specific script returns false, the edit request will be canceled, and no edit will occur.
method HE_AreaImportMerge(root as NodeRef, imported as NodeRef, oldToNew as LookupList indexed by ID of ID) // Used by SYSTEM.NODE.EDIT // Using this implies the entire import merge is handled in here. .
method HE_AreaImportMergeTarget(assoc as Association, errors references List of String) as Boolean // Used by SYSTEM.NODE.EDIT return false .
method HE_HandleEditingError(error as String, editor as NodeRef) // Used by SYSTEM.NODE.EDIT .
method HE_HandleEditingInfo(error as String, editor as NodeRef) // Used by SYSTEM.NODE.EDIT .
method HE_HandleEditingFailure(editor as ID) // Used by SYSTEM.NODE.EDIT .
method HE_HandleAreaImportMessage(msg as String) // Used by SYSTEM.NODE.EDIT .
method HE_HandleAreaImportDebug(debug as String) // Used by SYSTEM.NODE.EDIT .
method HE_CompressedPathNodeDataChanged(node as NodeRef) // Used by $EDIT .
Controlling area editing
- See also: /HEEDIT
The MMO Foundation Framework implements a very basic method for controlling area editing with a mechanism for locking an area so that it rejects edit requests unless the editor's account is included in the "allow" list for the current area.
Locking area editing
Locking an area may be accomplished with the following command in the Chat Panel.
/heedit lock true
Removing an Area Editing Lock
/heedit lock false
Allow Editing By an Account
Accounts added to an "allow" list are permitted to make edits in an area that is otherwise locked to editing. Adding an account to the "allow" list is accomplished with:
/heedit allow <character name>
Remove an Account from Allowed List
Accounts may be removed from the "allowed" list with:
/heedit remove <accountID>
Via the Utilities Interface
- Open the Utilities Interface, by CTRL-SHIFT-clicking in the upper lefthand corner of the viewport
- On the Tools tab, choose Area Edit Locking
- To lock or unlock an area, check or uncheck the checkbox.
- To add an allowable editor, add their character name and click ADD. The character must be online.
- To remove an editor, click the "Remove" button next to their name.
The following are a few of the more commonly used server-side exposed functions. For a more comprehensive list, see the "editing" section of the server-side _ExternalFunctions script.
Edit Script Recreate Instance
external function EditScriptRecreateInstance(oldID as ID, editInstance as Boolean, instanceType as String) as NodeRef
This function will cause a script error if it is not called during the actual processing of an edit message. It creates a node with the given ID and class. If called in an edit instance, the node will be persistent. Since the ID is supplied to this function, ID conflicts can occur if not used properly.
Edit Script Recreate Asset
external function EditScriptRecreateAsset(oldAssetID as ID, editInstance as Boolean) as NodeRef
This function will cause a script error if not called during the processing of an edit message. It creates a node with the given ID of class AreaAsset. If called in an edit instance, the node will be persistent. Since the ID is supplied to this function, ID conflicts can occur if not used properly.
Send Edit Request to World
external function SendEditRequestToWorld(editCommand as String, editNode as ID, fieldList as List of String, valueList as List of String)
This function sends an edit command to the world server, though since the world server does not have geometry, it is unlikely that this function will be used. The editing player is not set for the execution of this command.
- Adapting Clean Engine - Detailing the replacement/extension of clean engine via game-specific classes and the GUI created for that purpose.
- System Nodes - Primary mechanism for enabling the extension/overriding of the required clean engine implementations and a game-specific implementation of a licensee.
- World Knowledge for System Areas - Technical details on using the world system node to access information normally only known on the world area server in a system area.