{"pages":[{"title":"Ultimate Camera","description":"","slug":"ultimate-camera","path":"ultimate-camera/index.md","section":"Plugins","category":"Plugins","parent":null,"order":1,"content":"\n![Ultimate Camera](https://raw.githubusercontent.com/seailz/docs/refs/heads/main/images/ultimate-camera/banner.png)\n\n**Ultimate Camera** provides a powerful way to create rich, smooth, and detailed camera and cutscene experiences in Minecraft Java, without needing any mods - just a plugin and resource pack!\n\n![Keyframe List](https://raw.githubusercontent.com/seailz/docs/refs/heads/main/images/ultimate-camera/keyframelist.png)\n\nGet started by [installing the plugin](/docs/ultimate-camera/installation), or [purchasing it if you haven't already](https://builtbybit.com/resources/ultimate-camera.116877/)."},{"title":"Installation","description":"","slug":"ultimate-camera/installation","path":"ultimate-camera/installation.md","section":"Getting started","category":"Getting started","parent":"ultimate-camera","order":2,"content":"\nUltimate Camera is compatible with the following versions of Paper:\n- 26.2\n\n## Plugin\n\nMake sure to download the latest version of Ultimate Camera from [BuiltByBit](https://builtbybit.com/resources/ultimate-camera.116877/) and place it in your server's `plugins` folder. After the first startup, Ultimate Camera will automatically generate a `config.yml` file in the `plugins/UltimateCamera` folder.\n\n## Resource Pack\n\nUltimate Camera relies on a resource pack to function. Without it, cutscenes will not work properly.\n\nThe plugin will automatically attempt to apply the correct resource pack for each player who joins the server. Because the shaders which Ultimate Camera uses often change, it is important that the correct version is applied based on the player's Minecraft version.\n\nIf your server does not already have a resource pack, there is nothing else you need to do.\n\n:::accordion What if my server already has a resource pack?\n\nYou will need to handle versioned resource packs yourself and disable the `automatic-resource-pack -> use-ultimate-camera-packs` option in the `config.yml` file.\n\nUltimate Camera will publish updated versions of the resource pack for each Minecraft version on [GitHub](https://github.com/seailz/ultimate-camera-packs/releases/latest) (they are also included in your BuiltByBit download), and you should make sure to update your server's resource pack whenever a new version is released by copying the `assets/minecraft/shaders/core` and `assets/minecraft/shaders/include` folders into your pack.\nMake sure to download the correct version for your version of Ultimate Camera. You can find this by running `/version UltimateCamera` in-game.\n\nIf your server supports multiple Minecraft versions, you will need to provide a separate resource pack for each version and make sure that only the correct version is applied to each player. Ultimate Camera can help you do this automatically if you set `alternative-packs` in your `config.yml` for each version, including the URL and hash of the resource pack.\n\n\nFor the following versions:\n\n- Versions below 26.2: Not supported by Ultimate Camera.\n- 26.2.x: use the 26.2 resource pack.\n:::\n\n## Datapack\n\nUltimate Camera includes and automatically enables the datapack required by the plugin. You do not need to download or install it separately.\n\nAfter starting the server, check the console for the message `ACC datapack loaded successfully`. If the datapack cannot be loaded, Ultimate Camera will disable itself and print an error to the console."},{"title":"Creating a cutscene","description":"","slug":"ultimate-camera/cutscenes","path":"ultimate-camera/cutscenes.md","section":"Getting started","category":"Getting started","parent":"ultimate-camera","order":3,"content":"\nUltimate Camera provides an in-game cutscene editor to allow you to create cinematic cutscenes without writing any code.\n\nGet started by running `/cutscene create `, for which you'll need the `ultimatecamera.cutscene.create` permission. This will place you into the cutscene editor.\n![Cutscene Editor](https://raw.githubusercontent.com/seailz/docs/refs/heads/main/images/ultimate-camera/cutsceneeditor.png)\n\nUse the blaze rod to create a [keyframe](https://en.wikipedia.org/wiki/Key_frame) at your location and orientation. You can then modify the keyframe's properties such as easing, roll, FOV/Zoom, and more. Excessively wide FOV settings are discouraged as they may cause visual bugs. Once you're done, you can preview the keyframe using the enderpearl, and then save it.\n\nIf you want to go back and edit a keyframe at any time, you can use the `Keyframe Timeline` GUI, or you can click on the particles in the world to select it. You can also preview your entire cutscene at any time using the spyglass.\n\n![Keyframe List](https://raw.githubusercontent.com/seailz/docs/refs/heads/main/images/ultimate-camera/keyframelist.png)\n\n## Easing\n\nUltimate Camera provides a few different easing options built in.\n\n- `Hold`: The camera will hold its position and orientation until the next keyframe.\n- `Linear`: The camera will move in a straight line between keyframes.\n- `Smooth` (ease in/out): The camera will speed up and slow down as it approaches and leaves keyframes, creating a smooth transition.\n- `Sine`: The camera will move in a slightly softer and more cinematic way than linear.\n- `Cubic in`: The camera will start slow and speed up as it approaches the next keyframe.\n- `Cubic out`: The camera will start fast and slow down as it approaches the next keyframe.\n- `Cubic in/out`: The camera will start slow, speed up, and then slow down again as it approaches the next keyframe.\n- `Back out`: The camera will overshoot the next keyframe and then come back to it, creating a more dynamic/bouncey movement.\n- `Out Sine`: The camera will start fast and slow down as it approaches the next keyframe, with a sine wave motion.\n\nYou can also modify the strength of the curve.\n\n![Keyframe List](https://raw.githubusercontent.com/seailz/docs/refs/heads/main/images/ultimate-camera/easingoptions.png)\n\nCustomizing the curve more than this is not supported due to technical limitations, and easing functions need to be hard-coded into the resource pack. If you have a specific easing function in mind, please [create a support ticket in Discord,](https://discord.gg/QQKhZFxWAA) and we'll likely add it in a future update.\n\n## Cutscene Settings\n\nYou can modify global settings of a cutscene using the compass. \n\n### Position space\nThe position space of the animation defines where keyframes actually are in relation to the camera and world. There are two options:\n- **Fixed world position**: Keyframes are placed in the world at their actual coordinates. The animation will always play in the same location, regardless of where the player is when they start it. This is good for cutscenes that are meant to be played in a specific location, such as a cinematic or a scripted event.\n- **Relative to an origin point**: Keyframes are placed relative to an origin point. This can either be defined by you or it can be set to the player's head location.\n\n### Mimicking NPC\n\nWhen the cutscene is played, a player cannot see their own character. However, you can choose to create a \"mimicking NPC\" that will be visible to the player (and also other players) during the cutscene, creating an \"out of body\" experience. This feature requires [Citizens](https://www.spigotmc.org/resources/citizens.13811/) to be installed on the server.\n\nYou can also choose to allow the player to control the mimicking NPC during the cutscene or not. This requires [PacketEvents](https://modrinth.com/plugin/packetevents) to be installed on the server."},{"title":"API Installation","description":"","slug":"ultimate-camera/api-installation","path":"ultimate-camera/api-installation.md","section":"API Usage","category":"API Usage","parent":"ultimate-camera","order":4,"content":"\nOnce you've installed Ultimate Camera, you can start using the API to create cutscenes programmatically in your own plugin. It's included in the Ultimate Camera plugin, so you don't need to install it separately.\n\nThe API provides:\n- Three dimensional camera movement\n- Yaw, pitch, and roll control\n- Animated FOV/zoom\n- Multiple easing curves\n- World-space and origin-relative animations\n- Predefined and dynamically generated animation paths (so you don't need to send all keyframes in advance)\n- Optional Citizens player mimics\n- Safe playback lifecycle and resource-pack checking\n\n## Maven\n\nAdd the following to your `pom.xml` file. **Do not package or shade Ultimate Camera into your plugin.**\n\n```xml\n \n com.seailz\n advanced-camera-control\n 1.0.0\n provided\n \n```\n\nThere is not a public Maven repository for Ultimate Camera, so you will need to install it into your local repoistory.\n\n```shell\nmvn install:install-file -Dfile=\"C:\\path\\to\\UltimateCamera.jar\" -DgroupId=com.seailz -DartifactId=advanced-camera-control -Dversion=1.0.0 -Dpackaging=jar\n```\n\n## plugin.yml\nIf you're using `paper-plugin.yml`, include the following:\n```yaml\ndependencies:\n server:\n UltimateCamera:\n load: BEFORE\n required: true\n join-classpath: true\n```\nOr if you're using `plugin.yml`, include the following:\n```yaml\ndepend: [UltimateCamera]\n```\n"},{"title":"Animation Types","description":"","slug":"ultimate-camera/animation-types","path":"ultimate-camera/animation-types.md","section":"API Usage","category":"API Usage","parent":"ultimate-camera","order":5,"content":"\n\nUltimate Camera has two types of animations available in the API:\n\n- **Runtime Animations**: These contain the complete keyframe path from before the animation starts. Ultimate Camera uploads a few keyframes to start, then continues uploading keyframes while the animation runs. These can contain essentially unlimited keyframes.\n- **Live Animations**: These work similarly to Runtime Animations. They require you to upload at least two keyframes to start, but you can upload new keyframes in real time while the animation is running. This is useful for paths generated from dynamic data, but you must upload keyframes slightly in advance to stay ahead of the client. Call `finish()` when no more keyframes will be added.\n\nIn most cases, you'll want to build a `RuntimeAnimation` then use `tryPlay(...)` or `play(...)` to begin it for the player. Use `LiveAnimation` only when the full keyframes are not known in advance.\n"},{"title":"Keyframes","description":"","slug":"ultimate-camera/keyframes","path":"ultimate-camera/keyframes.md","section":"API Usage","category":"API Usage","parent":"ultimate-camera","order":6,"content":"A `Keyframe` defines the complete camera position at an absolute time.\n- X, Y, Z\n- Yaw\n- Pitch\n- Roll\n- FOV (the default is 70)\n- Easing\n- Position space\n\nYou can create keyframes with `Keyframe.builder()`.\n\n## Time\n```java\n.time(Duration.ofSeconds(3))\n```\nKeyframe times are absolute offsets from animation activation.\nFor example:\n- Keyframe A: 0 seconds\n- Keyframe B: 2 seconds\n- Keyframe C: 5 seconds\n\nThis produces:\n- A → B over 2 seconds\n- B → C over 3 seconds\n\nMake sure your first keyframe is at `Duration.ZERO`. A nonzero timestamp on that keyframe will not delay its activation. Ultimate Camera\nsupports precision of `0.01` seconds, and each individual gap between keyframes has a maximum of `655.35 seconds`. The complete animation,\nhowever, can be much longer. If you want to represent a jump cut, create two keyframes in sequence with the same timestamp.\n\n## Position\nPosition values are rounded to the nearest 1/16 block and must be between `-2048` and `2047.9375` inclusive. The meaning of the coordinates depends on the selected position space.\n## Orientation\nYaw and pitch must be between `-180` and `180` degrees, and are rounded to the nearest `2` degrees.\n\nRoll is rounded to the nearest `2` degrees, but may represent multiple revolutions. For example,\n```java\n.roll(720)\n```\nrequests two complete revolutions. Ultimate Camera will automatically divide the extended roll into more keyframes when the animation runs.\nThis will increase the effective keyframe count and upload time. \n\nOrdinary angular interpolation takes the shortest route. If you require a particular yaw or pitch rotation direction, add intermediate keyframes before crossing 180 degrees.\n\n## FOV\nFOV must be between 1 and 170 degrees.\nExamples:\n- 30: strongly zoomed in\n- 70: approximately normal\n- 100: wide\n- 150: extremely wide\n\nIf you go wider than the client's set FOV, you should expect graphical issues with terrain. So, wide FOVs are discouraged.\n\n## Easing and position spaces\nFor info on how easing and position spaces work, see [Cutscenes](/docs/ultimate-camera/cutscenes)."},{"title":"Animations","description":"","slug":"ultimate-camera/animations","path":"ultimate-camera/animations.md","section":"API Usage","category":"API Usage","parent":"ultimate-camera","order":7,"content":"\n## Runtime Animation\n\n`RuntimeAnimation` is the recommended animation type when the complete path is known in advance.\n\n```java\nRuntimeAnimation animation = RuntimeAnimation.builder()\n .keyframe(first)\n .keyframe(second)\n .keyframe(third)\n .build();\n```\n\nYou can then use `tryPlay` or `play` on the object depending on whether or not you would like to first validate\nwhether the player has installed the resource pack successfully.\n\n### Animation Length\n\nThe client will retain 16 keyframes at once, but this is not a total limit, as Ultimate Camera reuses keyframes as the playhead passes them. Before accepting playback, Ultimate Camera verifies that the path can be uploaded quickly enough. A path with excessively dense keyframes may throw an `IllegalArgumentException`.\n\n## Live Animation\n`LiveAnimation` is intended for camera paths created while playback is already running.\nA live animation needs at least two initial keyframes:\n```java\nLiveAnimation animation = LiveAnimation.builder()\n .keyframe(first)\n .keyframe(second)\n .build();\n```\n\nThen you can begin playback:\n```java\nAnimationPlayback.RequestResult result =\n animation.tryPlay(player, PlaybackOptions.DEFAULT);\n```\nAnd append future keyframes as you go:\n```java\nanimation.append(Keyframe.builder()\n .time(Duration.ofSeconds(6))\n .xyz(10, 4, 16)\n .yawPitchRoll(80, -10, 0)\n .fov(70)\n .easing(Keyframe.Ease.SMOOTH)\n .positionSpace(Keyframe.PositionSpace.ORIGIN_RELATIVE)\n .build());\n```\n\n\nAppended timestamps must:\n- Be in non-decreasing order\n- Not precede the animation’s current final timestamp\n\nEqual timestamps are allowed for cuts.\n\n### Finishing\nA live animation remains active when it reaches its latest available keyframe. It holds that pose and waits for more data.\nCall `animation.finish();` to declare that no more keyframes will arrive. Playback will then end naturally after the final timestamp.\n\n### Keeping ahead of the client\nKeyframes must arrive before the client needs them. You can calculate the required lead you must maintain using\n```java\nDuration requiredLead =\n LiveAnimation.minimumLeadFor(pendingKeyframesToUpload);\n```\nThe formula is:\n```\n500ms safety margin + 300ms per keyframe\n```\nSo, you should maintain a lead of about `800ms` for 1 keyframe, `2000ms` for 5 keyframes, `3500ms` for 10, etc. This doesn't\ntake account for network latency, lag, or other factors (which is why the safety margin exists), so as a rule of thumb, it is\nrecommended to always maintain a lead of approximatley two seconds.\n\n## Playback Options\n\n`PlaybackOptions` controls how Ultimate Camera manages the player and animation origin during playback. For most animations, you can use the default options:\n\n```java\nanimation.tryPlay(player, PlaybackOptions.DEFAULT);\n```\n\nPassing `null` as the options also uses `PlaybackOptions.DEFAULT`.\n\nThe default configuration:\n\n- Uses the player’s rendered camera as the origin for origin-relative animations\n- Fully locks the player during playback\n- Does not create a mimic NPC\n- Does not forward player input\n\nCustom options can be created using the builder:\n\n```java\nPlaybackOptions options = PlaybackOptions.builder()\n .build();\n\nanimation.tryPlay(player, options);\n```\n\n### Custom Origin\n\nWhen using `PositionSpace.ORIGIN_RELATIVE`, the origin normally comes from the player’s rendered camera immediately before playback begins. You can instead provide a fixed origin:\n\n```java\nLocation origin = new Location(\n world,\n 100,\n 75,\n -40,\n 90,\n -10\n);\n\nPlaybackOptions options = PlaybackOptions.builder()\n .originRelativeOrigin(origin)\n .build();\n\nanimation.tryPlay(player, options);\n```\n\nThe origin’s coordinates, yaw and pitch determine where and in which direction the relative animation is placed.\n\n### Player Mimics\n\nA Citizens NPC can be created to represent the player during the animation. This is useful because the player cannot normally see their own body while using a first-person camera.\n\n```java\nPlaybackOptions options = PlaybackOptions.builder()\n .createMimicNpc(true)\n .build();\n```\n\nThis feature requires Citizens to be installed on the server.\n\nPlayer input can optionally be forwarded to the mimic:\n\n```java\nPlaybackOptions options = PlaybackOptions.builder()\n .createMimicNpc(true)\n .forwardInputToMimic(true)\n .build();\n```\n\nInput forwarding includes movement, looking, held-item changes, using items and attacking. It requires PacketEvents 2.13 or newer.\n\n`forwardInputToMimic(true)` cannot be used unless `createMimicNpc(true)` is also enabled.\n\n### Player Locking\n\nUltimate Camera currently requires the player to be fully locked during playback because it uses the physical player for render tracking. The full lock is enabled by default:\n\n```java\nPlaybackOptions options = PlaybackOptions.builder()\n .lockPlayer(PlayerLock.full())\n .build();\n```\n\nDuring playback, Ultimate Camera temporarily manages the player’s location, flight, visibility, collision and invulnerability. Their previous state is restored when the animation finishes or is stopped.\n"}],"updatedAt":null,"repositoryAvailable":true}