How trackman/unity.package.figmatounity works
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