NebulaPlatformExtension

package dev.nebulastorage.api.platform

import net.minecraft.core.BlockPos
import net.minecraft.core.Direction
import net.minecraft.server.level.ServerLevel
import net.neoforged.neoforge.fluids.capability.IFluidHandler

/** Implement alongside NebulaExtension to register adapters requiring actual Minecraft owners. */
interface NebulaPlatformExtension {
    fun registerPlatform(registrar: NebulaPlatformRegistrar)
}

interface NebulaPlatformRegistrar {
    fun creatureCaptureRule(id: String, rule: NebulaCreatureCaptureRule) {
        throw UnsupportedOperationException("This Nebula runtime does not support creature capture rules")
    }
    fun physicalResourceMachineAdapter(id: String, adapter: NebulaPhysicalResourceMachineAdapter) {
        throw UnsupportedOperationException("This Nebula runtime does not support physical resource machines")
    }
    fun resourceContainerAdapter(id: String, adapter: NebulaResourceContainerAdapter) {
        throw UnsupportedOperationException("This Nebula runtime does not support resource containers")
    }
    fun resourceStorageAdapter(id: String, adapter: NebulaResourceStorageAdapter) {
        throw UnsupportedOperationException("This registrar does not support generic resource storage adapters")
    }
    fun fluidStorageAdapter(id: String, adapter: NebulaFluidStorageAdapter)
    fun physicalItemMachineAdapter(id: String, adapter: NebulaPhysicalItemMachineAdapter) {
        throw UnsupportedOperationException("This registrar does not support physical machine adapters")
    }
}

fun interface NebulaFluidStorageAdapter {
    /**
     * Returns a stable capability instance or null for unsupported owners. Called on the server thread, without forcing chunks.
     * Every accepted handler must mutate only the BlockEntity at [position], whose complete resources and Nebula persistent data
     * are saved together in its chunk NBT. Simulation is read-only; execution returns actual conserved quantities and components.
     * Creative/infinite stores, redirection to another owner, or persistence outside that NBT require another recovery protocol.
     * Revalidate this contract on every call, including configuration, upgrades, ownership and capability replacement.
     */
    fun resolve(level: ServerLevel, position: BlockPos, side: Direction): IFluidHandler?
}