Package ke.ric.renderer.api

Class SnapshotBuilder

java.lang.Object
ke.ric.renderer.api.SnapshotBuilder
public final class SnapshotBuilder extends Object
Immutable settings for one snapshot. Each modifier returns a new builder; retain or chain its return value. A builder may be reused to request multiple captures. Entity state is sampled on the server thread when each capture begins, not when the builder is configured.

Defaults are Classic 128×128, 70° vertical FOV, zero roll, a 16-block radius and at most two captured chunks per tick. Source entities are excluded; living cameras use their eye pose. Required chunks must already be loaded. Nothing in this API silently loads missing scenery.

capture() yields pixels and evidence without allocating maps. captureMap() requests a durable, automatically saved photo item. Callback overloads run on the server thread; ordinary future continuations have normal Java threading semantics. Cancellation propagates to owned capture/render/output work. Never block the server thread waiting for a future.


 renderer.snapshot(player)
         .fov(75).roll(5)
         .environment(RenderEnvironment.captured().timeOfDay(6000))
         .excluding(nearbyEntities)
         .capture(frame -> plugin.getLogger().info("Camera: " + frame.effectiveCamera()));

  • Method Details

    • resolution

      public SnapshotBuilder resolution(int width, int height)
      Sets explicit render dimensions. The immutable original builder is unchanged.
      Parameters:
      width - positive output width in pixels
      height - positive output height in pixels
      Returns:
      a new builder with this setting
      Throws:
      IllegalArgumentException - for invalid dimensions

    • fov

      public SnapshotBuilder fov(double degrees)
      Sets vertical field of view, changing the camera framing rather than image brightness. The default is 70°. Older providers explicitly reject unsupported custom FOV.
      Parameters:
      degrees - finite vertical angle strictly between 0 and 180
      Returns:
      a new builder with this setting
      Throws:
      IllegalArgumentException - for an invalid angle

    • profile

      public SnapshotBuilder profile(RenderSettings.Profile profile)
      Selects rendering quality. Check the active provider's advertised profiles before choosing a profile; explicit requested lights and shadows are not silently disabled by quality.
      Parameters:
      profile - supported quality profile; default CLASSIC
      Returns:
      a new builder with this setting

    • radius

      public SnapshotBuilder radius(double blocks)
      Sets how far loaded-world evidence is captured around the source camera. Larger radii increase capture and render work; required chunks must already be loaded.
      Parameters:
      blocks - finite positive radius in blocks; default 16
      Returns:
      a new builder with this setting
      Throws:
      IllegalArgumentException - for a nonpositive or nonfinite radius

    • chunksPerTick

      public SnapshotBuilder chunksPerTick(int chunks)
      Sets the maximum number of chunks read per server tick during this snapshot. Required chunks must already be loaded; this budget controls work, not chunk loading.
      Parameters:
      chunks - positive per-tick budget; default 2
      Returns:
      a new builder with this budget
      Throws:
      IllegalArgumentException - if chunks is not positive

    • settings

      public SnapshotBuilder settings(RenderSettings settings)
      Replaces rendering settings, including resolution, profile, attachments, memory and timeout. Camera FOV, roll, capture radius and recipe controls remain as configured.
      Parameters:
      settings - complete immutable render settings
      Returns:
      a new builder with this setting

    • excluding

      public SnapshotBuilder excluding(UUID... ids)
      Adds UUID exclusions before visual capture, cumulatively across every layer.
      Parameters:
      ids - UUIDs to omit; no null or duplicate elements
      Returns:
      a new builder with the combined exclusions

    • excluding

      public SnapshotBuilder excluding(Set<UUID> ids)
      Adds a defensive copy of UUID exclusions before visual capture. Exclusions are cumulative and apply to every layer, including Xray and lighting; the camera entity is already excluded.
      Parameters:
      ids - UUIDs to omit; no null elements
      Returns:
      a new builder with this setting

    • excluding

      public SnapshotBuilder excluding(org.bukkit.entity.Entity... entities)
      Adds entities to omit before visual capture. References are copied now; UUIDs are read on the server thread when preparing capture. The camera entity is already excluded.
      Parameters:
      entities - entities to omit; no null elements
      Returns:
      a new builder with this setting

    • capture

      public CompletableFuture<RenderedFrame> capture()
      Captures and renders pixels and native evidence without allocating maps. Safe to request from any thread: Bukkit reads are dispatched to the server thread and rendering runs asynchronously. Cancellation propagates to owned work; never block the server thread waiting for completion.
      Returns:
      a future for the immutable frame, or an exceptional completion on capture/render failure

    • capture

      public CompletableFuture<RenderedFrame> capture(Consumer<RenderedFrame> success)
      Requests a frame and delivers the success callback on the server thread after a final lifecycle check. Callback exceptions fail the returned future. No map is allocated.
      Parameters:
      success - nonnull consumer of the rendered frame
      Returns:
      a cancellable future settled after callback delivery; ordinary continuations have no thread guarantee

    • capture

      public CompletableFuture<RenderedFrame> capture(Consumer<RenderedFrame> success, Consumer<Throwable> error)
      Requests a frame and delivers the success callback on the server thread after a final lifecycle check. Callback exceptions fail the returned future. No map is allocated.
      Parameters:
      success - nonnull consumer of the rendered frame
      error - optional server-thread failure observer, or null; failures still complete the future exceptionally
      Returns:
      a cancellable future settled after callback delivery; ordinary continuations have no thread guarantee

    • captureMap

      public CompletableFuture<org.bukkit.inventory.ItemStack> captureMap()
      Captures, fits the result into one 128×128 map preserving aspect ratio with black letterboxing, and saves a provider-owned photo. Conversion and durable storage run off-thread; map allocation runs on the server thread. Completion means persistence succeeded, not merely that pixels exist. Your plugin owns item delivery, inventory-full policy and organisation.
      Returns:
      a cancellable future for the tagged photo item; fails if capture, conversion or saving fails

    • captureMap

      public CompletableFuture<org.bukkit.inventory.ItemStack> captureMap(Consumer<org.bukkit.inventory.ItemStack> success)
      Requests a saved photo and delivers the success callback on the server thread after a final lifecycle check. Callback exceptions fail the returned future. The photo is saved before delivery; your plugin chooses how to retain or deliver the item if an inventory is full.
      Parameters:
      success - nonnull consumer of the durable photo item
      Returns:
      a cancellable future settled after callback delivery; ordinary continuations have no thread guarantee

    • captureMap

      public CompletableFuture<org.bukkit.inventory.ItemStack> captureMap(Consumer<org.bukkit.inventory.ItemStack> success, Consumer<Throwable> error)
      Requests a saved photo and delivers the success callback on the server thread after a final lifecycle check. Callback exceptions fail the returned future. The photo is saved before delivery; your plugin chooses how to retain or deliver the item if an inventory is full.
      Parameters:
      success - nonnull consumer of the durable photo item
      error - optional server-thread failure observer, or null; failures still complete the future exceptionally
      Returns:
      a cancellable future settled after callback delivery; ordinary continuations have no thread guarantee

    • roll

      public SnapshotBuilder roll(double degrees)
      Rotates the camera around its viewing axis. Camera-relative lights follow the same roll. The default is zero; this convenience method uses degrees, while SceneCamera uses radians.
      Parameters:
      degrees - any finite roll angle, including full turns and inverted views
      Returns:
      a new builder with this setting
      Throws:
      IllegalArgumentException - if degrees is nonfinite

    • lighting

      public SnapshotBuilder lighting(RenderLighting value)
      Sets request-level world and explicit lighting. Layers inherit this setup unless they supply their own complete lighting value. Exposure and post-render brightness are separate controls.
      Parameters:
      value - immutable lighting setup; default RenderLighting.world()
      Returns:
      a new builder with this setting

    • onProgress

      public SnapshotBuilder onProgress(Consumer<FrameProgress> value)
      Observes measured stage-local work on the server thread, at most once per tick. Updates are coalesced; stages and render passes can restart at zero. Percentage is basisPoints / 100.0. Keep the callback quick. Throwing fails pending work; a final coalesced notification may arrive after successful completion and cannot revoke it. Lifecycle checks suppress callbacks after cancellation or owner/provider invalidation.
      Parameters:
      value - nonnull progress observer
      Returns:
      a new builder with this setting

    • content

      public SnapshotBuilder content(SceneContent value)
      Selects which captured block/entity geometry remains available to each render pass. Removed geometry cannot contribute to camera, reflection or shadow rays; sampled environment and light levels remain. Entity layers can instead restrict camera output while retaining scene geometry. Use excluding(...) to omit entities before capture.
      Parameters:
      value - immutable selection; default SceneContent.all()
      Returns:
      a new builder with this setting

    • appearance

      public SnapshotBuilder appearance(RenderAppearance value)
      Sets rendering appearance, including exposure. Exposure is applied by the renderer; layer brightness is a separate multiplication of already rendered pixels.
      Parameters:
      value - immutable appearance overrides; unspecified fields inherit captured values
      Returns:
      a new builder with this setting

    • recipe

      public SnapshotBuilder recipe(RenderRecipe value)
      Replaces the ordered render recipe. Every layer derives independently from the same original capture. Entity layers respect scene occlusion unless explicitly configured otherwise.
      Parameters:
      value - nonempty immutable recipe; default one full-scene layer
      Returns:
      a new builder with this setting

    • mapOptions

      public SnapshotBuilder mapOptions(MapOutputOptions value)
      Sets map-palette conversion options. This affects map output without changing the rendered RGBA image, capture settings or lighting.
      Parameters:
      value - conversion settings; default no dithering
      Returns:
      a new builder with this setting

    • visibleTo

      public SnapshotBuilder visibleTo(org.bukkit.entity.Player value)
      Applies Bukkit visibility rules for a viewer. Hidden entities are excluded from capture and privacy is checked again before publication. Layers and explicit Xray cannot restore them.
      Parameters:
      value - viewer whose canSee rules apply; does not itself create a player output
      Returns:
      a new builder with this setting

    • environment

      public SnapshotBuilder environment(RenderEnvironment value)
      Overrides rendered time/weather without changing the live world or captured provenance. Unspecified fields inherit captured facts. Layers can override individual fields again.
      Parameters:
      value - immutable environment settings
      Returns:
      a new builder with this setting

    • excluding

      public SnapshotBuilder excluding(Collection<? extends org.bukkit.entity.Entity> values)
      Adds entities from a list, set or other collection. References are defensively copied and UUIDs are read on the server thread. Exclusions are cumulative and apply to every recipe layer.
      Parameters:
      values - entity references to omit; no null elements
      Returns:
      a new builder with this setting

    • excludingIds

      public SnapshotBuilder excludingIds(Collection<UUID> values)
      Adds UUIDs from any collection without retaining the caller's collection. Use this overload when you already have IDs rather than live entity references.
      Parameters:
      values - entity UUIDs to omit; no null elements
      Returns:
      a new builder with this setting