{"id":13662290,"url":"https://github.com/Eastrall/Rosalina","last_synced_at":"2025-04-25T07:31:16.657Z","repository":{"id":37010600,"uuid":"444417832","full_name":"Eastrall/Rosalina","owner":"Eastrall","description":"Rosalina is a code generation tool for Unity's UI documents. It generates C# code-behind script based on a UXML template.","archived":false,"fork":false,"pushed_at":"2024-03-03T16:55:06.000Z","size":20534,"stargazers_count":146,"open_issues_count":6,"forks_count":20,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-07T01:52:17.550Z","etag":null,"topics":["binding-generator","code-behind","code-generation","csharp","dotnet","roslyn","ui-builder","ui-elements","ui-toolkit","uielements","unity","unity-editor","unity-plugin","unity-tool","unity-tools","unity-ui","unity-uielement","unity3d","unity3d-plugin"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Eastrall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-01-04T12:52:14.000Z","updated_at":"2025-03-13T01:41:44.000Z","dependencies_parsed_at":"2024-08-02T05:13:17.007Z","dependency_job_id":"49b439a1-06ed-476e-aad8-78f1e0315987","html_url":"https://github.com/Eastrall/Rosalina","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eastrall%2FRosalina","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eastrall%2FRosalina/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eastrall%2FRosalina/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eastrall%2FRosalina/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eastrall","download_url":"https://codeload.github.com/Eastrall/Rosalina/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250774721,"owners_count":21485209,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binding-generator","code-behind","code-generation","csharp","dotnet","roslyn","ui-builder","ui-elements","ui-toolkit","uielements","unity","unity-editor","unity-plugin","unity-tool","unity-tools","unity-ui","unity-uielement","unity3d","unity3d-plugin"],"created_at":"2024-08-02T05:01:54.565Z","updated_at":"2025-04-25T07:31:16.615Z","avatar_url":"https://github.com/Eastrall.png","language":"C#","funding_links":[],"categories":["GamePlay","C\\#"],"sub_categories":["Skill"],"readme":"# Rosalina\n\n[![openupm](https://img.shields.io/npm/v/com.eastylabs.rosalina?label=openupm\u0026registry_uri=https://package.openupm.com)](https://openupm.com/packages/com.eastylabs.rosalina/)\n\nRosalina is a code generation tool for Unity's UI documents make with the new UI Toolkit. It automatically generates C# UI binding scripts based on a UXML document template.\n\n## Key features\n\n* [UI Documents](https://docs.unity3d.com/Manual/UIE-simple-ui-toolkit-workflow.html)\n  * Automatic C# bindings generation\n  * C# document script\n* [`EditorWindow`](https://docs.unity3d.com/ScriptReference/EditorWindow.html) support\n  * Automatic C# bindings generation\n  * C# document script\n* Custom Components\n  * Automatic C# bindings generation\n  * C# document script\n\n## How to install\n\nRosalina can either be installed via OpenUPM: https://openupm.com/packages/com.eastylabs.rosalina/\nOr by using the following git repository: ``https://github.com/Eastrall/Rosalina.git``\n\n### Installing via OpenUPM\n\nRosalina is now available via OpenUPM:\nhttps://openupm.com/packages/com.eastylabs.rosalina/\n\nOpenUPM provides a detailed explanation of how to add packages to unity.\n\n### Installing via git repository\n\nIn Unity, navigate to ``Window -\u003e Package Manager``:\n\n![image](https://user-images.githubusercontent.com/4021025/204278700-989b139c-cbf3-4c56-8ebe-91309258aac2.png)\n\nIn the ``Package Manager``, click on the ``+`` on the top left and select ``Add package from git URL...``\n\n![image](https://user-images.githubusercontent.com/4021025/204278730-38f06044-b298-484e-b6ad-43cb1684134e.png)\n\nNo use the following path to install Rosalina ``https://github.com/Eastrall/Rosalina.git``\n\n![image](https://user-images.githubusercontent.com/4021025/204278754-8bfa4b2d-dd57-4a59-af45-ff05470272fc.png)\n\nYou can now start to work with Rosalina.\n\n## How it works\n\nRosalina watches your changes related to all `*.uxml` files contained in the `Assets` folder of your project, parses its content and generates the according C# UI binding code based on the element's names.\n\nTake for instance the following UXML template:\n\n**`SampleDocument.uxml`**\n\n```xml\n\u003cui:UXML xmlns:ui=\"UnityEngine.UIElements\" xmlns:uie=\"UnityEditor.UIElements\"\n         xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         engine=\"UnityEngine.UIElements\" editor=\"UnityEditor.UIElements\"\n         noNamespaceSchemaLocation=\"../../UIElementsSchema/UIElements.xsd\"\n         editor-extension-mode=\"False\"\u003e\n    \u003cui:VisualElement\u003e\n        \u003cui:Label text=\"Label\" name=\"TitleLabel\"/\u003e\n        \u003cui:Button text=\"Button\" name=\"Button\"/\u003e\n    \u003c/ui:VisualElement\u003e\n\u003c/ui:UXML\u003e\n```\n\nRosalina's `AssetProcessor` will automatically genearte the following C# UI bindings script:\n\n\u003e ℹ️ Note: All generated files are located in the `Assets/Rosalina/AutoGenerated/` folder.\n\n**`SampleDocument.g.cs`**\n\n```csharp\n// \u003cautogenerated /\u003e\nusing UnityEngine;\nusing UnityEngine.UIElements;\n\npublic partial class SampleDocument\n{\n    [SerializeField]\n    private UIDocument _document;\n\n    public Label TitleLabel { get; private set; }\n\n    public Button Button { get; private set; }\n\n    public VisualElement Root =\u003e _document?.rootVisualElement;\n\n    public void InitializeDocument()\n    {\n        TitleLabel = Root?.Q\u003cLabel\u003e(\"TitleLabel\");\n        Button = Root?.Q\u003cButton\u003e(\"Button\");\n    }\n}\n```\n\n\u003e ⚠️ This script behing an auto-generated code based on the UXML template, **you should not** write code inside this file. It will be overwritten everytime you update your UXML template file.\n\nAccording to Unity's UI Builder warnings, a `VisualElement` names can only contains **letters**, **numbers**, **underscores** and **dashes**.\nSince a name with **dashes** is not a valid name within a C# context, during the code generation process, Rosalina will automatically convert `dashed-names` into `PascalCase`.\nMeaning that if you have the following UXML:\n\n```xml\n\u003cui:VisualElement\u003e\n    \u003cui:Button text=\"Button\" name=\"confirm-button\"/\u003e\n\u003c/ui:VisualElement\u003e\n```\nRosalina will generate the following property:\n```csharp\npublic Button ConfirmButton { get; private set; }\n```\n\nIn case you already have a `ConfirmButton` as a `VisualElement` name, do not worry, Rosalina will detect it for you during the code generation process and throw an error letting you know there is a duplicate property in your UXML document.\n\n## How to use\n\nAfter installing Rosalina, the code generation process is disabled by default, and should be enabled.\nGo to `Edit \u003e Project Settings \u003e Rosalina` and enable it:\n\n![image](https://github.com/Eastrall/Rosalina/assets/4021025/124c946f-1a66-404e-8b91-1a3ed02d7c56)\n\nOnce Rosalina is enabled, you will need to manually add a UXML file to the Rosalina's code generation processor.\nTo do so, right-click on a UXML file, go to `Rosalina \u003e Properties...`:\n\n![image](https://github.com/Eastrall/Rosalina/assets/4021025/047b3b35-c913-4a38-9fc9-99127b68d887)\n\nThe Rosalina's properties window opens next to the inspector tab, and you can enable it to add the current file to the Rosalina's code generation processor.\n\n![image](https://github.com/Eastrall/Rosalina/assets/4021025/d4bf640a-a653-48b3-badc-602b5ebb4a09)\n\nRosalina provides three generator types:\n* Document\n* Component\n* Editor\n\nChoose the generator type according to your needs.\n\nWhen generating a UXML file binding-script, it will be automatically created and will be located at `Assets/Rosalina/AutoGenerated` and share it's name with a `.g.cs` extension.\n\nYou should **NOT** edit this file in any way or form, as it will be recreated on each change to the corresponding ``Visual Tree Asset`` document.\n\n### UI Document\n\nGenerator Type: `Document`\n\nWhen generating an UI Script, Rosalina will generate the following code:\n```csharp\nusing UnityEngine;\n\npublic partial class SampleDocument : MonoBehaviour\n{\n    private void OnEnable()\n    {\n        InitializeDocument();\n    }\n}\n```\nThe `InitializeDocument()` method contains all the UI properties initialization. Every interaction with UI properties such as assigning a text to a label or an clicked event action to a button **MUST** be defined **after** the `InitializeDocument()` call. Otherwise, you will have a `NullReferenceException`.\n\n```csharp\nusing UnityEngine;\n\npublic partial class SampleDocument : MonoBehaviour\n{\n    private void OnEnable()\n    {\n        InitializeDocument();\n        TitleLabel.text = \"Hello world!\";\n        Button.clicked += OnConfirmButtonClicked;\n    }\n\n    private void OnButtonClicked()\n    {\n        TitleLabel.text = \"Button clicked\";\n    }\n}\n```\n\n\u003e Note, even if this file has been generated, you still can edit it because it will not be overwritten each time you change a UXML file.\n\n### Custom components\n\nTo use a UI Document as an Unity's Editor Window, set the Generator type in Rosalina's properties window, to `Component`.\n\n![image](https://github.com/Eastrall/Rosalina/assets/4021025/db621190-4a49-43cb-8c28-89592dccf23a)\n\nTake this UXML file for example:\n```xml\n\u003cui:UXML ...\u003e\n    \u003cui:Label text=\"My custom label\" name=\"TitleLabel\" /\u003e\n    \u003cui:Button text=\"Sample Button\" display-tooltip-when-elided=\"true\" name=\"SampleButton\" /\u003e\n\u003c/ui:UXML\u003e\n```\n\nRosalina's code generator will generate the following class:\n```csharp\n// \u003cauto-generated\u003e\nusing UnityEngine.UIElements;\n\npublic partial class CustomComponent\n{\n    public Label TitleLabel { get; private set; }\n\n    public Button SampleButton { get; private set; }\n\n    public VisualElement Root { get; }\n\n    public CustomComponent(VisualElement root)\n    {\n        Root = root;\n        TitleLabel = Root?.Q\u003cLabel\u003e(\"TitleLabel\");\n        SampleButton = Root?.Q\u003cButton\u003e(\"SampleButton\");\n    }\n}\n```\n\nThen when using this component in another UI Document, Editor or component, Rosalina will automatically initialize it using it's constructor:\n```xml\n\u003cui:UXML ...\u003e\n    \u003cui:Template name=\"CustomComponent\" src=\"project://...\" /\u003e\n    \u003c!-- Other UI elements... --\u003e\n    \u003cui:Instance template=\"CustomComponent\" name=\"MyCustomComponent\" /\u003e\n\u003c/ui:UXML\u003e\n```\n```csharp\n// \u003cauto-generated\u003e\nusing UnityEngine;\nusing UnityEngine.UIElements;\n\npublic partial class SampleDocument\n{\n    [SerializeField]\n    private UIDocument _document;\n\n    // Other UI element properties...\n\n    public CustomComponent MyCustomComponent { get; private set; }\n\n    public VisualElement Root =\u003e _document?.rootVisualElement;\n\n    public void InitializeDocument()\n    {\n        // Other initializations...\n\n        CustomLabel = new CustomComponent(Root?.Q\u003cVisualElement\u003e(\"MyCustomComponent\"));\n    }\n}\n```\nIn your `SampleDocument` script, you can access the `CustomLabel` just like any other UI element or object instance:\n```csharp\nusing UnityEngine;\n\npublic partial class SampleDocument : MonoBehaviour\n{\n    private void OnEnable()\n    {\n        InitializeDocument();\n        // Setting the TitleLabel's text within the CustomLabel component.\n        CustomLabel.TitleLabel.text = \"Hello world!\";\n    }\n}\n```\n\n### Editor Window\n\nTo use a UI Document as an Unity's Editor Window, set the Generator type in Rosalina's properties window, to `Editor`.\n\nTake this UXML file for example:\n```xml\n\u003cui:UXML ...\u003e\n    \u003cui:Button text=\"Sample Button\" display-tooltip-when-elided=\"true\" name=\"SampleButton\" /\u003e\n\u003c/ui:UXML\u003e\n```\n\nRosalina's code generator will generate you a class that extends the `UnityEditor.EditorWindow`:\n\n```csharp\n// \u003cautogenerated /\u003e\nusing UnityEditor;\nusing UnityEngine;\nusing UnityEngine.UIElements;\n\npublic partial class CustomEditorWindow : EditorWindow\n{\n    public Button SampleButton { get; private set; }\n\n    public void CreateGUI()\n    {\n        VisualTreeAsset asset = AssetDatabase.LoadAssetAtPath\u003cVisualTreeAsset\u003e(\"Assets/...\");\n        VisualElement ui = asset.CloneTree();\n        rootVisualElement.Add(ui);\n        SampleButton = rootVisualElement?.Q\u003cButton\u003e(\"SampleButton\");\n        OnCreateGUI();\n    }\n\n    partial void OnCreateGUI();\n}\n```\n\nWhen generating an UI Script, Rosalina will generate the following code:\n```csharp\nusing UnityEditor;\nusing UnityEngine;\nusing UnityEngine.UIElements;\n\npublic partial class CustomEditorWindow : EditorWindow\n{\n    partial void OnCreateGUI()\n    {\n    }\n}\n```\n\nEvery interaction with UI properties such as assigning a text to a label or an clicked event action to a button **MUST** be defined **inside** the `OnCreateGUI()` method:\n\n```csharp\nusing UnityEditor;\nusing UnityEngine;\nusing UnityEngine.UIElements;\n\npublic partial class CustomEditorWindow : EditorWindow\n{\n    partial void OnCreateGUI()\n    {\n        SampleButton.clicked += OnSampleButtonClicked;\n    }\n\n    private void OnSampleButtonClicked()\n    {\n        Debug.Log(\"Hello world!\");\n    }\n}\n```\n\nIf you want, you can also control the behavior of the window and tell Unity how to open it; for instance, with from a `Menu Item`:\n\n```csharp\nusing UnityEditor;\nusing UnityEngine;\nusing UnityEngine.UIElements;\n\npublic partial class CustomEditorWindow : EditorWindow\n{\n    [MenuItem(\"Window/My Custom Editor Window\")]\n    public static void ShowWindow()\n    {\n        EditorWindow.CreateWindow\u003cCustomEditorWindow\u003e(\"My Custom Editor Window!\");\n    }\n\n    partial void OnCreateGUI()\n    {\n        SampleButton.clicked += OnSampleButtonClicked;\n    }\n\n    private void OnSampleButtonClicked()\n    {\n        Debug.Log(\"Hello world!\");\n    }\n}\n```\n\nThis will add a new entry named `My Custom Editor Window` to the `Window` menu item:\n\n![image](https://user-images.githubusercontent.com/4021025/204351292-d34f54e3-b3bb-4efb-a79b-b2768fb257fa.png)\n\nAnd when clicking on that menu item, the custom editor window will appear and you can now interact with the elements:\n\n![image](https://user-images.githubusercontent.com/4021025/204351418-008a1521-c796-4ec6-852c-43a2a5064e4d.png)\n\n## Notes\n\nAs pointed out by [JuliaP_Unity](https://forum.unity.com/members/juliap_unity.4707193/) on [Unity Forums](https://forum.unity.com/threads/share-your-ui-toolkit-projects.980061/#post-7799040) the document initialization process (element queries) **should** be done on the `OnEnable()` hook, since the `UIDocument` visual tree asset is instancied at this moment.\n*Thank you for the tip!*\n\n## Known limitations\n\n* The generated files share the name of the `Visual Tree Asset`. Currently, it's not possible to change the script names.\n* Rosalina currently does not support namespaces.\n\n## Final words\n\nIf you like the project, don't hesitate to contribute! All contributions are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEastrall%2FRosalina","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEastrall%2FRosalina","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEastrall%2FRosalina/lists"}