Skip to content

JSICallbackAnimator

Jump to bottom
MOARdV edited this page Jun 11, 2016 · 4 revisions

What it does

This module will animate a prop or change its texture color according to the results of variable computation, enabling or disabling animations, or setting colors or transforms based on whether or not the variable falls within a specific range. It is very similar to JSIVariableAnimator in threshold mode with a few differences. When used with appropriate variables, this module is both lower overhead than JSIVariableAnimator, and much more responsive.

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 not noisy (things like LIGHTS that have a limited number of defined values).
  • The controlling variable does not change frequently.
  • It is acceptable for the animation or color change to happen immediately (without ramping from 'off' to 'on' or vice versa).
  • The controlling variable is used in many, many props.

This module has low overhead since it uses a callback subscription method to be notified of changes. It allows RasterPropMonitor to query a variable one time per FixedUpdate regardless of the number of callback modules that use it, and those modules are only notified of changes (and thus do their additional computations) only if the variable has changed since the last time it was queried. These two properties allow for many props that use a common variable (eg, an "instrument panel lights are on" variable) to consume very little overhead when the common variable does not change. A side-effect of the callback system is that this module responds very quickly to changes (backlights will all switch on nearly instantly, instead of after a noticeable delay if the refresh rate of a JSIVariableAnimator is high enough).

It is not a good candidate for noisy variables (such as ALTITUDE, PERIAPSIS, METSECS, etc.), since those variables change at least a little bit every time there is a FixedUpdate, so each subscribed callback will trigger every FixedUpdate (effectively, a refreshRate of 1 or maybe 2).

Named defined variables may be used in the scale field, but the animator does not subscribe to changes to those values, so it's possible that this animator will overlook cases where a JSIVariableAnimator would have transitioned from off to on because the extents of the scale changed.

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 = JSICallbackAnimator
		variableName = CUSTOM_INSTRUMENT_BACKLIGHT
		flashRate = 0.5
		VARIABLESET
		{
			...
		}
	}

There are two global module configuration parameters:

  • flashRate -- The frequency with which animations will switch on and off when they're "on". A 1.0 means the animation will switch on for a second, and then switch off for a second. Defaults to 0 (no flashing). Individual animations have to opt-in to flashing in their VARIABLESET definitions.
  • variableName -- The name of the variable this module uses. The module subscribes to receive notifications when this value changes.

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

  • flash -- A boolean. If true, this animation will respond to flash commands. Defaults to false.
  • reverse -- A boolean. If true, the actuation of the scale will be reversed (the animation will use the 'on' value when the variable is outside the range of scale).
  • scale -- <variable or float value>,<variable or float value> -- The action is enabled when variableName falls between the two values in scale. While you can use defined variables for these values, the JSICallbackAnimator does not subscribe for notification when they change, so it's possible that a variable will fall out of range without updating this animator.

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 string (255, 255, 0, 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 'off' and 'on' state 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.

Translation mode

  • controlledTransform -- Name of the transform that will be moved.
  • localTranslationStart,localTranslationEnd -- <x>,<y>,<z> Positions, that will correspond to the 'off' and 'on' state 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 'off' and 'on' state 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 'off' and 'on' 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 'off' and 'on' scales of the texture.

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

Alarm sounds

In addition to the modes above, a VARIABLESET can have a sound attached to it that triggers when the variable is within its threshold.

  • 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.

Example of usage

For example, this will create a "lights are on" indicator lamp that will engage when external lights are on:

	MODULE 
	{
		name = JSICallbackAnimator
		variableName = LIGHTS
		VARIABLESET
		{
			coloredObject = LampObj
			passiveColor = 0,0,0,255
			activeColor = 0,255,58,255
			scale = 0.5,1.1
		}
	}
Clone this wiki locally