Skip to content

Commit a521cd5

Browse files
CoasterFreakDECoasterFreakDE
committed
Codex cleanup
1 parent 7e2743c commit a521cd5

File tree

19 files changed

+2702
-35
lines changed

19 files changed

+2702
-35
lines changed

‎.github/workflows/build.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,7 @@ jobs:
1616
cache: 'gradle'
1717
- name: Grant execute permission for gradlew
1818
run: chmod +x gradlew
19+
- name: API compatibility check
20+
run: ./gradlew apiCheck --stacktrace
1921
- name: Build with Gradle
20-
run: ./gradlew build --stacktrace
22+
run: ./gradlew build --stacktrace

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,5 @@ bin/
4545
.DS_Store
4646

4747
.idea/*
48-
.kotlin/*
48+
.kotlin/*
49+
/logs

‎api/KPaper.api‎

Lines changed: 2439 additions & 0 deletions
Large diffs are not rendered by default.

‎build.gradle.kts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import java.util.*
55
plugins {
66
kotlin("jvm") version "2.1.20"
77
`java-library`
8+
id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.17.0"
89
id("io.papermc.paperweight.userdev") version "2.0.0-beta.19"
910
kotlin("plugin.serialization") version "2.1.20"
1011
id("maven-publish")

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ Welcome to the comprehensive documentation for KPaper - a Kotlin utility library
1313
- [Plugin Development](core/plugin-development.md) - Understanding KPlugin and core concepts
1414
- [Feature Configuration](core/feature-config.md) - Managing plugin features
1515
- [Dependency Injection](core/dependency-injection.md) - Working with dependencies
16+
- [Naming Conventions](core/naming-conventions.md) - API and package naming standards
1617

1718
### API Guides
1819
- [Event System](api/events.md) - Event handling and custom events

‎docs/api/extensions.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Extensions
2+
3+
KPaper exposes many Kotlin extension helpers for Bukkit/Paper APIs. This page focuses on migration-safe naming and the current preferred API names.
4+
5+
## Naming Migration Quick Reference
6+
7+
Use the new names in new code. Old names remain available as deprecated compatibility bridges.
8+
9+
| Old API | Preferred API |
10+
|---|---|
11+
| `sendEmtpyLine()` | `sendEmptyLine()` |
12+
| `removePersistantDataIf(...)` | `removePersistentDataIf(...)` |
13+
| `str2Loc(serialized)` | `parseLocation(serialized)` |
14+
| `loc2Str(location)` | `locationToString(location)` |
15+
| `loc2BlockStr(location)` | `locationToBlockString(location)` |
16+
| `toSaveAbleString()` | `toSavableString()` |
17+
| `toSaveAbleBlockString()` | `toSavableBlockString()` |
18+
| `toSaveAbleDirectionalString()` | `toSavableDirectionalString()` |
19+
| `Inventory.clone(..., shuffeld = ...)` | `Inventory.cloneCompat(..., shuffled = ...)` |
20+
| `NAMESPACE_GUI_IDENTIFIER` | `GUI_IDENTIFIER_KEY` |
21+
| `NAMESPACE_ITEM_IDENTIFIER` | `ITEM_IDENTIFIER_KEY` |
22+
23+
## Migration Examples
24+
25+
```kotlin
26+
import cc.modlabs.kpaper.extensions.*
27+
28+
// Before
29+
sender.sendEmtpyLine()
30+
val loc = str2Loc(serialized)
31+
val raw = loc2Str(player.location)
32+
val blockRaw = loc2BlockStr(player.location)
33+
val key = NAMESPACE_GUI_IDENTIFIER
34+
35+
// After
36+
sender.sendEmptyLine()
37+
val loc = parseLocation(serialized)
38+
val raw = locationToString(player.location)
39+
val blockRaw = locationToBlockString(player.location)
40+
val key = GUI_IDENTIFIER_KEY
41+
```
42+
43+
```kotlin
44+
import cc.modlabs.kpaper.inventory.ItemBuilder
45+
import cc.modlabs.kpaper.extensions.cloneCompat
46+
47+
// Before
48+
builder.removePersistantDataIf(key, condition = true)
49+
val copy = inventory.clone(shuffeld = true)
50+
51+
// After
52+
builder.removePersistentDataIf(key, condition = true)
53+
val copy = inventory.cloneCompat(shuffled = true)
54+
```
55+
56+
## Notes
57+
58+
- Deprecated bridge APIs intentionally remain for backward compatibility.
59+
- Use IDE quick-fix (`ReplaceWith`) to migrate quickly.
60+
- For naming and package policy, see [Core Naming Conventions](../core/naming-conventions.md).

‎docs/api/inventory.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,27 @@
22

33
KPaper provides a comprehensive inventory and GUI system that makes creating interactive menus, item builders, and custom inventories simple and intuitive.
44

5+
## Preferred Naming Migration
6+
7+
Use the preferred API names below in new code. Legacy names still work as deprecated bridges.
8+
9+
| Old API | Preferred API |
10+
|---|---|
11+
| `removePersistantDataIf(...)` | `removePersistentDataIf(...)` |
12+
| `Inventory.clone(..., shuffeld = ...)` | `Inventory.cloneCompat(..., shuffled = ...)` |
13+
| `NAMESPACE_GUI_IDENTIFIER` | `GUI_IDENTIFIER_KEY` |
14+
| `NAMESPACE_ITEM_IDENTIFIER` | `ITEM_IDENTIFIER_KEY` |
15+
16+
```kotlin
17+
// Before
18+
builder.removePersistantDataIf(key, condition = true)
19+
val copy = inventory.clone(shuffeld = true)
20+
21+
// After
22+
builder.removePersistentDataIf(key, condition = true)
23+
val copy = inventory.cloneCompat(shuffled = true)
24+
```
25+
526
## Item Building
627

728
### Basic Item Creation

‎docs/api/utilities.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,34 @@ Other snippets are guidance/patterns and may require your own implementations.
99

1010
KPaper provides extensive utility functions and Kotlin extensions that make common Minecraft development tasks more intuitive and efficient.
1111

12+
## Preferred Naming Migration
13+
14+
Use the newer, explicit extension names in new code:
15+
16+
| Old API | Preferred API |
17+
|---|---|
18+
| `sendEmtpyLine()` | `sendEmptyLine()` |
19+
| `str2Loc(serialized)` | `parseLocation(serialized)` |
20+
| `loc2Str(location)` | `locationToString(location)` |
21+
| `loc2BlockStr(location)` | `locationToBlockString(location)` |
22+
| `toSaveAbleString()` | `toSavableString()` |
23+
| `toSaveAbleBlockString()` | `toSavableBlockString()` |
24+
| `toSaveAbleDirectionalString()` | `toSavableDirectionalString()` |
25+
26+
```kotlin
27+
import cc.modlabs.kpaper.extensions.*
28+
29+
// Before
30+
sender.sendEmtpyLine()
31+
val location = str2Loc(serialized)
32+
val raw = loc2Str(location)
33+
34+
// After
35+
sender.sendEmptyLine()
36+
val location = parseLocation(serialized)
37+
val raw = locationToString(location)
38+
```
39+
1240
## Utility Functions
1341

1442
### Console and Logging

‎docs/core/naming-conventions.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Naming And Structure Conventions
2+
3+
This document defines the naming and structure rules for KPaper to keep the API consistent, readable, and backward-compatible.
4+
5+
## Package Naming
6+
7+
- Use lowercase package names only.
8+
- Keep feature-oriented package roots under `cc.modlabs.kpaper`:
9+
- `command`, `coroutines`, `event`, `extensions`, `file`, `game`, `inventory`, `main`, `messages`, `npc`, `party`, `scoreboard`, `util`, `visuals`, `world`.
10+
- Prefer singular package names for feature domains (for example `event`, not `events`) unless a package already exists and changing it would break users.
11+
12+
## Type And File Naming
13+
14+
- Classes/interfaces/object names use `PascalCase`.
15+
- Function/property names use `camelCase`.
16+
- Constants use `UPPER_SNAKE_CASE`.
17+
- Avoid abbreviations unless widely understood (`api`, `uuid`, `url`, `json`).
18+
- File name should match the main public type when a file is type-centric.
19+
20+
## Public API Naming
21+
22+
- Prefer explicit verbs for functions (`parseLocation`, `locationToString`).
23+
- Boolean names must use `is`, `has`, `can`, or `should`.
24+
- Avoid typo-prone names and legacy shorthand (`str2Loc`, `loc2Str`).
25+
26+
## Backward Compatibility Policy
27+
28+
- Never remove/rename public API directly in normal releases.
29+
- For naming fixes:
30+
1. Add the new canonical API.
31+
2. Keep the old API as a deprecated bridge.
32+
3. Use `ReplaceWith(...)` for IDE-assisted migration.
33+
- Keep compatibility bridges for at least one full CalVer cycle unless intentionally breaking.
34+
35+
### Current Migration Map
36+
37+
- `sendEmtpyLine` -> `sendEmptyLine`
38+
- `removePersistantDataIf` -> `removePersistentDataIf`
39+
- `str2Loc` -> `parseLocation`
40+
- `loc2Str` -> `locationToString`
41+
- `loc2BlockStr` -> `locationToBlockString`
42+
- `toSaveAbleString` -> `toSavableString`
43+
- `toSaveAbleBlockString` -> `toSavableBlockString`
44+
- `toSaveAbleDirectionalString` -> `toSavableDirectionalString`
45+
- `Inventory.clone(..., shuffeld=...)` -> `Inventory.cloneCompat(..., shuffled=...)`
46+
- `NAMESPACE_GUI_IDENTIFIER` -> `GUI_IDENTIFIER_KEY`
47+
- `NAMESPACE_ITEM_IDENTIFIER` -> `ITEM_IDENTIFIER_KEY`
48+
49+
## Structure And Maintainability
50+
51+
- Keep helper APIs close to their domain package.
52+
- Prefer small cohesive files over large mixed-purpose files.
53+
- Add KDoc for all public APIs and all deprecated bridge APIs.
54+
- Add tests for new behavior and migration bridges where feasible.
55+
56+
## Performance Notes
57+
58+
- Prefer allocation-light APIs for hot paths.
59+
- Avoid unnecessary reflection and repeated object creation in frequently called extensions.
60+
- Validate and cap untrusted inputs (size/time limits) in serialization and network paths.

src/main/kotlin/cc/modlabs/kpaper/extensions/BlockExtension.kt renamed to src/main/kotlin/cc/modlabs/kpaper/extensions/BlockExtensions.kt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
@file:kotlin.jvm.JvmName("BlockExtensionKt")
2+
13
package cc.modlabs.kpaper.extensions
24

35
import org.bukkit.Material
@@ -30,4 +32,4 @@ val BlockFace.yaw: Float
3032
BlockFace.WEST -> 90f
3133
BlockFace.NORTH -> 180f
3234
else -> 0f
33-
}
35+
}

0 commit comments

Comments
 (0)