SoftSkies' scripting capabilities allow you to specify the appearance and behavior of the SoftSkies visualizer dynamically. Scripts written for SoftSkies, here referred to as "configs", allow you to create unique scene configurations on the fly using your own custom algorithms or by incorporating features from existing SoftSkies config files.

A Very Quick Introduction to Python

     All of the config files discussed in this document use the Python programming language "under-the-hood", but there's no need to know Python to start writing config files. Simple config files need only execute the simple functions outlined in this file and do not require any Python knowledge. At the same time, advanced users will find that Python provides a very powerful way to extend the capabilities of the visualizer indefinitely. This document does describe some basic Python functionality required to implement simple configs for the visualizer, but it is not meant as a general introduction to the Python language. More information about Python can be found at https://www.python.org.

     Two simple notes about Python before continuing: first, Python is very sensitive to "whitespace" (spaces, tabs and newlines). Be careful to use spaces and tabs as they are shown in this document–code may not work if whitespace is missing or if excess whitespace is included. Second, any line in Python beginning with a "#" character (a "hash" or "pound") is considered a comment and does not effect the way a program runs. The examples below are thus commented using the "#" character to explain why things work a certain way.

The Simplest Config

     The simplest config files simply specify a fixed set of cloud parameters. We'll begin with a quick demonstration of how to create a simple config. This demonstation config will simply change the color of the clouds. Follow these instructions to create your first custom config:

• Locate your SoftSkies folder
• Go into the Configs folder
• Create a text file named "MyConfig.config"
• Add the following line to the file:
       SoundSpectrum.SetRGBColor( "cloud_color", 0, 0, 0 )
• Save the config file–make sure the extension .config is used (some editors may try to change the extension!)
• Launch SoftSkies and use the SoftSkies menu to go to the "Skies Library"
• Select the "MyConfig" button–the clouds should fade to black!

More Information on Simple Configs

     The simple config presented in the previous step simply sets the color of the clouds. Most configs modify a larger set of parameters. This section describes in more detail how variables are set. There are two main types of SoftSkies parameters: numerical parameters and color parameters. Numerical parameters are set using the function SoundSpectrum.SetParameter(). This function is passed either two or three inputs (also known as "arguments") which specify its behavior. The first two input values specify the name of the parameter being set (in quotes) and the new value for the parameter. The third input is optional: all parameter settings in the visualizer work by fading parameters over time and the third value, if it is given, specifies the number of seconds the fade should take. The default fade duration, if none is given, is 3 seconds. The following two examples show how a parameter is set both with and without a duration value:

# This will set the camera angle to 45 degrees
# over the course of 3.0 seconds
SoundSpectrum.SetParameter( 'cloud_camera_angle', 45 )

# In this example, we want the change to go faster,
# so we specify a shorter fade time:
SoundSpectrum.SetParameter( 'cloud_camera_angle', 45, 1.0 )

     These two different ways of calling the function SoundSpectrum.SetParameter() are summarized in the following line:

SoundSpectrum.SetParameter( 'parameter_name', value [, duration] )

The text in italics indicates that the text should be replaced with the value you wish to provide to the function. The value shown in brackets ( [] ) indicates that it is optional. This convention is used throughout this documentation to describe how functions are used.

     Color parameters are specified using a similar technique, except that color values each consist of three components and thus use different functions: SoundSpectrum.SetHSVColor() and SoundSpectrum.SetRGBColor(). Both of these functions use 3 color components with values from 0.0 to 1.0 to determine the color for a parameter. The two functions use different ways of thinking about colors, though both ways can be used to express any color.

     SoundSpectrum.SetHSVColor() uses the "hue saturation value" color model in which the "hue" specifies color, "saturation" specifies how vibrant the color is, and "value" specifies the brightness of the color. SoundSpectrum.SetRGBColor() sets colors using the "red green blue" color model in which the 3 color components are specified as red, green and blue intensity values respectively. Either of the functions may be used for any color parameter, though typically, certain tasks are more easily accomplished using one method or the other. As with simple scalar parameters, color changes fade over a certain period of time. An optional duration argument specifies over how many seconds a transition should occur:

SoundSpectrum.SetHSVColor( 'color_parameter_name', hValue, sValue, vValue [, duration] )
SoundSpectrum.SetRGBColor( 'color_parameter_name', rValue, gValue, bValue [, duration] )

     Some examples of these functions are shown below:

# Set the cloud color to 1, implicitly over
# 3.0 seconds (since we don't specify a value)
SoundSpectrum.SetRGBColor( "cloud_color", 0, 0, 1 )

# Set the cloud lighting factor to 4.0 over 1.1 seconds
SoundSpectrum.SetParameter( "cloud_lighting_factor", 4.0, 1.1 )

# Set the cloud camera angle to 0 immediately!
SoundSpectrum.SetParameter( "cloud_camera_angle", 0.0 )

     A full list of parameters which can be used with SoftSkies is shown in the following section.

List of User-Modifiable Cloud Parameters and Their Meanings

     Using the simple functions outlined in the previous section, you can modify all of the SoftSkies scene settings. This section describes all of the user modifiable parameters. The variables are divided into two groups: color parameters and numerical parameters. In parenthesis are the names of the parameters as they appear in the SoftSkies Skies Builder.

     The first table shows the color parameters which can be customized in SoftSkies. All colors can be expressed either as HSV or RGB color values with each element in the range from 0.0 to 1.0.

     This table describes all of the user-modifiable numerical parameters. Also shown is the recommended range of values for each parameter. The recommended range is the range that is used by the standard SoftSkies configs and is considered to be capable of producing reasonable cloud behaviors and appearances. You may experiment with values outside of the ranges given here with the understanding that it may produce undesirable results. The SoftSkies engine also implements its own limits which prevents parameters which may cause instabilities or internal errors. For this reason, values set far outside of the recommended parameter range may not have any effect at all.