$ASSOCIATIONS

From HEWIKI
Jump to: navigation, search

Contents

The System Node $ASSOCIATIONS exposes wrappers for the external functions dealing with associations, allowing for additional functionality to be layered on top of the external function such as providing notification to the class methods scripts for the source and target nodes.

What problem(s) does this solve?

What problem(s) does this not solve?

Concepts

$ASSOCIATIONS is a System Node

System nodes were adopted as the primary mechanism at the HSL script level enabling game-specific implementations of a licensee to extend/override the required functionality included in Clean Engine. As with all system nodes, this is accomplished by GLOMming a game-specific class on the ASSOCIATIONS prototype from which a singleton node $ASSOCIATIONS is instantiated for a particular local GOM.

$ASSOCIATIONS Exists on Both Client and Server

The $ASSOCIATIONS system node is both a Client as well as a Server System node, so you can call its methods in both client and server scripts.

Usage

Adding game-specific functionality

As a required class/script, it is not permissible to make changes to the _associationsClassMethods 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 ASSOCIATIONS 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 _associations as a suffix to the name (ex. HJ_associations), this makes it easier to locate the pair of classes (the required script prefixed in _associations 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 ASSOCIATIONS 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

UtilitiesInterfaceConfigureSystemNodes.jpg

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.

Adding a class to a prototype is done via the CLI command Modify Prototype Add Class(MPAC).

Server: \mpac ASSOCIATIONS, hj_associations;
Client: |mpac ASSOCIATIONS, hj_associations;


Add an Association

The method has an identical signature to the external function AddAssociation and has a leading "_" for its name.

$ASSOCIATIONS._AddAssociation( source, associationType, target )

Following the Association operation, a call is made to the class methods scripts comprising the source and target nodes in a shared function _OnAddAssociation, allowing the class methods script to perform additional setup if required.

Remove an Association

The method has an identical signature to the external function RemoveAssociation and has a leading "_" for its name.

$ASSOCIATIONS._RemoveAssociation( source, associationType, target )

Following the Association operation, a call is made to the class methods scripts comprising the source and target nodes in a shared function _OnRemoveAssociation, allowing the class methods script to perform additional setup if required.

Calls to the Class Methods scripts

Called when an association is established between a source and target using the $ASSOCIATIONS class methods. Both source and target receive notification.

shared function _OnAddAssociation( this as NodeRef, source as NodeRef, AssociationType as String, target as NodeRef )
// Called following the addition of an association via the $ASSOCIATION system node's wrapper methods
//   Both source and target nodes receive calls to the class methods scripts for each of the classes that make up the node
//
//   THIS is set to what would normally be the "me" node in a method
//     IE when calling the shared functions in the class methods for the source node, THIS = SOURCE
//        likewise when calling the shared functions in the class methods for the target node, THIS = Target
.

Called prior to removal of an association between a source and target using the $ASSOCIATIONS class methods. Both source and target receive notification.

shared function _OnRemoveAssociation( this as NodeRef, source as NodeRef, AssociationType as String, target as NodeRef )
// Called prior to the removal of an association via the $ASSOCIATION system node's wrapper methods
//   Both source and target nodes receive calls to the class methods scripts for each of the classes that make up the node
//
//   THIS is set to what would normally be the "me" node in a method
//     IE when calling the shared functions in the class methods for the source node, THIS = SOURCE
//        likewise when calling the shared functions in the class methods for the target node, THIS = Target  
.

Leveraging $ASSOCIATIONS with the Asset Library

The Asset Library has the capability to run arbitrary commands immediately following the instantiation of an object (or group of objects) from a library entry. We can use that capability to run a command that interfaces with the $ASSOCIATIONS system node to associate the nodes to each other or to some system node.

Asset Library index numbers

When multiple items are grouped together to create a library object, they added in the order in which they were selected with the selection tool. When a library icon is clicked to add those objects to the world, they are recreated in the same order. You may use the index of an object in that ordered list to specify a particular instance.

LibraryIndex.jpg

/HEASSOCIATIONS Command

The command /heassociations has a variety of types of functionality, but the particular capability in which we are interested is the capability to take a list of instantiations created from the library, and selectively associate the created nodes to each other or to system nodes.

/HEASSOCIATIONS LIBRARY $GUIDS OPERATIONS operation1;operation2
Used to perform association operations from the Library. Each operation is delimited via a semi-colon(;).
OPERATION - Operations consist of a comma-delimited list of <source>,<associationType>,<target> with no whitespace and are separated from one another via a semi-colon(;).
<source>,<associationType>,<target>
<source> - Accepts the name of a system node, or an ID. In the case of the LIBRARY option, two additional options are a library index number or asset name.
<target> - Accepts the name of a system node, or an ID. In the case of the LIBRARY option, two additional options are a library index number or asset name.
<associationType> - Accepts an association type defined in the DOM, it is recommended you generally not use hard associations when working with area assets because of the engine's specific expectations for the structure of an area's assets.
Example: /HEASSOCIATIONS LIBRARY $GUIDS OPERATIONS 1,fooAssoc,2;$FOO,fooAssoc,3

Exercise

As a designer, say you want to create an object that consists of two spheres, the second one parented to the first. When the objects are instantiated from the library, you want to associate them both to the system node $FOO via a new association fooAssoc.

Steps to this exercise:

Create Server Association

Using the DOM Editor or the CLI, create a soft association named "fooAssoc" that is +unique and +uniqueSource.

Create a Library Object

Using the Asset Library, create a new library object from two of the Clean Engine asset sphere.gr2. Parent the second one to the first, then select both and add them to the library.

GLOMSphereLibraryObjectExample.jpg

Now we need to create the library command that will associate the spheres to the $FOO system node.

/HEASSOCIATONS LIBRARY $GUIDS OPERATIONS $FOO,fooAssoc,1;$FOO,fooAssoc,2


Now whenever we add the spheres via the Library Object, our spheres will automatically be associated to our $FOO system node and the class methods script for $FOO will be notified so that they may perform additional operations if required.

Appendix A: Associating Library Objects to System Nodes

When using the library command capabilities, it is possible to associate the newly created asset instances to a system node. It is important to understand, system nodes are not persisted and as a consequence even if the new instance is persisted the association will only exist so long as the local area GOM is running. Consequently, the most common usage for associating a library instance to a system node is to then catch the _OnAddAssociation() call in the system node's class method script to associate the instance(s) to the area root node or another child of its node hierarchy.

Reference

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox