Game Development Community

dev|Pro Game Development Curriculum

Plastic Gem #36: Plastic Tweaker Comments

by Anthony Rosenbaum · 08/11/2008 (6:36 am) · 1 comments

Download Code File


i936.photobucket.com/albums/ad202/vincismurf/banner.jpg


Plastic Tweaker II: Comments

Difficulty: Moderate

This article is designed as a follow up to Plastic Gem 35:Plastic Tweaker. Since the Plastic Tweaker is so involved we have saved some of the finer details for this and future gems. Here we will specifically discuss tweaker comments, the Tweak Property Window (TPW), and the Tweak List Editor (TLE).
The Plastic Tweaker exposes an object's properties and/or global variables to the Plastic Tweaker so that designers and artist may adjust values as they see fit, without having to open up the code. Some tweaks will have default set for objects' properties others however will need some adjusting, which is easily done either by typing in a comment or using the Tweak Property Window.


All the code presented here can be found in the tweakerComments.cs found in the zip. To follow along place tweakComments.cs in the root of your project's game folder ( where server/client/data folders are), load the app, in the console (~) type
exec("GAMENAME/tweakerComments.cs");
followed by Ctrl + T to bring up the Plastic tweaker, and switch panels to tweakerComment

Tweak Property Window (TPW)
Initially in the Plastic Tweaker had to type in sophisticated comments to tweak with the GUI interface. The TPW changed that; it is a glorified comment editor. First off let's look at what a sophisticated comment looks like

www.plasticgames.com/research/Tweaker/tweaker_img/tweakpropwind.png
//M[ tweakerComments
$num = "2"; //  TypeS8 (range=0 100) (values=10|20|30) (flags=S) test for  S8 type 
//M]


That is a lot to swallow, there are four distinct areas in this comment. It is good to mention none of these comments are required, and with the TPW they can be dynamically added. Another note is a comment MUST have a space after the statement's semi color AND a space after the comment operator. Each area is also space separated and if you want to set a type it must be in the first area. Those are the rules.

Types
The first area is used to set a Type for the tweak, these are used to choose a unique GUI control. Setting a Type is optional but if it is provided it must be the first area in the comment line. Tweaks which are established from the source code like datablock properties will be intrinsic, meaning they cannot be changed to another type.

Supported types are:
TypeString = editable text field 
TypeFilename  =  browse file button
TypeS8  = slider
TypeS32 = slider  
TypeF32 = slider
TypeBool = dropdown and Ratio button
TypeColorF = color sliders amd button for Torque color picker
TypeColorI = color sliders amd button for Torque color picker
TypePoint2I = editiable text field button for plastic picker
TypePoint2F = editiable text field
TypePoint3F = editiable text field
TypePoint4F = editiable text field
TypeRectI = editiable text field button for plastic picker
TypeBox3F = editiable text field
TypeEaseF = editable text field, drop downs, graphic showing selection

//M[ tweakerComments
$numberS32 = 0; // TypeS32
$numberF32 = 0.0; // TypeF32
$colorF = "0.0 0.0 1.0 1.0"; // TypeColorF green by default
$colorI= "255 0 0 255"; // TypeColorI red by default
$bool= false; // TypeBool
$file= ""; // TypeFilename  
//M]

The next areas Range, Values and Flags are also optional and do not have to be in any particular order. They may be provided first if a Type is omitted, each will be space separated.

Range
Range is quite simple, if you are using a type which is a number you will be provided with a slider it will have a default range which you can adjust. The TPW allows you to set a range for the slider. In order to do so, be sure to check the range checkbox and provide a space separate min and max values in the text field , then click ok in the TPW

//M[ tweakerComments
$look = 0; // TypeF32 (range=-360 360)
//M]

Values
Values are a bit more complicated, values are used to populate a tweak's value dropdown box. You have 3 options; building a list, providing an array or providing a function.

The first method building a list is the most direct and requires no support coding. Lists are use a vertical pipe ( | ) as the delimiter in the lists. You have three ways of making a list, fist off you could provide it in a comment
//M[ tweakerComments
$Week  = "Monday"; //  (values=Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday)
//M]

Secondly you could manually type in the list with the separators in the TPW's values edit box (provided list radio button is checked)

Thirdly you can press the (. . .) button and open up the Tweak List Editor (TLE) . The TLE allows you to add modify and rearrange values used in the list. Once you are happy with the list press ok and the list will be filled into the values' text filed in the TPW.
www.plasticgames.com/research/Tweaker/tweaker_img/tle.png
The next way to populate a dropdown is via a predefined array. First build an array like so
$daysOfWeek[0] = "Monday";
$daysOfWeek[1]  = "Tuesday";
$daysOfWeek[2]  = "Wednesday";
$daysOfWeek[3] = "Thursday";
$daysOfWeek[4]  = "Friday";
$daysOfWeek[5]  = "Saturday";
$daysOfWeek[6]  = "Sunday";

You can manually associate the array to the tweak via the comment like so.
//M[ tweakerComments
$Week = "Monday"; // (values=$daysOfWeek)
//M]
To set the array thru the TPW, be sure the values box is checked, select the array ratio button, and then select or type in the global array from the combo box. When you click ok in the TPW you will see your array has populated the dropdown list on the tweak line. The array must exist and have index 0 populated for it to be considered a valid array.

Finally the last way to set the values in a dropdown is with a function. Functions should be designed to take one parameter and will return strings to be used to populate the tweak dropdown. Functions must exist before attaching them to a property. Each function will be executed in an loop up to one thousands times. In order to break the looping return an empty string

function someTweakFunction(%ind){
	if(%ind $= 0) return "none";
	if(%ind $= 1) return "tom";
	if(%ind $= 2) return "dick";
	if(%ind $= 3) return "harry";
	return  "";
}
//M[ tweakerComments
$culpret = "none"; // (values=someTweakFunction) provide values for dropdown
//M]

Labels
You can allow the values to behave as an enumerator by making each value a combination of numerical value space separated by a string. To do so turn on the labeling checkbox, each value should be designed to start with a numerical value followed by the string which will be the label, the number and string should be space separated.

$lableArray[0] = "0 zero";
$lableArray[1] = "10 ten";
$lableArray[2] = "20 twenty";
//M[ tweakerComments
$amt= "none"; // TypeF32 (values=$lableArray) (range=0 100) provide values for dropdown
//M]

Flags

Flags provide another layer of sophistication within the comments; they are used for display settings on a panel on the Plastic Tweaker. They tell the Plastic Tweaker if the value has labels, is hidden or is followed by a separator here are a few examples of Flags, Flags can be arranged in any order you wish.

//M[ tweakerComments
$flagArray[0] = 0; // (flags=S) Tweak with separator
$flagArray[1] = 0; //  (flags=LS) Tweak with labels and separator
$flagArray[2] = 0; // (flags=S) Tweak with separator
$flagArray[3] = 0; // (flags=H) Tweak Hidden
$flagArray[4] = 0; // (flags=HL) Tweak with labels, Hidden
$flagArray[5] = 0; // (flags=HSL) Tweak with labels and separator, while Hidden
//M]