Skip to content

Commit 5c917f2

Browse files
#164 fix animation tutorial (#177)
* #164 Update the hello animation tutorial to use the modern AnimComposer
1 parent 1b43dc3 commit 5c917f2

File tree

1 file changed

+121
-134
lines changed

1 file changed

+121
-134
lines changed

docs/modules/tutorials/pages/beginner/hello_animation.adoc

+121-134
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
= jMonkeyEngine 3 Tutorial (7) - Hello Animation
22
:author:
33
:revnumber:
4-
:revdate: 2020/07/06
4+
:revdate: 2024/10/05
55
:keywords: beginner, intro, animation, documentation, keyinput, input, node, model
66

77

8-
This tutorial shows how to add an animation controller and channels, and how to respond to user input by triggering an animation in a loaded model.
8+
This tutorial shows how to add an animation controller and how to respond to user input by triggering an animation in a loaded model.
99

1010
image::beginner/beginner-animation.png[beginner-animation.png,width="",height="",align="center"]
1111

@@ -18,10 +18,12 @@ include::partial$add-testdata-tip.adoc[]
1818
1919
package jme3test.helloworld;
2020
21-
import com.jme3.animation.AnimChannel;
22-
import com.jme3.animation.AnimControl;
23-
import com.jme3.animation.AnimEventListener;
24-
import com.jme3.animation.LoopMode;
21+
import com.jme3.anim.AnimComposer;
22+
import com.jme3.anim.tween.Tween;
23+
import com.jme3.anim.tween.Tweens;
24+
import com.jme3.anim.tween.action.Action;
25+
import com.jme3.anim.tween.action.BlendSpace;
26+
import com.jme3.anim.tween.action.LinearBlendSpace;
2527
import com.jme3.app.SimpleApplication;
2628
import com.jme3.input.KeyInput;
2729
import com.jme3.input.controls.ActionListener;
@@ -32,60 +34,71 @@ import com.jme3.math.Vector3f;
3234
import com.jme3.scene.Node;
3335
3436
/** Sample 7 - how to load an OgreXML model and play an animation,
35-
* using channels, a controller, and an AnimEventListener. */
36-
public class HelloAnimation extends SimpleApplication
37-
implements AnimEventListener {
38-
private AnimChannel channel;
39-
private AnimControl control;
40-
Node player;
41-
public static void main(String[] args) {
42-
HelloAnimation app = new HelloAnimation();
43-
app.start();
44-
}
45-
46-
@Override
47-
public void simpleInitApp() {
48-
viewPort.setBackgroundColor(ColorRGBA.LightGray);
49-
initKeys();
50-
DirectionalLight dl = new DirectionalLight();
51-
dl.setDirection(new Vector3f(-0.1f, -1f, -1).normalizeLocal());
52-
rootNode.addLight(dl);
53-
player = (Node) assetManager.loadModel("Models/Oto/Oto.mesh.xml");
54-
player.setLocalScale(0.5f);
55-
rootNode.attachChild(player);
56-
control = player.getControl(AnimControl.class);
57-
control.addListener(this);
58-
channel = control.createChannel();
59-
channel.setAnim("stand");
60-
}
61-
62-
public void onAnimCycleDone(AnimControl control, AnimChannel channel, String animName) {
63-
if (animName.equals("Walk")) {
64-
channel.setAnim("stand", 0.50f);
65-
channel.setLoopMode(LoopMode.DontLoop);
66-
channel.setSpeed(1f);
37+
* using AnimComposer */
38+
public class HelloAnimation extends SimpleApplication{
39+
40+
private AnimComposer control;
41+
private Action advance;
42+
43+
Node player;
44+
public static void main(String[] args) {
45+
HelloAnimation app = new HelloAnimation();
46+
app.start();
47+
}
48+
49+
@Override
50+
public void simpleInitApp() {
51+
viewPort.setBackgroundColor(ColorRGBA.LightGray);
52+
initKeys();
53+
DirectionalLight dl = new DirectionalLight();
54+
dl.setDirection(new Vector3f(-0.1f, -1f, -1).normalizeLocal());
55+
rootNode.addLight(dl);
56+
player = (Node) assetManager.loadModel("Models/Oto/Oto.mesh.xml");
57+
player.setLocalScale(0.5f);
58+
rootNode.attachChild(player);
59+
control = player.getControl(AnimComposer.class);
60+
control.setCurrentAction("stand");
61+
62+
/* Compose an animation action named "halt"
63+
that transitions from "Walk" to "stand" in half a second. */
64+
BlendSpace quickBlend = new LinearBlendSpace(0f, 0.5f);
65+
Action halt = control.actionBlended("halt", quickBlend, "stand", "Walk");
66+
halt.setLength(0.5);
67+
68+
/* Compose an animation action named "advance"
69+
that walks for one cycle, then halts, then invokes onAdvanceDone(). */
70+
Action walk = control.action("Walk");
71+
Tween doneTween = Tweens.callMethod(this, "onAdvanceDone");
72+
advance = control.actionSequence("advance", walk, halt, doneTween);
6773
}
68-
}
69-
70-
public void onAnimChange(AnimControl control, AnimChannel channel, String animName) {
71-
// unused
72-
}
73-
74-
/** Custom Keybinding: Map named actions to inputs. */
75-
private void initKeys() {
76-
inputManager.addMapping("Walk", new KeyTrigger(KeyInput.KEY_SPACE));
77-
inputManager.addListener(actionListener, "Walk");
78-
}
79-
private ActionListener actionListener = new ActionListener() {
80-
public void onAction(String name, boolean keyPressed, float tpf) {
81-
if (name.equals("Walk") && !keyPressed) {
82-
if (!channel.getAnimationName().equals("Walk")) {
83-
channel.setAnim("Walk", 0.50f);
84-
channel.setLoopMode(LoopMode.Loop);
85-
}
86-
}
74+
75+
/**
76+
* Callback to indicate that the "advance" animation action has completed.
77+
*/
78+
void onAdvanceDone() {
79+
/*
80+
* Play the "stand" animation action.
81+
*/
82+
control.setCurrentAction("stand");
83+
}
84+
85+
/**
86+
* Map the spacebar to the "Walk" input action, and add a listener to initiate
87+
* the "advance" animation action each time it's pressed.
88+
*/
89+
private void initKeys() {
90+
inputManager.addMapping("Walk", new KeyTrigger(KeyInput.KEY_SPACE));
91+
92+
ActionListener handler = new ActionListener() {
93+
@Override
94+
public void onAction(String name, boolean keyPressed, float tpf) {
95+
if (keyPressed && control.getCurrentAction() != advance) {
96+
control.setCurrentAction("advance");
97+
}
98+
}
99+
};
100+
inputManager.addListener(handler, "Walk");
87101
}
88-
};
89102
}
90103
91104
----
@@ -128,59 +141,36 @@ After you load the animated model, you register it to the Animation Controller.
128141
[source,java]
129142
----
130143
131-
private AnimChannel channel;
132-
private AnimControl control;
144+
private AnimComposer control;
133145
134146
public void simpleInitApp() {
135147
...
136148
/* Load the animation controls, listen to animation events,
137149
* create an animation channel, and bring the model in its default position.
138150
*/
139-
control = player.getControl(AnimControl.class);
140-
control.addListener(this);
141-
channel = control.createChannel();
142-
channel.setAnim("stand");
151+
control = player.getControl(AnimComposer.class);
152+
control.setCurrentAction("stand");
143153
...
144154
}
145155
----
146156

147-
This line of code will return NULL if the AnimControl is not in the main node of your model.
157+
This line of code will return NULL if the AnimComposer is not in the main node of your model.
148158

149159
[source,java]
150160
----
151-
control = player.getControl(AnimControl.class);
161+
control = player.getControl(AnimComposer.class);
152162
----
153163

154164
To check this, btn:[RMB] select your model and click "`Edit in SceneComposer`" if the models file extension is .j3o, or "`View`" if not. You can then see the tree for the model so you can locate the node the control resides in. You can access the subnode with the following code.
155165

156166
[source,java]
157167
----
158-
player.getChild("Subnode").getControl(AnimControl.class);
168+
player.getChild("Subnode").getControl(AnimComposer.class);
159169
----
160170

161-
[NOTE]
162-
====
163-
In response to a question about animations on different channels interfering with each other, *Nehon*, on the jME forum wrote,
164-
165-
[quote, Nehon, Team Leader: Retired]
166-
____
167-
You have to consider channels as part of the skeleton that are animated. The default behavior is to use the whole skeleton for a channel.
168-
169-
In your example the first channel plays the walk anim, then the second channel plays the dodge animation.
170-
171-
Arms and feet are probably not affected by the doge animation so you can see the walk anim for them, but the rest of the body plays the dodge animation.
172-
173-
Usually multiple channels are used to animate different part of the body. For example you create one channel for the lower part of the body and one for the upper part. This allow you to play a walk animation with the lower part and for example a shoot animation with the upper part. This way your character can walk while shooting.
174-
175-
In your case, where you want animations to chain for the whole skeleton, you just have to use one channel.
176-
____
177-
====
178-
179-
180-
181171
== Responding to Animation Events
182172

183-
Add `implements AnimEventListener` to the class declaration. This interface gives you access to events that notify you when a sequence is done, or when you change from one sequence to another, so you can respond to it. In this example, you reset the character to a standing position after a `Walk` cycle is done.
173+
A Tween (part of an action sequence) can call a method on a class, allowing your application code to be informed of the animation state. In this example, you reset the character to a standing position after a `Walk` cycle is done.
184174

185175
[source,java]
186176
----
@@ -189,17 +179,24 @@ public class HelloAnimation extends SimpleApplication
189179
implements AnimEventListener {
190180
...
191181
192-
public void onAnimCycleDone(AnimControl control,
193-
AnimChannel channel, String animName) {
194-
if (animName.equals("Walk")) {
195-
channel.setAnim("stand", 0.50f);
196-
channel.setLoopMode(LoopMode.DontLoop);
197-
channel.setSpeed(1f);
182+
@Override
183+
public void simpleInitApp() {
184+
...
185+
Action walk = control.action("Walk");
186+
Tween doneTween = Tweens.callMethod(this, "onAdvanceDone");
187+
advance = control.actionSequence("advance", walk, halt, doneTween);
188+
...
189+
}
190+
191+
/**
192+
* Callback to indicate that the "advance" animation action has completed.
193+
*/
194+
void onAdvanceDone() {
195+
/*
196+
* Play the "stand" animation action.
197+
*/
198+
control.setCurrentAction("stand");
198199
}
199-
}
200-
public void onAnimChange(AnimControl control, AnimChannel channel, String animName) {
201-
// unused
202-
}
203200
...
204201
}
205202
----
@@ -220,45 +217,39 @@ There are ambient animations like animals or trees that you may want to trigger
220217
[source,java]
221218
----
222219
223-
private void initKeys() {
224-
inputManager.addMapping("Walk", new KeyTrigger(KeyInput.KEY_SPACE));
225-
inputManager.addListener(actionListener, "Walk");
226-
}
227-
228-
----
229-
230-
To use the input controller, you need to implement the actionListener by testing for each action by name, then set the channel to the corresponding animation to run.
231-
232-
* The second parameter of setAnim() is the blendTime (how long the current animation should overlap with the last one).
233-
* LoopMode can be Loop (repeat), Cycle (forward then backward), and DontLoop (only once).
234-
* If needed, use channel.setSpeed() to set the speed of this animation.
235-
* Optionally, use channel.setTime() to Fast-forward or rewind to a certain moment in time of this animation.
236-
237-
[source,java]
238-
----
239-
240-
private ActionListener actionListener = new ActionListener() {
241-
public void onAction(String name, boolean keyPressed, float tpf) {
242-
if (name.equals("Walk") && !keyPressed) {
243-
if (!channel.getAnimationName().equals("Walk")){
244-
channel.setAnim("Walk", 0.50f);
245-
channel.setLoopMode(LoopMode.Cycle);
220+
/**
221+
* Map the spacebar to the "Walk" input action, and add a listener to initiate
222+
* the "advance" animation action each time it's pressed.
223+
*/
224+
private void initKeys() {
225+
inputManager.addMapping("Walk", new KeyTrigger(KeyInput.KEY_SPACE));
226+
227+
ActionListener handler = new ActionListener() {
228+
@Override
229+
public void onAction(String name, boolean keyPressed, float tpf) {
230+
if (keyPressed && control.getCurrentAction() != advance) {
231+
control.setCurrentAction("advance");
232+
}
246233
}
247-
}
234+
};
235+
inputManager.addListener(handler, "Walk");
248236
}
249-
};
250237
251238
----
252239

253240

241+
* By default, the animation will loop, there is an overloaded `setCurrentAction` method that allows you to set the loop mode.
242+
* If needed, use Action::setSpeed to set the speed of this animation.
243+
* Optionally, use AnimComposer::.setTime to Fast-forward or rewind to a certain moment in time of this animation.
244+
254245
== Exercises
255246

256247

257248
=== Exercise 1: Two Animations
258249

259250
Make a mouse click trigger another animation sequence!
260251

261-
. Create a second channel in the controller.
252+
. Create a second layer in the controller.
262253
. Create a new key trigger mapping and action. (see: xref:beginner/hello_input_system.adoc[Hello Input])
263254
+
264255
[TIP]
@@ -269,7 +260,7 @@ Use:
269260
270261
[source,java]
271262
----
272-
for (String anim : control.getAnimationNames()) {
263+
for (String anim : control.getAnimClipsNames()) {
273264
System.out.println(anim);
274265
}
275266
----
@@ -293,8 +284,8 @@ Add the following import statements for the SkeletonDebugger and Material classe
293284
[source,java]
294285
----
295286
296-
import com.jme3.scene.debug.SkeletonDebugger;
297-
import com.jme3.material.Material;
287+
import com.jme3.scene.debug.custom.ArmatureDebugAppState;
288+
import com.jme3.anim.SkinningControl;
298289
299290
----
300291

@@ -303,13 +294,9 @@ Add the following code snippet to `simpleInitApp()` to make the bones (that you
303294
[source,java]
304295
----
305296
306-
SkeletonDebugger skeletonDebug =
307-
new SkeletonDebugger("skeleton", control.getSkeleton());
308-
Material mat = new Material(assetManager, "Common/MatDefs/Misc/Unshaded.j3md");
309-
mat.setColor("Color", ColorRGBA.Green);
310-
mat.getAdditionalRenderState().setDepthTest(false);
311-
skeletonDebug.setMaterial(mat);
312-
player.attachChild(skeletonDebug);
297+
ArmatureDebugAppState armatureDebugAppState = new ArmatureDebugAppState();
298+
armatureDebugAppState.addArmatureFrom(player.getControl(SkinningControl.class));
299+
this.getStateManager().attach(armatureDebugAppState);
313300
314301
----
315302

0 commit comments

Comments
 (0)