a lot of changes

Author: Mapacheee

README.md

@@ -63,6 +63,40 @@ You can combine it with `use-group-permissions` and your group policies.
 ## Placeholders (PlaceholderAPI)
 - `%extendedhorizons_view_distance%` — current effective distance
 
+---
+
+## API for Developers
+
+ExtendedHorizons provides a comprehensive API for other plugins to interact with fake chunks.
+
+### Documentation
+- **[Full API Documentation](API-USAGE.md)** - Complete guide with examples
+- **[Example Plugin](examples/)** - Working example showing all API features
+
+### Quick Example
+```java
+// Access the API
+ExtendedHorizonsAPI api = ExtendedHorizonsPlugin.getService(ExtendedHorizonsAPI.class);
+
+// Check if player is looking at a fake chunk
+int chunkX = player.getLocation().getBlockX() >> 4;
+int chunkZ = player.getLocation().getBlockZ() >> 4;
+if (api.isFakeChunk(player, chunkX, chunkZ)) {
+    player.sendMessage("You're in a fake chunk!");
+}
+
+// Get all fake chunks for a player
+Set<ChunkCoordinate> chunks = api.getFakeChunksForPlayer(player);
+player.sendMessage("Loaded: " + chunks.size() + " fake chunks");
+```
+
+### Available Events
+- `FakeChunkLoadEvent` - When a fake chunk is loaded (cancellable)
+- `FakeChunkUnloadEvent` - When a fake chunk is unloaded
+- `FakeChunkBatchLoadEvent` - When multiple chunks are loaded at once
+
+See **[API-USAGE.md](API-USAGE.md)** for complete documentation.
+
 ---
 # Support
 - Report issues and suggestions in the repository’s Issues section.

build.gradle

@@ -6,7 +6,7 @@ plugins {
 }
 
 group = 'me.mapacheee'
-version = '2.3.3'
+version = '2.3.4'
 description = 'ExtendedHorizons - Advanced view distance extension plugin'
 
 java {

examples/README.md

@@ -0,0 +1,141 @@
+# ExtendedHorizons API Example Plugin
+
+This is a complete, working example plugin that demonstrates how to use the ExtendedHorizons API.
+
+
+## Building This Example
+
+1. **Copy the ExtendedHorizons JAR** to `libs/` folder:
+   ```bash
+   mkdir libs
+   cp ../build/libs/ExtendedHorizons-2.3.3.jar libs/
+   ```
+
+2. **Build the plugin**:
+   ```bash
+   ./gradlew jar
+   ```
+
+3. **Find the JAR** in `build/libs/ExamplePlugin-1.0.0.jar`
+
+## Testing This Example
+
+1. Install both ExtendedHorizons and ExamplePlugin on your server
+2. Join the server
+3. Use the commands:
+   - `/fakechunkinfo` - Shows your current fake chunk status
+   - `/clearfakechunks` - Clears all your fake chunks
+   - `/refreshfakechunks` - Refreshes your fake chunks
+
+## Files Explained
+
+### build.gradle
+Shows how to configure your Gradle build to depend on ExtendedHorizons.
+
+**Key points:**
+- Uses `compileOnly` for ExtendedHorizons (it will be on the server at runtime)
+- Includes the JAR from a local `libs/` folder
+- Sets up Paper API dependency
+
+### plugin.yml
+Shows the required configuration.
+
+**Key points:**
+- `depend: [ExtendedHorizons]` ensures ExtendedHorizons loads first
+- Defines commands for testing
+
+### ExamplePlugin.java
+The main plugin class showing all API features.
+
+**Key sections:**
+- `setupAPI()` - How to safely access the API
+- `displayAPIStats()` - Using cache statistics methods
+- `showFakeChunkInfo()` - Using player-specific methods
+- Event handlers - How to listen to chunk events
+
+## Using This as a Template
+
+1. Copy this `examples/` folder as your project base
+2. Rename the package from `com.example.exampleplugin` to your own
+3. Update `plugin.yml` with your plugin information
+4. Modify `ExamplePlugin.java` to add your own logic
+5. Build and test!
+
+## Common Modifications
+
+### Make ExtendedHorizons Optional
+
+Change `plugin.yml`:
+```yaml
+softdepend: [ExtendedHorizons]  # Instead of depend
+```
+
+Then check if it's available:
+```java
+@Override
+public void onEnable() {
+    if (!setupAPI()) {
+        getLogger().warning("ExtendedHorizons not found, some features disabled");
+        // Continue loading with limited features
+    }
+}
+```
+
+### Track Chunk Statistics
+
+```java
+private int totalChunksLoaded = 0;
+private int totalChunksUnloaded = 0;
+
+@EventHandler
+public void onFakeChunkLoad(FakeChunkLoadEvent event) {
+    totalChunksLoaded++;
+}
+
+@EventHandler
+public void onFakeChunkUnload(FakeChunkUnloadEvent event) {
+    totalChunksUnloaded++;
+}
+```
+
+### Restrict Fake Chunks to Specific Regions
+
+```java
+@EventHandler
+public void onFakeChunkLoad(FakeChunkLoadEvent event) {
+    int chunkX = event.getChunkX();
+    int chunkZ = event.getChunkZ();
+    
+    // Only allow fake chunks in spawn area (-100 to +100)
+    if (Math.abs(chunkX) > 100 || Math.abs(chunkZ) > 100) {
+        event.setCancelled(true);
+    }
+}
+```
+
+## Troubleshooting
+
+### "Cannot find symbol" errors when building
+
+Make sure:
+1. ExtendedHorizons JAR is in the `libs/` folder
+2. The JAR filename matches what's in `build.gradle`
+3. You've run `./gradlew build` at least once
+
+### "ExtendedHorizons" plugin not found error
+
+Make sure:
+1. ExtendedHorizons is installed on your server
+2. It's in the `plugins/` folder
+3. It loads before your plugin (check `depend:` in plugin.yml)
+
+### API returns null
+
+This usually means:
+1. ExtendedHorizons isn't properly loaded
+2. You're calling `getService()` too early (before plugin is enabled)
+3. Version mismatch between your plugin and ExtendedHorizons
+
+## More Information
+
+See [API-USAGE.md](../API-USAGE.md) for complete API documentation.

examples/build.gradle

@@ -0,0 +1,35 @@
+plugins {
+    id 'java'
+}
+
+group = 'com.example'
+version = '1.0.0'
+
+repositories {
+    mavenCentral()
+    maven {
+        name = 'papermc-repo'
+        url = 'https://repo.papermc.io/repository/maven-public/'
+    }
+}
+
+dependencies {
+    // Paper API
+    compileOnly 'io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT'
+    
+    // ExtendedHorizons API
+    compileOnly('ExtendedHorizons-2.3.3.jar')
+}
+
+java {
+    toolchain.languageVersion = JavaLanguageVersion.of(21)
+}
+
+tasks.withType(JavaCompile).configureEach {
+    options.encoding = 'UTF-8'
+}
+
+jar {
+    archiveBaseName = 'ExamplePlugin'
+    archiveVersion = project.version
+}