Enhanced Chat Menu v3.02 - Developer's Manual

Introduction

This document is designed to aide scripters and voicepack makers in developing products to work with ECM. It assumes a moderate amount of knowledge on creating client scripts for the Tribes 2 game engine and in general. I have tried to make it as simple and as straight to the point as possible. If you have questions, please e-mail me at tracerdx@hotmail.com.

Table of Contents

• Voicepack Documentation
  • What is a voicepack to ECM?
  • Voicepack file orientation
  • Voicepack definition file
  • File header/directives
  • Menu definition commands
    • addVItem
    • startVMenu
    • endVMenu

Voicepack Documentation

This section describes how voicepacks are defined and implemented in ECM. It is very similar to existing voicepack protocols. The biggest difference is in the definition file. This is due to back, compatability with other voicepacks.

What is a voicepack to ECM?

To ECM, a correctly installed voicepack is a seperate entity from the actual V-Chat menu. When the user calls the voicepack's "root command", the voicepack is involked from that point and it's menu displayed to be traversed. The biggest point I'm trying to make here is that voicepacks are kept completely seperate from the ECM. They have their own objects and memory. This is why voicepacks do not need to be "rebuilt" when the menu changes. This is also why a user may have multiple voicepacks without the worry of 2 or more voicepacks with conflicting menu bind paths. (This is only a worry with the auto-bind feature, which attemts to create a root item in the user's menu at a specified location in the ECM. This fails if something exists there already, and the user is notified to manual create the root item).

Voicepack file orientation

A voicepack in ECM is a little bit simpler in definition than with other existing protocols. It consists of a single definition file, with very lax naming conventions and the actual wav files to be used. The only naming requirement is that the voicepack definition file end in a .cs as with all scripts in Tribes 2. The voicepacks definition file is stored at: /base/scripts/voicepacks/ The remaining files are the .wavs themselves. All voicepack sounds MUST be wav files. No other formats are supported. They go in the same spot all other protocols want them in: /base/audio/voice/custom/. That single definition file, if written right, will be found and executed by ECM automatically. There is no need for an autoexecution script for your voicepack. The fact that it resides in the voicepacks directory is all that is needed for ECM to know the file is there.

Voicepack definition file

The voicepack definition file is what tells ECM all about the voicepack and defines the what text will be bound to what sound and how the menu and submenus will be oriented. This is all done through rather intuitive list of commands in an executable script. The following sections will describe the various parts of a voicepack definition file. The following is an example of a definition file:

//#VOICEPACK
//#ID MyVoicepack
//#NAME My Awesome Voicepack
//#VERSION 1.4.9
//#AUTHOR TracerDX
//#DESCRIPTION This voicepack owns all voicepacks with its awesomeness.
//#DEFAULTKEY G:L

//Do not edit this file, thanks!

startVMenu( "1: First Submenu of Stuff" );
	addVItem( "Q: Howdy", "Howdy Son!", "howdy");
endVMenu();

startVMenu( "2: Second Submenu of Crap" );
	addVItem( "W: My Hair!", "My hair's on fire! My hair's on fire!", "haironfire");
endVMenu();

startVMenu( "3: Team Submenu" );
	addVItem( "A: Mortar Spam", "We've got incoming mortar spam!", "mspam", true);
endVMenu();

addVItem( "4: Pack Credit", "Using the Awesome Voicepack. Get it at www.myfreakingwebsite.com", "");

File header/directives

The first part of the voicepack definition file is it's header. The header contains "directives" that will tell ECM about the voicepack before it even executes the file. The first thing ECM does is scan the /base/scripts/voicepacks/ directory for valid voicepack definition files. If the right headers are not present, ECM will not even bother to execute the file or list it in the voicepack listing. That is why it is very important to make sure your definition file's headers are correct. The following is an example of a valid voicepack definition file's header directives:

//#VOICEPACK
//#ID MyVoicepack
//#NAME My Awesome Voicepack
//#VERSION 1.4.9
//#AUTHOR TracerDX
//#DESCRIPTION This voicepack owns all voicepacks with its awesomeness.
//#DEFAULTKEY G:L

• //#VOICEPACK - This directive tells ECM that this is a voicepack file. This must start at the VERY FIRST CHARACTER of the the voicepack definition file! If ECM does not read this directive on the first line of the file, exactly as it appears here, the file will be IGNORED COMPLETELY. This keeps ECM from accidentally scanning in files that weren't meant as voicepacks. It also speeds up the process of skipping over bad files as it does not waste time looking any further if this line is not present.
• //#ID - This gives ECM a unique identification string. This string is used in ECM's user's menu definition file to index a voicepack root item. This unique ID allows you to change the //#NAME property of the voicepack in future versions without having to make the user re-establish his/her root voicepack entries. It is also used, because there is no guaranteed order in which voicepacks will be loaded, so ECM cannot store entries over multiple sessions (ie Tribes goes on, Tribes goes off, Tribes goes on again) because numeric indexes may change with new voicepack installs, thus screwing any numeric indexing. Note: It is a good idea to use a good ID. By good, I mean one that is guaranteed to be unique. An ID of "voicepack" is not a good idea. If the user installs 2 voicepacks with the same ID, he/she will not be able to create a voicepack root entry for one of the voicepacks.
• //#NAME - This will define the display name of the pack. This is what the user will see as the label for your voicepack in all of ECM's GUIs.
• //#AUTHOR - This is where you would put your name or warrior name. It is displayed to the user when he clicks on the ABOUT button for your voicepack
• //#DESCRIPTION - Here you can write a little blurb about your voice pack, describe it, give shout-outs, etc. It is displayed to the user when they click on the ABOUT button for your voicepack
• //#DEFAULTKEY - This is used by ECM's auto-bind system to attmpt to automatically create a "voicepack root" to a point on the user's menu. In the example file, G:L means it is to be bound to VGL or as Item "L" under the submenu "G: Global". This is made under the assumption that the user has a "G" menu. If the G menu does not exist or there is already a "L" command under the "G" menu, then the auto-bind will fail, and the user will be notified to acomplish the bind manually.

Voicepack Definition Commands

A voicepack is defined by calling functions in sequence. There are only 3, but that's all that is needed to define a voicepack for ECM. The commands are described below.

addVItem

// Defines an item in the current submenu that will send a voicepack bind.

// SYNTAX:
addVMenu( Menu_Item_String, Text_String, Wav_File_Base, [Is_Team_Bind] );

// Menu_Item_String - Consists of a Key followed by a ':' followed by a label. Everything before the ':' is the key description.
//                    Most of the time this is a single character representing a letter on the keyboard, but you may also use
//                    descriptors like 'TAB' or 'ALT', Ex. "A: A Voice Bind" or "TAB: A Voice Bind"
//
// Text_String      - This is the text that will be displayed when this voice bind is "said".
//
// Wav_File_Base    - This is a base of the .wav file that is played when this voice bind is "said". By base I mean with the the
//                    path and without the .wav extension. That information is assumed and added by clients with voicepack support.
//                    Ex. "BigBoom" resolves to "base/audio/voice/custom/BigBoom.wav"
//
// Is_Team_Bind     - When this is set to true, the voice bind will be "said" to only team memembers. This is good for voicepacks
//                    that use status messages. If omited, the bind will be a "global" one.

startVMenu

// Defines an item in the current submenu that will call another submenu. All addVItem and startVMenu commands that are called
// after this will be made part of this new sub menu until a endVMenu(); is called.

// SYNTAX:
startVItem( Menu_Item_String );

// Menu_Item_String - Consists of a Key followed by a ':' followed by a label. Everything before the ':' is the key description.
//                    Most of the time this is a single character representing a letter on the keyboard, but you may also use
//                    descriptors like 'TAB' or 'ALT', Ex. "A: A Voice Menu" or "TAB: A Voice Menu"

startVMenu

// Terminates the current submenu and returns to binding all following addVItem and startVMenu commands to the parent menu.

// SYNTAX:
endVItem();