Merged
Conversation
… handling and deprecate DazzlConf usage
…nd deprecate String overload
…ved message handling
… in CommonComponents.kt
… Title.DEFAULT_TIMES
…eneration and selection
…on for improved error handling
… enhance error handling
… as deprecated with replacement suggestions
…tting and annotation retrieval functions
…onError for unavailable services
…n and thread-safe caching
…update version to 1.21.11-2.59.0
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands Surf API core capabilities around configuration, messaging utilities, pagination (including new suspend-based rendering), audience helpers, reflection proxy error reporting, and reworks weighted random selection to use Apache Commons Math3.
Changes:
- Added Apache Commons Math3 to version catalog and multiple modules; refactored
RandomSelectorimplementation to use Math3 distributions and introduced a JDK→Math3 RNG adapter. - Introduced suspend-based pagination APIs (
SuspendPagination*) with server-side implementations and bridge wiring. - Centralized MiniMessage configuration in
SurfMiniMessageHolderand updated serializers/utilities to use it; added multiple small API/utility enhancements (audience pointers, translation store, docs/formatting).
Reviewed changes
Copilot reviewed 60 out of 60 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| surf-api-velocity/surf-api-velocity-server/build.gradle.kts | Adds commons-math3 dependency to Velocity server module. |
| surf-api-standalone/build.gradle.kts | Adds commons-math3 dependency to standalone module. |
| surf-api-hytale/surf-api-hytale-server/build.gradle.kts | Adds commons-math3 dependency to Hytale server module. |
| surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/impl/messages/pagination/suspend/SuspendPaginationImpl.kt | New suspend pagination renderer implementation using coroutines. |
| surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/impl/messages/pagination/suspend/SuspendPaginationBuilderImpl.kt | New builder for suspend pagination. |
| surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/impl/messages/pagination/PaginationImpl.kt | Exposes page calculation and page iteration helpers for reuse. |
| surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/impl/messages/pagination/PaginationBuilderImpl.kt | Makes builder open (supports extension/customization). |
| surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/impl/messages/pagination/InternalPaginationBridgeImpl.kt | Wires new suspend pagination builder into internal bridge. |
| surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/surfapi/core/server/config/DazzlConfConfigTracker.kt | Suppresses deprecation error to keep legacy tracker compiling. |
| surf-api-core/surf-api-core-server/src/main/java/dev/slne/surf/surfapi/core/server/impl/reflection/reflection/ProxyInvocationException.java | Adds dedicated runtime exception for proxy invocation errors. |
| surf-api-core/surf-api-core-server/src/main/java/dev/slne/surf/surfapi/core/server/impl/reflection/reflection/ProxyCreationException.java | Adds dedicated runtime exception for proxy creation errors. |
| surf-api-core/surf-api-core-server/src/main/java/dev/slne/surf/surfapi/core/server/impl/reflection/SurfInvocationHandlerJava.java | Improves proxy error messages, method/field lookup, and adds VarHandle/Unsafe final-field setter path. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/util.kt | Adds Unsafe helpers + deprecations and expands utility KDoc. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/service-util.kt | Changes missing service error to ServiceConfigurationError. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/reflection-util.kt | Adds AccessibleObject.findAnnotation() convenience. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/date-util.kt | Adds KDoc for formatter and formatted-now helper. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/blockstate/BlockStateFactoryImpl.kt | Deprecates blockstate factory implementation. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/blockstate/BlockStateFactory.kt | Deprecates blockstate factory API. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/SurfTypeParameterMatcher.kt | Refactors matcher caching/thread-safety and expands docs. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/ParticleFactory.kt | Deprecates particle factory helpers and adds ReplaceWith guidance. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/LocationFactory.kt | Deprecates location factory and simplifies distance calculations. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/util/ItemStackFactory.kt | Deprecates itemstack factory and updates ReplaceWith guidance. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/service/PlayerLookupService.kt | Adds cached result types, custom expiry, and status-aware lookup logic. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/reflection/reflection-annotations.kt | Improves KDoc for reflection proxy annotations. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/reflection/SurfReflection.kt | Refactors companion access pattern and expands KDoc/examples. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/random/Weighted.kt | Expands docs and clarifies weight requirements. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/random/RandomSelectorImpl.kt | Reimplements selection using Commons Math3 EnumeratedDistribution; adds new pick/flow/sequence variants. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/random/RandomSelector.kt | Major API expansion: new pick/flow/sequence methods, deprecations, and overloads for RNGs. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/random/Jdk2ApacheRandomGenerator.kt | New adapter bridging JDK RandomGenerator to Commons Math3 RNG API. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/nbt/FastCompoundBinaryTag.kt | Adds documentation and unmodifiable keySet view annotation. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/nbt/CollectionBinaryTag.kt | Adds documentation and helper accessors for collection-like NBT tags. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/minimessage/SurfMiniMessageHolder.kt | New centralized MiniMessage holder with Surf tags + prefix tag. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/pagination/PaginationRowRenderer.kt | Adds Simple renderer and suspend row renderer variants. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/pagination/PaginationRenderer.kt | Adds suspend renderer interface and refactors footer rendering helpers. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/pagination/PaginationClickEventProvider.kt | Adds suspend click event provider and default implementation. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/pagination/PaginationBuilder.kt | Adds suspend pagination builder API and rowRendererSimple helper. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/pagination/Pagination.kt | Adds SuspendPagination API with builder entrypoint. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/pagination/InternalPaginationBridge.kt | Extends bridge with suspend pagination builder creation. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/bundle/SurfMessageBundle.kt | Switches to TranslationStore usage for bundle registration. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder.kt | Switches to corrected MAP_SEPARATOR constant. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/adventure/title-extensions.kt | Aligns title default timings with Adventure defaults. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/adventure/callback-extension.kt | Adds click callback helpers + options builder DSL. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/adventure/audience-extension.kt | Adds Audience pointer helpers (uuid/name/displayName/permissions). |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/DefaultFontInfo.kt | Suppresses enum entry naming warnings. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/CommonComponents.kt | Adds MAP_SEPARATOR, EM_DASH, refines docs, and improves time formatting output. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/Colors.kt | Updates palette definitions/docs and adds prefix character support. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/math/VoxelLineTracer.kt | Adds detailed documentation for voxel tracing utility. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/font/small-caps.kt | Changes toSmallCaps to accept CharSequence; deprecates old overload. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/extensions/glm/Vec3iExtensions.kt | Removes empty/unused file. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/serializer/SpongeConfigSerializers.kt | Switches component serializer to Surf MiniMessage holder; updates LinkedList serializer type handling. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/serializer/DefaultDazzlConfSerializers.kt | Uses thread-safe serializer list and central MiniMessage holder; deprecates customization API. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/manager/SpongeConfigManager.kt | Switches to UncheckedIOException and refines contracts/docs. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/manager/DazzlConfConfigManager.kt | Tightens opt-in/deprecation messaging for DazzlConf and adds shared message holder. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/config/SurfConfigApi.kt | Refactors singleton access pattern and marks DazzlConf APIs as errors. |
| surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/SurfCoreApi.kt | Refactors singleton access pattern and companion delegation. |
| surf-api-core/surf-api-core-api/build.gradle.kts | Adds commons-math3 to core API module dependencies. |
| surf-api-bukkit/surf-api-bukkit-server/build.gradle.kts | Adds commons-math3 to Bukkit server runtime libs. |
| gradle/libs.versions.toml | Adds Commons Math3 version + catalog entry. |
Comment on lines
+13
to
14
| @Deprecated("Not longer maintained.") | ||
| interface ParticleFactory { |
There was a problem hiding this comment.
Typo in the deprecation message: "Not longer maintained." should be "No longer maintained.".
| api(libs.configurate.kotlin) | ||
| compileOnlyApi(libs.flogger) | ||
| compileOnlyApi(libs.commons.math4.core) | ||
| compileOnlyApi(libs.commons.math3) |
There was a problem hiding this comment.
commons-math3 is referenced from surf-api-core-api code (e.g., RandomSelectorImpl uses org.apache.commons.math3.*), so declaring it as compileOnlyApi will compile but can fail at runtime for consumers that depend on surf-api-core-api without also pulling a server module. Consider using api(libs.commons.math3) (or otherwise ensuring it is on the runtime classpath transitively) so RandomSelector works out-of-the-box.
Suggested change
| compileOnlyApi(libs.commons.math3) | |
| api(libs.commons.math3) |
Comment on lines
28
to
+32
| val nbt = NBTCompound() | ||
| nbtConsumer.accept(nbt) | ||
|
|
||
| return ItemStack.builder().type(material).amount(amount).nbt(nbt).build() | ||
| return ItemStack.builder().type(material).amount(amount).nbt(NBTCompound().also { nbtConsumer.accept(it) }) | ||
| .build() |
There was a problem hiding this comment.
nbtConsumer is invoked twice and the first constructed nbt is never used. This changes behavior for consumers (side-effects run twice) and wastes allocations; it likely should pass the previously-built nbt into .nbt(nbt) instead of creating a second NBTCompound().
Comment on lines
+10
to
+15
| @Deprecated("Not longer maintained.") | ||
| interface ItemStackFactory { | ||
| companion object { | ||
| @Deprecated( | ||
| "Not longer maintained.", | ||
| ReplaceWith( |
There was a problem hiding this comment.
Typo in the deprecation message: "Not longer maintained." should be "No longer maintained.".
Comment on lines
+7
to
8
| @Deprecated("Not longer maintained.") | ||
| class BlockStateFactoryImpl { |
There was a problem hiding this comment.
Typo in the deprecation message: "Not longer maintained." should be "No longer maintained.".
Comment on lines
+11
to
13
| @Deprecated("Not longer maintained.") | ||
| interface BlockStateFactory { | ||
| @Suppress("unused") |
There was a problem hiding this comment.
Typo in the deprecation message: "Not longer maintained." should be "No longer maintained.".
Comment on lines
+6
to
8
| @Deprecated("Not longer maintained.") | ||
| interface LocationFactory { | ||
| companion object { |
There was a problem hiding this comment.
Typo in the deprecation message: "Not longer maintained." should be "No longer maintained.".
|
|
||
| @SuppressWarnings("removal") | ||
| private @Nullable Object setFieldViaUnsafe(Object[] args) throws ProxyInvocationException { | ||
| sun.misc.Unsafe unsafe = SurfUtil.getUnsafe(); |
There was a problem hiding this comment.
Access to unsupported JDK-internal API 'sun.misc.Unsafe'. (See https://openjdk.java.net/jeps/260)
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4f816ed122
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+42
to
+44
| launch { | ||
| clicker.sendMessage(pagination.renderComponent(content, targetPage)) | ||
| } |
There was a problem hiding this comment.
The default suspend click provider captures the transient CoroutineScope used while rendering pagination and calls launch on it inside the click callback. By the time a user clicks, that scope has already completed (the render call returned), so the launched job is cancelled immediately and page navigation never sends a new message. This breaks suspend pagination navigation in normal usage where callbacks are clicked after rendering.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces several enhancements and new features to the Surf API core, focusing on configuration management, message building, and audience utilities. It also adds support for the Apache Commons Math 3 library. The most significant changes include expanded configuration API capabilities, new asynchronous methods for message builders, and additional utilities for working with audiences and components.
Configuration Management Improvements:
SurfConfigApi$Companionclass to implementSurfConfigApiand added new methods for creating, retrieving, and reloading various config types, including Dazzl and Sponge configs, as well as config managers.DazzlConfDeprecationMessageHolderto hold deprecation messages for configuration.commons-math3as a dependency in the project and build files. [1] [2] [3]Message and Component Builder Enhancements:
Async) versions of methods for appending error, info, success, and warning prefixed lines in bothComponentBuilderColorsandSurfComponentBuilderclasses. [1] [2]CommonComponentswith new fields such asEM_DASHandMAP_SEPARATOR, and updated related formatting utilities. [1] [2]PREFIX_CHARACTERto theColorsinterface for more granular prefix control.Audience and Adventure API Utilities:
Audiencesuch asdisplayName,displayNameOrNull,hasPermission,name,nameOrNull,testPermission,uuid, anduuidOrNullto simplify audience information retrieval and permission checks.Callback_extensionKtandClickCallbackWithOptionsBuilderclasses to support advanced click callback options in adventure components, including permission requirements and custom options.Other Notable Changes:
toSmallCapsutility to acceptCharSequenceinstead of justString, improving API flexibility.DefaultDazzlConfSerializersto use a thread-safeCopyOnWriteArrayList.SurfCoreApi$Companion, addinggetPlayerandsendPlayerToServermethods.