Skip to content

JSIVariableAnimator

Jump to bottom
MOARdV edited this page May 25, 2016 · 4 revisions

What it does

This module will animate a prop or change its texture color according to the results of variable computation, interpolating the animation (or colors, or positions, or texture offsets) given between a minimum and a maximum value according to the output of a variable. The variables are the same as for the RasterPropMonitor (see Defined variables), though keep in mind that you can't use those that are returned as strings.

Where to use it

Use this module when you have a prop that needs an animation played on it, and at least one of the following is true:

  • The controlling variable is noisy (changes value frequently, such as ALTITUDE).
  • You want a continual ramp of animation (such as moving a gauge's needle gradually between two positions, instead of snapping instantly).
  • You want a blinking color effect (a flashing warning light).

How to use it

A single instance of the module can drive as many elements as you like, but configuration is slightly complicated:

	MODULE 
	{
		name = JSIVariableAnimator
		refreshRate = 3
		VARIABLESET
		{
			...
		}
	}

There is only one global module configuration parameter:

  • refreshRate -- Number of frames to skip between computing the variables.

Everything else is done in VARIABLESET blocks, and you can have as many as you like:

  • scale -- <variable or float value>,<variable or float value> -- the first variable or value corresponds to the beginning of the scale, second variable or value corresponds to the end of the scale.
  • maxRateChange -- The maximum change in the animation allowed per second. A '1' means it takes one second to cycle from off to on. Larger numbers mean shorter cycle times ('2' means 1/2 second), while smaller numbers mean larger times. This can simulate bulb fade and the physical limitations of mechanical movement. If not present, the animation can change instantaneously to any setting.
  • reverse -- A boolean. If true, the actuation of the scale will be reversed.
  • stateMethod -- Name of a RPM Buttons module and state method separated by a colon (eg JSIInternalRPMButtons:ButtonClearTargetState). This value will return a 1 or 0 depending on whether the method is true or false. Ignored if variableName is present in the VARIABLESET. For example, to drive a fuel gauge, you give it scale = 0,SYSR_LIQUIDFUELMAX and variableName = SYSR_LIQUIDFUEL.
  • variableName -- Name of the driving variable. This is actually something of a misnomer, in that it can also be a floating point number, i.e. you can drive a scale around a static number if you want to.

Once the scale is defined, you have a choice of four actuation modes. Only one of the four can be used in a single VARIABLESET block. There is nothing stopping you from applying multiple actuation modes to the same object in different VARIABLESET blocks, as long as they are all different actuation modes -- using multiple variable blocks to apply the same actuation to the same object is probably not going to give you satisfactory results.

Animation mode

  • animationName -- Name of the animation to run.
  • animateExterior -- If this variable is present, the animation is located on the exterior of the pod, otherwise, it is searched for on the prop itself.
  • loopingAnimation -- If this variable is present, the animation loops (plays continuously) when the variable animator is in threshold mode (see below) and the threshold conditions are met. If the variable goes out of the threshold range, the animation stops, and it is reset to the beginning of the animation loop (or the end if reverse is set).
  • animationSpeed -- How quickly a looping animation plays.

Animation mode is actually the easiest to use, since you define everything else in the Unity editor when defining the animation -- the beginning and end of the scale will correspond to the first and last frame respectively.

Color shift mode

  • coloredObject -- Name of the transform which will be color shifted.
  • passiveColor,activeColor -- Colors of the 'off' and 'on' state respectively. Mandatory if you wish to use color shift mode. Can be an RGBA sequence (eg, 128, 192, 192, 255) or Named Color.
  • colorName -- The name of the color property to drive in color shift mode. Defaults to _EmissiveColor.

The color shift mode will interpolate or switch between two color properties of a texture. Usually you want the _EmissiveColor, but not necessarily.

Rotation mode

  • controlledTransform -- Name of the transform that will be rotated.
  • localRotationStart,localRotationEnd -- <x>,<y>,<z> Rotations, in degrees, that will correspond to the beginning and end of the scale respectively. Notice that the initial rotation of the transform is remembered, these values are relative to whatever the initial rotation was.
  • longPath -- If the angle between your rotations is less than 180 degrees, rotation will go along the shortest path. Sometimes, this isn't what you want. In that case, you can longPath = yes, which will use a somewhat worse algorithm which will nevertheless correctly interpolate along the longer path.
  • modulo -- A numeric value that can be used to allow for sweep hands that make multiple laps, such as altimeter hands. This mode is explained more in the following text.

Some props include a component that goes around the face of a dial, such as the hands of an altimeter. Historically, those parts were configured with something like this (including only relevant parameters):

scale = 0,100000
variableName = SELECT_ALTITUDE
localRotationStart = 0,0,0
localRotationEnd = 0,36000,0
longPath = yes

In this configuration, the altimeter hand goes around the face of the dial 100 times between the 0 and 100000 meter altitude (it goes around the face of the dial one time for every kilometer of altitude). This is okay if the altimeter always reports altitude between those two values, but if the variable SELECT_ALTITUDE sets altitude to 0 if the craft leaves the atmosphere, then this animation will cause the hand to spin multiple times as it "unwinds" back to 0, which looks really bad.

By using the modulo operator, the hands can all go directly to 0 independently of each other. The localRotationEnd parameter has to change, and the modulo field has to be added:

scale = 0,100000
variableName = SELECT_ALTITUDE
localRotationStart = 0,0,0
localRotationEnd = 0,360,0
modulo = 1000
longPath = yes

This tells RPM that it should take the remainder of SELECT_ALTITUDE / 1000 and use that as the value to scale the rotation between start and end. In the above example, if the craft leaves the atmosphere and the altitude is set to zero, then the hands move directly to 0, instead of having to "unwind".

This feature can be used on props that cycle around the face once, such as a roll indicator hand, to prevent the odd-looking 'unwinding' effect when the roll transitions from +180 to -180.

Translation mode

  • controlledTransform -- Name of the transform that will be moved.
  • localTranslationStart,localTranslationEnd -- <x>,<y>,<z> Positions, that will correspond to the beginning and end of the scale respectively. Notice that the initial position of the transform is remembered, these values are relative to whatever the initial position was, and in scale based on the parent transform.

Scale mode

  • controlledTransform -- Name of the transform that will be scaled.
  • localScaleStart,localScaleEnd -- <x>,<y>,<z> Scales, per axis, that will correspond to the beginning and end of the scale respectively. Notice that the initial scale of the transform is remembered, these values are relative to whatever the initial scale was, and it is also relative to the parent transform.

Texture shift mode

  • controlledTransform -- Name of the transform the material on which will be affected.
  • textureLayers -- A comma-separated list of texture layers to affect, i.e. _MainTex,_Emissive.
  • textureShiftStart,textureShiftEnd -- <x>,<y> vectors denoting start and end positions of the texture offset.

Texture scale mode

  • controlledTransform -- Name of the transform the material on which will be affected.
  • textureLayers -- A comma-separated list of texture layers to affect, i.e. _MainTex,_Emissive.
  • textureScaleStart,textureScaleEnd -- <x>,<y> vectors denoting start and end scales of the texture.

Notice that texture shift and texture scale modes will work independently of each other on the same material.

Threshold mode

Threshold mode works regardless of which actuation method you choose, and is initiated when the threshold parameter is present. In threshold mode, actuation does not smoothly interpolate between states, but instead flips instantly between the ends of the scale. Extra configuration parameters available only in threshold mode:

  • threshold -- <minimum>,<maximum> -- If this parameter is present, threshold mode is enabled. The variable is scaled in between the minimum (0) and maximum (1) of the scale -- for example, assume that you gave the "scale" parameter as "3,5". 3 is the zero of the scale, 5 is the one, so if your variable returned 4, it would come out of this process as 0.5. If you the threshold parameter is "threshold = 0.4,0.6" then the resulting 0.5 would fall between the threshold edges -- and when this happens, the animation is immediately flipped to the end, and the alarm, if any, is triggered. Otherwise, it's kept at start.
  • flashingDelay -- In seconds. If this parameter is present, if the threshold condition is satisfied, the animation (or any other actuation mode) will flip between states continuously, spending only flashingDelay seconds in each state.
  • alarmSound -- A sound URL. If present, this sound will start playing when the threshold is entered.
  • alarmSoundVolume -- Sound volume. Defaults to 0.5.
  • alarmMustPlayOnce -- A boolean, defaults to false. If true, the alarm sound must finish playing and cannot be interrupted by the threshold condition disappearing.
  • alarmSoundLooping -- A boolean. True if the alarm should loop when it's triggered. Defaults to false.
  • alarmShutdownButton -- The name of a collider clicking which with a mouse will stop the sound alarm. Stopping the sound will have no effect on the state of the animation. If the variable isn't present, there will be no way to stop the alarm.
  • resourceAmount -- The amount of electrical charge consumed per second when the threshold is true. If there is not enough power to meet this demand, the animator switches off. The default is 0.0.
  • resourceName -- When 'resourceAmount' is positive, this provides the name of the resource used. Defaults to 'ElectricCharge'.

There is a known issue with Threshold Mode where rotation, translation, scale, and texture ops all are backwards from expected behavior. That is, the 'start' variable is used when the variable turns on, and the 'end' variable is used when it turns off.

Example of usage

For example, this will create an animated "low fuel" alarm light that will engage when you drop to 10% of total fuel capacity and play a looping alarm sound, which will be stopped when the user clicks it:

	MODULE 
	{
		name = JSIVariableAnimator
		refreshRate = 10
		VARIABLESET
		{
			animationName = LightThatButton
			variableName = SYSR_LIQUIDFUEL
			scale = 0,SYSR_LIQUIDFUELMAX
			threshold = 0.0,0.1
			alarmSound = MyPropLocation/AnnoyingSound
			alarmSoundLoop = true
			alarmShutdownButton = FuelButtonCollider
		}
	}
Clone this wiki locally