interface %world {
    use common.{position, entity-pose, block-pos};
    use block-entity.{block-entity, command-block-entity, block-entity-type};
    use text.{text-component};
    use scoreboard.{scoreboard};
    use particles.{particle};
    use sounds.{sound};
    use entity-types.{entity-type};
    use biomes.{biome};

    use uuid.{uuid};

    /// 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,

        /// Whether this block can catch fire.
        burnable: bool,
        /// Whether a specific tool is required to mine this block and get drops.
        tool-required: bool,
        /// Whether this block has transparency on its sides.
        sided-transparency: bool,
        /// Whether this block can be replaced by another block (e.g., grass).
        replaceable: bool,
        /// Whether this block is considered a solid block for redstone purposes.
        is-solid-block: bool,
        /// The numerical ID of the block entity type, if any.
        block-entity-type: u16,
        /// The instrument used for note blocks when placed on top of this block.
        instrument: noteblock-instrument,
        /// The collision shapes of this block.
        collision-shapes: list<bounding-box>,
        /// The outline shapes of this block.
        outline-shapes: list<bounding-box>,

        /// Whether the bottom side of the block is solid.
        down-side-solid: bool,
        /// Whether the top side of the block is solid.
        up-side-solid: bool,
        /// Whether the north side of the block is solid.
        north-side-solid: bool,
        /// Whether the south side of the block is solid.
        south-side-solid: bool,
        /// Whether the west side of the block is solid.
        west-side-solid: bool,
        /// Whether the east side of the block is solid.
        east-side-solid: bool,
        /// Whether the center of the bottom side is solid.
        down-center-solid: bool,
        /// Whether the center of the top side is solid.
        up-center-solid: bool,
        /// The color of this block when displayed on a map.
        map-color: u8,
    }

    /// Musical instruments used by note blocks.
    enum noteblock-instrument {
        harp,
        basedrum,
        snare,
        hat,
        bass,
        flute,
        bell,
        guitar,
        chime,
        xylophone,
        iron-xylophone,
        cow-bell,
        didgeridoo,
        bit,
        banjo,
        pling,
        trumpet,
        trumpet-exposed,
        trumpet-oxidized,
        trumpet-weathered,
        zombie,
        skeleton,
        creeper,
        dragon,
        wither-skeleton,
        piglin,
        custom-head,
    }

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

    resource entity {
        get-id: func() -> u32;
        get-uuid: func() -> uuid;
        get-type: func() -> entity-type;

        get-position: func() -> position;
        get-world: func() -> %world;

        get-yaw: func() -> f32;
        get-pitch: func() -> f32;
        get-head-yaw: func() -> f32;

        teleport: func(pos: position, world-ref: %world);
        set-velocity: func(velocity: position);
        get-velocity: func() -> position;

        get-pose: func() -> entity-pose;
        get-name: func() -> text-component;
        set-custom-name: func(name: text-component);
        get-custom-name: func() -> option<text-component>;
        set-custom-name-visible: func(visible: bool);
        is-custom-name-visible: func() -> bool;

        is-invulnerable: func() -> bool;
        set-invulnerable: func(invulnerable: bool);

        get-fire-ticks: func() -> s32;
        set-fire-ticks: func(ticks: s32);

        get-health: func() -> f32;
        set-health: func(health: f32);
        get-max-health: func() -> f32;
        damage: func(amount: f32);
        is-dead: func() -> bool;

        get-absorption: func() -> f32;
        set-absorption: func(amount: f32);

        get-age: func() -> s32;
        set-age: func(age: s32);

        get-fall-distance: func() -> f32;
        set-fall-distance: func(distance: f32);

        get-ticks-lived: func() -> s32;
        set-ticks-lived: func(ticks: s32);

        is-sneaking: func() -> bool;
        set-sneaking: func(sneaking: bool);
        is-sprinting: func() -> bool;
        set-sprinting: func(sprinting: bool);
        is-swimming: func() -> bool;
        set-swimming: func(swimming: bool);
        is-invisible: func() -> bool;
        set-invisible: func(invisible: bool);
        is-glowing: func() -> bool;
        set-glowing: func(glowing: bool);
        is-fall-flying: func() -> bool;
        set-fall-flying: func(fall-flying: bool);

        get-width: func() -> f32;
        get-height: func() -> f32;

        set-rotation: func(yaw: f32, pitch: f32);

        is-on-ground: func() -> bool;
        is-on-fire: func() -> bool;
        set-on-fire: func(on-fire: bool);
        has-visual-fire: func() -> bool;
        set-visual-fire: func(visual-fire: bool);

        get-portal-cooldown: func() -> u32;
        set-portal-cooldown: func(cooldown: u32);

        get-remaining-air: func() -> s32;
        set-remaining-air: func(air: s32);
        get-max-air: func() -> s32;

        send-system-message: func(message: text-component);

        get-eye-height: func() -> f32;
        get-eye-position: func() -> position;

        get-nearby-entities: func(x: f64, y: f64, z: f64) -> list<entity>;

        get-vehicle: func() -> option<entity>;
        set-vehicle: func(vehicle: option<entity>);
        get-passengers: func() -> list<entity>;
        add-passenger: func(passenger: entity);
        remove-passenger: func(passenger: entity);
        eject-passengers: func();

        get-bounding-box: func() -> bounding-box;

        is-in-water: func() -> bool;
        is-in-lava: func() -> bool;

        remove: func();

        /// Performs a raycast from the entity's eye position in its looking direction.
        raycast: func(max-distance: f64, fluid-handling: bool) -> option<raycast-result>;
    }

    /// Result of a raycast operation.
    record raycast-result {
        /// The block position that was hit.
        pos: block-pos,
        /// The face of the block that was hit.
        face: block-direction,
    }

    resource chunk {
        /// Gets the chunk's X coordinate.
        get-x: func() -> s32;

        /// Gets the chunk's Z coordinate.
        get-z: func() -> s32;

        /// Gets the block state ID at the specified position relative to the chunk.
        /// X and Z must be in the range [0, 15].
        get-block-state-id: func(pos: block-pos) -> u16;

        /// Gets detailed block state information at the specified position relative to the chunk.
        /// X and Z must be in the range [0, 15].
        get-block-state: func(pos: block-pos) -> block-state;

        /// Sets the block state at the specified position relative to the chunk.
        /// X and Z must be in the range [0, 15].
        set-block-state: func(pos: block-pos, state: u16);

        /// Gets the biome at the specified position relative to the chunk.
        /// X and Z must be in the range [0, 15].
        get-biome: func(pos: block-pos) -> biome;

        /// Gets the block entity at the specified position relative to the chunk, if any.
        /// X and Z must be in the range [0, 15].
        get-block-entity: func(pos: block-pos) -> option<block-entity-type>;

        /// Gets the highest non-air block Y coordinate at the specified X and Z relative to the chunk.
        /// X and Z must be in the range [0, 15].
        get-top-block-y: func(x: s32, z: s32) -> s32;

        /// Gets the sky light level at the specified position relative to the chunk.
        /// X and Z must be in the range [0, 15].
        get-sky-light: func(pos: block-pos) -> u8;

        /// Gets the block light level at the specified position relative to the chunk.
        /// X and Z must be in the range [0, 15].
        get-block-light: func(pos: block-pos) -> u8;
    }

    /// Represents the boundaries of a world.
    resource world-border {
        /// Gets the center X coordinate of the border.
        get-center-x: func() -> f64;
        /// Gets the center Z coordinate of the border.
        get-center-z: func() -> f64;
        /// Sets the center coordinates of the border.
        set-center: func(x: f64, z: f64);

        /// Gets the current diameter of the border.
        get-diameter: func() -> f64;
        /// Sets the diameter of the border, optionally with a speed (in ticks) for lerping.
        set-diameter: func(diameter: f64, speed: option<u64>);

        /// Gets the distance from the border where warning effects start (in blocks).
        get-warning-distance: func() -> s32;
        /// Sets the warning distance (in blocks).
        set-warning-distance: func(distance: s32);

        /// Gets the time before a player hitting the border is warned (in seconds).
        get-warning-delay: func() -> s32;
        /// Sets the warning delay (in seconds).
        set-warning-delay: func(delay: s32);

        /// Returns whether the specified coordinates are within the border.
        contains: func(x: f64, z: f64) -> bool;
    }

    /// Represents an axis-aligned bounding box.
    record bounding-box {
        min: position,
        max: position,
    }

    /// Represents a cardinal direction or block face.
    enum block-direction {
        down,
        up,
        north,
        south,
        west,
        east,
    }

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

        /// Gets the world border associated with this world.
        get-world-border: func() -> world-border;

        /// Gets the chunk at the specified chunk coordinates.
        get-chunk: func(x: s32, z: s32) -> option<chunk>;

        /// 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: sound, category: sound-category, pos: position, volume: f32, pitch: f32);

        /// Spawns particles at the specified position.
        spawn-particle: func(particle: particle, 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;

        /// Returns the sky light level at the specified position.
        get-sky-light: func(pos: block-pos) -> u8;

        /// Sets the sky light level at the specified position.
        set-sky-light: func(pos: block-pos, level: u8);

        /// Returns the block light level at the specified position.
        get-block-light: func(pos: block-pos) -> u8;

        /// Sets the block light level at the specified position.
        set-block-light: func(pos: block-pos, level: u8);

        /// Returns the biome at the specified position.
        get-biome: func(pos: block-pos) -> biome;

        /// Spawns an entity of the specified type at the given position.
        spawn-entity: func(entity-type: entity-type, pos: position) -> entity;

        /// Returns a list of all entities in this world.
        get-entities: func() -> list<entity>;

        /// Returns the block entity at the specified position, if any.
        get-block-entity: func(pos: block-pos) -> option<block-entity-type>;
    }
}