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

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

    resource entity {
        get-id: func() -> u32;
        get-uuid: func() -> string;
        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;

        is-on-ground: func() -> bool;
        
        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);
        
        is-on-fire: func() -> bool;
        set-on-fire: func(on-fire: bool);

        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);

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

    /// 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 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 a list of all entities in this world.
        get-entities: func() -> list<entity>;
    }
}