# ferryyoungfan/virtualcockroach architecture

> Architecture diagram of the GitHub repository ferryyoungfan/virtualcockroach, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ferryyoungfan/virtualcockroach
- Repository: https://github.com/ferryyoungfan/virtualcockroach

## Overview

##### Project type and purpose
- This is a standalone desktop “pet” application built on the Adobe Air (Flash) runtime.
- Purpose: display and animate a virtual cockroach on the user’s Windows or macOS desktop, with interactive modules (feeding, roaming, shop, animations), system tray integration, and packaged for distribution as both .air and self-contained .exe/.zip.

##### File structure
- Top-level assets & source:
- VirtualCockroach.fla – the master Flash project containing code (ActionScript), timelines, UI layouts.
- Releases folder:
- Release_成品发布/Mac_Win_AirPack/*.air – Adobe-Air installer packages for both platforms.
- Release_成品发布/WinX86_exe_zip/*.zip / .exe – self-contained Windows executables and zipped versions.
- Historical versions in __Old__ for traceability.
- No separate backend or database directories—this is entirely client-side.
- Build/deployment is via Adobe Air SDK or the Flash IDE’s packaging tools.

##### README for additional insights
- Confirms use of Adobe Air, highlights features added over versions (tray menu, shop, animations, localization, bug fixes).
- No external web services or backend APIs—purely local desktop integration.
- Versioning and distribution methods (.air vs .exe) must be represented.

##### Main components & interactions
a. Components
1. Development environment
– Flash IDE / Adobe Animate + AIR SDK
– Source FLA files & asset library
2. Build/packaging pipeline
– AIR compiler
– .air package generator
– Captive runtime packager for Windows .exe/.zip
3. Runtime environment
– Adobe AIR runtime (captive or standalone)
4. Application modules inside AIR
– UI layer (window, animations, context menus)
– Behavior engine (roaming AI, feeding logic, shop logic, easter-egg triggers)
5. User Desktop
– OS-level interactions: system tray, window manager, user input (clicks, drag)
b. Relationships & data flow
- User ↔ AIR Runtime: input events flow into the UI layer.
- UI layer ↔ Behavior engine: UI triggers behavior modules (e.g., feed action).
- Behavior engine ↔ Asset manager: requests sprites/animations.
- Build pipeline → outputs → end user: packaging transforms FLA → .swf + descriptor → .air/.exe → installation
c. Architectural patterns/design principles
– Modular separation: UI vs. logic vs. asset management vs. system integration
– Single runtime host (Adobe AIR) encapsulates all modules
– Packaging pipeline decoupled from runtime logic
d. Key technologies/frameworks
– Adobe Flash/Animate (FLA for authoring, ActionScript 3)
– Adobe AIR (XML descriptor, captive runtime packaging)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Development Environment
    subgraph "Development Environment"
        direction TB
        Flash_IDE["Flash IDE / Adobe Animate"]:::dev
        AIR_SDK["AIR SDK"]:::dev
        VirtualCockroach_fla["VirtualCockroach.fla"]:::dev
        icon_fla["icon.fla"]:::dev
        Source_iconPack["Source_iconPack/"]:::dev
        VirtualCockroach_appxml["VirtualCockroach-app.xml"]:::dev
    end

    %% Build / Packaging Pipeline
    subgraph "Build / Packaging Pipeline"
        direction TB
        AIR_Compiler["AIR Compiler"]:::pipeline
        Captive_Packager["Captive Runtime Packager"]:::pipeline
        Readme_MD["README.md"]:::pipeline
        Gitattributes[".gitattributes"]:::pipeline
    end

    %% Packaged Deliverables
    subgraph "Packaged Deliverables"
        direction TB
        AirPackage["VirtualCockroach V019.air"]:::deliver
        AirReadme["ReadMe_请读我.txt"]:::deliver
        ExeZip["VirtualCockroach V019.zip"]:::deliver
        ZipReadme["ReadMe_请读我.txt"]:::deliver
        OldReleases["__Old__ Releases"]:::deliver
    end

    %% Runtime Host and Modules
    subgraph "Adobe AIR Runtime" 
        direction TB
        UI_Layer["UI Layer (windows, animations, menus)"]:::runtime
        Behavior_Engine["Behavior Engine (AI, feeding, shop)"]:::runtime
        Asset_Loading["Asset Loading (sprites, sounds)"]:::runtime
        System_Integration["System Integration (tray, prefs I/O)"]:::runtime
    end

    %% OS Services
    subgraph "Operating System"
        direction TB
        System_Tray["System Tray"]:::os
        Window_Manager["Window Manager"]:::os
        User_Input["User Input (clicks, drag)"]:::os
    end

    %% User
    User["End User"]:::os

    %% Connections - Development to Build
    Flash_IDE -->|uses| VirtualCockroach_fla
    Flash_IDE -->|uses| icon_fla
    Flash_IDE -->|uses| Source_iconPack
    AIR_SDK -->|compiles| AIR_Compiler
    VirtualCockroach_fla -->|source| AIR_Compiler
    VirtualCockroach_appxml -->|descriptor| AIR_Compiler
    icon_fla -->|assets| AIR_Compiler
    Source_iconPack -->|assets| AIR_Compiler
    Readme_MD -->|docs| AIR_Compiler
    Gitattributes -->|metadata| AIR_Compiler

    %% Build to Deliverables
    AIR_Compiler -->|generates .air| AirPackage
    AIR_Compiler -->|includes ReadMe| AirReadme
    Captive_Packager -->|wraps .exe/.zip| ExeZip
    Captive_Packager -->|includes ReadMe| ZipReadme
    AirPackage -->|versioning history| OldReleases
    ExeZip -->|versioning history| OldReleases

    %% Runtime interactions
    User -->|launches app| UI_Layer
    User -->|interacts| User_Input
    User_Input -->|events| UI_Layer
    UI_Layer -->|triggers| Behavior_Engine
    Behavior_Engine -->|loads sprites| Asset_Loading
    Behavior_Engine -->|updates| System_Integration
    Asset_Loading -->|reads| Source_iconPack
    Asset_Loading -->|reads| icon_fla
    System_Integration -->|invokes| System_Tray
    System_Integration -->|controls| Window_Manager

    %% Deliverables to User
    AirPackage -->|installed by| User
    ExeZip -->|installed by| User

    %% Styles
    classDef dev fill:#d0e1ff,stroke:#333,stroke-width:1px
    classDef pipeline fill:#b3ffcc,stroke:#333,stroke-width:1px
    classDef deliver fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef runtime fill:#ffd080,stroke:#333,stroke-width:1px
    classDef os fill:#e0e0e0,stroke:#333,stroke-width:1px

    %% Click Events
    click VirtualCockroach_fla "https://github.com/ferryyoungfan/virtualcockroach/blob/master/VirtualCockroach.fla"
    click icon_fla "https://github.com/ferryyoungfan/virtualcockroach/blob/master/icon.fla"
    click Source_iconPack "https://github.com/ferryyoungfan/virtualcockroach/tree/master/Source_iconPack/"
    click VirtualCockroach_appxml "https://github.com/ferryyoungfan/virtualcockroach/blob/master/VirtualCockroach-app.xml"
    click AirPackage "https://github.com/ferryyoungfan/virtualcockroach/blob/master/Release_成品发布/Mac_Win_AirPack/VirtualCockroach V019.air"
    click AirReadme "https://github.com/ferryyoungfan/virtualcockroach/blob/master/Release_成品发布/Mac_Win_AirPack/ReadMe_请读我.txt"
    click ExeZip "https://github.com/ferryyoungfan/virtualcockroach/blob/master/Release_成品发布/WinX86_exe_zip/VirtualCockroach V019.zip"
    click ZipReadme "https://github.com/ferryyoungfan/virtualcockroach/blob/master/Release_成品发布/WinX86_exe_zip/ReadMe_请读我.txt"
    click OldReleases "https://github.com/ferryyoungfan/virtualcockroach/tree/master/Release_成品发布/__Old__/"
    click Readme_MD "https://github.com/ferryyoungfan/virtualcockroach/blob/master/README.md"
    click Gitattributes "https://github.com/ferryyoungfan/virtualcockroach/blob/master/.gitattributes"
```
