docs.unity3d.com

    Unity Coding Support Tools

    The Unity Coding package contains tooling and configurations to ensure your code is automatically formatted, encoded, and linted according to standard Unity development conventions and best practices.

    Add this to your Project and the package automatically formats your code. In the future this package will also configure compilers to emit warnings about code that violates our code conventions. Later on, you will be able to write your own analyzers for rules that are specific to your project.

    Requirements

    • As of today, this package should be added to a Project, i.e, your package cannot depend on this package; instead, the recommended way to setup it is to have a Unity Project which depends both in your package and in the Unity Coding package (you can see an example here)
    • Unity 2019.3 or newer
    • Your Project needs to be configured to use .NET 4.0
    • One or more .editorconfig file(s) used to define which sources will get formatted (see below)
    • (Optional but recommended) a .gitattributes at the root that configures eol's for certain file types so that
      • git and the formatters are aligned, avoiding annoying warnings
      • Certain tools that are picky about eol's (notably T4) work properly and smoothly

    How to install

    • Create a Project (if you don't have one) to host your package

    • Configure ProjectRoot/Packages/manifest.json to enable the staging registry by adding the following line just after the dependencies node:

      "registry": "https://artifactory.prd.cds.internal.unity3d.com/artifactory/api/npm/upm-candidates"

    • Also in the manifest.json, add this line to the dependencies section

      "com.unity.coding" : "0.1.0-preview.13"

      Note: If you get compilation errors, make sure your project is configured to use the new scripting runtime.

      Go to Project Settings/Player select .Net 4.x equivalent in Scriping Runtime Version (this option was removed in 2019.2 along with the old runtime)

    • To enable formatting, copy Coding~/Configs/EditorConfig/.editorconfig from the com.unity.coding package root to ProjectRoot/.editorconfig which will configure sources under Assets/ and Packages/ folders to be formatted. Copy to PackageRoot/.editorconfig to configure package formatting.

    • Copy the .gitattributes from the same location as .editorconfig into your repo root. If you've already got one there, then append the template into it.

    • To do the initial format, right-click the Assets/ folder (or package root folder) in the Unity Editor and select Format Code.

    Formatting

    How to configure

    The formatter uses .editorconfig files (EditorConfig) to figure out which files should be formatted.

    In general, given a file F, the formatter will process it if it finds a .editorconfig that matches that file. The formatter will look for that file starting at the directory where F is stored and all of its parents until it finds a match.

    Inside the .editorconfig file, in a session that matches the files you want to format, add a property called formatters which can be set to generic and/or uncrustify, for example:

    # this will only format cs files that are under "MyFolder" folder (not in subfolders)
    [MyFolder/*.cs]
    formatters = uncrustify, generic
    
    # this will format cs files under "MyFolder" folder and any of its subfolders
    [MyFolder/**.cs]
    formatters = uncrustify, generic
    

    You can also place a .editorconfig file in the subfolder, and take advantage of inheritance. There are many other ways to configure how your repo is formatted. Visit the official site for more details about .editorconfig.

    How to use it

    Once configured the formatter will ensure that any changed or added source will be formatted.

    If you want to do a initial format (after adding UnityCoding to your project) or in cases where you tweak your .editorconfig file you'll need to explicitly run the formatter by right clicking the files (or folders) you want to format and selecting Format Code from the context menu.

    If, for any reason, you want to disable auto-formating (i.e, you want to format only explicitly) you can set disable_auto_format to true in your .editorconfig

    It is possible to invoke Api Scraper manually using Unity.Coding.Editor.ApiScraping.ApiScraping.Scrape(). Calling this method will include all .asmdef files that have no match in .editorconfing (this is not true when the scraper is running automatically).

    Api files integrity

    To validate if .api files are up-to-date in the project Unity.Coding.Editor.ApiScraping.ApiScraping.ValidateAllFilesScraped(List) can be used. For CI verification, call this method from an EditMode test.

    Known issues

    FAQ

    Q: I've changed .editorconfig to include some more files to be formatted, then switched back to Editor, but nothing got formatted.

    A: The formatter's auto-format ability only notices when you change the source files, and doesn't try to figure out what files might be affected by a change to .editorconfig itself. You can just right-click the file (or a folder) you want and select Format Code from the context menu.

    API Scraping

    The public API of your .asmdefs can be tracked in checked-in .api files which are regenerated in the editor after compilation. .api files capture the entire public API from a single assembly in the form of C#-like declarations. For more info on the .api format, see (this confluence page).

    How to configure

    The template in UnityCoding\Packages\com.unity.coding\Coding~\Configs\EditorConfig.editorconfig is set up to scrape non-test asmdefs. Or you can add scrape_api = true for the .asmdefs you wish to scrape in your .editorconfig.

    Ex, from the template

    [*.asmdef]
    scrape_api = true
    
    [**/Tests/**.asmdef]
    scrape_api = false
    

    How to use it

    Once configured, files named <assembly name>.api will be generated next to each configured asmdef after every compilation in the editor.

    Note that if these files are updated while the editor is run with -batchmode, an error will be logged to the console and the editor will close with a non-zero exit code. This is to cause continuous integration builds to fail if the .api files are not fully up to date in the repository.


    Did you find this page useful? Please give it a rating:

    Thanks for rating this page!

    Report a problem on this page

    What kind of problem would you like to report?

    • This page needs code samples
    • Code samples do not work
    • Information is missing
    • Information is incorrect
    • Information is unclear or confusing
    • There is a spelling/grammar error on this page
    • Something else

    Thanks for letting us know! This page has been marked for review based on your feedback.

    If you have time, you can provide more information to help us fix the problem faster.

    Provide more information

    You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:

    You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:

    You've told us there is information missing from this page. Please tell us more about what's missing:

    You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:

    You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:

    You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:

    You've told us this page has a problem. Please tell us more about what's wrong:

    Thank you for helping to make the Unity documentation better!

    Your feedback has been submitted as a ticket for our documentation team to review.

    We are not able to reply to every ticket submitted.

    In This Article
    • Unity Coding Support Tools
    • Requirements
    • How to install
    • Formatting
      • How to configure
      • How to use it
      • Api files integrity
      • Known issues
      • FAQ
    • API Scraping
      • How to configure
      • How to use it
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023