Skip to content

Experiments

Jump to bottom Edit New page
jwvanderbeck edited this page May 4, 2015 · 11 revisions

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.

Typically 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 phase, 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.

However experiments can also be what are known as open ended experiments. In this type of experiment, there is not defined amount of data needed to complete the experiment. Instead once the player starts the experiment, it continues to run, constantly transmitting the research back to KSC for small bits of science over time. The experiment will continue to run like this until the player pauses it, or the defined maximum data cap is reached.

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: If greater than 0, the amount of research data that must be accumulated to complete a standard experiment. **One of requiredData or maximumData must be above 0. Which one is determines whether the experiment is open ended or not.
  • maximumData - float: If greater than 0, the experiment is considered an open ended experiment, and this property indicates the maximum amount of research data, and indirectly science, the player can obtain.

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.
  • scienceValuePerData - float - default=0: Defines how much science the experiment is worth when transmitted. The total amount of science awarded is this times the amount of researchData collected.
  • 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.
  • dataPerPacket - float - default=0: Defines the overall transmission size of the data by specifying how much research data can be transmitted per packet.
  • canFailAtAnyTime - bool - default=false: By default an experiment can only be failed (based on conditions) during the research phase. By setting this property to true, the experiment can be failed at any time.
  • transmitValue - float - default=1: Indicates how much research data can be transmitted for science gains, versus how much needs to be recovered. A value of 1, the default, means 100% of the data can be transmitted for science. If the value is less than 1, then some portion of the data is held back and science is only gained on that portion when the craft is recovered.

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

Add a custom footer
Add a custom sidebar
Clone this wiki locally