t2:gpc_scripting:interactive_configuration

GPC Interactive Configuration

Interactive Configuration (IC) is the designation for the graphical user interface official Gamepacks use and user-made scripts can use, too.
It allows adjustment of script features without having to change the code of a script.1)

If you install a script to a slot of your Titan Two a gear icon will indicate if it has an Interactive Configuration:

This is what an IC will look like:2)

Basic Structure

The configuration descriptor is defined within the tag cfgdesc, in a commented block of the GPC code. The GPC compiler automatically scan the code, and any included header file, for an existing configuration descriptor when updating a memory slot, or publishing a script.

The configuration descriptor follows the very known INI format, which is constituted of:

  • sections, keys and values
  • Each section defines a configuration of your script
  • A section is identified by the configuration title within square brackets [ ] and must have an unique name
  • Following the definition of a section, are the pairs key = value that belongs to that section
/* This is a multi-line comment, the IC section begins in the next line.
<cfgdesc>
 
[unique section name]
key = value
key = value
key = value
...
 
[next unique section]
key = value
.
.
</cfgdesc>
The previous line closed the section
*/

The configuration descriptor itself does not increase your scripts bytecode size. Only the code needed for reading from/writing to it (pmem_load,pmem_read,pmem_write,pmem_save) adds to your scripts size.

Valid Keys

Key Description Required
group Group this control on previous section. Optional
Allowed values: true or false.
groupcol Create a new column and group this control on previous section. Optional
Allowed values: true or false.
color Sets the color of the title. Optional
The color must be specified using a hexadecimal value in the form: #RRGGBB, where RR (red), GG (green) and BB (blue) are hexadecimal values between 00 and FF.
border By default the 'info' control has non surrounding border, all other and groups have one. Use 'border' to change the default behaviour. Optional
Allowed values: -1,0,1 -1=default, 0=no border, 1=border
collapsible Allow collapsing of the control or group Optional
Allowed values: 1,2,3 1=collapsible, 2=collapsed, 3=hide/invisible
shortdesc Provide a short description for the section. You can use html tags to format the text, adding links, ..
you can create multiline shortdesc too:
shortdesc = <<<MULTILINE
Multi line text
can be written here.
MULTILINE
Optional
control Visual/Type of control to use. Mandatory for all sections.
Allowed values: info config space checkbox radiobox combobox spinbox spinboxf slider dial
byteoffset Defines where in the permanent memory array the configuration value should be stored. 3) Mandatory for all sections, except info.
Allowed values: from 0 to 127
bitsize Defines the size of the value, in bits. 4) Mandatory for all sections, except info.
Allowed values: 1, 2, 3, 4, 5, 6, 7, 8, 16, 32
bitoffset Defines the bit position where the configuration value should be stored. 5) Mandatory when bitsize is less than 8.
Allowed values: 0, 1, 2, 3, 4, 5, 6, 7
default Defines the default configuration value for the section or the height in pixels for space. Mandatory for all sections, except info.
item List the items name available in the section. Mandatory for config, checkbox, radiobox, combobox.
minimum Defines the minimum value acceptable in this configuration. Mandatory for spinbox, spinboxf, slider, dial.
maximum Defines the maximum value acceptable in this configuration. Mandatory for spinbox, spinboxf, slider, dial.
step Defines the increment/decrement step value. Mandatory for spinbox, spinboxf, slider, dial.
decimals Defines how many decimal digits to display. Optional for spinboxf.

Examples

"Configuration Discriptor"

Search in the Online Resource for “Configuration Descriptor” to get an example by J2kbr that contains all available controls including code to read the settings from the IC into variables.

"Spinboxf 16bits"

A small special example to use a spinboxf control for decimal numbers using bitsize=16 to save some PMEM storage space.

fix32 bitsize=16 value range is -127.99 to 127.99
fix32 bitsize=32 value range is -32768.000000 to 32767.999985
/* Interactive Configuration descriptor
<cfgdesc>
[Stick Deadzone]
group      = true
shortdesc  = Deadzone
byteoffset = 1
bitsize    = 16
control    = spinboxf
default    = 432
minimum    = 0
maximum    = 2000
step       = 1
decimals   = 2
</cfgdesc> 
 
*/
 
fix32  DZone;
 
init {
    pmem_load();
DZone= pmem_read_int16tofix32(1); // read "fix16" value from byteoffset 1
printf("val: %f",DZone);
}
 
// read fix16 from pmem position ( read int16 and return it as fix32 )
fix32 pmem_read_int16tofix32 (uint8 pmem_location) {
  int16 valInt16;
  pmem_read(pmem_location, &valInt16);
  return (fix32)valInt16 / 256.0;
}
 

Error Checking & More

IC-Bytetable , available through the Titan Two Download Page 6), is a tool for Interactive Configuration definitions. Features:

  • Error Checking
  • Overlapping memory usage of sections
  • Missing mandatory keywords
  • and more
  • Overview of persistent memory usage with detailed listing to spot free offsets easily
  • Input of values and export of all or selected only for easy creation of config = control presets
  • Import of config-strings (export of Interactive Configuration settings) with validation

This tool does not check your scripts code.
It only checks the Interactive Configuration descriptor section, that is the code between the tags <cfgdesc> and </cfgdesc>.

IC-Bytetable Forum Post for getting help and release information

1) Only for features the script author has specified to be adjustable
2) The available options and layout depends on the configuration descriptor definition the script author has created
3) , 4) , 5) Read Data Types for the bitsize of the data types and Persistent Memory to avoid overlapping byteoffset/bitoffset usage
6) For Windows Only
t2/gpc_scripting/interactive_configuration.txt · Last modified: 2019/09/09 03:20 by scachi