Rusfort/Asset-Frameworker
1
0
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects 3 Releases Wiki Activity
Asset-Frameworker/Documentation/02_Developer_Guide/01_Architecture.md

6.9 KiB
Raw Blame History

Developer Guide: Architecture

This document provides a high-level overview of the Asset Processor Tool's architecture and core components for developers.

High-Level Architecture

The Asset Processor Tool is designed to process 3D asset source files into a standardized library format. Its high-level architecture consists of:

  1. Core Processing Engine (processing_engine.py): The primary component responsible for executing the asset processing pipeline for a single input asset based on a provided SourceRule object and static configuration. The older asset_processor.py remains in the codebase for reference but is no longer used in the main processing flow.
  2. Configuration System (Configuration): Handles loading core settings (including centralized type definitions) and merging them with supplier-specific rules defined in JSON presets and the persistent config/suppliers.json file.
  3. Multiple Interfaces: Provides different ways to interact with the tool:
    • Graphical User Interface (GUI)
    • Command-Line Interface (CLI)
    • Directory Monitor for automated processing. The GUI now acts as the primary source of truth for processing rules, generating and managing the SourceRule hierarchy before sending it to the processing engine. It also accumulates prediction results from multiple input sources before updating the view. The CLI and Monitor interfaces can also generate SourceRule objects to bypass the GUI for automated workflows.
  4. Optional Integration: Includes scripts and logic for integrating with external software, specifically Blender, to automate material and node group creation.

Hierarchical Rule System

A key addition to the architecture is the Hierarchical Rule System, which provides a dynamic layer of configuration that can override the static settings loaded from presets. This system is represented by a hierarchy of rule objects: SourceRule, AssetRule, and FileRule.

  • SourceRule: Represents rules applied at the top level, typically corresponding to an entire input source (e.g., a ZIP file or folder).
  • AssetRule: Represents rules applied to a specific asset within a source (a source can contain multiple assets).
  • FileRule: Represents rules applied to individual files within an asset.

This hierarchy allows for fine-grained control over processing parameters. The GUI's prediction logic generates this hierarchy with initial predicted values for overridable fields based on presets and file analysis. The processing engine then operates solely on the explicit values provided in this SourceRule object and static configuration, without internal prediction or fallback logic.

Core Components

  • config/app_settings.json: Defines core, global settings, constants, and centralized definitions for allowed asset and file types (ASSET_TYPE_DEFINITIONS, FILE_TYPE_DEFINITIONS), including metadata like colors and descriptions. This replaces the old config.py file.
  • config/suppliers.json: A persistent JSON file storing known supplier names for GUI auto-completion.
  • Presets/*.json: Supplier-specific JSON files defining rules for file interpretation and initial prediction.
  • configuration.py (Configuration class): Loads config/app_settings.json settings and merges them with a selected preset, pre-compiling regex patterns for efficiency. This static configuration is used by the processing engine.
  • rule_structure.py: Defines the SourceRule, AssetRule, and FileRule dataclasses used to represent the hierarchical processing rules.
  • gui/: Directory containing modules for the Graphical User Interface (GUI), built with PySide6. The GUI is responsible for generating and managing the SourceRule hierarchy via the Unified View, accumulating prediction results, and interacting with background handlers (ProcessingHandler, PredictionHandler).
    • unified_view_model.py: Implements the QAbstractItemModel for the Unified Hierarchical View, holding the SourceRule data, handling inline editing (including direct model restructuring for target_asset_name_override), and managing row coloring based on config definitions.
    • delegates.py: Contains custom QStyledItemDelegate implementations for inline editing in the Unified View, including the new SupplierSearchDelegate for supplier name auto-completion and management.
    • prediction_handler.py: Generates the initial SourceRule hierarchy with predicted values for a single input source based on its files and the selected preset. It uses the "standard_type" from the configuration's FILE_TYPE_DEFINITIONS to populate FileRule.standard_map_type and implements a two-pass classification logic to handle and prioritize bit-depth variants (e.g., _DISP16_ vs _DISP_).
    • processing_engine.py (ProcessingEngine class): The new core component that executes the processing pipeline for a single SourceRule object using the static Configuration. A new instance is created per task for state isolation. It contains no internal prediction or fallback logic. Supplier overrides from the GUI are correctly preserved and used by the engine for output path generation and metadata.
  • asset_processor.py (AssetProcessor class): The older processing engine, kept for reference but not used in the main processing flow.
  • main.py: The entry point for the Command-Line Interface (CLI). It handles argument parsing, logging, parallel processing orchestration, and triggering Blender scripts. It now orchestrates processing by passing SourceRule objects to the ProcessingEngine.
  • monitor.py: Implements the directory monitoring feature using watchdog.
  • blenderscripts/: Contains Python scripts designed to be executed within Blender for post-processing tasks.

Processing Pipeline (Simplified)

The primary processing engine (processing_engine.py) executes a series of steps for each asset based on the provided SourceRule object and static configuration:

  1. Extraction of input to a temporary workspace.
  2. Classification of files (map, model, extra, ignored, unrecognised) using preset rules.
  3. Determination of base metadata (asset name, category, archetype).
  4. Skip check if output exists and overwrite is not forced.
  5. Processing of maps (resize, format/bit depth conversion, inversion, stats calculation).
  6. Merging of channels based on rules.
  7. Generation of metadata.json file.
  8. Organization of processed files into the final output structure.
  9. Cleanup of the temporary workspace.
  10. (Optional) Execution of Blender scripts for post-processing.

This architecture allows for a modular design, separating configuration, rule generation/management (primarily in the GUI), and core processing execution. The SourceRule object serves as a clear data contract between the GUI/prediction layer and the processing engine. Parallel processing is utilized for efficiency, and background threads keep the GUI responsive.