sadguitarius / typescript-for-max

TypeScript for Cycling '74 Max

TypeScript for Cycling '74 Max / MSP / Jitter

Examples showing how to use the Max Javascript type definitions available as part of the DefinitelyTyped project and more broadly how to compile Javascript that Max can run.

npm install @types/maxmsp --save-dev

If you want to contribute to the type definitions themselves please see DefinitelyTyped

VS Code is the recommended TypeScript IDE.

Follow this guide to set up Sublime Text.

Getting started

Clone this repo to your Max 8/Library folder

Install its dependencies with npm install. You can then compile the .ts files in src to max compatible es3 javascript by running either npm run compile or tsc.

Once you have done this you will see the compiled js files in the dist folder and you can open the patches in the maxpatches folder.

Using the definitions in your own project

You can install these types in your own project by using the command npm install @types/maxmsp --save-dev

You should ensure that your tsconfig.json is set up in a similar one to this project as there are a few important things that you need to note:

• Max uses an archaic es5 javascript (for more information see here), which means that for lots of modern functionality you will need to include polyfills. In our tsconfig.json we define this "target": "es5", and this means that we also need to set "ignoreDeprecations": "5.0", because es3 support will soon be dropped by Typescript

• tsconfig.json includes "lib": ["es5"] to stop Typescript from trying to use DOM declarations. Not including this lib directive results in duplicate declaration errors because some max items share names with DOM items.

• We configure the types so that we can use them from the top level by including the line "types": ["maxmsp"], in our tsconfig.json

API Documentation

See Max Javascript Reference for full documentation on all functions and properties.

Notes

• The TypeScript configuration file (tsconfig.json) is set up to output a separate .js file for each .ts file.

• .ts files for scripts to be used in a [js] or [jsui] object must end in:

   let module = {};
   export = {};
  

  This tricks tsc in outputting it as a separate module file, while still allowing Max to read it as a script. Do not do this in module files.

• Make sure the compiled JavaScript files are in Max' search path, set this with "outDir" in your tsconfig.json. Make sure your TypeScript folder is not in a Max project directory or Max will mess up the file structure.

• For continuous development run tsc --watch in the directory with your tsconfig.json. The .js files are then generated on save and Max will then reload automatically.

• For more information on configuration files, look here.

• Import modules using non local paths. Max will resolve ExampleModule but ./ExampleModule will not work without path rewriting. In more complex projects where you may want to hide subdirectories or use shorter paths you might need to include a paths directive in your tsconfig.json. For example:

"paths": {
      "Cursor": [
        "Cursor/Cursor"
      ]
}

Assigning properties to objects of type Global

Cast to <any> to assign properties to objects of type Global like so:

var g = new Global("Foo");
(<any>g).newProperty = "I am new.";
post("(<any>g).newProperty: " + (<any>g).newProperty + "\n");