Pumpkin/pumpkin-plugin-wit/v0.1.0/world.wit

interface %world {
    use common.{position};
    use text.{text-component};
    use scoreboard.{scoreboard};

    /// Defines how a block reacts when pushed by a piston.
    enum piston-behavior {
        /// Normal behavior; the block can be pushed and pulled.
        normal,
        /// The block is destroyed when pushed.
        destroy,
        /// The block cannot be pushed or pulled.
        block,
        /// The block is ignored by pistons.
        ignore,
        /// The block can only be pushed, not pulled.
        push-only
    }

    /// Categories for sounds to control their volume independently.
    enum sound-category {
        master,
        music,
        records,
        weather,
        blocks,
        hostile,
        neutral,
        players,
        ambient,
        voice,
    }

    /// Defines how an explosion interacts with blocks in the world.
    enum explosion-interaction {
        /// No interaction with blocks.
        none,
        /// Blocks are destroyed and may drop loot.
        block,
        /// Interaction typical for mob-caused explosions.
        mob,
        /// Interaction typical for TNT explosions.
        tnt,
        /// Triggers specific block behaviors.
        trigger,
    }

    /// Flags used to control block updates and notifications.
    flags block-flags {
        /// Notifies neighbor blocks of the change.
        notify-neighbors,
        /// Notifies client listeners of the change.
        notify-listeners,
        /// Forces the block state even if it's the same.
        force-state,
        /// Skips dropping items when the block is removed.
        skip-drops,
        /// Indicates the block was moved (e.g., by a piston).
        moved,
        /// Skips state replacement for redstone wires.
        skip-redstone-wire-state-replacement,
        /// Skips the callback when a block entity is replaced.
        skip-block-entity-replaced-callback,
        /// Skips the callback when a block is added.
        skip-block-added-callback,
    }

    /// Detailed information about a block's state.
    record block-state {
        /// The internal numerical ID of the block state.
        id: u16,
        /// The light level emitted by this block (0-15).
        luminance: u8,
        /// How much light this block blocks.
        opacity: u8,
        /// The hardness of the block, determining mining speed.
        hardness: f32,
        /// Whether this block is considered air.
        is-air: bool,
        /// Whether this block is a liquid.
        is-liquid: bool,
        /// Whether this block is a solid.
        is-solid: bool,
        /// Whether this block occupies a full cube.
        is-full-cube: bool,
        /// How this block behaves when pushed by a piston.
        piston-behavior: piston-behavior,
        /// Whether this block receives random ticks.
        has-random-ticks: bool,
    }

    /// A simple wrapper for a block state ID.
    record block-state-id {
        id: u16,
    }

    /// A position in the world grid.
    record block-pos {
        x: s32,
        y: s32,
        z: s32,
    }

    /// Represents a Minecraft world (dimension).
    resource %world {
        /// Returns the unique identifier of this world.
        get-id: func() -> string;

        /// Gets the block state ID at the specified position.
        get-block-state-id: func(pos: block-pos) -> u16;

        /// Gets detailed block state information at the specified position.
        get-block-state: func(pos: block-pos) -> block-state;

        /// Sets the block state at the specified position.
        set-block-state: func(pos: block-pos, state: u16, update-flags: block-flags);

        /// Returns the current time of day in ticks.
        get-time-of-day: func() -> u64;

        /// Sets the current time of day in ticks.
        set-time-of-day: func(time: u64);

        /// Returns the total age of the world in ticks.
        get-world-age: func() -> u64;

        /// Returns the dimension type (e.g., "minecraft:overworld").
        get-dimension: func() -> string;

        /// Gets the highest non-air block Y coordinate at the specified X and Z.
        get-top-block-y: func(x: s32, z: s32) -> s32;

        /// Gets the highest motion-blocking block Y coordinate.
        get-motion-blocking-height: func(x: s32, z: s32) -> s32;

        /// Returns whether it is currently raining or snowing.
        is-raining: func() -> bool;

        /// Sets whether it should be raining or snowing.
        set-raining: func(raining: bool);

        /// Returns whether there is currently a thunderstorm.
        is-thundering: func() -> bool;

        /// Sets whether there should be a thunderstorm.
        set-thundering: func(thundering: bool);

        /// Broadcasts a system message to all players in this world.
        broadcast-system-message: func(message: text-component, overlay: bool);

        /// Returns the scoreboard associated with this world.
        get-scoreboard: func() -> scoreboard;

        /// Plays a sound at the specified position for all players in the world.
        play-sound: func(sound: string, category: sound-category, pos: position, volume: f32, pitch: f32);

        /// Spawns particles at the specified position.
        spawn-particle: func(particle: string, pos: position, offset: position, max-speed: f32, count: s32);

        /// Creates an explosion at the specified position.
        create-explosion: func(pos: position, power: f32, create-fire: bool, interaction: explosion-interaction);

        /// Returns the sea level of this world.
        get-sea-level: func() -> s32;

        /// Returns the minimum Y coordinate (bottom of the world).
        get-min-y: func() -> s32;
    }
}