Package dev.miyomiyo.agentbridge.api.world

Interface WorldSession

public interface WorldSession
One extension's resources for one visit to a world, including travel between dimensions.

  • Method Summary

    Modifier and Type
    Method
    Description
    java.util.concurrent.CompletionStage<java.lang.Void>
    close()
    Called once on the client thread after the session is unavailable to new tool calls.
    default void
    relocated(WorldContext context)
    Called promptly on the client thread after the host records the new location.
    default void
    tick()
    Called on the client thread during an active visit to apply already completed background work and sample small local changes.

  • Method Details

    • tick

      default void tick() throws java.lang.Exception
      Called on the client thread during an active visit to apply already completed background work and sample small local changes. Do not block, perform I/O or run expensive computation. The host serializes this with relocation and close; a callback failure retires this session. Calls made while opening or another callback is running are not replayed. The next normal tick observes the latest state. Cleanup must never depend on this callback being called again.
      Throws:
      java.lang.Exception - if this session cannot continue

    • relocated

      default void relocated(WorldContext context) throws java.lang.Exception
      Called promptly on the client thread after the host records the new location. Keep the same world data; invalidate only observations that belong to the old location. Do not perform blocking I/O here.
      Parameters:
      context - the latest location in the same world visit
      Throws:
      java.lang.Exception - if this session cannot continue; the host then closes this session

    • close

      java.util.concurrent.CompletionStage<java.lang.Void> close() throws java.lang.Exception
      Called once on the client thread after the session is unavailable to new tool calls. Seal admissions and begin cleanup promptly, returning actual completion of accepted persistence and resource release. A caller's timeout is not completion. The returned stage must settle without another client tick. Report failures exceptionally with a structured diagnostic where possible. Do not use this callback to change a newer world's state.
      Returns:
      actual cleanup completion; cancellation of an observer must not cancel accepted work
      Throws:
      java.lang.Exception - when cleanup fails synchronously