Lattice

Lattice 0.8.8 - Integration Failure Surfacing And Diagnostics Cleanup

Added

- PaperDiagnosticContributor.snapshot() now includes the current JVM thread name as a currentThread diagnostic detail. This makes it easier to verify Folia scheduler context when inspecting a runtime snapshot through diagnostics. - Reflective integration bootstrap failures now consistently surface the offending exception class and message through SimpleIntegration.failed(...) details. Diagnostics commands can read the same reason and message keys for every optional integration (previously only PacketEvents exposed them).

Changed

- PaperIntegrationBootstrap failure logging is now a concise single-line warning per integration instead of a full reflective stack trace. The exception class and message are still preserved in the details map on the returned SimpleIntegration so diagnostics remain rich. - PaperDiagnosticContributor.snapshot() entries are still keyed by their original ordering; currentThread is appended after enabled.

Fixed

- Inconsistent diagnostic detail population for failed reflective integrations: Junction, PlaceholderAPI, Nexo, Oraxen, ItemsAdder, and CraftEngine bootstrap failures now report reason and message consistently with PacketEvents.

Compatibility

- No plugin authoring API changes. - No stable @StableApi types were modified. - No new transitive dependencies. - Server owners who relied on full reflective stack traces in plugin logs see a single-line summary instead; the underlying exception class and message are still available through the diagnostic snapshot for any Integration with FAILED status.

Still Experimental (no change in status)

- dev.beryl.lattice.update - dev.beryl.lattice.hook - dev.beryl.lattice.template and annotation processors

Lattice 0.8.7 - Folia Thread-Safety Hardening

Fixed

Critical (AsyncCatcher Errors)

- [CRITICAL] Fixed PaperTaskService.scheduleEntity() thread validation - Added thread ownership validation before entity access - Prevents unsafe entity lookups from async contexts - Uses ReentrantLock for better granularity - [CRITICAL] Fixed race conditions in UI event handlers - Synchronized onInventoryClick() with ReentrantLock - Synchronized onPrepareAnvil() with ReentrantLock - Added closed() checks to prevent operations on closed sessions - [CRITICAL] Fixed block/player access in text input renderers - Protected getBlock() calls in PaperVirtualSignTextInputRenderer.restore() - Protected getLocation() calls in both virtual sign and anvil renderers - Prevents AsyncCatcher errors during text input UI operations - [CRITICAL] Fixed PacketEvents callback thread safety - Wrapped PacketEvents listeners to execute in global region scheduler - Prevents unsafe operations from packet thread

Important (Race Conditions)

- [IMPORTANT] Added volatile modifiers to PaperTextInputUiSession - completed, anvilView, signPosition, signLocation are now volatile - Ensures visibility across event handler and scheduler threads - [IMPORTANT] Synchronized handleVirtualSignChange() with ReentrantLock - Prevents race condition with concurrent session removal - [IMPORTANT] Synchronized PaperInventorySurfaceRenderer.render() page access - Copies button list atomically to avoid concurrent modification - Prevents IndexOutOfBoundsException - [IMPORTANT] Synchronized runOnPlayer() ownership check - Prevents race condition between region ownership check and schedule - [IMPORTANT] Added thread-safety documentation to PlaceholderAPI integrations - Documents that handlers are called from arbitrary threads - Lists unsafe and safe operations

Minor (Edge Cases)

- Improved lock granularity in session(Inventory) lookup - Prevented double registration in registerRefreshEvent()

Added

- Added direct standalone host contract coverage for managed plugin registration, duplicate registration protection, handle detach, host diagnostics, reverse-order shutdown, and shared storage cleanup. - Added an experimental UpdateService for GitHub release checks, typed update results, release assets, and explicit jar install requests. - Added PaperUpdateInstaller so Paper plugins can implement confirmed update commands that back up the old jar into Lattice/Old, replace the plugin jar, and prompt for a server restart.

Changed

- Standalone host shutdown now disables all managed plugin runtimes in reverse registration order even when one dependent plugin fails during disable. - Standalone host close now continues through managed plugin disable, shared storage pool close, and handle cleanup before rethrowing a collected shutdown failure. - The standalone Lattice plugin shutdown path now continues through managed plugin disable, host runtime disable, Bukkit service unregister, and host close before rethrowing a collected shutdown failure. - LatticeRuntime#disable() now closes registered services and cancels tasks even when called before the runtime has loaded. - The standalone Lattice plugin now performs a best-effort startup check for newer Lattice GitHub releases and stays silent when it is already current. - Public docs now describe the shared runtime host lifecycle, dependent plugin detach behavior, and the disable() before load() cleanup guarantee. - Public docs now include update-check and confirmed-install examples for plugin-owned admin commands.

Fixed

- A failed dependent plugin disable no longer prevents later managed plugins from being disabled during standalone host shutdown. - Shared JDBC pools are now closed during standalone host close even if a managed plugin fails while disabling. - Hosted plugin handles are now detached when a newly created runtime is disabled before it has loaded. - The runtime lifecycle docs no longer duplicate the enable() lifecycle step.

Compatibility

- Existing LatticeHost, LatticePluginHandle, and LatticeRuntime method signatures are unchanged. - Dependent plugins using LatticePaperPlugin or LatticePaper.bootstrap(...) do not need code changes. - Shutdown failures are still surfaced to the caller, but cleanup now continues before the failure is rethrown. - Update installs are opt-in and must be triggered by plugin code; no dependent plugin jar is replaced automatically.

Added

- Added optional lifecycle failure context on LifecycleException, including runtime id, phase, failed operation, and module id when available. - Added structured startup report entries while keeping the existing string-based startup event list. - Added optional config failure context on ConfigException, including config path and operation when Lattice can identify them. - Added lifecycle diagnostics details for failed runtime operations, including event count, failed operation, module id, and failure message.

Changed

- Module lifecycle callback failures now preserve module id and operation context across load, enable, ready, and disable paths. - YAML config load, parse, render, defaults, deserialize, validate, migrate, serialize, save, and update validation failures now use context-aware ConfigException reporting. - Public diagnostics and getting-started docs now describe how plugin-owned logging and diagnostics commands can surface lifecycle and config context.

Fixed

- Lifecycle diagnostics no longer report a failure finding for a fresh runtime that has not started. - Lifecycle diagnostics now keep an error status when a failed lifecycle entry remains after a later phase transition. - Disable failures now use lifecycle-neutral diagnostic wording instead of startup-specific wording.

Compatibility

- Existing LifecycleException and ConfigException constructors remain supported. - Existing StartupReport#events() callers continue to receive the legacy string event list. - Structured startup report write helpers remain runtime-owned and are not exposed as stable plugin authoring API.

Added

- Added ConfiguredUiException for configured inventory authoring failures, including a stable path() accessor and contextual messages. - Added configured inventory authoring documentation with a YAML-style menu example, fallback icons, configured actions, and resolver ownership guidance.

Changed

- ConfiguredInventoryUiCompiler now reports invalid configured UI input with screen, page, button, icon, fallback, and action context. - Configured UI resolver and text rendering failures are wrapped with configured UI paths so plugin authors can report actionable admin-facing errors. - Lattice.VERSION is generated from the Gradle latticeVersion used by the build instead of being maintained as a separate Java literal. - The GitHub Release workflow now supports stable 0.8.x releases as latest releases, recovery switches for publication steps, and tag-pinned reruns for existing release updates.

Fixed

- Maven Central PUBLISHING validation timeouts no longer prevent the workflow from continuing to mirror publication and GitHub Release creation. - GitHub Release notes now only claim GitHub Packages mirror publication when the mirror publish step succeeds. - Existing GitHub Release refreshes now refuse to upload assets built from a commit that does not match the release tag. - Generated version sources are now wired into source jar task dependencies.

Compatibility

- ConfiguredUiException extends IllegalArgumentException, so existing callers that catch authoring failures through the previous exception type continue to work. - Existing configured inventory defaults are preserved, including default rows for non-positive row counts and default icon amount for non-positive amounts. - ConfiguredUiAction remains a lightweight type + data declaration. Plugins still own action resolution through ConfiguredUiActionResolver.

Added

- Added CommandExceptionMappers as the reusable default command failure mapper for plugins that build command registration manually. - Added LatticeRuntime.COMMAND_EXCEPTION_MAPPER so Paper plugins can customize command failure wording through the runtime service model. - Added explicit LatticeBuilder helpers for default service registration, intentional service replacement, and service lookup during bootstrap. - Added standalone descriptor coverage to keep the Paper release jar dependency list intentional.

Changed

- Typed LatticeBuilder service helpers now provide defaults only when a service has not already been supplied. - Paper bootstrap now creates the default command registrar after plugin customization and passes the configured command exception mapper into it. - The standalone Paper descriptor no longer declares Junction as an optional dependency; Junction remains available through reflective integration detection when present. - Public authoring docs now spell out service customization, command feedback ownership, command help ownership, and optional integration checks.

Fixed

- Supplying a custom COMMAND_SERVICE no longer constructs the default Paper command registrar or registers its lifecycle handler as a side effect. - The standalone descriptor test now fails on accidental optional dependency additions, not just missing expected dependencies.

Compatibility

- Existing strict LatticeBuilder#service(key, service) behavior is unchanged. - Plugin code that intentionally replaces a service should use replaceService(key, service). - Plugin code that only needs custom command failure text should prefer commandExceptionMapper(...) instead of replacing the full command service. - Plugins using Junction integration should check PaperIntegrations.JUNCTION_VARIABLES; declare a plugin dependency only when their own load order requires Junction.

Added

- Added typed PacketEvents listener registration with Lattice-owned unregister handles, listener priority, packet event wrappers, and a safe API handle for version-specific access. - Added command argument builders for custom parsers, completions, and greedy final string arguments. - Added command help entries for flattened command-tree diagnostics and plugin-owned help commands. - Added integration detail metadata, hook diagnostics, command-tree diagnostics, and isolated-mode active JDBC health reporting. - Added README examples of public plugins built on Lattice: Tabular, Junction, and Onboard.

Changed

- PacketEvents binding now reports API class/version details when available. - Runtime diagnostics now include hooks and richer integration, command, and storage details. - DefaultIntegrationManager closes AutoCloseable integration services during runtime shutdown.

Fixed

- PacketEvents bootstrap now catches linkage failures in the same defensive style as PlaceholderAPI. - Isolated storage diagnostics now report active JDBC connection health instead of only registered providers.

Compatibility

- Existing new CommandArgument<>(name, type, required) calls continue to work. - Existing new CommandDiagnostics(name, aliases, description, permission) calls continue to work. - Existing PacketEventsService#api() callers continue to work; new code should prefer apiHandle() and typed listener registration.

Changed

- Added Maven Central publishing for lattice-api, lattice-core, and lattice-paper. - Kept GitHub Packages as a permanent Maven mirror for the same artifacts. - Updated developer documentation to use Maven Central as the default dependency source. - Added Apache-2.0 project licensing metadata for Maven Central publication.

Compatibility

- Maven Central coordinates are now io.github.hydr46605:lattice-api, io.github.hydr46605:lattice-core, and io.github.hydr46605:lattice-paper. - GitHub Packages keeps the original dev.beryl coordinates as an authenticated mirror. - Existing GitHub Packages consumers can keep using the authenticated GitHub Packages repository.

Added

- Added the lattice-api artifact as the first small shared API boundary for the 1.0 runtime split. - Added a standalone Lattice host service that dependent plugins can discover through Paper services. - Added shared JDBC pool management for the standalone runtime, with ref-counted HikariCP pools and storage diagnostics.

Changed

- Prefer the standalone shared-runtime deployment model for new Paper/Folia plugins. - Keep legacy shaded library usage available as isolated mode for self-contained plugin jars. - Updated GitHub release automation to attach lattice-api artifacts. - Added explicit Modrinth workflow checks for the project id and token.

Compatibility

- Existing shaded plugins can keep using LatticePaperPlugin in isolated mode. - Shared-runtime plugins should install the standalone Lattice plugin, compile against Lattice without relocation, and declare a hard Paper dependency with join-classpath: true.

Fixed

- Made the Paper bootstrap resilient when Paper reaches onEnable() before a Lattice runtime was created in onLoad(). - Deferred Paper UI listener registration until the plugin is enabled, avoiding IllegalPluginAccessException during plugin loading. - Regenerated the standalone plugin descriptor when the Lattice version changes so the packaged Paper metadata stays accurate.

Compatibility

- No plugin authoring API changes are required. - Existing plugins extending LatticePaperPlugin keep the same entrypoint shape.

No changelog was specified.