README.md

PlayCanvas Attribute Parser

| User Manual | API Reference | Blog | Forum |

This is the official JSDoc attribute parser used in the PlayCanvas Editor.

It collects metadata from user scripts by parsing @attribute JSDoc annotations. These attributes enable the PlayCanvas Editor to expose UI controls and contextual information for your script properties.

Example

Given a script like this:

class Rotator extends ScriptType {
    /**
     * @attribute
     * Speed determines how fast to rotate things
     */
    speed = new Vec3();

    /**
     * @attribute
     * An array of Entities to rotate
     *
     * @type {Entity[]}
     */
    thingsToRotate;
}

The parser outputs:

{
    "rotator": {
        "attributes": {
            "speed": {
                "type": "vec3",
                "name": "speed",
                "array": false,
                "description": "Speed determines how fast to rotate things",
                "default": [0, 0, 0]
            },
            "thingsToRotate": {
                "type": "entity",
                "name": "thingsToRotate",
                "array": true,
                "description": "An array of Entities to rotate",
                "default": null
            }
        },
        "errors": []
    }
}

JSDocs tags are parsed and values and outputs the metadata in a serializable format.

Usage

// Initialise the parser
// Initialize the parser
const parser = new JSDocParser();
await parser.init();

// Load your source files: {[filename: string]: string}[]
const scripts = await fetchScripts([...paths, './playcanvas.d.ts']);

// Update the parser program
parser.updateProgram(scripts);

// Parse attributes from the entry point
const [attributes, errors] = parser.parseAttributes('./index.js');

Attribute structure

See the test fixtures for examples of supported JSDoc tags and output formats.

Tests

This project includes good test coverage for all supported tag formats and edge cases.