585class Engine:
 586    """
 587    Main game engine class providing core functionality with structured logging.
 588    
 589    This class wraps the Rust implementation and provides a Python-friendly API
 590    with full access to the tracing-based logging system.
 591    
 592    Attributes:
 593        version (str): The engine version number.
 594    
 595    Example:
 596        Basic usage with console logging:
 597        >>> engine = Engine()
 598        >>> engine.log_info("Engine started")
 599        >>> engine.log_warn("Low memory warning")
 600        >>> engine.log_error("Failed to load resource")
 601        
 602        With file logging enabled:
 603        >>> engine = Engine(
 604        ...     enable_file_logging=True,
 605        ...     log_directory="./logs",
 606        ...     log_level="DEBUG"
 607        ... )
 608        >>> engine.log_debug("Debug information")
 609    """
 610    
 611    def __init__(
 612        self,
 613        enable_file_logging: bool = False,
 614        log_directory: Optional[str] = None,
 615        log_level: Optional[str] = None,
 616    ) -> None:
 617        """
 618        Initialize a new Engine instance with optional logging configuration.
 619        
 620        Args:
 621            enable_file_logging: Enable logging to files (default: False).
 622                Files are rotated daily and stored in the log directory.
 623            log_directory: Directory path for log files (default: "./logs").
 624                Only used if enable_file_logging is True.
 625            log_level: Minimum log level to display. Options:
 626                - "TRACE": Most verbose, includes all logs
 627                - "DEBUG": Debug and higher
 628                - "INFO": Info and higher (default)
 629                - "WARN": Warnings and errors only
 630                - "ERROR": Errors only
 631        
 632        Example:
 633            >>> # Console only with INFO level (default)
 634            >>> engine = Engine()
 635            
 636            >>> # Enable file logging with DEBUG level
 637            >>> engine = Engine(
 638            ...     enable_file_logging=True,
 639            ...     log_directory="./my_logs",
 640            ...     log_level="DEBUG"
 641            ... )
 642        """
 643        self._engine = _RustEngine(
 644            enable_file_logging=enable_file_logging,
 645            log_directory=log_directory,
 646            log_level=log_level,
 647        )
 648        self._input = Input(self)
 649        self._runtime_state = _RUNTIME_STATE_IDLE
 650        self._window_icon_path: Optional[str] = None
 651    
 652    @property
 653    def input(self) -> Input:
 654        """
 655        Get the input manager for the engine.
 656        
 657        Returns:
 658            Input: The input manager instance.
 659        """
 660        return self._input
 661
 662    @property
 663    def is_running(self) -> bool:
 664        """Return whether the engine is currently running in any loop mode."""
 665        return self._runtime_state != _RUNTIME_STATE_IDLE
 666
 667    def _ensure_not_running(self, entrypoint_name: str) -> None:
 668        if self._runtime_state != _RUNTIME_STATE_IDLE:
 669            raise RuntimeError(
 670                f"Cannot call {entrypoint_name} while engine is already running "
 671                f"in '{self._runtime_state}' mode."
 672            )
 673
 674    def get_handle(self) -> EngineHandle:
 675        """
 676        Get a thread-safe handle to the engine that can be passed to background threads.
 677        
 678        Returns:
 679            EngineHandle: A handle used to queue commands from other threads.
 680        """
 681        return EngineHandle(self._engine.get_handle())
 682    
 683    def log(self, message: str) -> None:
 684        """
 685        Log a message at INFO level (default log method).
 686        
 687        This is an alias for log_info() for backward compatibility.
 688        
 689        Args:
 690            message: The message to log.
 691        """
 692        self._engine.log(message)
 693    
 694    def log_trace(self, message: str) -> None:
 695        """
 696        Log a message at TRACE level (most verbose).
 697        
 698        Use for very detailed debugging information.
 699        Only visible when log level is set to TRACE.
 700        
 701        Args:
 702            message: The message to log.
 703        """
 704        self._engine.log_trace(message)
 705    
 706    def log_debug(self, message: str) -> None:
 707        """
 708        Log a message at DEBUG level.
 709        
 710        Use for debugging information that's useful during development.
 711        Visible when log level is DEBUG or TRACE.
 712        
 713        Args:
 714            message: The message to log.
 715        """
 716        self._engine.log_debug(message)
 717    
 718    def log_info(self, message: str) -> None:
 719        """
 720        Log a message at INFO level.
 721        
 722        Use for general informational messages about engine operation.
 723        This is the default log level.
 724        
 725        Args:
 726            message: The message to log.
 727        """
 728        self._engine.log_info(message)
 729    
 730    def log_warn(self, message: str) -> None:
 731        """
 732        Log a message at WARN level.
 733        
 734        Use for warnings that don't prevent operation but indicate
 735        potential issues.
 736        
 737        Args:
 738            message: The message to log.
 739        """
 740        self._engine.log_warn(message)
 741    
 742    def log_error(self, message: str) -> None:
 743        """
 744        Log a message at ERROR level.
 745        
 746        Use for errors that may affect engine operation.
 747        
 748        Args:
 749            message: The message to log.
 750        """
 751        self._engine.log_error(message)
 752
 753    def set_window_title(self, title: str) -> None:
 754        """
 755        Set the window title.
 756        
 757        Args:
 758            title: The new window title.
 759        """
 760        self._engine.set_window_title(title)
 761
 762    def set_window_icon(self, icon_path: str) -> None:
 763        """
 764        Set the window icon from an image file path.
 765
 766        The path is remembered and will be reused for future `run()` /
 767        `start_manual()` calls unless overridden per call.
 768        """
 769        self._window_icon_path = icon_path
 770        self._engine.set_window_icon(icon_path)
 771
 772    def get_display_size(self) -> tuple[int, int]:
 773        """Get the current display size (window client size) in pixels."""
 774        return self._engine.get_display_size()
 775
 776    def start_manual(
 777        self,
 778        title: str = "PyG Engine",
 779        width: int = 1280,
 780        height: int = 720,
 781        resizable: bool = True,
 782        background_color: Optional[Any] = None,
 783        vsync: bool = True,
 784        redraw_on_change_only: bool = True,
 785        show_fps_in_title: bool = False,
 786        icon_path: Optional[str] = None,
 787        min_width: Optional[int] = None,
 788        min_height: Optional[int] = None,
 789    ) -> None:
 790        """
 791        Start the engine in manual-loop mode without entering a blocking loop.
 792
 793        This mode is for advanced use cases where Python controls the frame loop
 794        manually using:
 795        `poll_events()`, `update()`, and `render()`.
 796
 797        Raises:
 798            RuntimeError: If the engine is already running in another loop mode.
 799
 800        Args:
 801            title: Window title.
 802            width: Initial window width.
 803            height: Initial window height.
 804            resizable: Whether the window can be resized.
 805            background_color: Optional `pyg_engine.Color`.
 806            vsync: Enable/disable vertical sync.
 807            redraw_on_change_only: When True (default), only redraw on scene changes.
 808            show_fps_in_title: When True, appends current FPS to window title.
 809            icon_path: Optional icon file path. If omitted, uses the most recent
 810                `set_window_icon(...)` value when present, otherwise the built-in
 811                default icon.
 812            min_width: Minimum window width in pixels (default: 640).
 813            min_height: Minimum window height in pixels (default: 480).
 814        """
 815        self._ensure_not_running("start_manual()")
 816        resolved_icon_path = (
 817            icon_path if icon_path is not None else self._window_icon_path
 818        )
 819        self._engine.initialize(
 820            title=title,
 821            width=width,
 822            height=height,
 823            resizable=resizable,
 824            background_color=background_color,
 825            vsync=vsync,
 826            redraw_on_change_only=redraw_on_change_only,
 827            show_fps_in_title=show_fps_in_title,
 828            icon_path=resolved_icon_path,
 829            min_width=min_width,
 830            min_height=min_height,
 831        )
 832        self._runtime_state = _RUNTIME_STATE_MANUAL
 833
 834    def poll_events(self) -> bool:
 835        """
 836        Poll events from the window system.
 837        
 838        Returns:
 839            bool: True if the loop should continue, False if exit requested.
 840        """
 841        should_continue = self._engine.poll_events()
 842        if not should_continue and self._runtime_state in (
 843            _RUNTIME_STATE_MANUAL,
 844            _RUNTIME_STATE_RUNNING_CALLBACK,
 845        ):
 846            self._runtime_state = _RUNTIME_STATE_IDLE
 847        return should_continue
 848
 849    def update(self) -> None:
 850        """Run a single update step."""
 851        self._engine.update()
 852
 853    def render(self) -> None:
 854        """Render a single frame."""
 855        self._engine.render()
 856
 857    def run(
 858        self,
 859        title: str = "PyG Engine",
 860        width: int = 1280,
 861        height: int = 720,
 862        resizable: bool = True,
 863        background_color: Optional[Any] = None,
 864        vsync: bool = True,
 865        redraw_on_change_only: bool = True,
 866        show_fps_in_title: bool = False,
 867        icon_path: Optional[str] = None,
 868        min_width: Optional[int] = None,
 869        min_height: Optional[int] = None,
 870        *,
 871        update: Optional[Callable[..., object]] = None,
 872        max_delta_time: Optional[float] = 0.1,
 873        user_data: Any = None,
 874    ) -> None:
 875        """
 876        Run the engine and start the frame loop.
 877
 878        Default mode (no callback):
 879        - Enter the native blocking loop until close.
 880
 881        Callback mode (`update=...`):
 882        - Start a Python-managed loop and invoke callback once per frame.
 883        - Callback can return `False` or call `context.stop()` to exit.
 884        - See `UpdateContext` for injected values.
 885        - Frame order is: poll events -> native update -> callback -> render.
 886          (Future GameObject script updates are intended to run in native update.)
 887
 888        Raises:
 889            RuntimeError: If the engine is already running in another loop mode.
 890
 891        Args:
 892            title: Window title.
 893            width: Initial window width.
 894            height: Initial window height.
 895            resizable: Whether the window can be resized.
 896            background_color: Optional `pyg_engine.Color`.
 897            vsync: Enable/disable vertical sync.
 898            redraw_on_change_only: When True (default), only redraw on scene changes.
 899            show_fps_in_title: When True, appends current FPS to window title.
 900            icon_path: Optional icon file path. If omitted, uses the most recent
 901                `set_window_icon(...)` value when present, otherwise the built-in
 902                default icon.
 903            min_width: Minimum window width in pixels (default: 640).
 904            min_height: Minimum window height in pixels (default: 480).
 905            update: Optional callback invoked once per frame. When omitted,
 906                the native blocking run loop is used.
 907            max_delta_time: Clamp callback `dt` to this value in seconds.
 908                Only used in callback mode (`update` provided).
 909            user_data: Arbitrary object exposed via callback context.
 910                Only used in callback mode (`update` provided).
 911        """
 912        self._ensure_not_running("run()")
 913
 914        if update is None:
 915            resolved_icon_path = (
 916                icon_path if icon_path is not None else self._window_icon_path
 917            )
 918            self._runtime_state = _RUNTIME_STATE_RUNNING_BLOCKING
 919            try:
 920                self._engine.run(
 921                    title=title,
 922                    width=width,
 923                    height=height,
 924                    resizable=resizable,
 925                    background_color=background_color,
 926                    vsync=vsync,
 927                    redraw_on_change_only=redraw_on_change_only,
 928                    show_fps_in_title=show_fps_in_title,
 929                    icon_path=resolved_icon_path,
 930                    min_width=min_width,
 931                    min_height=min_height,
 932                )
 933            finally:
 934                self._runtime_state = _RUNTIME_STATE_IDLE
 935            return
 936
 937        if max_delta_time is not None and max_delta_time <= 0.0:
 938            raise ValueError("max_delta_time must be > 0.0 or None")
 939
 940        invoke_callback = _compile_update_callback(update)
 941
 942        self.start_manual(
 943            title=title,
 944            width=width,
 945            height=height,
 946            resizable=resizable,
 947            background_color=background_color,
 948            vsync=vsync,
 949            redraw_on_change_only=redraw_on_change_only,
 950            show_fps_in_title=show_fps_in_title,
 951            icon_path=icon_path,
 952            min_width=min_width,
 953            min_height=min_height,
 954        )
 955        self._runtime_state = _RUNTIME_STATE_RUNNING_CALLBACK
 956
 957        context = UpdateContext(self, user_data=user_data)
 958
 959        native_engine = self._engine
 960        poll_events = native_engine.poll_events
 961        update_step = native_engine.update
 962        render_frame = native_engine.render
 963
 964        try:
 965            while True:
 966                if not poll_events():
 967                    break
 968
 969                # Update native systems first so callback gets current dt/input.
 970                update_step()
 971
 972                context.delta_time = native_engine.delta_time
 973                if max_delta_time is not None and context.delta_time > max_delta_time:
 974                    context.delta_time = max_delta_time
 975                context.elapsed_time = native_engine.elapsed_time
 976
 977                callback_result = invoke_callback(context)
 978                if callback_result is False or context._should_stop:
 979                    break
 980
 981                render_frame()
 982                context.frame += 1
 983        finally:
 984            self._runtime_state = _RUNTIME_STATE_IDLE
 985
 986    def add_game_object(self, game_object: Any) -> Optional[int]:
 987        """
 988        Add a `pyg_engine.GameObject` to the runtime scene.
 989
 990        Returns:
 991            The runtime object id, or None if add failed.
 992        """
 993        return self._engine.add_game_object(game_object)
 994
 995    def create_game_object(self, name: Optional[str] = None) -> Optional[int]:
 996        """
 997        Create and add a runtime GameObject.
 998
 999        Returns:
1000            The runtime object id, or None if creation failed.
1001        """
1002        return self._engine.create_game_object(name)
1003
1004    def remove_game_object(self, object_id: int) -> None:
1005        """Remove a runtime GameObject by id."""
1006        self._engine.remove_game_object(object_id)
1007
1008    def set_game_object_position(self, object_id: int, position: Any) -> bool:
1009        """
1010        Update a runtime GameObject position by id.
1011
1012        Returns:
1013            True if the object exists and was updated, False otherwise.
1014        """
1015        return self._engine.set_game_object_position(object_id, position)
1016
1017    @property
1018    def camera_object_id(self) -> Optional[int]:
1019        """Get the runtime id of the active camera GameObject."""
1020        return self._engine.camera_object_id()
1021
1022    def get_camera_position(self) -> Any:
1023        """Get the active camera world position."""
1024        return self._engine.get_camera_position()
1025
1026    def set_camera_position(self, position: Any) -> bool:
1027        """Set the active camera world position."""
1028        return self._engine.set_camera_position(position)
1029
1030    def get_camera_viewport_size(self) -> tuple[float, float]:
1031        """Get the active camera viewport size in world units."""
1032        return self._engine.get_camera_viewport_size()
1033
1034    def set_camera_viewport_size(self, width: float, height: float) -> bool:
1035        """Set the active camera viewport size in world units."""
1036        return self._engine.set_camera_viewport_size(width, height)
1037
1038    def get_camera_aspect_mode(self) -> str:
1039        """Get the camera aspect handling mode."""
1040        return self._engine.get_camera_aspect_mode()
1041
1042    def set_camera_aspect_mode(self, mode: str) -> bool:
1043        """Set the camera aspect handling mode."""
1044        return self._engine.set_camera_aspect_mode(mode)
1045
1046    def set_camera_background_color(self, color: Any) -> None:
1047        """Set the active camera background clear color."""
1048        self._engine.set_camera_background_color(color)
1049
1050    def get_camera_background_color(self) -> Any:
1051        """Get the active camera background clear color."""
1052        return self._engine.get_camera_background_color()
1053
1054    def world_to_screen(self, world_position: Any) -> tuple[float, float]:
1055        """Convert world-space coordinates to screen-space pixel coordinates."""
1056        return self._engine.world_to_screen(world_position)
1057
1058    def screen_to_world(self, screen_x: float, screen_y: float) -> Any:
1059        """Convert screen-space pixel coordinates to world-space coordinates."""
1060        return self._engine.screen_to_world(screen_x, screen_y)
1061
1062    def clear_draw_commands(self) -> None:
1063        """Clear all immediate-mode drawing commands."""
1064        self._engine.clear_draw_commands()
1065
1066    def add_draw_commands(self, commands: list[Any]) -> None:
1067        """Submit many draw commands in one call."""
1068        self._engine.add_draw_commands(commands)
1069
1070    def draw_pixel(
1071        self,
1072        x: int,
1073        y: int,
1074        color: Any,
1075        draw_order: float = 0.0,
1076    ) -> None:
1077        """Draw a pixel in window coordinates."""
1078        self._engine.draw_pixel(x, y, color, draw_order=draw_order)
1079
1080    def draw_line(
1081        self,
1082        start_x: float,
1083        start_y: float,
1084        end_x: float,
1085        end_y: float,
1086        color: Any,
1087        thickness: float = 1.0,
1088        draw_order: float = 0.0,
1089    ) -> None:
1090        """Draw a line in window coordinates."""
1091        self._engine.draw_line(
1092            start_x,
1093            start_y,
1094            end_x,
1095            end_y,
1096            color,
1097            thickness=thickness,
1098            draw_order=draw_order,
1099        )
1100
1101    def draw_rectangle(
1102        self,
1103        x: float,
1104        y: float,
1105        width: float,
1106        height: float,
1107        color: Any,
1108        filled: bool = True,
1109        thickness: float = 1.0,
1110        draw_order: float = 0.0,
1111    ) -> None:
1112        """Draw a rectangle in window coordinates."""
1113        self._engine.draw_rectangle(
1114            x,
1115            y,
1116            width,
1117            height,
1118            color,
1119            filled=filled,
1120            thickness=thickness,
1121            draw_order=draw_order,
1122        )
1123
1124    def draw_circle(
1125        self,
1126        center_x: float,
1127        center_y: float,
1128        radius: float,
1129        color: Any,
1130        filled: bool = True,
1131        thickness: float = 1.0,
1132        segments: int = 32,
1133        draw_order: float = 0.0,
1134    ) -> None:
1135        """Draw a circle in window coordinates."""
1136        self._engine.draw_circle(
1137            center_x,
1138            center_y,
1139            radius,
1140            color,
1141            filled=filled,
1142            thickness=thickness,
1143            segments=segments,
1144            draw_order=draw_order,
1145        )
1146
1147    def draw_gradient_rect(
1148        self,
1149        x: float,
1150        y: float,
1151        width: float,
1152        height: float,
1153        top_left: Any,
1154        bottom_left: Any,
1155        bottom_right: Any,
1156        top_right: Any,
1157        draw_order: float = 0.0,
1158    ) -> None:
1159        """Draw a gradient rectangle with per-corner colors."""
1160        self._engine.draw_gradient_rect(
1161            x,
1162            y,
1163            width,
1164            height,
1165            top_left,
1166            bottom_left,
1167            bottom_right,
1168            top_right,
1169            draw_order=draw_order,
1170        )
1171
1172    def draw_image(
1173        self,
1174        x: float,
1175        y: float,
1176        width: float,
1177        height: float,
1178        texture_path: str,
1179        draw_order: float = 0.0,
1180    ) -> None:
1181        """Draw an image from a file path."""
1182        self._engine.draw_image(
1183            x,
1184            y,
1185            width,
1186            height,
1187            texture_path,
1188            draw_order=draw_order,
1189        )
1190
1191    def draw_image_from_bytes(
1192        self,
1193        x: float,
1194        y: float,
1195        width: float,
1196        height: float,
1197        texture_key: str,
1198        rgba: bytes,
1199        texture_width: int,
1200        texture_height: int,
1201        draw_order: float = 0.0,
1202    ) -> None:
1203        """Draw an image from raw RGBA bytes."""
1204        self._engine.draw_image_from_bytes(
1205            x,
1206            y,
1207            width,
1208            height,
1209            texture_key,
1210            rgba,
1211            texture_width,
1212            texture_height,
1213            draw_order=draw_order,
1214        )
1215
1216    def draw_text(
1217        self,
1218        text: str,
1219        x: float,
1220        y: float,
1221        color: Any,
1222        font_size: float = 24.0,
1223        font_path: Optional[str] = None,
1224        letter_spacing: float = 0.0,
1225        line_spacing: float = 0.0,
1226        draw_order: float = 0.0,
1227    ) -> None:
1228        """
1229        Draw text in window coordinates.
1230
1231        By default, this uses the engine's built-in open-source font.
1232        Provide `font_path` to use a custom TTF/OTF font file.
1233        """
1234        self._engine.draw_text(
1235            text,
1236            x,
1237            y,
1238            color,
1239            font_size=font_size,
1240            font_path=font_path,
1241            letter_spacing=letter_spacing,
1242            line_spacing=line_spacing,
1243            draw_order=draw_order,
1244        )
1245    
1246    @property
1247    def version(self) -> str:
1248        """
1249        Get the engine version.
1250        
1251        Returns:
1252            The version string (e.g., "1.2.0").
1253        """
1254        return self._engine.version
1255
1256    @property
1257    def delta_time(self) -> float:
1258        """Get the time since the last frame in seconds."""
1259        return self._engine.delta_time
1260
1261    @property
1262    def elapsed_time(self) -> float:
1263        """Get the total elapsed time in seconds since the engine started."""
1264        return self._engine.elapsed_time