Package ke.ric.renderer.api

Interface RendererClient

All Superinterfaces:
AutoCloseable
public interface RendererClient extends AutoCloseable
A consuming plugin's lifecycle and ownership boundary for captures, scenes, assets, and tasks. Clients become stale when closed or when their provider generation is disabled or reloaded.

  • Method Details

    • active

      boolean active()
      Returns a current lifecycle snapshot; individual operations always recheck validity.

    • capabilities

      RendererCapabilities capabilities()
      Returns a snapshot of this provider generation's advertised capabilities.

    • lightingCapabilities

      default LightingCapabilities lightingCapabilities()
      Returns explicit-lighting and primary-camera visibility limits for this provider generation. Older providers safely report unsupported capabilities. Check these before requesting creative controls; unsupported controls fail explicitly rather than being ignored.
      Returns:
      immutable provider lighting capabilities

    • newSceneBuilder

      SceneBuilder newSceneBuilder()
      Starts a manual scene builder; callers must supply all required world/visual evidence instead of relying on live lookup.

    • capture

      CompletionStage<Scene> capture(CaptureRequest request)
      Captures loaded Paper world state asynchronously, batching thread-affine reads on the main server thread. The completion continuation has no general thread guarantee. Required chunks must already be loaded; missing evidence fails rather than loading chunks.
      Parameters:
      request - copied camera, finite radius in blocks, dimensions and per-tick chunk budget
      Returns:
      stage yielding an immutable client-owned scene or a typed failure; never block the server thread waiting

    • capture

      default CompletionStage<Scene> capture(CaptureRequest request, double fovDegrees)
      Captures loaded world evidence with a vertical field of view in degrees. Required chunks must already be loaded. Older providers retain their 70° default and reject other values explicitly. Completion continuations have no general server-thread guarantee.
      Parameters:
      request - copied camera, capture radius, settings and per-tick budget
      fovDegrees - finite vertical FOV strictly between 0 and 180
      Returns:
      asynchronous immutable client-owned capture
      Throws:
      IllegalArgumentException - if FOV is invalid
      RendererException - if the provider does not support the requested FOV

    • capture

      default CompletionStage<Scene> capture(CaptureRequest request, double fovDegrees, double rollDegrees, Consumer<FrameProgress> progress)
      Captures loaded evidence with FOV and roll in degrees. Optional progress may arrive on any thread; fluent builders provide server-thread/coalesced observers. Older providers reject nonzero roll explicitly and may omit capture progress.
      Parameters:
      request - copied camera, capture radius, settings and per-tick budget
      fovDegrees - finite vertical FOV strictly between 0 and 180
      rollDegrees - any finite camera roll; zero preserves the ordinary orientation
      progress - optional capture-stage observer, or null
      Returns:
      asynchronous immutable client-owned capture
      Throws:
      IllegalArgumentException - if a requested angle is invalid
      RendererException - if the provider cannot support the requested controls

    • saveMap

      default CompletionStage<org.bukkit.inventory.ItemStack> saveMap(org.bukkit.World world, byte[] palette)
      Saves a copied 128×128 map palette and creates an item only after durable photo storage. Invoke on the server thread; conversion to palette bytes is the caller's responsibility. The provider restores saved photos independently of the consuming plugin. Older providers explicitly reject this optional operation.
      Parameters:
      world - loaded world in which the map is allocated
      palette - exactly 16384 row-major Minecraft map-palette bytes; copied before retention
      Returns:
      asynchronous saved photo item, or exceptional completion if allocation/persistence fails

    • createTemporaryMap

      default RenderedMap createTemporaryMap(org.bukkit.World world, byte[] palette)
      Creates a guarded temporary map on the server thread. The caller owns cleanup; this map is not stored as a durable photograph. Older providers reject this optional operation.
      Parameters:
      world - loaded allocation world
      palette - exactly 16384 row-major map-palette bytes
      Returns:
      temporary map helper; close it when no longer needed
      Throws:
      RendererException - if temporary allocation is unsupported or unsafe

    • deriveScene

      default Scene deriveScene(Scene source, SceneSelection selection)
      Derives an immutable selection from existing scene evidence, without recapturing live state. The source remains unchanged; removed evidence cannot be restored by a later derivation. Providers predating this optional operation reject it with UNSUPPORTED_CAPABILITY. This preview operation is supported only when validated with a matching development provider.
      Parameters:
      source - scene owned by this active client/provider generation
      selection - block/entity evidence to retain; camera, object IDs and generation identity stay unchanged
      Returns:
      immutable derivative; the source is not modified and no live Bukkit entity is read

    • deriveScene

      default Scene deriveScene(Scene source, SceneTransform transform)
      Derives immutable scene evidence after validating client and provider ownership. Older providers reject even identity transforms with UNSUPPORTED_CAPABILITY.
      Parameters:
      source - scene owned by this active client
      transform - immutable content/environment/appearance and optional lighting/visibility controls
      Returns:
      immutable derivative, or the validated source for an identity transform

    • reserveComposition

      default CompositionLease reserveComposition(long bytes)
      Reserves composition bytes from the provider-generation shared pool until close or shutdown.
      Parameters:
      bytes - positive reservation size
      Returns:
      idempotent, thread-safe lease
      Throws:
      RendererException - if unsupported, permanently oversized, or temporarily exhausted

    • supportedSceneOperations

      default Set<SceneOperation> supportedSceneOperations()
      Returns the optional scene operations implemented by this provider. Older providers return empty.

    • appendEntities

      default Scene appendEntities(Scene source, List<SceneEntity> entities)
      Appends copied, complete resolved entity evidence without changing the source or recapturing world state. The scene must belong to this active client and provider generation. UUIDs and nonzero object IDs must be unique across captured and appended entities. Targets require actual meshes with finite, nondegenerate geometry enclosed by their world bounds. Camera, chunks, lighting and weather are preserved. No live entity or resource lookup occurs.
      Parameters:
      source - immutable scene owned by this client
      entities - immutable exact visual evidence; the list is defensively copied
      Returns:
      a new client-owned scene; subsequent selections include the appended classifications
      Throws:
      RendererException - for unsupported composition, stale ownership or invalid/oversized evidence

    • reframeScene

      default Scene reframeScene(Scene source, SceneCamera camera, SceneReusePolicy policy)
      Renders a new camera pose against unchanged captured world evidence. This does not read the world or refresh captured entities, environment or capture age. The camera must remain in the original centre chunk and captured build-height coverage, within the displacement bound. Age starts at the first capture read and is checked at derivation, admission and worker start. Selecting or appending visuals never renews these limits. Camera-relative lights follow the new effective camera. A fresh capture is required on STALE_SCENE or MISSING_CHUNK.
      Parameters:
      source - captured scene owned by this active client/provider generation
      camera - effective camera in world blocks and radians; remains in the source world
      policy - maximum evidence age and displacement from the original capture
      Returns:
      immutable camera-only derivative
      Throws:
      RendererException - if unsupported, stale, foreign or outside captured coverage

    • registerAsset

      AssetHandle registerAsset(AssetPack pack)
      Registers copied archive evidence and returns a client-owned handle; invalid/bounded archives fail synchronously.

    • submit

      RenderTask submit(RenderJob job)
      Validates and attempts bounded queue/memory admission, returning immediately on success.
      Parameters:
      job - owned scene, matching settings and active asset hashes
      Returns:
      nonblocking task; rendering is performed off the server thread
      Throws:
      RendererException - if validation, capability, lifecycle, queue or memory admission fails

    • close

      void close()
      Idempotently cancels or releases client-owned work and registrations.
      Specified by:
      close in interface AutoCloseable