Request

Response

    TypeScript

    The Fusion API enables you to create scripts and add-ins that automate design workflows. Fusion desktop supports scripts written in Python, C++, and TypeScript; the Fusion Automation API runs TypeScript scripts only.

    This page explains how to develop TypeScript scripts for the Fusion engine, including how to create and debug them locally in Fusion, how to run them on the Automation API, and the API restrictions you should be aware of.

    Creating a TypeScript Script

    TypeScript scripts are created and managed from Fusion’s Scripts and Add-Ins dialog. No separate add-in is required.

    1. In Fusion, open Utilities > Add-Ins > Scripts and Add-Ins.
    2. Click Create to open the New Script or Add-In dialog.
    3. Select Script, choose TypeScript as the programming language, and enter a name.

    Fusion generates a working script that you can run immediately. The script template includes the API type definition files (.d.ts), which provide code completion and type checking for the Fusion API in your editor.

    For details on the TypeScript script lifecycle and language specifics, see TypeScript Specific Issues in the Fusion API documentation.

    Local Development and Debugging

    Use Visual Studio Code to edit and debug your script against Fusion desktop:

    1. In the Scripts and Add-Ins dialog, right-click your script and select Edit in code editor. The script folder opens in VS Code.
    2. Set breakpoints as needed.
    3. Use VS Code’s standard Run and Debug view to start the script. The script runs inside your local Fusion session, and the debugger stops at your breakpoints.

    Running on the Automation API

    To run your script as a WorkItem on the Automation API without writing HTTP requests yourself, install the Fusion Automation API extension for VS Code. The extension submits the open script to Design Automation and shows the job output in VS Code.

    1. Install the extension from the Visual Studio Marketplace.
    2. Create an APS application at aps.autodesk.com/myapps, or use an existing one, and add the callback URL listed on the extension’s Marketplace page.
    3. In VS Code, run the Set Client ID and Set Client Secret commands and enter your application’s credentials.
    4. Under Settings > Extensions > Fusion Automation API, set the Activity ID (Fusion.ScriptJob+Latest is recommended) and the Fusion environment.
    5. With your .ts file open and focused, click Run Remotely in the top-right corner of the editor. The first time, you are prompted to sign in to Autodesk Platform Services.

    See the extension’s Marketplace page for the full list of settings and authentication options.

    API Restrictions

    The TypeScript API provides most of the functionality available in Fusion’s desktop APIs, with these key limitations:

    • User Interface: Interactive elements like dialogs and user input methods are unavailable
    • Custom Features: Custom events, graphics, and text commands are not supported
    • Render Environment: The rendering API is completely unavailable
    • File Access: Scripts can only access files within their designated working directory (including AppBundle content and WorkItem input files). Use appbundle:// URIs to read non-code files shipped in an AppBundle — see Auxiliary Files in AppBundles.
    • Package Management: Third-party packages cannot be imported via npm or other package managers

    These restrictions ensure scripts run reliably in the cloud automation environment.

    Auxiliary Files in AppBundles

    TypeScript and JavaScript modules under Contents/ are loaded and transpiled automatically. Other files in the bundle — JSON, CSV, images, add-in payloads, and similar assets — are copied to the worker as-is. They are not imported as modules; read them with the file APIs exposed to your script (for example adsk.readFileSync).

    On a Fusion Automation worker, each AppBundle is expanded under the job working directory with a qualified folder name (for example mynickname.MyAppBundle!4/MyAppBundle/Contents/...). Version numbers and zip root folder names can change when you publish a new bundle version. To read auxiliary files without hard-coding those paths, use the read-only appbundle:// URI scheme:

    appbundle://<qualified-app-bundle-id>/<path-under-Contents>
    
    • Qualified app bundle id — Typically <your-forge-nickname>.<AppBundleId> (the same id you register with POST appbundles). This matches the deployment folder name on the worker before the ! version suffix.
    • Path under Contents — Relative to the bundle Contents/ folder, using forward slashes (for example data/settings.json or tool_data/mytools.json).

    Example AppBundle layout:

    MyAppBundle/
        PackageContents.xml
        Contents/
            main.ts
            data/
                settings.json
    

    Example script:

    import { adsk } from "@adsk/fas";
    
    const settingsPath = "appbundle://mynickname.MyAppBundle/data/settings.json";
    const json = adsk.readFileSync(settingsPath);
    const settings = JSON.parse(json);
    

    Read-only access

    Paths using the appbundle:// scheme are allowed for read operations only. Attempts to create, modify, or delete files through this scheme fail. Write outputs to the job working directory or to WorkItem arguments (for example OutputFile) instead.

    When to use appbundle://

    Use appbundle:// for auxiliary files in Activities that run an AppBundle on the Automation Service. Inline scripts supplied through TaskScript or TaskScriptUrl do not include a bundle layout, so they cannot use this scheme. See Arguments.

    appbundle:// URIs are resolved only by the Automation Service. Running a script locally in Fusion desktop that uses an appbundle:// path fails with an error. When running locally, read auxiliary files using paths relative to the script folder instead.

    Text and Fonts

    The Automation API for Fusion supports text and fonts in designs. Cloud workers ship with a set of pre-installed fonts, and you can also bundle custom fonts in your AppBundle when a design needs a typeface that is not already available.

    Pre-Installed Fonts

    Every Fusion worker includes the fonts below. If a design references a font that is neither pre-installed nor supplied in your AppBundle, Fusion substitutes Arial.

    Andale Mono DejaVu Sans Mono Cdm_nc.shx
    Arial DejaVu Serif G12f13.shx
    Arial Black Georgia G13f12d.shx
    Arimo Impact G13f12w.shx
    Artifakt Element Liberation Mono Geniso.shx
    Artifakt Element Black Liberation Sans Geniso12.shx
    Artifakt Element Extra Bold Liberation Sans Narrow Iso.shx
    Artifakt Element Extra Light Liberation Serif Isocp.shx
    Artifakt Element Light Monospace Italic8.shx
    Artifakt Element Medium Sans Serif Monotxt8.shx
    Artifakt Element Semi Bold Serif Romans.shx
    Artifakt Element Thin Times New Roman Simplex.shx
    Comic Sans MS Trebuchet MS Simplex8.shx
    Courier New Verdana Weidner.shx
    DejaVu Sans Cdm.shx

    Custom Fonts in AppBundles

    To use a font that is not pre-installed on the worker, include the font files in the AppBundle you reference on your Activity. When the WorkItem starts, Fusion discovers and installs those fonts automatically — in parallel with token setup and script transpilation — before your TypeScript entry point runs.

    Supported file formats: .ttf, .otf, and .ttc.

    Placement: Put font files anywhere under the AppBundle root folder. Fusion scans the bundle recursively when the task is read; you do not need a specific subfolder name.

    AppBundle-only: Custom fonts are available only when your Activity runs an AppBundle. Inline scripts supplied through the TaskScript or TaskScriptUrl well-known arguments do not include a bundle folder, so they cannot carry font files. See Arguments.

    Example layout:

    ConfigureDesignAppBundle/
        PackageContents.xml
        Contents/
            main.ts
        Fonts/
            MyCompany-Regular.ttf
            MyCompany-Bold.otf
    

    Each font file is registered with the Fusion font database before your script runs. If any bundled font cannot be installed or registered, the WorkItem fails with an AppBundle font installation failed error.

    Use the pre-installed font list above when you can; bundle custom fonts only for typefaces your design requires that are not already on the worker.

    Forum Support

    Post questions and get community help on the Fusion API and Scripts forum. This public forum connects you with other developers and Autodesk experts who can help troubleshoot Fusion API issues.