Class Spring

java.lang.Object

net.ixdarklord.coolcatcanvas.api.client.armature.Spring

public final class Spring
extends Object

Secondary motion: a joint that lags behind and swings back, as a tail, ears, antennae, a cape or a hanging lantern would. The joint's tip is a weight on a spring, pulled toward where the animation puts it, so it reacts to the creature walking and turning and to the clips themselves. Chain springs down a tail for a whip.

animator.spring("tail").stiffness(90).damping(7);
animator.spring("tail_tip").stiffness(60).damping(5).gravity(4);
animator.spring("antenna").stiffness(200).maxAngle(35);

Colliders keep the weight out of the body: each is a ball round a point of the model (a locator), so a cape drapes over the back and the spikes on it instead of swinging through them. Chain a cape from a few joints, each with the same colliders, and it folds over them.

animator.spring("cape_1").collider("back", 5).collider("spine_spike_2", 2.5);

Free parts: with no stiffness a joint isn't pulled back to its animated place at all, and hangs or floats where the world puts it: a lantern on a chain swinging as its holder walks, or a balloon on a string held in a hand. Buoyancy lifts it (a balloon, a jellyfish's bell, a kite), a rope lets its string go slack when its holder jerks it back instead of acting as a rod, wind sets it drifting in slow gusts, and twist spins it on its string as it is swung. The animation still moves where it hangs from, so it reacts to every clip: a walk tugs it along behind, a blow whips it round, an idle sets it bobbing.

animator.spring("balloon").stiffness(0).buoyancy(9).damping(1.8).rope(true).wind(1.2).twist(0.6).maxAngle(180);
animator.spring("lantern").stiffness(0).gravity(9.8).damping(1.5).maxAngle(150);

The world: a spring's weight can be kept out of the blocks round it and the entities near it, a ball of collisionRadius round it: a tail that rests on the ground and slides along walls, a balloon that bumps a ceiling or is pushed aside by a player walking into it, a cape that lies on the stairs it is dragged up. It bounces off (bounce) and drags along what it touches (friction).

animator.spring("balloon").stiffness(0).buoyancy(9).collideBlocks(true).collideEntities(true).collisionRadius(2.2);

Springs that bump: those of one animator marked bump keep their weights apart, each a ball of collisionRadius, pushing on each other and bouncing off each other: a bunch of balloons jostling on their strings, a row of hanging charms knocking together.

animator.spring("balloon_red").stiffness(0).buoyancy(9).bump(true).collisionRadius(2.2);
animator.spring("balloon_blue").stiffness(0).buoyancy(8).bump(true).collisionRadius(2.0);

Cloth: springs linked to their neighbours (link(String...)) keep the distance between their weights that the animation gives them, as threads woven between them would, so a cape of a few hanging chains side by side, or a skirt of panels round a waist, moves as one sheet: it ripples across, folds and bunches (it gives a little when pushed together, linkStiffness, and hardly at all when pulled apart) instead of parting into strips.

animator.spring("cape_0_1").link("cape_1_1");                  // and cape_1_1 links back to cape_0_1, and so on

What the cloth is: its mass (heavy cloth swings slowly and shrugs off the wind; light cloth answers every tug), the airDrag that makes it stream out behind as its wearer moves, the flutter that ripples it the faster they go, how far it stretches and springs back, and how stiffly a chain of it resists folding (bend: canvas hangs in long curves, silk folds sharp); a steady windDirection on top of the drifting wind. A Fabric sets them all at once.

animator.spring("cape_0_1").fabric(Fabric.WOOL).stiffness(40);
animator.spring("veil").fabric(Fabric.SILK).wind(0.8).windDirection(1, 0, 0);

It is kept light: a frame allocates nothing; it takes at most 8 sub-steps; one that has come to rest with nothing moving it sleeps until something does; the world's blocks are looked up a few times a second (or when it has moved half a block) and its entities every few frames; and farther than simulationDistance from the camera it is not worked out at all.

Method Summary

Modifier and Type	Method	Description
Spring	airDrag(float drag)	Air resistance, growing with its speed (squared): moving fast, it is held back and streams out behind, then settles as it slows; how cloth flows.
Spring	bend(float bend)	How stiffly it holds its shape against folding, per second squared: a pull back to its animated place (which rides on its parent joint's swing, so a chain keeps the curve the animation gives it) that its mass does not weaken, as stiffness is, damped critically to match so it does not ring.
Spring	bounce(float bounce)	How much of its speed into a block or an entity it keeps, bouncing off, 0 to 1; 0.3 by default.
Spring	bump(boolean bump)	Whether its weight bumps into the other springs of its animator that bump: each keeps the others' balls of collisionRadius out of its own, and they bounce off each other.
Spring	buoyancy(float buoyancy)	How hard it is lifted, in blocks per second squared: the opposite of gravity, for something that floats (a balloon on a string, a kite, a bell of a jellyfish).
Spring	collideBlocks(boolean blocks)	Whether its weight is kept out of the world's blocks (their collision shapes).
Spring	collideEntities(boolean entities)	Whether its weight is kept out of other entities (their boxes), and pushed aside as they move into it.
Spring	collider(String point, float radius)	Keeps the weight out of a ball round a point of the model (a locator, by name), radius in pixels.
Spring	collisionRadius(float pixels)	How big its weight is for the world's blocks and entities: a ball this many pixels round; 1 by default.
Spring	damping(float damping)	How quickly the swinging dies down, per second.
Spring	enabled(boolean enabled)
Spring	fabric(Fabric fabric)	What it is made of: sets its mass, damping, gravity, airDrag, flutter, stretch, bend and linkStiffness at once.
Spring	flutter(float flutter)	How much it ripples in the air its wearer moves through, more the faster they go: a flag's snap.
Spring	follow(float follow)	How much it moves along with its wearer, 0 to 1: its damping works on its speed relative to where the animation carries it rather than its speed in the world, so at 1 it keeps up with every move and only its own swinging is damped (cloth sewn to a body), and at 0 (the default) it is held back as if dragged through the air (a tail, a dangling charm).
Spring	friction(float friction)	How much it drags along what it touches, 0 (slides freely) to 1; 0.4 by default.
Spring	gravity(float gravity)	How hard it is pulled down, in blocks per second squared: a sagging tail or hanging chain.
String	joint()
Spring	length(float pixels)	How long the joint is, in pixels, from its pivot to the weight.
Spring	link(String... joints)	Weaves its weight to the weights of other springs of its animator (by joint), as cloth: they keep the distance the animation puts between them, so side by side they move as one sheet.
Spring	linkStiffness(float stiffness)	How firmly its links hold when pushed together, 0 (they bunch freely, a soft cloth) to 1 (stiff as card); pulled apart they always hold.
Spring	mass(float mass)	How heavy it is, 1 by default: everything that moves it (its pull back to place, the wind, the air, a fold) moves it less the heavier it is, so heavy cloth swings slowly and keeps swinging, and light cloth answers every tug.
Spring	maxAngle(float degrees)	The furthest it swings from the animated place, in degrees, up to 180 for a part that hangs free; 70 by default.
Spring	pulls(boolean pulls)	Whether it pulls on what it hangs from: stretched taut, its weight tugs the weight of the spring on its joint's parent along its length (each giving way by the other's share of their mass), as a balloon pulls its string taut toward it, instead of the string standing on its own and the balloon folding over at its top.
void	reset()	Puts the weight back where the animation has it, with no swing; for a teleport or a respawn.
Spring	rope(boolean rope)	Whether it hangs on a rope rather than a rod: it can come nearer the joint than its length (the rope goes slack) when the joint is jerked toward it, and only its length holds it from going further.
Spring	simulationDistance(float blocks)	How far from the camera, in blocks, it is still worked out; farther, it holds the swing it had (too small to see) and costs nothing.
Spring	spacing(float pixels)	Room it keeps from the other springs that bump, in pixels past their balls: within it they are eased apart, gently at its edge and harder the nearer they come, before they ever touch.
Spring	stiffness(float stiffness)	How hard it pulls back toward the animated place, per second squared.
Spring	stretch(float stretch)	How far it stretches and springs back, a share of its length (0.05 is five percent): cloth gives a little as it is yanked.
Spring	twist(float twist)	How readily it spins about its own length as it is swung (a balloon turning on its string, a hanging sign), 0 to about 1; the spin dies down by itself.
Spring	weight(float weight)	How much of the swing shows, 0 to 1.
Spring	wind(float wind)	How hard the wind pushes it about, in blocks per second squared: a slow drift that now and then gusts.
Spring	windDirection(float x, float y, float z)	A steady breeze the wind blows along as well as drifting about, in the world's axes (any length; it is normalized): a banner on a windy hill, a cloak in a gale.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

joint

public String joint()

stiffness

public Spring stiffness(float stiffness)

How hard it pulls back toward the animated place, per second squared. Higher is snappier; 140 by default.

damping

public Spring damping(float damping)

How quickly the swinging dies down, per second. Low values wobble long; 12 by default.

gravity

public Spring gravity(float gravity)

How hard it is pulled down, in blocks per second squared: a sagging tail or hanging chain. 0 by default.

buoyancy

public Spring buoyancy(float buoyancy)

How hard it is lifted, in blocks per second squared: the opposite of gravity, for something that floats (a balloon on a string, a kite, a bell of a jellyfish). With no stiffness it rises straight up from where it is held and trails behind as its holder moves.

rope

public Spring rope(boolean rope)

Whether it hangs on a rope rather than a rod: it can come nearer the joint than its length (the rope goes slack) when the joint is jerked toward it, and only its length holds it from going further. Off by default.

pulls

public Spring pulls(boolean pulls)

Whether it pulls on what it hangs from: stretched taut, its weight tugs the weight of the spring on its joint's parent along its length (each giving way by the other's share of their mass), as a balloon pulls its string taut toward it, instead of the string standing on its own and the balloon folding over at its top. Down a chain whose every length pulls, the tension runs all the way down: a string of cord lengths curves toward its balloon as its holder swings it. Off by default.

animator.spring("balloon_string_0").fabric(Fabric.CORD).stiffness(0).rope(true).pulls(true);
animator.spring("balloon").stiffness(0).buoyancy(9).rope(true).pulls(true);

wind

public Spring wind(float wind)

How hard the wind pushes it about, in blocks per second squared: a slow drift that now and then gusts. 0 by default.

windDirection

public Spring windDirection(float x,
 float y,
 float z)

A steady breeze the wind blows along as well as drifting about, in the world's axes (any length; it is normalized): a banner on a windy hill, a cloak in a gale. None by default (the wind only drifts).

mass

public Spring mass(float mass)

How heavy it is, 1 by default: everything that moves it (its pull back to place, the wind, the air, a fold) moves it less the heavier it is, so heavy cloth swings slowly and keeps swinging, and light cloth answers every tug. Gravity pulls all alike.

airDrag

public Spring airDrag(float drag)

Air resistance, growing with its speed (squared): moving fast, it is held back and streams out behind, then settles as it slows; how cloth flows. 0 by default; a few hundredths is cloth.

flutter

public Spring flutter(float flutter)

How much it ripples in the air its wearer moves through, more the faster they go: a flag's snap. 0 by default.

stretch

public Spring stretch(float stretch)

How far it stretches and springs back, a share of its length (0.05 is five percent): cloth gives a little as it is yanked. 0 by default (it holds its length exactly).

bend

public Spring bend(float bend)

How stiffly it holds its shape against folding, per second squared: a pull back to its animated place (which rides on its parent joint's swing, so a chain keeps the curve the animation gives it) that its mass does not weaken, as stiffness is, damped critically to match so it does not ring. Heavy, stiff cloth (canvas, leather) then hangs heavily yet curves in long arcs instead of sagging and folding sharp at each joint as heavy silk would, and settles instead of whipping. 0 by default. (A long chain of springs whips if it is too lightly damped for its weight: raise damping with mass.)

follow

public Spring follow(float follow)

How much it moves along with its wearer, 0 to 1: its damping works on its speed relative to where the animation carries it rather than its speed in the world, so at 1 it keeps up with every move and only its own swinging is damped (cloth sewn to a body), and at 0 (the default) it is held back as if dragged through the air (a tail, a dangling charm). airDrag always drags against the world.

fabric

public Spring fabric(Fabric fabric)

What it is made of: sets its mass, damping, gravity, airDrag, flutter, stretch, bend and linkStiffness at once. Set any of them afterwards to change just that.

twist

public Spring twist(float twist)

How readily it spins about its own length as it is swung (a balloon turning on its string, a hanging sign), 0 to about 1; the spin dies down by itself. 0 by default.

bump

public Spring bump(boolean bump)

Whether its weight bumps into the other springs of its animator that bump: each keeps the others' balls of collisionRadius out of its own, and they bounce off each other. Off by default.

spacing

public Spring spacing(float pixels)

Room it keeps from the other springs that bump, in pixels past their balls: within it they are eased apart, gently at its edge and harder the nearer they come, before they ever touch. With a gentle buoyancy(float), a bunch of balloons opens out into a spread bouquet instead of crowding into one clump. 0 by default.

link

public Spring link(String... joints)

Weaves its weight to the weights of other springs of its animator (by joint), as cloth: they keep the distance the animation puts between them, so side by side they move as one sheet. Link both ways (each to the other).

linkStiffness

public Spring linkStiffness(float stiffness)

How firmly its links hold when pushed together, 0 (they bunch freely, a soft cloth) to 1 (stiff as card); pulled apart they always hold. 0.6 by default.

collideBlocks

public Spring collideBlocks(boolean blocks)

Whether its weight is kept out of the world's blocks (their collision shapes). Off by default.

collideEntities

public Spring collideEntities(boolean entities)

Whether its weight is kept out of other entities (their boxes), and pushed aside as they move into it. Off by default.

collisionRadius

public Spring collisionRadius(float pixels)

How big its weight is for the world's blocks and entities: a ball this many pixels round; 1 by default.

bounce

public Spring bounce(float bounce)

How much of its speed into a block or an entity it keeps, bouncing off, 0 to 1; 0.3 by default.

friction

public Spring friction(float friction)

How much it drags along what it touches, 0 (slides freely) to 1; 0.4 by default.

simulationDistance

public Spring simulationDistance(float blocks)

How far from the camera, in blocks, it is still worked out; farther, it holds the swing it had (too small to see) and costs nothing. 64 by default; 0 or less works it out at any distance.

maxAngle

public Spring maxAngle(float degrees)

The furthest it swings from the animated place, in degrees, up to 180 for a part that hangs free; 70 by default.

weight

public Spring weight(float weight)

How much of the swing shows, 0 to 1.

length

public Spring length(float pixels)

How long the joint is, in pixels, from its pivot to the weight. By default it reaches to its first child's pivot, or to the middle of its own faces.

collider

public Spring collider(String point,
 float radius)

Keeps the weight out of a ball round a point of the model (a locator, by name), radius in pixels. The point must move with a joint that comes before this one (a parent, or one posed earlier), or it is skipped.

enabled

public Spring enabled(boolean enabled)

reset

public void reset()

Puts the weight back where the animation has it, with no swing; for a teleport or a respawn.