Module Creation Basics

Introduction

Modules can include QML files and/or Qt Plugins for their content. These are linked through module.json.

The basic directory structure of a module is:

[Short Module Name]
├── config.json
├── module.json
└── [QML files]

module.json

Inside module.json contains the information needed to properly load the module. Example:

{
    "name": "Example Module",
    "description": "An example module to show off Stardust",
    "author": "technobaboo",
    "source": "https://github.com/technobaboo/stardust-example-module",
    "website": "https://stardustxr.org",

    "version": "1.0.0",
    "id": "org.stardustxr.example",
    "type": "generic",

    "qml": [
        "Example.qml"
    ],
    "binaries": [
        "example_binary"
    ],
    "deps": [
        "org.stardustxr.logmessage"
    ],
    "autostart": [
        "Example.qml"
    ]
}

All paths are relative to module.json.

All available properties:

name - The long name for the module, shown on the module install page and in settings for disabling/enabling the module.

description - The description for the module, shown on the module install page and in settings for disabling/enabling the module.

author - The name or username of the company/individual who originally created this module.

source - If this module is open source, put the link to the source code here (GitHub, GitLab, SVN, etc.) Otherwise, don't include this property. Forks are allowed here as long as they still have a reference to the original module.

website - If this module has a website or page that is not its source, put the link here. Otherwise, don't include this property.

version - The version for the module, used to determine if any modules that depend on it are able to use it. Must have 3 version numbers (e.g. 1.0.0, 0.1.0).

id - The ID for your module. This must match the ID used if you are creating a Qt Plugin as your module content.

type - The type of module. This must be one of generic, app-shell, lens, lens-frame, panel, panel-shell, keyboard or keyboard-adapter.

qml - An array containing paths to QML components to load. The QML components will be loaded in order. The last one will be instanced and placed into the space when your module is enabled. If this property is present then the binaries will not be instanced, but will be accessible from QML instantly.

binaries - An array containing paths to compiled binary Qt plugins to load. Each binary will be loaded in order. The last one will be instanced and placed into the space when your module is enabled unless there are QML files to load.

deps - An array containing the IDs of all module dependencies. If a dependency is not found the module will not load and will print an error to the log. If no module dependencies are needed, do not include this property.

autostart - An object containing an array containing the QML filenames of objects to instantiate immediately after the module is created. These will be instantiated in order.

config.json

config.json contains the default configuration, including both user and system properties. All system properties may be overwritten by root, and all user properties may be overwritten by the user at any time.

Example:

{
    "system": {
        "init_message": "Example module has successfully loaded!"
    },
    "user": {
        "message": "Hello, World!"
    }
}

You may leave out the system or user objects and they will not be used.