Making Your Own Tools Tutorial
- This is an Advanced-level tutorial for tool creation. For easier tutorials, see Tutorials.
HeroEngine exposes virtually everything to manipulation by HSL, this facilitates the creation of systems and tools that might in another game engine require changes to the C++ code of the engine itself. The ability to modify the engine in fundamental ways through HSL highlights one of the greatest strengths of HeroEngine, that of a rapid iterative development style where code changes can be compiled and submitted nearly instantaneously.
Our philosophy at HeroEngine is to invest time in making good tools to increase the productivity of our content teams, as evidenced by the toolset that certainly has played a role in your choosing to license HeroEngine. Not only do we invest time in C++ tools, but we also spend the same effort in the HSL tools included in HeroEngine and those we create for our designers to create our game Hero's Journey. Consequently the designers for Hero's Journey can easily create new abilities, quests, special effects, and so on without ever touching any code via data-driven HSL systems manipulated by a sophisticated GUI.
The design requirements for the tools to build your game are dramatically different from the tools some other game might require. Consequently HeroEngine includes a variety of generic tools/systems as a part of the MMO Foundation Framework, while leaving you free to use the powerful capabilities of HeroScript Language to create the tools your game needs. Attempting to describe the tools you might implement would be impossible as they are driven by your game's needs, so this tutorial will instead use some of the tools included as a part of the MMO Foundation Framework as examples of ways you can use HeroEngine and HSL to implement a tool.
Tools may be designed to be as simple as a command you type into the chat panel whose text is parsed to produce some result to as complex as a data-driven UI whose data HSL interprets to do something. Other tools might be constructed to be executed by the Asset Library to perform complex setup of objects that designers place in your world.
For HeroEngine, we often design our tools initially to be commands invoked via the Chat Panel and then later on layer a UI to produce a more user-friendly interface.
Invoking a Tool
Creating a tool is useless without a way for your users to invoke the tool, depending on the design of your tool one method of invocation may be more appropriate than another. In many cases you may find the version 1.0 of a tool may be driven via a command line, while version 2.0 layers on a user-friendly UI.
There are several ways a tool might be accessed:
- a chat command line
- a GUI invoked via the HotSpot Menu
- a GUI invoked via the Asset Library
- calling a function in a script via the HeroBlade Console Panel
Chat Command Line
The major difference between the Chat Panel and the Console Panel is that chat is interpreted by the HSL system $COMMANDHANDLER, while the Console Panel is interpreted by the C++ client code for communicating to the fundamental framework of the engine such as the DOM and GOM via CLI commands.
Fundamentally, $COMMANDHANDLER allows you to register a command (ex /wave) to call a script that you specify at a particular shared function passing in the string the user typed. Once in script, you can parse a command to do anything.
Creating a new command:
- Create a new server script using the template script cmdTemplate
- Register the command using /REGISTER
Creating a command script
Using the Script Editor, create a new server script using the script template cmdTemplate. Creating a new script from a template script copies the code from the template into the new script providing a ready framework for you to modify for the particular needs of your script.
The newly created script should have code inserted similar to the following code:
shared function HE_ProcessCommandInput( account as NodeRef, input as String ) // The Command Handler calls this shared function based on a mapping stored on the COMMANDHANDLER prototype // which maps a /command to a script to call // args as List of String Tokenize( input, args ) if args.length < 2 HE_CommandUsage( account, input ) return . partialMatch toLower( args ) to "" // option 1 . to "" // option 2 . default HE_CommandUsage( account, input ) return . . . shared function HE_CommandUsage( account as NodeRef, input as String ) // NOTE, this style is much more efficient on the client than doing a seperate Msg() for each line. // This is because only a single label gets created in chat, rather than one per line. msg as String = "/COMMAND KEYWORD <parameter>$R" msg = msg + " - describe what this option does$R" Msg( account, msg ) . function Msg( account as NodeRef, msg as String ) $CHAT.CHATPLAYER( account, "", msg ) .
Creating the functionality for your command is as simple as parsing the input and implementing functionality based on the parameters supplied.
Register a Script as a Command
Once a script has been created with the proper shared functions declared, you can now register that script to be called when you type a particular command in chat.
In the Chat Panel type:
/REGISTER ADD /wave script="cmdWave"
Chat Command example
The MMO Foundation Framework command
/heglom is used to interface with the $GLOM system node supporting one way of performing node composition (dynamic addition of class(es) to a node). Typing
/heglom in the chat panel and hitting enter will cause the help for the command to be displayed (because the script processing /heglom defined that behavior).
The functionality of the command
/heglom is implemented in the class method script _glomClassMethods of the system node $GLOM.
Console Command Line
The console command line is typically used to issue CLI commands, debugging commands for HeroBlade, and other functionality that is directly interpreted by the C++/C# code. Consequently, you do not typically use the Console as an access point to a tool. The functionality that allows you to use the Console Panel to invoke a tool is the ability to CALL a function in a client script.
Invoking a function via the Console Panel:
CALL <scriptName> <functionName>
CALL <scriptName> <functionName>; [optional String Parameter]
CALL foo bar
CALL foo bar; someString
The HotSpot Menu is an HSL construct implemented to provide access to a variety of tools that are included as a part of the MMO Foundation Framework. As with other foundational components it is extensible allowing for the addition of your own tools to the UI.
The Asset Library is capable of running one or more arbitrary commands registered in the Command Handler System when a library object is used to add an instance (or instances to the world). Much like implementing a tool via a Chat Command, the code parses input and performs some code based on that parsing. The primary difference is that you may pass into the command the IDs of the instances created, allowing for extremely complex behaviors to be performed on the instantiations as they come into existence.
Library objects do not necessarily need to create instantiations, they may also be used to simply run an arbitrary command. Such a command may be used to invoke the GUI for a tool. In Hero's Journey, we use this capability to open our Mob Spawner interface that allows designers to create or modify a Mob Spawner parametrically. To use the library in this fashion, you must first create a command that can invoke your custom GUI.