ModuleAnimateGeneric field definitions needed for...

[linuxgurugamer]

The following fields are listed in the API, not mentioned in the Wiki, and I can't find any description of them:

allowDeployLimit = true
revClampDirection = false
revClampSpeed = true
revClampPercent = true

Can some kind soul please define them?  I'll be happy to update the Wiki once I have an answer.

Thx

[cakepie]

Background

The full animation in the model file plays in one direction and has a defined start (0.0f) and end (normalized to 1.0f) which is tracked by float value Progress while the part is animating.

ModuleAnimateGeneric plays the animation in one direction (positive playback speed) to "deploy" or "open", and in reverse (negative playback speed) to "retract" / "close"
(I might have gotten the two directions mixed up, but you get the idea)

allowDeployLimit

normally, deploy/retract actions in Part Action Window (PAW) correspond to "play the animation fully"
E.g. service bays do not have the option true and will only open/close fully
Their animation state is either LOCKED when at fully open/closed state and MOVING when animating between the two

allowDeployLimit adds a control on the PAW so that the animation is clamped, i.e. "does not play fully"
clear example of this is cargo bays. e.g. for Mk3 cargo ramp:
If Deploy Limit set to 100% it will animate the full possible range when opening/closing
If Deploy Limit set to around 55% the ramp will only open as far as approximately "horizontal"
When the ramp has stopped moving while "half open" because of the deploy limit, the animation state is CLAMPED instead of LOCKED

 

revClampDirection

reverse the clamp direction of the animation
changes whether animation is clamped from start or clamped from end.

- one way is you can play from start of the animation clip to the clamp / deploy limit i.e. progress can range between 0.0 ~ X
- the other way applies the clamp from the other direction i.e. progress must be between X ~ 1.0

 

revClampPercent
the number displayed for the Deploy Limit control in PAW is reversed.
If you clamp a cargo bay door open with deploy limit 10% and it is "only slightly ajar" i.e. the meaning is "10% open"
Then close KSP and change the value of this field to the opposite, it will now be 90% to be "only slightly ajar" i.e. it is "90% closed"

 

revClampSpeed

If the clamping condition occurs while animation is forward playback (speed > 0) then revClampSpeed = false
which will stop playback when deploy limit is reached/exceeded while in forward playback
but if the part is somehow already beyond the limit it is allowed to animate in the other direction (and go back within the defined limit)
It is coded like this for safety/robustness -- consider if you just force stop animation when progress > clamplimit then could be stuck forever if beyond the limit and not allowed to move back in range.

If the clamping condition is while animation is reverse playback (speed < 0) then you need revClampSpeed = true

I'm not sure I explained this one well but basically you can just fiddle with this last one until the behavior is correct.

 

 

 

Edited May 5, 2019 by cakepie

[linuxgurugamer]

Thank you.

One more question:  if a mod wants to stop an animation at a specific time (ie:  say at progress == .33), what's the proper way to do that?

[cakepie]

18 minutes ago, linuxgurugamer said:

a mod wants to stop an animation at a specific time

Elaborate use case please. For what reason?

Generally the modeling/animation should go hand-in-hand with anything you might want to do via PartModule or other plugin code.
So if you have something that should be a two-part animation, e.g. a centrifuge, that has a deploy animation, and then a spinning animation,  that sort of situation is usually handled by having two separate animations.

ModuleAnimateGeneric is obviously written with only certain use cases in mind. Some of which is a bit hacked on tbh.
If it is not suitable for purpose then you may need to extend it or brew your own. Or maybe one of the existing alternative animation PartModules that are out there in various mods might fit the bill.

 

[linuxgurugamer]

The use case is probably unnecessary, to a certain extent I was trying to see if it could be done.

A cargo door part was made for one of my mods with three individual animations.  Each animation needs to be adjustable (ie:  clamping the max open), and also needs to start at a different point in the previous animation's progress.

I was trying to have the mod flexible enough to have multiple start/stop events, but seems that is not as easily doable.

 

[cakepie]

So like there's Anim1, Anim2, Anim3, and they all have their own separate deploy/retract button, but individual animations may have prerequisites i.e can only be used if another animation is in a particular state?

that would seem quite similar to inflatable/deployable centrifuge case, where:

- spin animation cannot be turned on unless deploy/inflate is in fully open state
- retract/deflate cannot be done while spinning is active, must stop the spinning first

But I don't think ModuleAnimationGroup helps you here, though, because that is for (deploy-retract)<->(active looping) setup only. Sounds like bespoke PartModule probably needed.

[linuxgurugamer]

On 5/5/2019 at 11:16 PM, cakepie said:

So like there's Anim1, Anim2, Anim3, and they all have their own separate deploy/retract button, but individual animations may have prerequisites i.e can only be used if another animation is in a particular state?

that would seem quite similar to inflatable/deployable centrifuge case, where:

- spin animation cannot be turned on unless deploy/inflate is in fully open state
- retract/deflate cannot be done while spinning is active, must stop the spinning first

But I don't think ModuleAnimationGroup helps you here, though, because that is for (deploy-retract)<->(active looping) setup only. Sounds like bespoke PartModule probably needed.

I've solved the problem, will be releasing my new mod SequentialAnimateGeneric soon.

[cakepie]

24 minutes ago, linuxgurugamer said:

SequentialAnimateGeneric

I'd suggest calling it ModuleSequentialAnimate to stick with the convention, also definitely not generic anymore.

[linuxgurugamer]

1 hour ago, cakepie said:

I'd suggest calling it ModuleSequentialAnimate to stick with the convention, also definitely not generic anymore.

The full name is ModuleSequentialAnimationGeneric, it works with multiple ModuleAnimationGeneric modules on a single part. But I'm playing around with the name right now, suggestions are welcome

[cakepie]

Yeah that sounds reasonable now that you've explained that its function is to lock/unlock multiple ModuleAnimationGeneric on the part. A bit of a mouthful perhaps but clarity is more important than a short name.

[linuxgurugamer]

23 hours ago, cakepie said:

Yeah that sounds reasonable now that you've explained that its function is to lock/unlock multiple ModuleAnimationGeneric on the part. A bit of a mouthful perhaps but clarity is more important than a short name.

And of course, just as I was demoing it for the first time, an edge case came up, I now need to fix it.

So the release will be delayed a few days