@rb-games/core 0.1.0

package/dist/plugins/resource/ResourcePlugin.d.ts

@@ -0,0 +1,189 @@
+import { PixiEngine } from '../../engine/PixiEngine';
+import type { EnginePlugin } from '../Plugin.types';
+import '@esotericsoftware/spine-pixi-v8';
+import type { ResourcePluginConfig, LoadingProgress } from './ResourcePlugin.types';
+/**
+ * Asset loading and management plugin for PixiJS games.
+ *
+ * ResourcePlugin manages game assets with automatic resolution selection,
+ * platform-specific loading, and priority-based strategies. It uses PixiJS
+ * native features (isMobile, detectWebp) for device detection.
+ *
+ * ## Features
+ *
+ * - **Automatic Resolution Selection**: Based on devicePixelRatio
+ * - **Platform-Specific Assets**: Desktop vs mobile asset variants
+ * - **Priority-Based Loading**: Critical, high, medium, low priority bundles
+ * - **Lazy Loading**: Load assets on-demand
+ * - **WebP Support**: Automatic WebP format detection
+ * - **Font Loading**: Integrated font asset management
+ * - **Progress Tracking**: Per-bundle loading progress callbacks
+ *
+ * ## Asset Resolution Strategy
+ *
+ * Assets are organized in directories with resolution variants:
+ * ```
+ * /assets/graphics/
+ *   package-name/
+ *     package-name-0@0.25x.webp.json  // Low quality
+ *     package-name-0@0.5x.webp.json   // Medium quality
+ *     package-name-0@1x.webp.json     // High quality
+ *     package-name-0@2x.webp.json     // Ultra quality
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const resourcePlugin = new ResourcePlugin({
+ *   basePath: '/assets/graphics/',
+ *   devicePixelRatio: window.devicePixelRatio,
+ *   bundles: [
+ *     {
+ *       name: 'ui',
+ *       packages: ['buttons', 'icons'],
+ *       priority: 0  // Critical
+ *     },
+ *     {
+ *       name: 'game',
+ *       packages: ['symbols', 'backgrounds'],
+ *       priority: 1,  // High
+ *       isLazy: false
+ *     }
+ *   ]
+ * });
+ *
+ * engine.registerPlugin(resourcePlugin);
+ * await engine.initialize();
+ *
+ * // Load critical assets
+ * await resourcePlugin.loadCriticalAssets();
+ *
+ * // Load all non-lazy bundles
+ * await resourcePlugin.preloadAssets();
+ * ```
+ *
+ * @category Plugins
+ * @public
+ */
+export declare class ResourcePlugin implements EnginePlugin {
+    name: string;
+    priority: number;
+    dependencies: string[];
+    private config;
+    private engine;
+    private isInitialized;
+    private bundleStates;
+    private manifest;
+    private resolution;
+    private resolutionSuffix;
+    private textureFormat;
+    /** Sound alias -> channel mapping collected from bundle configs */
+    private _soundChannelMappings;
+    constructor(config: ResourcePluginConfig);
+    initialize(engine: PixiEngine): Promise<void>;
+    onReady(engine: PixiEngine): void;
+    /**
+     * Calculates optimal asset resolution based on device screen size and DPR.
+     * Uses diagonal ratio between device physical resolution and design resolution (1920x1080).
+     *
+     * Formula: requiredScale = deviceDiagonal / designDiagonal
+     *
+     * Strategy:
+     * - Mobile: Round DOWN to nearest available resolution (performance priority)
+     * - Desktop: Round UP to nearest available resolution (quality priority)
+     *
+     * @param dpr - Device pixel ratio
+     * @param platform - 'mobile' or 'desktop'
+     * @param forceResolution - Optional forced scale value (bypasses diagonal calculation)
+     */
+    private calculateOptimalResolution;
+    isReady(): boolean;
+    cleanup(): void;
+    /**
+     * Check if a package config is a Spine package
+     */
+    private isSpinePackage;
+    /**
+     * Check if a package config is a Sound package
+     */
+    private isSoundPackage;
+    private generateManifest;
+    /**
+     * Check if a package should be loaded on current platform
+     */
+    private shouldLoadPackage;
+    /**
+     * Generate asset URL based on resolution support and texture format.
+     */
+    private generateAssetURL;
+    /**
+     * Generate Spine asset URLs (skeleton + atlas) with resolution support.
+     *
+     * @param pkg - Spine package configuration
+     * @returns Array of AssetItems for skeleton and atlas, or null if platform doesn't match
+     */
+    private generateSpineAssets;
+    /**
+     * Generate Sound asset URL with format fallback support.
+     *
+     * @param pkg - Sound package configuration
+     * @returns AssetItem for the sound, or null if platform doesn't match
+     */
+    private generateSoundAsset;
+    /**
+     * Returns sound alias -> channel mappings collected from bundle configs.
+     */
+    get soundChannelMappings(): ReadonlyMap<string, string>;
+    private initializePixiAssets;
+    /**
+     * Loads a specific asset bundle.
+     *
+     * @param bundleName - Name of the bundle to load
+     * @param onProgress - Optional progress callback
+     * @throws Error if bundle not found
+     *
+     * @example
+     * ```typescript
+     * await resourcePlugin.loadBundle('ui', (progress) => {
+     *   console.log(`Loading: ${progress.percentage}%`);
+     * });
+     * ```
+     */
+    loadBundle(bundleName: string, onProgress?: (progress: LoadingProgress) => void, globalContext?: {
+        bundleIndex: number;
+        totalBundles: number;
+    }): Promise<void>;
+    /**
+     * Loads all critical priority assets (priority 0).
+     *
+     * Should be called during initial loading screen before game starts.
+     *
+     * @param onProgress - Optional progress callback
+     */
+    loadCriticalAssets(onProgress?: (progress: LoadingProgress) => void): Promise<void>;
+    /**
+     * Preloads all non-lazy bundles.
+     *
+     * Loads all bundles that are not marked as lazy, typically called
+     * after critical assets are loaded.
+     *
+     * @param onProgress - Optional progress callback
+     */
+    preloadAssets(onProgress?: (progress: LoadingProgress) => void): Promise<void>;
+    /**
+     * Checks if a bundle has been loaded.
+     *
+     * @param bundleName - Name of the bundle
+     * @returns True if loaded, false otherwise
+     */
+    isBundleLoaded(bundleName: string): boolean;
+    /**
+     * Returns the count of critical bundles (priority 0).
+     */
+    getCriticalBundleCount(): number;
+    /**
+     * Returns the count of non-lazy bundles to preload.
+     */
+    getPreloadBundleCount(): number;
+    [key: symbol]: any;
+}
+//# sourceMappingURL=ResourcePlugin.d.ts.map

package/dist/plugins/resource/ResourcePlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourcePlugin.d.ts","sourceRoot":"","sources":["../../../plugins/resource/ResourcePlugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAIpD,OAAO,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,oBAAoB,EAGpB,eAAe,EAKhB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,cAAe,YAAW,YAAY;IAC1C,IAAI,EAAE,MAAM,CAAoB;IAChC,QAAQ,EAAE,MAAM,CAAM;IACtB,YAAY,EAAE,MAAM,EAAE,CAAM;IAEnC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,aAAa,CAAS;IAG9B,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,UAAU,CAAe;IACjC,OAAO,CAAC,gBAAgB,CAAU;IAClC,OAAO,CAAC,aAAa,CAAwB;IAE7C,mEAAmE;IACnE,OAAO,CAAC,qBAAqB,CAAkC;gBAEnD,MAAM,EAAE,oBAAoB;IAW3B,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BnD,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAIxC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,0BAA0B;IAqD3B,OAAO,IAAI,OAAO;IAIlB,OAAO,IAAI,IAAI;IAQtB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,gBAAgB;IA6ExB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAoC3B;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;OAEG;IACH,IAAW,oBAAoB,IAAI,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAE7D;IAED,OAAO,CAAC,oBAAoB;IAoB5B;;;;;;;;;;;;;OAaG;IACU,UAAU,CACrB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,EAChD,aAAa,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,IAAI,CAAC;IA+ChB;;;;;;OAMG;IACU,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhG;;;;;;;OAOG;IACU,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3F;;;;;OAKG;IACI,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAKlD;;OAEG;IACI,sBAAsB,IAAI,MAAM;IAKvC;;OAEG;IACI,qBAAqB,IAAI,MAAM;IAKtC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB"}

package/dist/plugins/resource/ResourcePlugin.types.d.ts

@@ -0,0 +1,153 @@
+import type { PluginConfig } from '../Plugin.types';
+/**
+ * Supported texture formats for asset loading.
+ */
+export type TextureFormat = 'png' | 'webp' | 'avif';
+/**
+ * Configuration for an asset package within a bundle.
+ *
+ * Allows fine-grained control over package loading behavior including
+ * resolution support and platform targeting.
+ *
+ * @public
+ */
+export interface PackageConfig {
+    /** Package name (must match directory name) */
+    name: string;
+    /** Whether package has resolution variants (default: true) */
+    hasResolutions?: boolean;
+    /** Optional alias override for asset loading */
+    alias?: string;
+    /** Target platform for this package (default: 'both') */
+    platform?: 'desktop' | 'mobile' | 'both';
+}
+/**
+ * Sound channel types for audio categorization.
+ *
+ * @public
+ */
+export type SoundChannel = 'music' | 'voice' | 'sfx' | 'ui';
+/**
+ * Configuration for a sound package.
+ *
+ * @public
+ */
+export interface SoundPackageConfig {
+    /** Sound file name (without extension) */
+    name: string;
+    /** Must be 'sound' to identify as sound package */
+    type: 'sound';
+    /** Optional alias override for asset loading */
+    alias?: string;
+    /** Direct source path with format pattern e.g. 'ambiance.{ogg,mp3}' */
+    src?: string;
+    /** Channel assignment for SoundPlugin */
+    channel?: SoundChannel;
+    /** Target platform for this package (default: 'both') */
+    platform?: 'desktop' | 'mobile' | 'both';
+}
+/**
+ * Configuration for a Spine animation package.
+ *
+ * @public
+ */
+export interface SpinePackageConfig {
+    /** Package name (must match Spine export name) */
+    name: string;
+    /** Must be 'spine' to identify as Spine package */
+    type: 'spine';
+    /** Optional alias override for asset loading */
+    alias?: string;
+    /** Whether package has resolution variants (default: true) */
+    hasResolutions?: boolean;
+    /** Skeleton file format: 'skel' (binary) or 'json' (default: 'skel') */
+    skeletonFormat?: 'skel' | 'json';
+    /** Target platform for this package (default: 'both') */
+    platform?: 'desktop' | 'mobile' | 'both';
+}
+/**
+ * Asset bundle configuration.
+ *
+ * Bundles group related assets together for efficient loading.
+ * Supports priority-based loading and lazy loading.
+ *
+ * @public
+ */
+export interface AssetBundle {
+    name: string;
+    packages: (string | PackageConfig | SpinePackageConfig | SoundPackageConfig)[];
+    path?: string;
+    priority?: number;
+    isLazy?: boolean;
+}
+export interface AssetPackage {
+    type: 'spritesheet' | 'spine-skel' | 'spine-data' | 'spine-atlas' | 'font';
+    name: string;
+    alias?: string;
+}
+export interface AssetItem {
+    alias: string;
+    src: string;
+    data?: any;
+    preferred?: number;
+}
+export interface AssetManifestEntry {
+    name: string;
+    assets: AssetItem[];
+    priority?: number;
+}
+/**
+ * Configuration for ResourcePlugin.
+ *
+ * Defines asset bundles and loading strategies. ResourcePlugin automatically
+ * detects device capabilities using PixiJS native features (isMobile, detectWebp)
+ * and calculates optimal asset resolution based on devicePixelRatio.
+ *
+ * @public
+ */
+export interface ResourcePluginConfig extends PluginConfig {
+    /** Base path for asset loading (default: '/assets/graphics/') */
+    basePath?: string;
+    /** Base path for Spine assets (default: '/assets/spine/') */
+    spineBasePath?: string;
+    /** Base path for sound assets (default: '/assets/sounds/') */
+    audioBasePath?: string;
+    /** Asset bundles to load */
+    bundles: AssetBundle[];
+    /** Available resolution scales for assets (default: [0.25, 0.5, 1.0, 2.0]) */
+    availableResolutions?: number[];
+    /** Force specific resolution, bypassing automatic calculation */
+    forceResolution?: number;
+    /** Available texture formats in the game (default: ['png', 'webp']) */
+    availableTextureFormats?: TextureFormat[];
+    /** Font assets to load */
+    fonts?: FontAsset[];
+}
+export interface LoadingProgress {
+    bundleName: string;
+    loaded: number;
+    total: number;
+    percentage: number;
+    globalPercentage: number;
+    bundleIndex: number;
+    totalBundles: number;
+}
+export interface AssetBundleState {
+    name: string;
+    status: 'pending' | 'loading' | 'loaded' | 'error';
+    priority: number;
+    assets: AssetItem[];
+    error?: Error;
+}
+export type LoadPriority = 0 | 1 | 2 | 3;
+export interface FontAsset {
+    alias: string;
+    src: string;
+    data?: {
+        family: string;
+        weights?: string[];
+        style?: string;
+        display?: string;
+    };
+}
+//# sourceMappingURL=ResourcePlugin.types.d.ts.map

package/dist/plugins/resource/ResourcePlugin.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResourcePlugin.types.d.ts","sourceRoot":"","sources":["../../../plugins/resource/ResourcePlugin.types.ts"],"names":[],"mappings":"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"}

package/dist/plugins/resource/index.d.ts

@@ -0,0 +1,3 @@
+export { ResourcePlugin } from './ResourcePlugin';
+export type { ResourcePluginConfig, AssetBundle, AssetPackage, AssetItem, AssetManifestEntry, AssetBundleState, LoadingProgress, LoadPriority } from './ResourcePlugin.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/resource/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../plugins/resource/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACR,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACf,MAAM,wBAAwB,CAAC"}

package/dist/plugins/scene/Scene.d.ts

@@ -0,0 +1,203 @@
+import { Container } from 'pixi.js';
+import { PixiEngine } from '../../engine';
+/**
+ * Abstract base class for all game scenes.
+ *
+ * Scene provides a structured lifecycle for game screens (menus, gameplay, etc.).
+ * Extends PixiJS Container, so all display objects can be added as children.
+ *
+ * ## Lifecycle Methods
+ *
+ * 1. **onInitialize()** - Called once when scene is first entered
+ * 2. **onEnter()** - Called every time scene becomes active (async, for animations)
+ * 3. **update()** - Called every frame while scene is active
+ * 4. **onResize()** - Called when window is resized
+ * 5. **onExit()** - Called when leaving scene (async, for exit animations)
+ * 6. **cleanup()** - Called after exit for resource cleanup
+ *
+ * ## Usage Pattern
+ *
+ * 1. Create a class extending Scene
+ * 2. Override lifecycle methods as needed
+ * 3. Register scene with ScenePlugin
+ * 4. Switch to scene using ScenePlugin.switchScene()
+ *
+ * @example
+ * ```typescript
+ * class MainMenuScene extends Scene {
+ *   private logo: Sprite;
+ *
+ *   constructor() {
+ *     super('MainMenu');
+ *   }
+ *
+ *   protected onInitialize(): void {
+ *     // Create UI elements
+ *     this.logo = new Sprite(texture);
+ *     this.addChild(this.logo);
+ *   }
+ *
+ *   protected async onEnter(): Promise<void> {
+ *     // Fade in animation
+ *     await gsap.to(this, { alpha: 1, duration: 0.5 });
+ *   }
+ *
+ *   public update(deltaTime: number): void {
+ *     // Update logic
+ *     this.logo.rotation += deltaTime * 0.001;
+ *   }
+ *
+ *   protected async onExit(): Promise<void> {
+ *     // Fade out animation
+ *     await gsap.to(this, { alpha: 0, duration: 0.3 });
+ *   }
+ *
+ *   protected cleanup(): void {
+ *     // Clean up resources
+ *     this.logo.destroy();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class Scene extends Container {
+    sceneName: string;
+    protected engine: PixiEngine;
+    constructor(sceneName: string);
+    /**
+     * Sets the engine reference.
+     *
+     * Called automatically by ScenePlugin when scene is registered.
+     *
+     * @param engine - PixiEngine instance
+     * @internal
+     */
+    setEngine(engine: PixiEngine): void;
+    /**
+     * Enters the scene.
+     *
+     * Calls onInitialize() and onEnter() in sequence.
+     * Called automatically by ScenePlugin when switching to this scene.
+     *
+     * @param params - Optional parameters passed from switchScene()
+     * @internal
+     */
+    enter(params?: unknown): Promise<void>;
+    /**
+     * Exits the scene.
+     *
+     * Calls onExit() and cleanup() in sequence.
+     * Called automatically by ScenePlugin when switching away from this scene.
+     *
+     * @internal
+     */
+    exit(): Promise<void>;
+    /**
+     * Initializes the scene.
+     *
+     * Called once when the scene is first entered.
+     * Override to create UI elements and set up initial state.
+     *
+     * @example
+     * ```typescript
+     * protected onInitialize(): void {
+     *   this.background = new Sprite(bgTexture);
+     *   this.addChild(this.background);
+     * }
+     * ```
+     */
+    protected onInitialize(): Promise<void>;
+    /**
+     * Called when the scene becomes active.
+     *
+     * Override to implement entry animations.
+     * This method is async, so you can await animations.
+     *
+     * @param _params - Optional parameters passed from switchScene()
+     *
+     * @example
+     * ```typescript
+     * protected async onEnter(params?: { level: number }): Promise<void> {
+     *   this.alpha = 0;
+     *   if (params) {
+     *     this.level = params.level;
+     *   }
+     *   await gsap.to(this, { alpha: 1, duration: 0.5 });
+     * }
+     * ```
+     */
+    protected onEnter(_params?: unknown): Promise<void>;
+    /**
+     * Called when leaving the scene.
+     *
+     * Override to implement exit animations.
+     * This method is async, so you can await animations.
+     *
+     * @example
+     * ```typescript
+     * protected async onExit(): Promise<void> {
+     *   await gsap.to(this, { alpha: 0, duration: 0.3 });
+     * }
+     * ```
+     */
+    protected onExit(): Promise<void>;
+    /**
+     * Cleans up scene resources.
+     *
+     * Called after onExit() when the scene is removed.
+     * Override to destroy textures, remove event listeners, etc.
+     *
+     * @example
+     * ```typescript
+     * protected cleanup(): void {
+     *   this.background.destroy();
+     *   this.removeAllListeners();
+     * }
+     * ```
+     */
+    protected cleanup(): void;
+    /**
+     * Updates the scene every frame.
+     *
+     * Override to implement per-frame logic like animations,
+     * physics, or input handling.
+     *
+     * @param _deltaTime - Time elapsed since last frame in milliseconds
+     *
+     * @example
+     * ```typescript
+     * public update(deltaTime: number): void {
+     *   this.player.x += this.velocity * deltaTime;
+     *   this.checkCollisions();
+     * }
+     * ```
+     */
+    update(_deltaTime: number): void;
+    /**
+     * Called when the window is resized.
+     *
+     * Override to reposition or scale UI elements.
+     *
+     * @param _width - New window width
+     * @param _height - New window height
+     *
+     * @example
+     * ```typescript
+     * public onResize(width: number, height: number): void {
+     *   this.background.width = width;
+     *   this.background.height = height;
+     *   this.centerLogo(width, height);
+     * }
+     * ```
+     */
+    onResize(_width: number, _height: number): void;
+    /**
+     * Get the stage (root container) by traversing up the parent chain.
+     * Useful for attaching global event listeners.
+     *
+     * @returns The stage container or null if not attached to stage
+     */
+    getStage(): Container | null;
+}
+//# sourceMappingURL=Scene.d.ts.map

package/dist/plugins/scene/Scene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scene.d.ts","sourceRoot":"","sources":["../../../plugins/scene/Scene.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,8BAAsB,KAAM,SAAQ,SAAS;IAGxB,SAAS,EAAE,MAAM;IAFpC,SAAS,CAAC,MAAM,EAAG,UAAU,CAAC;gBAEX,SAAS,EAAE,MAAM;IAMpC;;;;;;;OAOG;IACI,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAI1C;;;;;;;;OAQG;IACU,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD;;;;;;;OAOG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKlC;;;;;;;;;;;;;OAaG;cACa,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7C;;;;;;;;;;;;;;;;;;OAkBG;cACa,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzD;;;;;;;;;;;;OAYG;cACa,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAKvC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,OAAO,IAAI,IAAI;IAIzB;;;;;;;;;;;;;;;OAeG;IACI,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAMvC;;;;;;;;;;;;;;;;OAgBG;IACI,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKtD;;;;;OAKG;IACI,QAAQ,IAAI,SAAS,GAAG,IAAI;CASpC"}