Refactor Design
This document details the thoughts behind a refactor of RealScience. RealScience original was built mostly in a void, with a purpose to solve a specific annoyance that I had with the stock science system in KSP. While it was built fairly well, once exposed to other players its design started drifting and features that were never originally conceived shoehorned in. The end result is that RealScience right now it in a very messy half-baked state.
This document attempts to take another look at the over all design of RealScience and how it might be redesigned to be cleaner, and more flexible.
Instruments are essentially sensors that sample the environment, or a subject, and generate a specific type of data. That data is then used by a research experiment.
Instruments have three main properties, sampleRate which defines how many samples of data it can generate per second, bufferSize which indicates the size of the data buffer for storing data, and transferRate which indicates how many samples of data can be transferred out of the buffer and into research per second. Note that the transferRate is an optimum rate, but the actual transfer is driven by the research experiment that requests it, and it may not always be requesting data, so some data may build up in the buffer until such time as the experiment requests more.
On top of this there will be a sort of procedural parts type system where players can adjust, within configured limits, these properties on the instrument and thus affect the overall operating parameters and its launch costs. This introduces a sort of mini-game where you can balance instrument capabilities with cost, as well as balance multiple instruments to work together optimally for a given experiment. These properties will be controlled by a custom UI.
This system also allows for instrument progression. A thermometer in 1960 might be a lot slower for example than one in 2015.
A research experiment in a nutshell is the gathering of data from instruments under certain conditions until you have enough data to gain some value from it.
An experiment is a collection of research units, and therefore it is important to define just what a research unit is. A research unit is a collection of instrument readings that come in, and has a certain value when it goes out (out being when it is transmitted or recovered). So essentially you have to define two aspects of a research unit; what it is composed of, and what it is worth.
What is it Composed Of?
A research unit is composed of multiple individual instrument readings take under certain conditions. For example perhaps the research experiment is to monitor the physiological reactions of a monkey in sub orbital flight. This may perhaps entail instrument readings such as EKG, ECG, Galvanic Skin Response, Body Temperature, Hydration, and a visual record from a video camera. These are all instruments that generate data which the experiment then collects and collates as research data. One single unit of research data therefore is X amount of data samples from a defined collection of instruments. Each instrumentData line defines the instrument data needed, and how much of it is needed for a single unit of research. When the experiment has managed to collect all the individual instrument data specified, then one unit of research data is generated.
instrumentData
{
dataType = ecg
samplesRequired = 10
}
instrumentData
{
dataType = ekg
samplesRequired = 5
}
instrumentData
{
dataType = skinSensors
samplesRequired = 25
}
instrumentData
{
dataType = video
samplesRequired = 100
}
For certain experiments it may be desirable to limit how close together samples can be and still be useful. This is slightly different than conditions, as it is more of a restriction on how often the research data is gathered. For example, the experiment me be an atmospheric analysis where the player records temperature and pressure readings at various altitudes and you want to force them to collect data from various disparate altitudes instead of all at the same altitude. You can do this with one or more sampleLimit nodes. Internally this keeps a record of where each research unit was acquired, and based on the limitations will prevent the acquisition of another research unit if the craft is too close to a previous one. Important Note: This system requires keeping a record of where it has recorded in the past, and therefore can result in large data sets if the restrictions are too great. Consider the scales involved, and try to choose sensible limits. If you are trying to map a planet, don't set 1km limits, or else you would end up with millions of sample points and the entire system would probably crash KSP. Limitations that result in a few thousand points at most should be used. As a safety measure you can, and should, specify maximumDataPoints in the definition. If found, then the system will restrict itself to collecting only that many points total and if it needs to collect more, the oldest will be thrown out.
sampleLimit
{
limitType = altitude
distance = 10000 // This would be 10km of altitude
maximumDataPoints = 5000
}
sampleLimit
{
limitType = latlong
distance = 10 // This would be 10 degrees of latitude or longitude
maximumDataPoints = 5000
}
What is it Worth? To define the value of a research unit, instead of a simple property, we will use a ConfigNode. This allows for more flexibility, and will be key for example in defining differing science schools at a later date.
researchValue
{
reward = science
value = 5
transmitValue = 0.8
recoverValue = 0.2
canTransmit = True
}
researchValue
{
reward = contract_configurator
value = 1
transmitValue = 1.0
recoverValue = 0.0
canTransmit = True
}
researchValue
{
reward = custom_science
school = Physics
value = 1
transmitValue = 0.0
recoverValue = 1.0
canTransmit = False
}
Once the size and value of the research is determined, it is necessary to define how much of it the experiment requires. Here, there are three values; the minimum required to successfully complete the experiment, the maximum allowed before the experiment auto-completes, and the queue size, which indicates how much research data is accumulated internally before an analysis & transmit cycle is initiated. These are indicated in research units, with the properties minimumResearch, maximumResearch and researchQueueSize respectively.
Once started an experiment goes through a life cycle of sorts. This is a continuing loop of research, analysis, and transmission. This happens each time the research queue fills up. The first such cycle however will not happen until the minimumResearch value has been reached. Each time the transmission of research data happens, the player receives the specified rewards for the data sent in that cycle. The cycle continues until such time as the player stops the experiment, or the maximumResearch amount is reached, whichever occurs first.
Note that this asynchronous cycle always happens, but if you would rather the experiment be run in a more linear, synchronous manner where the player first gathers all the research, then analyzes it, then transmits it, and then is done, you can achieve this quite easily by setting the minimumResearch, maximumResearch and researchQueueSize values to the same value.
A much more complete view of the system can be seen in this image, which is a diagram of the state machine used.
Beyond defining the properties of the experiment, you also define under what conditions it may be researched. After all you can't do the research just anywhere whenever you feel like it. Research needs to be done in certain conditions, and experiment conditions let you define that. Research data can only be acquired when all specified conditions are met.
Failure Conditions Conditions can also be defined to cause failure of the experiment if met. If an experiment is failed, then it can not be restarted.
One thing to not lose sight of is how to handle experiments involving test on a physical subject returned from a mission. These types of thing at first glance don't really fit in well with the RealScience paradigm, but they can if we think outside the box a bit.
One possible way of handling these is that the player can return samples from a mission, and when they do those samples go into an inventory of sorts maintained by RealScience at KSC. Then the player can at will essentially do the same sort of experiments as normal on these samples, but instead of doing it on a flight, they do it in a special GUI right there at KSC. Possibly inside the R&D building if it is possible to hook into that. Samples should degrade with each experiment run on them, and they should have a finite amount somehow defined by what the player brought back.
Even better would be to set up a system whereby the player simply needs certain facilities required to perform these experiments. KSC would have the facilities by default. In early tech the player would not be able to build these facilities, but in later technology they would be able to build them but they would be larger modules perhaps the type of thing best suited for a research base but not on a craft. This allows "sample return" science to not only fit in perfect with the existing system, but not necessarily always require return to KSC. In real life we brought stuff back especially early on from the Moon, but today the rovers on Mars for example can do a lot of that itself.