|
22 | 22 | import static kr.toxicity.model.api.util.ReflectionUtil.classExists; |
23 | 23 |
|
24 | 24 | /** |
25 | | - * A provider class for BetterModel plugin instance. |
| 25 | + * The main entry point for the BetterModel API. |
| 26 | + * <p> |
| 27 | + * This class provides static access to the plugin instance, configuration, model managers, |
| 28 | + * NMS handlers, and entity registries. It serves as a service provider for interacting with the BetterModel engine. |
| 29 | + * </p> |
| 30 | + * |
| 31 | + * @since 1.15.2 |
26 | 32 | */ |
27 | 33 | public final class BetterModel { |
28 | 34 |
|
29 | 35 | /** |
30 | | - * Private initializer |
| 36 | + * Private initializer to prevent instantiation. |
31 | 37 | */ |
32 | 38 | private BetterModel() { |
33 | 39 | throw new RuntimeException(); |
34 | 40 | } |
35 | 41 |
|
36 | 42 | /** |
37 | | - * Check a running platform is Folia. |
| 43 | + * Checks if the server is running on the Folia platform. |
| 44 | + * @since 1.15.2 |
38 | 45 | */ |
39 | 46 | public static final boolean IS_FOLIA = classExists("io.papermc.paper.threadedregions.RegionizedServer"); |
40 | 47 | /** |
41 | | - * Check a running platform is Purpur. |
| 48 | + * Checks if the server is running on the Purpur platform. |
| 49 | + * @since 1.15.2 |
42 | 50 | */ |
43 | 51 | public static final boolean IS_PURPUR = classExists("org.purpurmc.purpur.PurpurConfig"); |
44 | 52 | /** |
45 | | - * Check a running platform is Paper. |
| 53 | + * Checks if the server is running on the Paper platform (or a fork like Purpur/Folia). |
| 54 | + * @since 1.15.2 |
46 | 55 | */ |
47 | 56 | public static final boolean IS_PAPER = IS_PURPUR || IS_FOLIA || classExists("io.papermc.paper.configuration.PaperConfigurations"); |
48 | 57 |
|
49 | 58 | /** |
50 | | - * Plugin instance. |
| 59 | + * The singleton plugin instance. |
51 | 60 | */ |
52 | 61 | private static BetterModelPlugin instance; |
53 | 62 |
|
54 | 63 | /** |
55 | | - * Gets config manager |
56 | | - * @return config |
| 64 | + * Returns the plugin configuration manager. |
| 65 | + * |
| 66 | + * @return the configuration manager |
| 67 | + * @since 1.15.2 |
57 | 68 | */ |
58 | 69 | public static @NotNull BetterModelConfig config() { |
59 | 70 | return plugin().config(); |
60 | 71 | } |
61 | 72 |
|
62 | 73 | /** |
63 | | - * Gets model renderer by name |
64 | | - * @param name name |
65 | | - * @return optional renderer |
| 74 | + * Retrieves a model renderer by its name, wrapped in an Optional. |
| 75 | + * |
| 76 | + * @param name the name of the model |
| 77 | + * @return an optional containing the renderer if found |
| 78 | + * @since 1.15.2 |
66 | 79 | */ |
67 | 80 | public static @NotNull Optional<ModelRenderer> model(@NotNull String name) { |
68 | 81 | return Optional.ofNullable(modelOrNull(name)); |
69 | 82 | } |
70 | 83 |
|
71 | 84 | /** |
72 | | - * Gets model renderer or null by name |
73 | | - * @param name name |
74 | | - * @return nullable renderer |
| 85 | + * Retrieves a model renderer by its name, or null if not found. |
| 86 | + * |
| 87 | + * @param name the name of the model |
| 88 | + * @return the renderer, or null |
| 89 | + * @since 1.15.2 |
75 | 90 | */ |
76 | 91 | public static @Nullable ModelRenderer modelOrNull(@NotNull String name) { |
77 | 92 | return plugin().modelManager().model(name); |
78 | 93 | } |
79 | 94 |
|
80 | 95 | /** |
81 | | - * Gets player animation renderer by name |
82 | | - * @param name name |
83 | | - * @return optional renderer |
| 96 | + * Retrieves a player limb renderer by its name, wrapped in an Optional. |
| 97 | + * |
| 98 | + * @param name the name of the limb model |
| 99 | + * @return an optional containing the renderer if found |
| 100 | + * @since 1.15.2 |
84 | 101 | */ |
85 | 102 | public static @NotNull Optional<ModelRenderer> limb(@NotNull String name) { |
86 | 103 | return Optional.ofNullable(limbOrNull(name)); |
87 | 104 | } |
88 | 105 |
|
89 | 106 | /** |
90 | | - * Gets player animation renderer or null by name |
91 | | - * @param name name |
92 | | - * @return nullable renderer |
| 107 | + * Retrieves a player limb renderer by its name, or null if not found. |
| 108 | + * |
| 109 | + * @param name the name of the limb model |
| 110 | + * @return the renderer, or null |
| 111 | + * @since 1.15.2 |
93 | 112 | */ |
94 | 113 | public static @Nullable ModelRenderer limbOrNull(@NotNull String name) { |
95 | 114 | return plugin().modelManager().limb(name); |
96 | 115 | } |
97 | 116 |
|
98 | 117 | /** |
99 | | - * Gets player channel by uuid. |
100 | | - * @param uuid uuid |
101 | | - * @return optional channel |
| 118 | + * Retrieves a player channel handler by the player's UUID. |
| 119 | + * |
| 120 | + * @param uuid the player's UUID |
| 121 | + * @return an optional containing the channel handler if found |
| 122 | + * @since 1.15.2 |
102 | 123 | */ |
103 | 124 | public static @NotNull Optional<PlayerChannelHandler> player(@NotNull UUID uuid) { |
104 | 125 | return Optional.ofNullable(plugin().playerManager().player(uuid)); |
105 | 126 | } |
106 | 127 |
|
107 | 128 | /** |
108 | | - * Gets entity registry by entity's uuid. |
109 | | - * @param uuid uuid |
110 | | - * @return optional registry |
| 129 | + * Retrieves an entity tracker registry by the entity's UUID. |
| 130 | + * |
| 131 | + * @param uuid the entity's UUID |
| 132 | + * @return an optional containing the registry if found |
| 133 | + * @since 1.15.2 |
111 | 134 | */ |
112 | 135 | public static @NotNull Optional<EntityTrackerRegistry> registry(@NotNull UUID uuid) { |
113 | 136 | return Optional.ofNullable(registryOrNull(uuid)); |
114 | 137 | } |
115 | 138 |
|
116 | 139 | /** |
117 | | - * Gets entity registry by entity. |
118 | | - * @param entity entity |
119 | | - * @return optional registry |
| 140 | + * Retrieves an entity tracker registry for a Bukkit entity. |
| 141 | + * |
| 142 | + * @param entity the Bukkit entity |
| 143 | + * @return an optional containing the registry if found |
| 144 | + * @since 1.15.2 |
120 | 145 | */ |
121 | 146 | public static @NotNull Optional<EntityTrackerRegistry> registry(@NotNull Entity entity) { |
122 | 147 | return Optional.ofNullable(registryOrNull(entity)); |
123 | 148 | } |
124 | 149 |
|
125 | 150 | /** |
126 | | - * Gets entity registry by entity. |
127 | | - * @param entity entity |
128 | | - * @return optional registry |
| 151 | + * Retrieves an entity tracker registry for a base entity. |
| 152 | + * |
| 153 | + * @param entity the base entity |
| 154 | + * @return an optional containing the registry if found |
| 155 | + * @since 1.15.2 |
129 | 156 | */ |
130 | 157 | public static @NotNull Optional<EntityTrackerRegistry> registry(@NotNull BaseEntity entity) { |
131 | 158 | return Optional.ofNullable(registryOrNull(entity)); |
132 | 159 | } |
133 | 160 |
|
134 | 161 | /** |
135 | | - * Gets entity registry by entity's uuid. |
136 | | - * @param uuid uuid |
137 | | - * @return registry or null |
| 162 | + * Retrieves an entity tracker registry by the entity's UUID, or null if not found. |
| 163 | + * |
| 164 | + * @param uuid the entity's UUID |
| 165 | + * @return the registry, or null |
| 166 | + * @since 1.15.2 |
138 | 167 | */ |
139 | 168 | public static @Nullable EntityTrackerRegistry registryOrNull(@NotNull UUID uuid) { |
140 | 169 | return EntityTrackerRegistry.registry(uuid); |
141 | 170 | } |
142 | 171 |
|
143 | 172 | /** |
144 | | - * Gets entity registry by entity. |
145 | | - * @param entity entity |
146 | | - * @return registry or null |
| 173 | + * Retrieves an entity tracker registry for a Bukkit entity, or null if not found. |
| 174 | + * |
| 175 | + * @param entity the Bukkit entity |
| 176 | + * @return the registry, or null |
| 177 | + * @since 1.15.2 |
147 | 178 | */ |
148 | 179 | public static @Nullable EntityTrackerRegistry registryOrNull(@NotNull Entity entity) { |
149 | 180 | return registryOrNull(nms().adapt(entity)); |
150 | 181 | } |
151 | 182 |
|
152 | 183 | /** |
153 | | - * Gets entity registry by entity. |
154 | | - * @param entity entity |
155 | | - * @return registry or null |
| 184 | + * Retrieves an entity tracker registry for a base entity, or null if not found. |
| 185 | + * |
| 186 | + * @param entity the base entity |
| 187 | + * @return the registry, or null |
| 188 | + * @since 1.15.2 |
156 | 189 | */ |
157 | 190 | public static @Nullable EntityTrackerRegistry registryOrNull(@NotNull BaseEntity entity) { |
158 | 191 | return EntityTrackerRegistry.registry(entity); |
159 | 192 | } |
160 | 193 |
|
161 | 194 | /** |
162 | | - * Gets all models |
163 | | - * @return all models |
| 195 | + * Returns a collection of all loaded model renderers. |
| 196 | + * |
| 197 | + * @return an unmodifiable collection of models |
| 198 | + * @since 1.15.2 |
164 | 199 | */ |
165 | 200 | public static @NotNull @Unmodifiable Collection<ModelRenderer> models() { |
166 | 201 | return plugin().modelManager().models(); |
167 | 202 | } |
168 | 203 |
|
169 | 204 | /** |
170 | | - * Gets all limbs |
171 | | - * @return all limbs |
| 205 | + * Returns a collection of all loaded player limb renderers. |
| 206 | + * |
| 207 | + * @return an unmodifiable collection of limb models |
| 208 | + * @since 1.15.2 |
172 | 209 | */ |
173 | 210 | public static @NotNull @Unmodifiable Collection<ModelRenderer> limbs() { |
174 | 211 | return plugin().modelManager().limbs(); |
175 | 212 | } |
176 | 213 |
|
177 | 214 | /** |
178 | | - * Gets all keys of model |
179 | | - * @return all model keys |
| 215 | + * Returns a set of all loaded model names. |
| 216 | + * |
| 217 | + * @return an unmodifiable set of model keys |
| 218 | + * @since 1.15.2 |
180 | 219 | */ |
181 | 220 | public static @NotNull @Unmodifiable Set<String> modelKeys() { |
182 | 221 | return plugin().modelManager().modelKeys(); |
183 | 222 | } |
184 | 223 |
|
185 | 224 | /** |
186 | | - * Gets all keys of limb |
187 | | - * @return all limb keys |
| 225 | + * Returns a set of all loaded player limb model names. |
| 226 | + * |
| 227 | + * @return an unmodifiable set of limb keys |
| 228 | + * @since 1.15.2 |
188 | 229 | */ |
189 | 230 | public static @NotNull @Unmodifiable Set<String> limbKeys() { |
190 | 231 | return plugin().modelManager().limbKeys(); |
191 | 232 | } |
192 | 233 |
|
193 | 234 | /** |
194 | | - * Gets plugin instance of BetterModel. |
| 235 | + * Returns the singleton instance of the BetterModel plugin. |
| 236 | + * |
| 237 | + * @return the plugin instance |
| 238 | + * @throws NullPointerException if the plugin has not been initialized |
195 | 239 | * @see org.bukkit.plugin.java.JavaPlugin |
196 | | - * @return instance |
| 240 | + * @since 1.15.2 |
197 | 241 | */ |
198 | 242 | public static @NotNull BetterModelPlugin plugin() { |
199 | 243 | return Objects.requireNonNull(instance, "BetterModel hasn't been initialized yet!"); |
200 | 244 | } |
201 | 245 |
|
202 | 246 | /** |
203 | | - * Gets nms |
204 | | - * @return nms |
| 247 | + * Returns the NMS handler instance. |
| 248 | + * |
| 249 | + * @return the NMS handler |
| 250 | + * @since 1.15.2 |
205 | 251 | */ |
206 | 252 | public static @NotNull NMS nms() { |
207 | 253 | return plugin().nms(); |
208 | 254 | } |
209 | 255 |
|
210 | 256 | /** |
211 | | - * Sets plugin instance of BetterModel. |
212 | | - * @param instance instance |
| 257 | + * Registers the plugin instance. |
| 258 | + * <p> |
| 259 | + * This method is intended for internal use only during plugin initialization. |
| 260 | + * </p> |
| 261 | + * |
| 262 | + * @param instance the plugin instance |
| 263 | + * @throws RuntimeException if an instance is already registered |
| 264 | + * @since 1.15.2 |
213 | 265 | */ |
214 | 266 | @ApiStatus.Internal |
215 | 267 | public static void register(@NotNull BetterModelPlugin instance) { |
|
0 commit comments