Introduction
User Interface
Components
Scripting
Framework
Physics
Virtual Commissioning
Digital Shadow
Analysis
Tutorials

Packages

Packages are collections of scripts that can be installed instantly into your model at the click of a button, extending the functionality of ProtoTwin. Packages can contain scripted components, tools and utility classes or functions. Packages provide a simple method for sharing and reusing scripts. The package manager is integrated into the script editor which provides a UI for installing, uninstalling and updating packages.

Installing Packages

To install a package use the package manager integrated into the script editor. After opening the package manager, you can browse all the available packages. Select a package from the list, select the package version from the dropdown menu, then click the install button to install the package into your model.

Uninstalling Packages

Open the package manager and switch to the Installed tab. Select the package that you want to uninstall from the list and click the uninstall button.

Updating Packages

Open the package manager and switch to the Updates tab. Select the package that you want to update from the list, then select the package version you want updating to from the dropdown menu, then click the install button.

Package Definition File

The package manager will automatically create/modify the package.json file when installing, uninstalling and updating packages. It is possible to create/modify this file yourself. Packages will be installed/uninstalled/updated upon saving the file. The example below shows the package.json file corresponding to a single installed package:

{
    "dependencies": {
        "@prototwin/air-gun": "1.0.0"
    }
}

Publishing Packages

Packages must be published under an organization.

Organizations

The manager of an organization, along with all members of the organization, will have access to any private packages published under the organization. The manager can publish packages and may also permit members to publish packages.

Joining an Organization

To join an organization as a member, ask the manager of the organization to invite you to the organization. Once invited, you should receive a verification email. Click the link in the email to join the organization.

Creating an Organization

You can create an organization. After approval, you will become the manager of the created organization. This will allow you to publish packages under the organization. You will also be able to invite other users to join the organization, as members. Members of the organization may also be permitted to publish packages under the organization.

Package Format

Packages are created through the script editor. All the files listed are bundled into the package upon publishing it. The following files are mandatory:

  • package.json: Defines the package name, version, description and list of dependencies.
  • index.ts: Exports all the types, including components and tools, that should be available to users that install the package.
  • README.md: Describes the contents of the package along with any pertinent documentation.

The package.json file must contain a JSON object with the following properties:

  • Name: The name for the package, including the organization scope.
  • Version: The unique version for the package, in the Semantic Versioning (SemVer) format (MAJOR.MINOR.PATCH).
  • Description: A very short description of the package.

The following option properties may also be defined:

  • Public: Whether the package should be publicly available to users that are not members of the organization.
  • Dependencies: The list of package dependencies.

Please see the illustrative example below:

{
    "name": "@cyberdyne/rgb-color-sensor",
    "version": "1.2.7",
    "description": "A color sensor component with real valued outputs for the R, G and B channels.",
    "public": false,
    "dependencies": {
        "@cyberdyne/color-utils": "1.0.0"
    }
}

You can re-export any types from the index.ts file:

export { ColorSensor, ColorSensorIO } from "./ColorSensor";

Alternatively, you can define and export the types from directly inside the index.ts file:

export class ColorSensorIO extends IO {
    // ...
}

export class ColorSensor extends Component {
    // ...
}

The easiest way to start creating a package is to right-click in the file explorer and select New Item from the context menu. This will open a dialog menu, which allows you to select from one of the templates. Select Package from the dropdown to create all the necessary files required to publish a package.

Publishing

Please check over your package carefully before publishing. Published packages CANNOT be deleted. You can only publish a new version of the package if it already exists. To publish the package, right-click on the package.json file in the script editor and select Publish from the context menu.

Security

Before installing or updating packages, please check the contents of the package to ensure there are no malicious code contained in the package. To do this, click the button to the right of the package’s name in the package manager. This will open a page in your browser, which lists the full contents of the package. Select the Code tab from the menu to the left and then carefully check the contents of each file contained in the package.

Checking the contents of a package is particularly important when installing public packages that are not marked with the verified checkmark. If you suspect a package contains malicious code, please do not install the package and contact us immediately.