1. Introduction and Setup

1.1. Core Philosophy and Features

Monolith API's core philosophy revolves around providing powerful, yet intuitive, abstractions that make custom block development feel as native as working with the Bukkit API. It focuses on a small set of foundational concepts that can be combined to create complex and dynamic block interactions.

Key features include:

• Type-Safe Block Definitions: Define custom blocks with unique identifiers, display names, and underlying vanilla materials.
• Persistent Data Storage: Attach arbitrary, type-safe data to individual PlacedBlock instances, persisting across server restarts.
• Granular Event System: Implement block-specific behaviors using a flexible event system, allowing precise control over interactions.
• Seamless Item Integration: Convert custom block definitions to ItemStacks for inventory management and world placement, and retrieve definitions from items.
• Advanced Spatial Utilities: Utilize Vec3i for enhanced 3D coordinate manipulation, including distance calculations and entity proximity checks.
• Cross-Language Compatibility: Full support for both Kotlin and Java development, with idiomatic API access for each.
• Lightweight and Performant: Designed for efficiency, minimizing overhead and ensuring smooth server operation.

1.2. Installation

To integrate Monolith API into your Paper plugin project, you need to declare it as a dependency in your plugin.yml and your build system (Maven or Gradle).

plugin.yml Configuration

Ensure your plugin.yml includes MonolithAPI in its depend section:

name: YourPluginName
version: 1.0.0
main: your.plugin.MainClass
api-version: 1.19
depend:
  - MonolithAPI

Maven Dependency

Add the following dependency to your pom.xml:

<dependencies>
    <dependency>
        <groupId>io.github.zawarka03</groupId>
        <artifactId>monolith-api</artifactId>
        <version>VERSION</version> <!-- Replace with the latest version -->
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle Dependency

Add the following dependency to your build.gradle (Groovy) or build.gradle.kts (Kotlin):

// build.gradle (Groovy)
repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'io.github.zawarka03:monolith-api:VERSION' // Replace with the latest version
}

// build.gradle.kts (Kotlin)
repositories {
    mavenCentral()
}

dependencies {
    compileOnly("io.github.zawarka03:monolith-api:VERSION") // Replace with the latest version
}

1.3. API Entry Point

The Monolith API is accessed through a central entry point, providing access to various subsystems. The method of access differs slightly between Java and Kotlin to maintain idiomatic usage.

Java Access

import io.github.zawarka03.monolithAPI.MonolithAPI;
import io.github.zawarka03.monolithAPI.api.BlockAPI;

// Access the main API instance
BlockAPI api = MonolithAPI.api();

Kotlin Access

import io.github.zawarka03.monolithAPI.MonolithAPI

// Access the main API instance
val api = MonolithAPI.api

The BlockAPI instance provides access to the following core components:

Component	Description
blocks	Manages the placement and destruction of custom blocks in the world.
storage	Provides access to the runtime storage of PlacedBlock instances.
registry	Handles the registration and retrieval of BlockDefinitions.
items	Facilitates conversion between ItemStacks and BlockDefinitions.
events	The global event bus for registering listeners and dispatching events.
dataTypes	Manages the registration of custom DataTypes for persistent storage.
repository	The underlying database repository (SQLite) for persistent block storage.