6. World Block Management (PlacedBlock)

The API provides comprehensive methods for interacting with custom blocks that are placed in the world.

6.1. Retrieving PlacedBlock Instances

You can retrieve a PlacedBlock instance from the API's storage using its Vec3i position. This is crucial for accessing a block's persistent data or definition.

// Kotlin Example
import io.github.zawarka03.monolithAPI.MonolithAPI
import io.github.zawarka03.monolithAPI.vec3i.utils.toVec3i
import org.bukkit.block.Block

fun processBlock(bukkitBlock: Block) {
    val position = bukkitBlock.toVec3i()
    
    // Retrieve the PlacedBlock from storage
    val placedBlock = MonolithAPI.api.storage[position]

    if (placedBlock != null) {
        // It's a custom block!
        println("Found custom block: ${placedBlock.identifier}")
        // Access data: val energy = placedBlock.data[energyKey]
    } else {
        // It's a vanilla block
    }
}

6.2. Programmatic Placement and Destruction

The BlockPlacement component (MonolithAPI.api().blocks()) allows you to programmatically place and destroy custom blocks.

• Standard Methods (place, destroy): These methods simulate player interaction. They dispatch the corresponding events (MonolithBlockPlaceEvent, MonolithBlockBreakEvent, MonolithBlockDropEvent) and respect event cancellation.
• Forced Methods (placeForced, destroyForced): These methods bypass the event system entirely. They directly modify the world, update the internal storage, and update the database repository. They are useful for internal plugin logic where event dispatching is unnecessary or undesirable (e.g., generating structures or handling explosions).

// Java Example
import io.github.zawarka03.monolithAPI.MonolithAPI;
import io.github.zawarka03.monolithAPI.api.block.BlockDefinition;
import io.github.zawarka03.monolithAPI.vec3i.Vec3i;
import org.bukkit.entity.Player;

public void manageBlocks(Player player, Vec3i pos, BlockDefinition def) {
    
    // Standard placement (dispatches events, can be cancelled)
    MonolithAPI.api().blocks().place(pos, def, player);

    // Forced placement (bypasses events, updates DB immediately)
    MonolithAPI.api().blocks().placeForced(pos, def);

    // Standard destruction (dispatches events, drops items)
    MonolithAPI.api().blocks().destroy(pos, player, true, true);

    // Forced destruction (bypasses events, no item drops)
    MonolithAPI.api().blocks().destroyForced(pos, true);
}