You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Avoid interactive prompts during package installation
5
+
ENV DEBIAN_FRONTEND=noninteractive
6
+
7
+
# Install OpenJDK 21, git, curl, and other common utilities
8
+
RUN apt-get update && \
9
+
apt-get install -y \
10
+
openjdk-21-jdk \
11
+
curl \
12
+
git \
13
+
jq \
14
+
unzip \
15
+
zip \
16
+
ca-certificates \
17
+
sed && \
18
+
rm -rf /var/lib/apt/lists/*
19
+
20
+
# Configure Java environment
21
+
ENV JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
22
+
ENV PATH="${JAVA_HOME}/bin:${PATH}"
23
+
24
+
# (Optional) Install dotenvx system-wide for environment management
25
+
RUN curl -sfS https://dotenvx.sh/install.sh | sh
26
+
27
+
# Create a non-root user 'appuser' with a home directory
28
+
RUN useradd --create-home --shell /bin/bash appuser
29
+
30
+
# Switch to the new user before creating user-specific files
31
+
USER appuser
32
+
WORKDIR /home/appuser
33
+
34
+
# --- Minecraft Server Setup ---
35
+
# Create a directory for the Minecraft server
36
+
RUN mkdir /home/appuser/minecraft
37
+
38
+
# Download the latest Paper server jar (1.21.8, build #35)
39
+
RUN curl -o /home/appuser/minecraft/paper.jar "https://fill-data.papermc.io/v1/objects/bfbfb67f06dceaceebc8a390766f87f5c87c5b57094244b25334b8a2a99d0d73/paper-1.21.8-35.jar"
40
+
41
+
# Create the plugins directory for the server
42
+
RUN mkdir /home/appuser/minecraft/plugins
43
+
44
+
# Download the latest ProtocolLib jar (v5.4.0) into the plugins directory
45
+
RUN curl -L -o /home/appuser/minecraft/plugins/ProtocolLib.jar "https://github.com/dmulloy2/ProtocolLib/releases/download/5.4.0/ProtocolLib.jar"
46
+
47
+
# Agree to the Minecraft EULA to allow the server to start
48
+
RUN echo "eula=true" > /home/appuser/minecraft/eula.txt
49
+
# --- End Minecraft Server Setup ---
50
+
51
+
# Set the final working directory for the development environment.
52
+
# A project repository will typically be cloned here.
53
+
WORKDIR /home/appuser
54
+
55
+
# Set the default command to open a shell for development.
Oraxen is a Gradle-based Java plugin for Minecraft Paper/Spigot servers that delivers data-driven custom items, blocks, HUD, fonts, sounds, and mechanics. It includes a resource-pack generation pipeline and abstracts Minecraft server internals (NMS) via per-version modules.
8
+
9
+
### Modules
10
+
11
+
- `core`: Main plugin code and APIs. Contains mechanics, commands, resource-pack generation, font/HUD systems, recipes, configuration, and compatibility layers.
12
+
- NMS version modules: `v1_20_R1` … `v1_21_R5`. Each implements NMS shims for a specific server version (e.g., `io.th0rgal.oraxen.nms.v1_21_R5.NMSHandler`). They are discovered at runtime via reflection and selected based on the running server version.
13
+
- Root project: Aggregates all subprojects, configures build, and produces a shaded plugin JAR.
14
+
15
+
### Build System
16
+
17
+
- Gradle (Kotlin DSL) with Java toolchain 21.
18
+
- Key plugins:
19
+
- `io.github.goooler.shadow`: Produces a shaded plugin artifact.
20
+
- `net.minecrell.plugin-yml.bukkit`: Generates `plugin.yml` from the Gradle DSL.
21
+
- `xyz.jpenilla.run-paper`: Local dev server tasks.
22
+
- `io.papermc.paperweight.userdev`: In each NMS subproject to compile against specific Paper mappings.
23
+
- Repositories: Paper, Spigot, Sonatype snapshots, JitPack, Oraxen’s repos, etc.
24
+
- Version matrix: Root `build.gradle.kts` defines `SUPPORTED_VERSIONS`; `settings.gradle.kts` includes `core` and all `v1_xx_Ry` modules.
25
+
- Outputs:
26
+
- Root `shadowJar` builds `oraxen-<pluginVersion>.jar` and relocates dependencies.
27
+
- NMS modules produce reobfuscated artifacts via paperweight; root build wires them into the final shaded JAR.
28
+
- `plugin.yml` is generated under `build/resources/main`.
- Loader: `core/.../nms/NMSHandlers.java` chooses an implementation by server version and registers related listeners. If no match is found, a safe `EmptyNMSHandler` disables NMS features gracefully.
43
+
- Implementations: Each `v1_xx_Ry` module contains `NMSHandler` and `GlyphHandler` classes under `io.th0rgal.oraxen.nms.<version>` compiled against the matching Paper dev bundle.
- Extract required/default assets into the plugin data folder (`pack/`).
50
+
- Gather textured items from `OraxenItems` and either generate model predicates (pre-1.21.4) or model definitions (1.21.4+).
51
+
- Generate font providers from glyphs and fonts; optionally hide scoreboard numbers/background via shaders or packets.
52
+
- Verify, de-duplicate, and optionally slice textures; build atlas if enabled.
53
+
- Merge and emit `sounds.json`; generate jukebox datapack when needed.
54
+
- Zip the result and publish via `UploadManager`, sending packs to players on startup or on-demand reload.
55
+
56
+
### Configuration & Content
57
+
58
+
- YAML resources under `core/src/main/resources`: `items/`, `recipes/`, `languages/`, `pack/`, `glyphs/`, `hud.yml`, `mechanics.yml`, etc. These drive item definitions, models, sounds, HUD, and mechanics.
59
+
- Generated assets: Pack files are written under `<plugin data>/pack/` and then zipped to `pack.zip`.
60
+
61
+
### Mechanics & Features
62
+
63
+
- Located under `core/.../mechanics/provided/` across categories: `gameplay`, `farming`, `combat`, `cosmetic`, `misc`.
64
+
- `MechanicsManager` registers native mechanics; features like furniture, string/note blocks, and custom armor integrate with the resource-pack pipeline and NMS layer.
- Public API in `core/.../api` and custom events in `core/.../api/events` (e.g., `OraxenItemsLoadedEvent`, `OraxenPackGeneratedEvent`).
70
+
71
+
### Compatibility Layer
72
+
73
+
- Integrations under `core/.../compatibilities/provided` for ProtocolLib, PlaceholderAPI, WorldEdit, ModelEngine, MythicMobs, MMOItems, EcoItems, BlockLocker, etc. Compatibility is enabled/disabled at runtime based on detected plugins.
74
+
75
+
### Development Workflow
76
+
77
+
- Local run: Use the pre-configured Paper test server in the Docker environment at `/home/appuser/minecraft` (Paper 1.21.8 build #35, ProtocolLib 5.4.0 installed, EULA pre-accepted). Build with `./gradlew build`, copy the resulting JAR to `/home/appuser/minecraft/plugins/`, then launch:
- Build: `./gradlew build` (root wires `build` to `shadowJar`; NMS modules produce reobf jars first). Final artifact: `build/libs/oraxen-<pluginVersion>.jar`.
80
+
- Version & publishing: `gradle.properties` defines `pluginVersion`. Maven publishing is configured with environment credentials (see `core/build.gradle.kts`).
81
+
82
+
### Maintenance Triggers
83
+
84
+
Update this document when:
85
+
- Server versions: New Minecraft/Paper versions are supported. Add a new `v1_xx_Ry` module, update `SUPPORTED_VERSIONS` in root `build.gradle.kts`, and include it in `settings.gradle.kts`.
86
+
- NMS API: `NMSHandler` contract changes or new capabilities are added.
87
+
- Resource pack: Generation pipeline behavior or file layout changes.
- Plugin surface: New major mechanics, commands, or compatibility providers are added/removed.
90
+
## Oraxen Project Overview
91
+
92
+
Oraxen is a Gradle-based Java plugin for Minecraft Paper/Spigot servers that delivers data-driven custom items, blocks, HUD, fonts, sounds, and mechanics. It includes a resource-pack generation pipeline and abstracts Minecraft server internals (NMS) via per-version modules.
93
+
94
+
### Modules
95
+
96
+
- `core`: Main plugin code and APIs. Contains mechanics, commands, resource-pack generation, font/HUD systems, recipes, configuration, and compatibility layers.
97
+
- NMS version modules: `v1_20_R1` … `v1_21_R5`. Each implements NMS shims for a specific server version (e.g., `io.th0rgal.oraxen.nms.v1_21_R5.NMSHandler`). They are discovered at runtime via reflection and selected based on the running server version.
98
+
- Root project: Aggregates all subprojects, configures build, and produces a shaded plugin JAR.
99
+
100
+
### Build System
101
+
102
+
- Gradle (Kotlin DSL) with Java toolchain 21.
103
+
- Key plugins:
104
+
- `io.github.goooler.shadow`: Produces a shaded plugin artifact.
105
+
- `net.minecrell.plugin-yml.bukkit`: Generates `plugin.yml` from the Gradle DSL.
106
+
- `xyz.jpenilla.run-paper`: Local dev server tasks.
107
+
- `io.papermc.paperweight.userdev`: In each NMS subproject to compile against specific Paper mappings.
108
+
- Repositories: Paper, Spigot, Sonatype snapshots, JitPack, Oraxen’s repos, etc.
109
+
- Version matrix: Root `build.gradle.kts` defines `SUPPORTED_VERSIONS`; `settings.gradle.kts` includes `core` and all `v1_xx_Ry` modules.
110
+
- Outputs:
111
+
- Root `shadowJar` builds `oraxen-<pluginVersion>.jar` and relocates dependencies.
112
+
- NMS modules produce reobfuscated artifacts via paperweight; root build wires them into the final shaded JAR.
113
+
- `plugin.yml` is generated under `build/resources/main`.
- Loader: `core/.../nms/NMSHandlers.java` chooses an implementation by server version and registers related listeners. If no match is found, a safe `EmptyNMSHandler` disables NMS features gracefully.
128
+
- Implementations: Each `v1_xx_Ry` module contains `NMSHandler` and `GlyphHandler` classes under `io.th0rgal.oraxen.nms.<version>` compiled against the matching Paper dev bundle.
- Extract required/default assets into the plugin data folder (`pack/`).
135
+
- Gather textured items from `OraxenItems` and either generate model predicates (pre-1.21.4) or model definitions (1.21.4+).
136
+
- Generate font providers from glyphs and fonts; optionally hide scoreboard numbers/background via shaders or packets.
137
+
- Verify, de-duplicate, and optionally slice textures; build atlas if enabled.
138
+
- Merge and emit `sounds.json`; generate jukebox datapack when needed.
139
+
- Zip the result and publish via `UploadManager`, sending packs to players on startup or on-demand reload.
140
+
141
+
### Configuration & Content
142
+
143
+
- YAML resources under `core/src/main/resources`: `items/`, `recipes/`, `languages/`, `pack/`, `glyphs/`, `hud.yml`, `mechanics.yml`, etc. These drive item definitions, models, sounds, HUD, and mechanics.
144
+
- Generated assets: Pack files are written under `<plugin data>/pack/` and then zipped to `pack.zip`.
145
+
146
+
### Mechanics & Features
147
+
148
+
- Located under `core/.../mechanics/provided/` across categories: `gameplay`, `farming`, `combat`, `cosmetic`, `misc`.
149
+
- `MechanicsManager` registers native mechanics; features like furniture, string/note blocks, and custom armor integrate with the resource-pack pipeline and NMS layer.
- Public API in `core/.../api` and custom events in `core/.../api/events` (e.g., `OraxenItemsLoadedEvent`, `OraxenPackGeneratedEvent`).
155
+
156
+
### Compatibility Layer
157
+
158
+
- Integrations under `core/.../compatibilities/provided` for ProtocolLib, PlaceholderAPI, WorldEdit, ModelEngine, MythicMobs, MMOItems, EcoItems, BlockLocker, etc. Compatibility is enabled/disabled at runtime based on detected plugins.
159
+
160
+
### Development Workflow
161
+
162
+
- Local run: `runServer` (from `xyz.jpenilla.run-paper`) spins up a Paper dev server (root `build.gradle.kts` sets a default like 1.20.4).
163
+
- Build: `./gradlew build` (root wires `build` to `shadowJar`; NMS modules produce reobf jars first). Final artifact: `build/libs/oraxen-<pluginVersion>.jar`.
164
+
- Version & publishing: `gradle.properties` defines `pluginVersion`. Maven publishing is configured with environment credentials (see `core/build.gradle.kts`).
165
+
166
+
### Maintenance Triggers
167
+
168
+
Update this document when:
169
+
- Server versions: New Minecraft/Paper versions are supported. Add a new `v1_xx_Ry` module, update `SUPPORTED_VERSIONS` in root `build.gradle.kts`, and include it in `settings.gradle.kts`.
170
+
- NMS API: `NMSHandler` contract changes or new capabilities are added.
171
+
- Resource pack: Generation pipeline behavior or file layout changes.
- **Simplicity and Clarity**: Strive for simple, well-designed code.
8
+
- **Naming Over Comments**: Prefer clear, descriptive naming for classes, methods, and variables. Only add Javadoc to public APIs or when behavior is complex and cannot be conveyed by the name alone.
9
+
10
+
### Java Conventions
11
+
12
+
- **Language & Tooling**: Java 21 via the Gradle toolchain. Builds must succeed with `./gradlew build` and produce the shaded plugin.
13
+
- **Nullability**: Use `@NotNull`/`@Nullable` (org.jetbrains) where helpful, especially on public APIs and NMS boundaries.
14
+
- **Exceptions**: Fail fast with guard clauses. Do not swallow exceptions; log via `io.th0rgal.oraxen.utils.logs.Logs` and only print stack traces in debug flows. Surface user-facing issues via `Message` when appropriate.
15
+
- **Logging & Messages**: Use `Logs` for console logging and the `Message` enum for user-visible strings.
16
+
- **Immutability**: Prefer `final` for fields/locals where practical. Avoid mutable public state.
17
+
- **Collections**: Prefer standard Java collections; avoid exposing mutable internals. Avoid excessive `Optional` for fields; prefer null + annotations.
18
+
- **Dependencies**: Keep external dependencies shaded and relocated through Shadow as configured in the root build.
19
+
20
+
### Code Organization
21
+
22
+
- **Modules**: Keep public APIs and shared logic in `core`. Place server-version-specific code in the corresponding `v1_xx_Ry` module implementing `io.th0rgal.oraxen.nms.NMSHandler`.
23
+
- **Entry Point**: `OraxenPlugin` is the plugin root. Initialization work is staged in `onLoad`, `onEnable`, and `onDisable` with minimal side effects.
24
+
- **Subsystems**: Resource-pack generation under `core/.../pack/generation`, mechanics under `core/.../mechanics/provided`, and integrations under `core/.../compatibilities/provided`.
- **Unit Tests**: For pure logic (e.g., helpers/serialization-free code), place tests under `src/test/java` within the same module. Keep tests deterministic.
30
+
- **Integration/Manual**: Use `runServer` tasks (Paper dev server) for manual verification of plugin behavior across supported versions. Document steps in PRs for reproducibility.
- **Gradle**: Use the provided wrapper. Do not change plugin versions or repos without updating `build.gradle.kts` and `settings.gradle.kts` coherently.
36
+
- **Docker Dev Server**: A Paper test server is pre-installed in the container at `/home/appuser/minecraft` (Paper 1.21.8 build #35 with ProtocolLib 5.4.0). Build with `./gradlew build`, copy the plugin JAR to `/home/appuser/minecraft/plugins/`, then run:
0 commit comments