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.
- In Fusion, open Utilities > Add-Ins > Scripts and Add-Ins.
- Click Create to open the New Script or Add-In dialog.
- 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:
- In the Scripts and Add-Ins dialog, right-click your script and select Edit in code editor. The script folder opens in VS Code.
- Set breakpoints as needed.
- 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.
- Install the extension from the Visual Studio Marketplace.
- 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.
- In VS Code, run the Set Client ID and Set Client Secret commands and enter your application’s credentials.
- Under Settings > Extensions > Fusion Automation API, set the Activity ID (
Fusion.ScriptJob+Latestis recommended) and the Fusion environment. - With your
.tsfile 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 exampledata/settings.jsonortool_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.