# trackman/unity.package.figmatounity architecture

> Architecture diagram of the GitHub repository trackman/unity.package.figmatounity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trackman/unity.package.figmatounity
- Repository: https://github.com/trackman/unity.package.figmatounity

## Overview

##### Project Type and Purpose
- This is a Unity Editor plugin (“Unity.Package.FigmaForUnity”) that integrates with the Figma REST API to import Figma designs directly into Unity’s UI Toolkit (UXML/USS).
- It consists of two logical layers:
a. Editor‐time tools (fetching, transforming and generating assets)
b. Runtime components (Element scripts, attributes, and extensions that drive UI behavior inside the game)

##### Key Architectural Components
a. External Service
- Figma REST API (requires Personal Access Token)
b. Unity Editor Layer (“Editor” folder)
- FigmaDownloader.cs / Api.cs – HTTP client using AsyncAwaitUtil to fetch Figma document JSON and images.
- FigmaWriter.cs – Invokes Core writers to produce UXML and USS.
- Core modules:
- UxmlBuilder, UxmlWriter – generate UXML assets from Figma JSON.
- UssWriter, StylesPreprocessor, GradientWriter – generate USS style sheets.
- AssetsInfo, CachedAssets – manage/downloaded images and metadata.
- Inspector UI (FigmaInspector.cs, Panel Settings asset) – Unity Editor window to configure import settings.
- Extensions & Utilities – JsonUtility, NodeMetadata, NodesRegistry, UI theme assets.
c. Unity Asset Database
- Asset storage:
- Generated UXML (.uxml) and USS (.uss) files under Assets or user‐specified folders
- Cached JSON metadata (e.g. CachedAssets_UI.json)
- Images folder (png/svg)
- Fonts folder
d. Runtime Layer (“Runtime” folder)
- Element base class, IRootElement, ISubElement interfaces – define the contract for UI components.
- Attributes: UxmlAttribute, QueryAttribute – metadata for code‐driven UXML generation and runtime binding.
- Extensions: EnumerableExtensions, VisualElementExtensions – helper methods for manipulating VisualElement hierarchy.
- Figma.cs – orchestrates runtime update & sync logic using the generated UXML/USS assets.
e. Sample Scene (~Samples folder)
- Provides a Test.unity scene and Test.cs Element script demonstrating UXML attributes, Query attributes, and custom elements (e.g. PerfectCircle).

##### Relationships & Data Flow
- Designer updates Figma →
- In Unity Editor, user opens FigmaInspector →
- Editor code (FigmaDownloader) issues HTTP calls to Figma REST API →
- JSON + images returned →
- Core writers (UxmlWriter & UssWriter) transform JSON into UXML/USS assets →
- Unity AssetDatabase imports those assets →
- At runtime, Figma.cs reads UXML/USS assets and instantiates VisualElements →
- Element scripts (Test, PerfectCircle, etc.) attach via AddComponentMenu →
- QueryAttribute binds fields to named UXML elements →
- Events and UI logic execute in Play mode

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Editor vs Runtime code separated into distinct folders/assemblies.
- HTTP fetching, transformation, and asset generation layers are modular.
- Code‐First UI Definition: UxmlAttribute + QueryAttribute for declarative UI binding
- Plug‐in Extension Points: custom elements via inheritance of Element and SyncButtonSimple<T>
- Asynchronous Operations: use of AsyncAwaitUtil for non‐blocking HTTP calls
- Unity Package Manager: uses .asmdef to define Editor and Runtime assemblies

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% External Service
  subgraph "External Service"
    FigmaAPI["Figma REST API"]:::external
  end

  %% Editor Assembly
  subgraph "Editor Assembly"
    FDownloader["FigmaDownloader"]:::editor
    ApiClient["Api (HTTP Client)"]:::editor
    FWriter["FigmaWriter"]:::editor

    subgraph "Core Modules"
      UxmlBuilder["UxmlBuilder"]:::core
      UxmlWriter["UxmlWriter"]:::core
      UssWriter["UssWriter"]:::core
      StylesPreprocessor["StylesPreprocessor"]:::core
      GradientWriter["GradientWriter"]:::core
      AssetsInfo["AssetsInfo"]:::core
      CachedAssets["CachedAssets"]:::core
      JsonUtility["JsonUtility"]:::core
      NodeMetadata["NodeMetadata"]:::core
      NodesRegistry["NodesRegistry"]:::core
    end

    subgraph "Inspector & Settings"
      InspectorUI["FigmaInspector"]:::editor
      PanelSettings["Panel Settings Asset"]:::editor
    end

    subgraph "Editor Extensions"
      Ext1["Extensions.cs"]:::editor
      Ext2["NodeExtensions.cs"]:::editor
      Ext3["UssStyleExtensions.cs"]:::editor
    end

    subgraph "UI Theme Assets"
      Theme1["UI Theme.tss"]:::asset
      Theme2["UnityBase.uss"]:::asset
    end
  end

  %% Asset Database
  AssetDB["Unity AssetDatabase\n(UXML, USS, JSON, Images)"]:::db

  %% Runtime Assembly
  subgraph "Runtime Assembly"
    ElementBase["Element Base Class"]:::runtime
    UxmlAttr["UxmlAttribute"]:::runtime
    QueryAttr["QueryAttribute"]:::runtime

    subgraph "Runtime Extensions"
      RExt1["EnumerableExtensions"]:::runtime
      RExt2["Extensions"]:::runtime
      RExt3["PathExtensions"]:::runtime
      RExt4["VisualElementExtensions"]:::runtime
    end

    FigmaRuntime["Figma.cs"]:::runtime
  end

  %% Samples
  subgraph "Samples" style sample
    TestScene["Test.unity"]:::sample
    TestScript["Test.cs"]:::sample
  end

  %% Data Flow
  InspectorUI -->|opens| FDownloader
  FDownloader -->|uses| ApiClient
  ApiClient -->|HTTP/REST| FigmaAPI
  FDownloader -->|passes JSON| UxmlBuilder
  FDownloader -->|passes JSON| UssWriter
  UxmlBuilder -->|writes| AssetDB
  UssWriter -->|writes| AssetDB
  StylesPreprocessor -->|processes| UssWriter
  GradientWriter -->|augments| UssWriter
  AssetsInfo -->|metadata| AssetDB
  CachedAssets -->|caches| AssetDB

  AssetDB -->|loads| FigmaRuntime
  FigmaRuntime -->|instantiates| ElementBase
  FigmaRuntime -->|binds| UxmlAttr
  FigmaRuntime -->|binds| QueryAttr
  FigmaRuntime -->|uses| RExt4

  TestScript -->|demonstrates| ElementBase
  TestScene -->|contains| TestScript

  %% Click Events
  click FDownloader "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/FigmaDownloader.cs"
  click ApiClient "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Api.cs"
  click FWriter "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/FigmaWriter.cs"
  click UxmlBuilder "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Uxml/UxmlBuilder.cs"
  click UxmlWriter "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Uxml/UxmlWriter.cs"
  click UssWriter "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Uss/UssWriter.cs"
  click StylesPreprocessor "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/StylesPreprocessor.cs"
  click GradientWriter "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Assets/GradientWriter.cs"
  click AssetsInfo "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Assets/AssetsInfo.cs"
  click CachedAssets "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/Assets/CachedAssets.cs"
  click JsonUtility "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/JsonUtility.cs"
  click NodeMetadata "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/NodeMetadata.cs"
  click NodesRegistry "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Core/NodesRegistry.cs"
  click InspectorUI "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Inspector/FigmaInspector.cs"
  click PanelSettings "https://github.com/trackman/unity.package.figmatounity/blob/master/Assets/Panel Settings.asset"
  click Ext1 "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Extensions/Extensions.cs"
  click Ext2 "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Extensions/NodeExtensions.cs"
  click Ext3 "https://github.com/trackman/unity.package.figmatounity/blob/master/Editor/Extensions/UssStyleExtensions.cs"
  click Theme1 "https://github.com/trackman/unity.package.figmatounity/blob/master/Assets/UI Theme.tss"
  click Theme2 "https://github.com/trackman/unity.package.figmatounity/blob/master/Assets/UnityBase.uss"
  click ElementBase "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Core/Element.cs"
  click UxmlAttr "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Core/UxmlAttribute.cs"
  click QueryAttr "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Core/QueryAttribute.cs"
  click RExt1 "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Extensions/EnumerableExtensions.cs"
  click RExt2 "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Extensions/Extensions.cs"
  click RExt3 "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Extensions/PathExtensions.cs"
  click RExt4 "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Extensions/VisualElementExtensions.cs"
  click FigmaRuntime "https://github.com/trackman/unity.package.figmatounity/blob/master/Runtime/Figma.cs"
  click TestScene "https://github.com/trackman/unity.package.figmatounity/blob/master/~Samples/Test.unity"
  click TestScript "https://github.com/trackman/unity.package.figmatounity/blob/master/~Samples/Scripts/Test.cs"

  %% Styles
  classDef external fill:#f9c784,stroke:#e69500,stroke-width:1px
  classDef editor fill:#b3d1f2,stroke:#1f78b4,stroke-width:1px
  classDef core fill:#aed6f1,stroke:#3498db,stroke-width:1px
  classDef asset fill:#f0e68c,stroke:#bdb76b,stroke-width:1px
  classDef db fill:#d3d3d3,stroke:#808080,stroke-width:1px
  classDef runtime fill:#c5f5c7,stroke:#2ecc71,stroke-width:1px
  classDef sample stroke-dasharray: 5 5,fill:#ffffff,stroke:#000000,stroke-width:1px
```
