Experiments

Experiments

The whole point of doing science is to do science! In order to do any science though, you must have an experiment. This page shows how to write a config to define an experiment.

Experiment config contains two main elements. The definition of the experiment itself, and the conditions under which the experiment can be conducted.

Experiment Definition

The experiment definition defines what the experiment is, how it should appear to the user, how much science it gives, how long it takes, etc.

Unlike in Stock KSP, experiments in RealScience are designed to actually take time. You need to perform the research, not just click a button at the right time.

Completing an experiment moves the player through three main phases:

1. Research
2. Analysis
3. Transmission

First the player needs to collect research data. This is usually where the bulk of the time will be spent. Research Data is an abstract concept, but represents the actual work of performing experiments and recording results. For defining the research phase of an experiment, you have two main properties. requiredData and researchDataRate. The first indicates how much research data the player needs to collect, and the second indicates the rate at which it is gained. The value is in data per second. Research data can only be collected while the experiment conditions are valid. Conditions will be covered later.

Once all the research data has been collected, the player needs to analyze the data. This is really just a time wasting phase, and can be as short or long as you desire. No resources are used during this pahse, and no conditions need be met. The property analysisTime simply indicates how many seconds the player must spend analyzing the data.

Lastly, once all the data is collected, and analyzed, the final results must be transmitted back to KSC to collect the science points. Data is transmitted just like any science experiment, and the size of the data for transmission can be defined by the dataSize property.

Experiment Properties

Required

• experimentName - string: Internal name for the experiment. Must be unique.
• experimentTitle - string: Player friendly experiment name show to the player.
• description - string: A full description of what the experiment is, its requirements, flavor text, etc.
• requiredData - float: The amount of research data that must be accumulated.

Optional

• discipline - string - default=science: Currently unused. This will be used in Phase 2 of RealScience to denote what type of points are being awarded for the experiment.
• analysisTime - float - default=0: Amount of seconds required to analyze the research data.
• scienceValue - float - default=0: How many points to be awarded for completing this experiment.
• researchDataRate - float - default=1: Amount of research data reward per second during the research phase.
• multiFlight - bool - default=false: Can this experiment be conducted over multiple flights? ##Not currently supported.**
• autoAnalyze - bool - default=true: Once the research phase is complete, should the experiment auto advance to analysis? If false, the user must initiate analysis manually.
• autoTransmit - bool - default= rue: Once the analysis phase is complete, should the experiment auto transmit the results? If false, the user must manually initiate transmission to complete the experiment.
• dataSize - float - default=0: Number of packets that must be transmitted to complete the experiment.

Conditions

Conditions are used to define the scope of when and where the player may do the experiment. For example you m ay be creating an experiment for a sounding rocket that is a study of the upper atmosphere. You might want to limit the experiment to only be doable when the craft is actually in the upper atmosphere, say between 50km and 100km of altitude. You could do this with an Altitude condition.

Any supplied conditions must be considered valid for an experiment to gather research data. Alternatively, condition groups can be used to provide more complex logic. You can not however mix bare conditions and condition groups. Choose one method or the other. For all but the most basic setups, you will most often use condition groups.

Each individual type of condition will have its own specific properties, and you will find links to the supported conditions below. All conditions do however have some basic common properties.

• conditionType - string: Indicates the specific condition you are defining. This is case sensitive and must be given exactly as specified in the specific condition documentation!
• restriction - bool - default=false: If true, then the condition essentially acts as an inverted condition. It means that in order for the condition to be valid it must not be met.
• exclusion - string - default=none: Valid values: fail|reset. This property only matters if restriction is true. In the case of a restriction being met, normally the experiment just pauses until the restriction is unmet. However, by setting an exclusion you can make the penalties a bit more severe. If set to fail and the restriction is met, the entire experiment is failed and can no longer be completed. If set to reset and the restriction is met, all collected research data is wiped, and the experiment must be started over.
• dataRateModifier - float - default=1: This can be used to modify the researchDataRate as defined in the base experiment. It is a multiplier, and thus a value of 1 means no change. You could for example use this to allow some conditions to be more favorable than others and result in quicker collection of data. Or the opposite.

Conditions must be placed inside the experiment config, and look like:

condition
{
    // condition properties
}

Condition Groups

Condition groups are simply collections of conditions in either an AND or an OR logical grouping that allows for more complex condition logic. There is no hard limit of the number of allowed groups, nor how many conditions they may contain. In order for an experiment to be continue, all given groups must evaluate as valid.

Condition groups have the same restriction and exclusion properties as defined above for conditions. When a condition is placed inside a group, these properties are ignored on the individual conditions, and the group value of these properties is used instead.

In addition to the restriction and exclusion properties, condition groups have the following property:

• groupType - string - default="or": Valid values: or|and. If group type is or then only one condition in the group must be valid for the group to be valid. Conditions are evaluated first to last and evaluation stops once one is found to be valid. If the group type is and then all conditions in the group must be valid for the group to be valid.

Like conditions, conditions groups must be placed inside the experiment definition, and will look somethign like this:

conditionGroup
{
    condition
    {
        // condition properties
    }
}

Supported Conditions

• Altitude
• Biome
• Body
• GeeForce
• Orbit
• Part
• Resource
• Situation