IMS2  Pre-Alpha
An Orbiter add-on to allow on-runtime construction of spacecraft from predefined modules
IMS_ModuleFunctionData_Animation Class Reference

Defines an arbitrary amount of animations as a module function. More...

Inheritance diagram for IMS_ModuleFunctionData_Animation:
IMS_ModuleFunctionData_Base

Public Member Functions

bool LoadFromFile (string configfile, IMSFILE cfg)
 Loads the data from config file. More...
 
- Public Member Functions inherited from IMS_ModuleFunctionData_Base
virtual bool HasGui ()
 This function serves to check whether a module function has a GUI before creating it. More...
 
FUNCTIONTYPE GetType ()
 
string GetName ()
 

Private Member Functions

ANIMATIONDATA loadAnimation (string id, IMSFILE cfg)
 
ANIMCOMPONENTDATA loadAnimComponent (IMSFILE cfg)
 
bool processConfigLine (vector< string > &tokens)
 Receives all lines of the config file that concern this ModuleFunction one by one. More...
 
bool validateData (string configfile)
 Validates the data for completeness after loading. More...
 

Private Attributes

vector< ANIMATIONDATAanimations
 

Friends

class IMS_ModuleFunction_Animation
 

Additional Inherited Members

- Protected Attributes inherited from IMS_ModuleFunctionData_Base
FUNCTIONTYPE type
 Stores the type of the ModuleFunction.
 
string name = ""
 Stores the Name of the ModuleFunction.
 

Detailed Description

Defines an arbitrary amount of animations as a module function.

Note that all parts of this animation must be contained in and limited to the specific module it is declared in!

Config file parameters

IMS2 handles animations as part of a module function just like any other module function. Contrary to other module functions, though, an animation module function has no purpose unless the animations inside it are referenced by other module functions in the same module. As a result, an animation module function usually consists of several animations, which again consist of several animation components. These components generally use the same data that is used by orbiter itself and provides a syntax familiar to SC3 ini files.

BEGIN_MODULEFUNCTION ANIMATION
BEGIN_ANIM <string id> //Begins an animation with the passed id. The id may NOT contain spaces and MUST be unique in the entire module.
Type = <Sequence|Continuous|Track <x y z>> //The type of the animation: Sequence means a sequential animation that will start, and then stop once it is finished.
//Continuous is a looped animation that is intended to repeat after it has run.
//Track is a special kind of animation used to align with an ingame object.
//It needs a normalised vector that describes the direction it is pointing towards in its default state as an argument.
Duration = <float seconds> //The duration the whole animation will last (in case of continuous animations, the duration of one loop).
[Dependency] = <see below> //Lets you declare a dependency on another animation. See below for details.
BEGIN_COMP <int index> //Begins a block declaring an animation component. See below for details.
END_COMP //Ends an animation component block
END_ANIM //ends an animation block
END_MODULEFUNCTION

animation dependencies

Some animations may depend on another animation in this module. For example, a module that has two folded up antennas might have them folded in a way that one antena is folded on top of the other, ergo the other can't deploy unless the first one is deployed, while the first one cannot fold up unless the other one is folded up. An arbitrary number of dependencies can be defined for any animation.

Dependency = <int direction> <string id> <float state>
direction: <-1 | 1> //For which direction of THIS animation the dependency applies.
//To get back to the initial example, the antena below cannot deploy unless the antena above it is deployed,
//so the direction for which it is dependant on the other one is its usual direction, i.e. 1.
//On the other hand, the upper antenna cannot be retracted unless the antena below it has been retracted,
//so it has a dependency on that animation for the reverse of the deployment animation, i.e. -1.
id: <string> //The id of the animation this animation depends on.
state: <float> //The state the OTHER animation must be in for THIS animation to be able to execute.
//Again refering to the above example, the lower antena cannot deploy until the upper antenna has deployed,
//so the state would be 1.0 (upper antena has completely deployed). The uper antena, on the other hand,
//would depend of the lower antena having a state of 0.0 (completely retracted) in order to retract.

animation components

Animation components work practically the same to how they work in orbiter or in SC3. As such, it is highly recommended to read up on animations in the orbiter API guide (not the code, but the concepts).

BEGIN_COMP [<int idx>] //idx is the index of this component in the animation, starting at 0 for the first component.
//Note that this index is not actually required or even read by the parser, but noting it makes the file a LOT more readable. Trust me on this, you won't regret it!
Groups = <array<int> indices> //The mesh groups involved in this part of the animation. an arbitrary number of space-delimited mesh-group indices can be defined.
Type = <Rotate|Translate|Scale> //Whether this part of the animation rotates, translates or scales the referenced mesh groups.
[Origin] = <float x> <float y> <float z> //Required for rotation and scale, but not for translation. For rotations, this defines the center of rotation. For scale, it defines the origin from which to scale.
[Axis] = <float x> <float y> <float z> //Required for rotations. The axis around which to rotate, as a normalised vector.
[Range] = <float> //Required for rotations. The angle by how much the referenced meshgroups should be rotated, in degrees.
[Translate] = <float x> <float y> <float z> //Required for translation. The magnitude and direction of the translation to be performed.
[Scale] = <float x> <float y> <float z> //Required for scaling. The magnitude of the scaling in the 3 principle axes.
[Duration] = <float> <float> //Where in the overall animation this component begins and where it ends. The values can range from 0 to 1,
//and the first value must always be smaller than the second. Default is 0.0 to 1.0, i.e. duration of entire animation.
[Parent] = <int idx> //Makes this component the child of another component, i.e. transformations from the parent component will be applied
//to this component before this component applies its own transformation.
//Note that child components must ALWAYS be defined after their parent!
END_COMP

Member Function Documentation

bool IMS_ModuleFunctionData_Animation::LoadFromFile ( string  configfile,
IMSFILE  cfg 
)
virtual

Loads the data from config file.

Parameters
configfileThe name of the config file
cfgThe config file itself, wrapped in an IMSFILE structure for oapi independency
Note
This function sends all lines concerning this ModuleFunction to processConfigLine() one by one. In general, it will be much easier to overload processConfigLine(). Overload this function only if you cannot practically load your data on a pure line by line basis.
Returns
True if loading was succesful, false otherwise
See also
processConfigLine()

Reimplemented from IMS_ModuleFunctionData_Base.

bool IMS_ModuleFunctionData_Animation::processConfigLine ( vector< string > &  tokens)
inlineprivatevirtual

Receives all lines of the config file that concern this ModuleFunction one by one.

Overload this function to receive the relevant data of your module.

Parameters
tokensa vector of strings that contains the individual parts of the line, delimited by whitespace or '='
Note
Throw runtime_error with an error message if you encounter an invalid line! The message will be loged in Orbiter.log together with the name of the config file.
Returns
true if the passed line was processed, false if not.

Implements IMS_ModuleFunctionData_Base.

bool IMS_ModuleFunctionData_Animation::validateData ( string  configfile)
inlineprivatevirtual

Validates the data for completeness after loading.

Implement this function to validate your data at the end of the loading process. Check if everything's there that needs to be, and write log messages if it isn't.

Parameters
configfileThe name of the configfile, so you can add it to your messages so config writers find their mistakes faster.
Returns
False if the modulefunction is unable to function, otherwise return true.
Note
If your Implementation returns false, The loading process will be aborted by forcing orbiter to crash, so be sure to keep your loging straight!

Implements IMS_ModuleFunctionData_Base.


The documentation for this class was generated from the following files: