Skip to content

Fix Cinematic initialization and serialization bugs #2560

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
capdevon wants to merge 22 commits into
base: master
Choose a base branch
from
Draft

Fix Cinematic initialization and serialization bugs #2560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
a0ac32d
AnimEvent: fix serialization bug
capdevon Sep 22, 2025
dc88115
Cinematic: fix initialization and serialization events
capdevon Sep 22, 2025
b2ff79d
Merge branch 'jMonkeyEngine:master' into capdevon-Cinematic
capdevon Jan 17, 2026
1f06ea3
Refactor AnimEvent class and update copyright year
capdevon Jan 17, 2026
544b174
Add dispose method to AnimEvent class
capdevon Jan 17, 2026
23de7bd
Update ArrayList
capdevon Jan 17, 2026
2e850c7
Update Cinematic
capdevon Jan 17, 2026
84dc780
fix Cinematic attach/detach/cleanup state
capdevon Jan 17, 2026
1bc14f6
remove debug log
capdevon Jan 17, 2026
36881e7
remove unused field
riccardobl Jan 18, 2026
2a3d582
relink deserialized AnimEvents from the cinematic appstate
riccardobl Jan 18, 2026
f85de8b
Merge branch 'jMonkeyEngine:master' into capdevon-Cinematic
capdevon Jan 19, 2026
7d9880d
throw if spatial is not found
riccardobl Jan 19, 2026
3a784d9
add tests
riccardobl Jan 19, 2026
fe2ab03
add cinematic abstraction
riccardobl Jan 19, 2026
a597097
make cinematic handler savable
riccardobl Jan 19, 2026
de30e2e
move deprecated fallback into CinematicEvent
riccardobl Jan 19, 2026
1c48509
make CinematicHandler extend CinematicEvent for backward compatibility
riccardobl Jan 19, 2026
a6a5df1
improve abstraction
riccardobl Jan 20, 2026
b9b4d81
cleanup
riccardobl Jan 20, 2026
803cd48
code review
capdevon Jan 21, 2026
013016f
Update SoundEvent
capdevon Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 182 additions & 10 deletions jme3-core/src/main/java/com/jme3/cinematic/Cinematic.java
View file
Open in desktop

Large diffs are not rendered by default.

104 changes: 104 additions & 0 deletions jme3-core/src/main/java/com/jme3/cinematic/CinematicBase.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
package com.jme3.cinematic;

import com.jme3.animation.LoopMode;

/**
* The base interface for cinematic.
*/
public interface CinematicBase {

/**
* Starts the animation
*/
public void play();

/**
* Stops the animation
*/
public void stop();

/**
* this method can be implemented if the event needs different handling when
* stopped naturally (when the event reach its end)
* or when it was forced stopped during playback
* otherwise it just calls regular stop()
*/
public void forceStop();

/**
* Pauses the animation
*/
public void pause();

/**
* Returns the actual duration of the animation
* @return the duration
*/
public float getDuration();

/**
* Sets the speed of the animation (1 is normal speed, 2 is twice faster)
*
* @param speed the desired speed (default=1)
*/
public void setSpeed(float speed);

/**
* returns the speed of the animation
* @return the speed
*/
public float getSpeed();

/**
* returns the PlayState of the animation
* @return the plat state
*/
public PlayState getPlayState();

/**
* @param loop Set the loop mode for the channel. The loop mode
* determines what will happen to the animation once it finishes
* playing.
*
* For more information, see the LoopMode enum class.
* @see LoopMode
*/
public void setLoopMode(LoopMode loop);

/**
* @return The loop mode currently set for the animation. The loop mode
* determines what will happen to the animation once it finishes
* playing.
*
* For more information, see the LoopMode enum class.
* @see LoopMode
*/
public LoopMode getLoopMode();

/**
* returns the initial duration of the animation at speed = 1 in seconds.
* @return the initial duration
*/
public float getInitialDuration();

/**
* Sets the duration of the animation at speed = 1, in seconds.
*
* @param initialDuration the desired duration (in de-scaled seconds)
*/
public void setInitialDuration(float initialDuration);

/**
* Fast-forwards to the given time, where time=0 is the start of the event.
*
* @param time the time to fast-forward to
*/
public void setTime(float time);

/**
* returns the current time of the cinematic event
* @return the time
*/
public float getTime();

}
120 changes: 120 additions & 0 deletions jme3-core/src/main/java/com/jme3/cinematic/CinematicHandler.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
package com.jme3.cinematic;

import com.jme3.asset.AssetManager;
import com.jme3.cinematic.events.CinematicEvent;
import com.jme3.export.Savable;
import com.jme3.scene.CameraNode;

/**
* A interface that defines an object that can compose and coordinate cinematic events.
*/
public interface CinematicHandler extends CinematicBase, Savable {

/**
* Adds a cinematic event to this cinematic at the given timestamp. This
* operation returns a keyFrame
*
* @param timeStamp the time when the event will start after the beginning
* of the cinematic
* @param cinematicEvent the cinematic event
* @return the keyFrame for that event.
*/
KeyFrame addCinematicEvent(float timeStamp, CinematicEvent cinematicEvent);

/**
* Enqueue a cinematic event to a Cinematic. This is handy when you
* want to chain events without knowing their durations.
*
* @param cinematicEvent the cinematic event to enqueue
* @return the timestamp the event was scheduled.
*/
float enqueueCinematicEvent(CinematicEvent cinematicEvent);

/**
* removes the first occurrence found of the given cinematicEvent.
*
* @param cinematicEvent the cinematicEvent to remove
* @return true if the element has been removed
*/
boolean removeCinematicEvent(CinematicEvent cinematicEvent);

/**
* removes the first occurrence found of the given cinematicEvent for the
* given time stamp.
*
* @param timeStamp the timestamp when the cinematicEvent has been added
* @param cinematicEvent the cinematicEvent to remove
* @return true if the element has been removed
*/
boolean removeCinematicEvent(float timeStamp, CinematicEvent cinematicEvent);

/**
* removes the first occurrence found of the given cinematicEvent for the
* given keyFrame
*
* @param keyFrame the keyFrame returned by the addCinematicEvent method.
* @param cinematicEvent the cinematicEvent to remove
* @return true if the element has been removed
*/
boolean removeCinematicEvent(KeyFrame keyFrame, CinematicEvent cinematicEvent);

/**
* returns a cameraNode given its name
*
* @param cameraName the camera name (as registered in
* Cinematic#bindCamera())
* @return the cameraNode for this name
*/
CameraNode getCamera(String cameraName);

/**
* Sets the active camera instantly (use activateCamera if you want to
* schedule that event)
*
* @param cameraName the camera name (as registered in
* Cinematic#bindCamera())
*/
void setActiveCamera(String cameraName);

/**
* schedule an event that will activate the camera at the given time
*
* @param timeStamp the time to activate the cam
* @param cameraName the camera name (as registered in
* Cinematic#bindCamera())
*/
void activateCamera(float timeStamp, String cameraName);

/**
* used internally put an eventdata in the cinematic
*
* @param type the type of data
* @param key the key
* @param object the data
*/
void putEventData(String type, Object key, Object object);

/**
* used internally return and event data
*
* @param type the type of data
* @param key the key
* @return the pre-existing object, or null
*/
Object getEventData(String type, Object key);

/**
* Used internally remove an eventData
*
* @param type the type of data
* @param key the key of the data
*/
void removeEventData(String type, Object key);

/**
* Returns the AssetManager associated with this CinematicHandler.
*
* @return The AssetManager instance.
*/
AssetManager getAssetManager();
}
18 changes: 15 additions & 3 deletions jme3-core/src/main/java/com/jme3/cinematic/events/AbstractCinematicEvent.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,7 @@

import com.jme3.animation.AnimationUtils;
import com.jme3.animation.LoopMode;
import com.jme3.app.Application;
import com.jme3.cinematic.Cinematic;
import com.jme3.cinematic.CinematicHandler;
import com.jme3.cinematic.PlayState;
import com.jme3.export.InputCapsule;
import com.jme3.export.JmeExporter;
Expand All @@ -60,6 +59,7 @@ public abstract class AbstractCinematicEvent implements CinematicEvent {
protected float speed = 1;
protected float time = 0;
protected boolean resuming = false;
protected CinematicHandler cinematic;

/**
* The list of listeners.
Expand Down Expand Up @@ -294,6 +294,7 @@ public void write(JmeExporter ex) throws IOException {
oc.write(speed, "speed", 1);
oc.write(initialDuration, "initalDuration", 10);
oc.write(loopMode, "loopMode", LoopMode.DontLoop);
oc.write(cinematic, "cinematic", null);
}

/**
Expand All @@ -308,6 +309,7 @@ public void read(JmeImporter im) throws IOException {
speed = ic.readFloat("speed", 1);
initialDuration = ic.readFloat("initalDuration", 10);
loopMode = ic.readEnum("loopMode", LoopMode.class, LoopMode.DontLoop);
cinematic = (CinematicHandler) ic.readSavable("cinematic", null);
}

/**
Expand All @@ -317,7 +319,8 @@ public void read(JmeImporter im) throws IOException {
* @param cinematic ignored
*/
@Override
public void initEvent(Application app, Cinematic cinematic) {
public void initEvent(CinematicHandler cinematic) {
this.cinematic = cinematic;
}

/**
Expand Down Expand Up @@ -370,4 +373,13 @@ public float getTime() {
@Override
public void dispose() {
}

public CinematicHandler getCinematic() {
return cinematic;
}

public void setCinematic(CinematicHandler cinematic) {
this.cinematic = cinematic;
}

}
Loading
Loading