$GLOM

From HEWIKI
Jump to: navigation, search

Contents

The System Node $GLOM exposes wrappers for the external functions dealing with GLOMming, allowing for additional functionality to be layered on top of the external function such as initializing default values and receiving a callback to the class methods script.

What problem(s) does this solve?

What problem(s) does this not solve?

Concepts

$GLOM 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 the clean engine. As with all system nodes, this is accomplished by GLOMming a game-specific class on the GLOM prototype from which a singleton node $GLOM is instantiated for a particular local GOM.

$GLOM Exists on Both Client and Server

The $GLOM 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 _glomClassMethods 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 GLOM 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 _glom as a suffix to the name (ex. HJ_glom), this makes it easier to locate the pair of classes (the required script prefixed in _glom 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 GLOM 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 GLOM, hj_glom;
Client: |mpac GLOM, hj_glom;


Add a Class

Add a Class to a Node

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

$GLOM._GLOMClass( "className", targetNode )

Following the GLOM operation, a call is made to the class method script for the class just glommed in the shared function _GetGLOMDefaultValuesPrototype() allowing the class methods script to specify a prototype whose values should be used as the default values for the member fields of the GLOMmed class. If the method _GetGLOMDefaultValuesPrototype() is not implemented then $GLOM checks for existence of a well known prototype name for the class which is the <className> + OnGLOMDefaultValues.

After initializing the member fields (if an appropriate prototype was found containing the default values), a call is made to the shared function _OnGLOMClass() in the class methods script of the class that was just GLOMmed allowing for any additional setup/initialization.

Add a Class to a Prototype

CautionSign.gif It is important to note that due to the way DOM Coordination functions the mechanics for setting default values and performing a callback to the class method script are disabled for GLOM operations on a prototype.


The method has an identical signature to the external function GLOMClassToPrototype and has a leading "_" for its name. As with the external function, this results in a DOM Coordination event.

$GLOM._GlomClassToPrototype( "className", prototypeNode )

Calls to The Class Methods Script For the Added Class

Asking the class methods script for a prototype to be used to initialize the member fields of the added class to defaults stored in that prototype.

// This shared function would be one you implement in your class methods script
shared function _GetGLOMDefaultValuesPrototype() as NodeRef
// Called following a GLOM operation on nodes (not done for prototypes), allows the class methods script
//    to specify the prototype that should be used for the initial values of the class just glommed.  The
//    default behavior of the $GLOM system node is to look for a prototype named <className> + "OnGLOMDefaultValues"
  return None
.

Notification to the class methods script that the class was just added, passes in the node to which the class was added.

// This shared function would be on you implement in your class methods script
shared function _OnGlomClass( n as NodeRef )
// Called following a GLOM performed by $GLOM's _GLOMClass or _GLOMClassToPrototype methods
//   in the class methods script for the class that was just GLOMmed
//
//   This function is NOT called if you use the normal external functions, this flexible design permits you to
//   choose whichever method is most appropriate for your usage.  The external functions are of course
//   faster, but lack the extended functionality provided by $GLOM's wrapper methods.
.

Remove Class

Remove Class From a Node

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

$GLOM._RemoveClassFromNode( "className", targetNode )

Prior to removal of the class, a call is made to the class methods script for the class about to be removed to a shared function _OnRemoveClass().

Remove Class From a Prototype

The method has an identical signature to the external function RemoveClassFromPrototype and has a leading "_" for its name. As with the external function, this method causes a DOM Coordination event.

$GLOM._RemoveClassFromPrototype( "className", prototypeNode )

Prior to removal of the class, a call is made to the class methods script for the class about to be removed to a shared function _OnRemoveClass().

Calls to The Class Methods Script For the Removed Class

Notification to the class methods script of the class about to be removed.

shared function _OnRemoveClass( n as NodeRef )
// Called prior a Remove Class performed by $GLOM's _RemoveClassFromNode or _RemoveClassFromPrototype methods 
//   in the class methods script for the class about to be removed.
//
//   The function is NOT called if you use the normal external functions, this flexible design permits you to
//   choose whichever method is most appropriate for your usage.  The external functions are of course
//   faster, but lack the extended functionality provided by $GLOM's wrapper methods.
.

Specify Default Values

The external functions that perform GLOMming operations do not support any method for setting default values for fields in a newly GLOMmed class. Which means, all member fields of the newly GLOMmed class are at their uninitialized value (0, "", 0.0, NONE, etc).

Following the GLOM operation, a call is made to the class method script for the class just glommed in the shared function _GetGLOMDefaultValuesPrototype() allowing the class methods script to specify a prototype whose values should be used as the default values for the member fields of the GLOMmed class. If the shared function _GetGLOMDefaultValuesPrototype() is not implemented then $GLOM checks for existence of a well known prototype name for the class which is the <className> + OnGLOMDefaultValues (ex. FooOnGLOMDefaultValues).

// This shared function would be one you implement in your class methods script
shared function _GetGLOMDefaultValuesPrototype() as NodeRef
// Called following a GLOM operation on nodes (not done for prototypes), allows the class methods script
//    to specify the prototype that should be used for the initial values of the class just glommed.  The
//    default behavior of the $GLOM system node is to look for a prototype named <className> + "OnGLOMDefaultValues"
  return None
.

Leveraging $GLOM 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 $GLOM system node to add additional classes to one or all of those objects as well as setting default values if desired.

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

/HEGLOM Command

The command /heglom has a variety 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 GLOM one or more classes to any or all of the instantiations.

/HEGLOM LIBRARY $GUIDS OPERATIONS operation1;operation2
Used to perform glomming operations from the Library.
OPERATIONS
<target>:<class1>,<class2>,...N;
Operations consist of a target separated by a colon (:) with a list of classes following delimited by commas (,). Each operation is delimited from the next by a semicolons (;).
<target>:
LibraryIndex - Each object in a library entry is stored in an ordered list the index for a particular asset is called the LibraryIndex example - 1:foo,bar
FQN - You may specify the target by its FQN example - sphere.gr2:foo,bar
ALL - You may specify the operation should be performed on all instances created from the library for this library object example - all:foo,bar
Example: /HEGLOM LIBRARY $GUIDS OPERATIONS 1:foo;sphere.gr2:foo,bar;all:zipper
operation1(1:foo) - Glom foo on the first instance created
operation2(sphere.gr2:foo,bar) - Glom foo and bar on any instance of asset sphere.gr2
operation3(all:zipper) - Glom zipper on all instances created.
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 would like the first to have the class foo and the second the class bar GLOMmed to the instance.

Once instantiated, you want to initialize field values from prototypes specified by the class methods script for the respective classes.

Steps to this exercise:

Create Server Classes

Using the DOM Editor or the CLI, create two server classes named foo and bar. Once you have created the two classes, create a string field for each class fooString and barString adding each to its respective class.

Viewing each class via the DOM Editor you should see:

DomEditorFooClass.jpg DomEditorBarClass.jpg

Create Default Values Prototypes

Normally when a class is GLOMmed using the external functions, any field values in the newly added class are set to their "zero" value. That is to say, there is not an equivalent to the ideal of constructors. Using the $GLOM system node, we have the additional capability to support some constructor-like behaviors such as initializing member fields to some default values. To do this, $GLOM allows the class methods script for a class to specify a prototype to use for the default values.

So lets create our default value prototypes using the CLI command Create Prototype From Class(CPFC).

\cpfc foo, fooDefaultValues; description="Default values prototype for the wiki examples class foo." \cpfc var, barDefaultValues; description="Default values prototype for the wiki examples class bar."

Once created, we need to set our two string fields to have some default value, again we use a CLI command Modify Prototype(MP) to set the field values.

\mp fooDefaultValues; fooString="foo foo foo foo" \mp barDefaultValues; barString="bar bar bar bar"

You can verify your prototypes now store the default values you set using a CLI command Show Prototype(SP)

\sp fooDefaultValues

CLIShowPrototypeFooDefaultValues.jpg

Create the server class methods scripts

Using the Script Editor, create a server class method script for each of our classes; fooClassMethods and barClassMethods and add the HSL callbacks _OnGlomClass() and _GetGLOMDefaultValuesPrototype().

// fooClassMethods Script
shared function _OnGlomClass( n as NodeRef )
// Called following a GLOM performed by $GLOM's _GLOMClass or _GLOMClassToPrototype methods
//   in the class methods script for the class that was just GLOMmed
//
//   This function is NOT called if you use the normal external functions, this flexible design permits you to
//   choose whichever method is most appropriate for your usage.  The external functions are of course
//   faster, but lack the extended functionality provided by $GLOM's wrapper methods.
 
  // type cast the node so we can access its member field fooString
  where n is kindof foo
    // Display a println message in chat
    println( "Foo was just GLOMmed onto node(" + n + ") and has a default value(" + n.fooString + ")")
  .
.
 
shared function _GetGLOMDefaultValuesPrototype() as NodeRef
// Called following a GLOM operation on nodes (not done for prototypes), allows the class methods script
//    to specify the prototype that should be used for the initial values of the class just glommed.  The
//    default behavior of the $GLOM system node is to look for a prototype named <className> + "OnGLOMDefaultValues"
 
  return getPrototype( "fooDefaultValues" )
.
 
shared function _OnRemoveClass( n as NodeRef )
// Called prior a Remove Class performed by $GLOM's _RemoveClassFromNode or _RemoveClassFromPrototype methods 
//   in the class methods script for the class about to be removed.
//
//   The function is NOT called if you use the normal external functions, this flexible design permits you to
//   choose whichever method is most appropriate for your usage.  The external functions are of course
//   faster, but lack the extended functionality provided by $GLOM's wrapper methods.
 
  // Nothing we want to do yet
.
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.png

Now we need to create the library command that will glom foo onto the first sphere and bar onto the second.

/HEGLOM LIBRARY $GUIDS OPERATIONS 1:foo;2:bar

GLOMSphereLibraryCommandExample.pngGLOMSphereLibraryCommand.png


Now whenever we add the spheres via the Library Object, our classes will automatically be GLOMmed onto the appropriate instance and the member fields set to the default values as specified by the prototype declared in our class methods script.

When you add the spheres from the library you should see:

GLOMSphereAddFromLibrary.png

Reference

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox