{"id":26094147,"url":"https://github.com/slne-development/surf-api","last_synced_at":"2026-06-06T22:01:08.967Z","repository":{"id":276873427,"uuid":"930585008","full_name":"SLNE-Development/surf-api","owner":"SLNE-Development","description":"Multi-platform plugin API framework with modular service discovery, lifecycle-managed components, and NMS bridge abstractions for multiple server platforms.","archived":false,"fork":false,"pushed_at":"2026-05-25T12:43:17.000Z","size":15599,"stargazers_count":5,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"version/26.1","last_synced_at":"2026-05-25T14:28:48.901Z","etag":null,"topics":["api","kotlin","nms","packet","packets","paper","papermc","utility","velocity"],"latest_commit_sha":null,"homepage":"https://docs.slne.dev/surf-api","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SLNE-Development.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"SLNE-Development"}},"created_at":"2025-02-10T21:46:43.000Z","updated_at":"2026-05-25T12:39:01.000Z","dependencies_parsed_at":"2026-04-07T15:01:34.043Z","dependency_job_id":null,"html_url":"https://github.com/SLNE-Development/surf-api","commit_stats":null,"previous_names":["slne-development/surf-api"],"tags_count":173,"template":false,"template_full_name":null,"purl":"pkg:github/SLNE-Development/surf-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SLNE-Development%2Fsurf-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SLNE-Development%2Fsurf-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SLNE-Development%2Fsurf-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SLNE-Development%2Fsurf-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SLNE-Development","download_url":"https://codeload.github.com/SLNE-Development/surf-api/tar.gz/refs/heads/version/26.1","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SLNE-Development%2Fsurf-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33586821,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","kotlin","nms","packet","packets","paper","papermc","utility","velocity"],"created_at":"2025-03-09T12:50:02.800Z","updated_at":"2026-05-27T23:01:01.495Z","avatar_url":"https://github.com/SLNE-Development.png","language":"Kotlin","funding_links":["https://github.com/sponsors/SLNE-Development"],"categories":[],"sub_categories":[],"readme":"# surf-api\n\n**Multi-platform plugin API framework** for Minecraft servers — providing modular service\ndiscovery, lifecycle-managed components, NMS bridge abstractions, and rich DSLs across Paper,\nVelocity, and Standalone platforms.\n\n[![Latest Release](https://img.shields.io/github/v/release/SLNE-Development/surf-api?label=release)](https://github.com/SLNE-Development/surf-api/releases/latest)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)\n[![Kotlin](https://img.shields.io/badge/Kotlin-2.3.20-7F52FF?logo=kotlin)](https://kotlinlang.org/)\n[![Java](https://img.shields.io/badge/Java-25-orange?logo=openjdk)](https://openjdk.org/)\n[![Docs](https://img.shields.io/badge/docs-slne.dev-informational)](https://docs.slne.dev/surf-api)\n\n---\n\n## Overview\n\nsurf-api is the shared foundation for SLNE's server plugin ecosystem. It provides:\n\n- **Platform-abstracted APIs** for Paper (Bukkit/NMS), Velocity, and Standalone environments\n- **Service discovery** via `ServiceLoader` (`requiredService\u003cT\u003e()`) for singleton bridges\n- **Component system** with compile-time KSP discovery, topological lifecycle ordering, and\n  conditional activation\n- **NMS bridge pattern** to safely abstract version-specific internals behind stable interfaces\n- **Inventory framework DSLs**, command helpers, scoreboard utilities, and extension-rich APIs\n- **Gradle plugin** (`surf-api-gradle-plugin`) that configures downstream projects, handles\n  dependency shading, and runs the KSP processor\n\n---\n\n## Module Structure\n\n```\nsurf-api\n├── surf-api-core                  # Platform-agnostic core API \u0026 implementation\n│   ├── surf-api-core              # Core API interfaces\n│   └── surf-api-core-server       # Core implementations\n│\n├── surf-api-paper                 # Paper/Bukkit platform\n│   ├── surf-api-paper             # Public API (extensions, bridges, DSLs)\n│   ├── surf-api-paper-server      # Implementations (shaded into final JAR)\n│   ├── surf-api-paper-nms\n│   │   ├── surf-api-paper-nms-common     # Shared NMS bridge interfaces\n│   │   ├── surf-api-paper-nms-v1-21-11   # NMS impl for 1.21.11\n│   │   └── surf-api-paper-nms-v26-1      # NMS impl for 26.1\n│   └── surf-api-paper-plugin-test # Local test server (excluded from CI)\n│\n├── surf-api-velocity              # Velocity proxy platform\n│   ├── surf-api-velocity          # Public API\n│   └── surf-api-velocity-server   # Implementations\n│\n├── surf-api-standalone            # Standalone (non-server) platform\n│\n├── surf-api-shared                # Cross-platform annotations \u0026 component system\n│   ├── surf-api-shared-public     # Public shared annotations (@ComponentMeta, etc.)\n│   └── surf-api-shared-internal   # Internal shared utilities\n│\n├── surf-api-gradle-plugin         # Gradle convention plugins \u0026 KSP processor\n│   └── surf-api-processor         # KSP processor — discovers @ComponentMeta at compile time\n│\n└── surf-api-generator             # NMS module scaffolding generator (local only)\n```\n\n\u003e **API/Implementation split:** `-api` modules define public interfaces consumed by downstream\n\u003e projects. `-server` modules contain implementations that are shaded into the final JAR and never\n\u003e exposed as a public API dependency.\n\n---\n\n## Key Concepts\n\n### Service Discovery\n\nTwo mechanisms are available depending on the use case:\n\n#### 1. `requiredService\u003cT\u003e()` — Singleton bridges\n\nFor singleton platform bridges and NMS abstractions. Backed by Java `ServiceLoader`; implementations\nregister themselves with `@AutoService`.\n\n```kotlin\n// In -api: declare the bridge interface with companion delegation\n@NmsUseWithCaution\ninterface SurfBukkitNmsCommonBridge {\n    fun nextEntityId(): Int\n\n    companion object : SurfBukkitNmsCommonBridge by requiredService()\n}\n\n// In -server: provide the implementation\n@AutoService(SurfBukkitNmsCommonBridge::class)\nclass SurfBukkitNmsCommonBridgeImpl : SurfBukkitNmsCommonBridge {\n    init { checkInstantiationByServiceLoader() }\n\n    override fun nextEntityId(): Int = TODO()\n}\n\n// Usage — callers go through the companion, unaware of the implementation\nval id = SurfBukkitNmsCommonBridge.nextEntityId()\n```\n\n#### 2. Component System — Lifecycle-managed components\n\nClasses annotated with `@ComponentMeta` (or the meta-annotations `@Service` / `@Repository`) are\ndiscovered at compile-time by the KSP processor, which writes JSON metadata to\n`META-INF/surfapi/components/`. At runtime, `ComponentService`:\n\n1. Loads all component metadata\n2. Topologically sorts by `@Priority` and `@DependsOnComponent`\n3. Checks conditions (`@ConditionalOnProperty`, `@DependsOnPlugin`, `@DependsOnClass`, …)\n4. Calls `suspend fun load()` → `enable()` → `disable()` in order\n\n```kotlin\n@Service\nclass MyFeatureService : SurfComponent {\n    override suspend fun enable() {\n        // runs after all dependencies are enabled\n    }\n\n    override suspend fun disable() {\n        // runs in reverse order on shutdown\n    }\n}\n```\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Java 25 (GraalVM recommended for CI)\n- Gradle 8+\n\n### Build\n\n```bash\n# Full build (produces shadow JARs with relocated dependencies)\n./gradlew build shadowJar\n\n# Build a single module\n./gradlew :surf-api-paper:surf-api-paper-server:build\n\n# Publish to local Maven repository\n./gradlew publishToMavenLocal\n\n# Run the Paper test server (local only, not available in CI)\n./gradlew :surf-api-paper:surf-api-paper-plugin-test:runServer\n```\n\n---\n\n## Conventions\n\n### Kotlin\n\n| Convention | Details |\n|---|---|\n| **Context parameters** | Enabled globally (`-Xcontext-parameters`). Used in inventory DSLs and other scoped builders. |\n| **`@InternalSurfApi`** | `@RequiresOptIn` — mark new internal APIs with this annotation. All subprojects opt-in via compiler args. |\n| **Coroutines** | All async work uses Kotlin coroutines. Component lifecycle methods are `suspend`. Bukkit uses MCCoroutine (Folia-aware). |\n| **Extension functions** | Primary API enrichment pattern; organized in files named `*-extension.kt` or `*-extensions.kt`. |\n| **DSL markers** | `@InventoryFrameworkDSL`, `@ItemDsl`, `@PaneMarker` restrict scope in builder DSLs. |\n\n### Logging\n\nUse Google Flogger via the `logger()` helper:\n\n```kotlin\nprivate val log = logger() // FluentLogger.forEnclosingClass()\n\nlog.atInfo().log(\"Server started\")\nlog.atWarning().withCause(e).log(\"Failed to load component %s\", name)\n```\n\n### Package Layout\n\n```\ndev.slne.surf.api                      # Root\ndev.slne.surf.api.core.api             # Core API interfaces\ndev.slne.surf.api.core.server          # Core implementations\ndev.slne.surf.api.paper.api            # Paper API (extensions, bridges, DSLs)\ndev.slne.surf.api.paper.server         # Paper implementations\ndev.slne.surf.api.velocity.api         # Velocity API\ndev.slne.surf.api.velocity.server      # Velocity implementations\ndev.slne.surf.api.shared.api           # Shared annotations \u0026 component system\ndev.slne.surf.api.libs.*               # Relocation target for all shaded dependencies\n```\n\n### Dependency Shading\n\nAll non-platform dependencies are shaded via Shadow and relocated to `dev.slne.surf.api.libs.*`\n(configured via `relocationPrefix` in `gradle.properties`). Platform APIs (Paper, Velocity) remain\n`compileOnly`. Relocations are declared in `CommonSurfPlugin` using an infix DSL:\n\n```kotlin\n\"me.devnatan.inventoryframework\" relocatesTo \"devnatan.inventoryframework\"\n```\n\n---\n\n## Notable Dependencies\n\n| Library | Purpose |\n|---|---|\n| [PacketEvents](https://github.com/retrooper/packetevents) | Packet-level networking abstraction |\n| [CommandAPI](https://commandapi.jorel.dev/) | Brigadier-based command framework |\n| [MCCoroutine](https://github.com/Shynixn/MCCoroutine) (SLNE fork) | Folia-aware coroutine dispatching |\n| [Inventory Framework](https://github.com/devnatan/inventory-framework) | GUI/inventory DSL |\n| [Adventure](https://docs.advntr.net/) | Text \u0026 component API |\n| [LuckPerms](https://luckperms.net/) | Permissions API |\n| [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) | Placeholder support |\n| [Caffeine](https://github.com/ben-manes/caffeine) | High-performance caching |\n| [Flogger](https://google.github.io/flogger/) | Fluent logging |\n| [Ktor](https://ktor.io/) | HTTP client |\n| [Configurate](https://github.com/SpongePowered/Configurate) | Configuration loading |\n| [KSP](https://github.com/google/ksp) | Compile-time component discovery |\n| [AutoService](https://github.com/google/auto/tree/main/service) | `ServiceLoader` registration |\n\n---\n\n## Contributing\n\nWhen making changes:\n\n- **API changes** go in `-api` modules. **Never** expose `-server` types in the public API.\n- **Implementations** go in `-server` modules.\n- **New components**: annotate with `@ComponentMeta` / `@Service` / `@Repository` and implement the\n  appropriate lifecycle methods.\n- **New NMS bridges**: declare the interface in `-api`, implement in `-server`, register via\n  `@AutoService`, and call `checkInstantiationByServiceLoader()` in the `init` block.\n- Publishing is automated — push to a `version/*` branch to trigger a release.\n\n---\n\n## License\n\nThis project is licensed under the [GNU General Public License v3.0](LICENSE).\n\n---\n\n## Links\n\n- 📖 [Documentation](https://docs.slne.dev/surf-api)\n- 📦 [Releases](https://github.com/SLNE-Development/surf-api/releases)\n- 🐛 [Issues](https://github.com/SLNE-Development/surf-api/issues)\n- 💬 [Discussions](https://github.com/SLNE-Development/surf-api/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslne-development%2Fsurf-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslne-development%2Fsurf-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslne-development%2Fsurf-api/lists"}