Cutscene API

This release brings some useful features and optimizations, as well as some changes to existing ones.

Overview

• You can now specify cutscene length in seconds
• You can now allow the player to rotate their camera during a cutscene
• Added an effect that plays sounds
• Optimized point providers by caching them
• Added an event that modders can listen to that is triggered when a cutscene ends

Format changes

• Added an optional version field to cutscenes. Future versions will use this to log a warning if you use an usupported version. Current version is 0.
• Changed the way the length of cutscenes is defined - you now have more control over it:
  • length can now be an object with fields:
    • [resource location] type (one of ticks or seconds)
    • [double] length - the length of the cutscene. If type is ticks, this value is the length of the cutscene in ticks, if type is seconds, this is the length in seconds.
  • When specifying the length in seconds, the server's tickrate and lag is ignored, and the cutscene always lasts as long as you specify - no more or less.
  • The unit you choose applies to all other places where you enter some time (e.g. effect start and end times)
  • The old format is still supported
• Rotation handling has been changed:
  • Rotation handlers are defined with the rotation_handler field:
    • Can be a string, one of cutscene, player or add (see types below)
    • Can be an object with fields:
      • [resource location] type - one of cutscenes:cutscene, cutscenes:player, cutscenes:add or cutscenes:ease_back:
        • cutscenes:cutscene - blocks all player rotation (equivalent to "block_rotation" : true)
        • cutscenes:player - blocks all cutscene rotation, showing only the player rotation (equivalent to "block_rotation": false)
        • cutscenes:add - adds them together
        • cutscenes:ease_back - makes your camera slowly return to the cutscene's rotation
          • Has an additional field: [double] decay. The higher the value, the faster the camera returns. Works best with values between 1 and 25.
  • block_rotation field overrides the rotation handing if present:
    • true sets the handler to cutscene
    • false sets it to player if there's no rotation path, and cutscene otherwise
  • Default is cutscene
• Added a new effect: cutscenes:play_sound
  • Plays some sound the moment it starts
  • Ignores the end time
  • Format:
    • [resource location] sound - the sound that plays
    • [number between 0 and 1] volume - the volume of the sound. Default: 1
    • [number between 0 and 2] pitch - the pitch of the sound. Default: 1
    • [vec3] pos - the position of the sound relative to the player, in format [x, y, z]. Default: [0, 0, 0]

API changes

• PointProvider#getPoint(Level, Vec3) is now deprecated. Use its static equivalent (#getPoint(PointProvider, Level, Vec3) as it handles the point cache
• Added method PointProvider#shouldCache that returns a boolean indicating whether the point should get cached. If this method returns false, the point's value is calculated each frame. Defaults to true.
• Added an event system for modders:
  • Event<T> is a class representing an event. The type parameter T is any functional interface that can be used as a listener in your opinion.
  • You can add a listener with Event#addListener. It will be called every time the event is invoked.
  • You can invoke an event by calling Event#invoke with a consumer that runs each listener.
  • There are 2 events added in this release, then can be found in class CutsceneEvents:
    • CUTSCENE_OVER_CLIENT is called on the client whenever a cutscene ends. You are given the type of the cutscene, its ID, the player watching it and an EndingReason describing why it's over
    • CUTSCENE_OVER_SERVER is the same, but on the server. Since the server has no proper way of tracking the client's state, it may be off by a couple of ticks.
• An EndingReason is now needed to stop a cutscene. It is an enum describing why the cutscene is being stopped:
  • FINISH - the cutscene is over, like it should be
  • INTERRUPT - the cutscene has been interrupted by something, like another cutscene or the player logging out
  • COMMAND - the /cutscene stop command has been used
  • ERROR - something went wrong when running a cutscene. Should be impossible under normal circumstances.
• The registries with a default value in CutsceneAPI now use the exact type.
• Cutscene length is now defined with TimeManager objects. They are stored in TimeManager#REGISTRY with an accompanying DEFAULT_TRANSITIONS map that holds the default transitions for each type.
• Rotation handlers are a registry, found in CutsceneAPI#ROTATION_HANDLERS. Parameterless handlers can be inlined in JSON with a short string after adding them to RotationSerializer#SIMPLE_HANDLERS.

Fixes

• The mod now works on Fabric (for real)
• Waypoints are now much less laggy because of point caching, described above
• Fixed cutscenes lagging when the server tick rate is above 20 TPS
• The position of the camera during a cutscene shown on the F3 screen is now updated every frame instead of every tick

Compatibility

Most cutscenes made for previous versions still work. Mods should still work fine with no changes needed.