RMMZ Plugin metadata generator from YAML

[Masked]

Hey \o

Introduction

So, I've been working on a tool for generating plugin metadata/annotations from a YAML file. It's a simple script that gets a path to a plugin metadata file as input (can be YAML or JSON, but I think we can all agree YAML is clearly superior) and spits out a comment header that'll work on RMMZ (either on the stdout or into a file).

Github Repository: https://github.com/comuns-rpgmaker/plugin-metadata

Advantages

• A JSON Schema can provide intellisense and insightful error messages for the metadata file, whereas a mistake on a comment header would be undetectable unless you actively go to the plugin manager and see if it worked as expected (also no intellisense);
• More maintainable than a header comment, specially when internationalization comes into play;
• When building from multiple files (see our plugin archetypes for Babel and Typescript for example), it's definitely more elegant to separate plugin metadata from actual code, and a YAML/JSON file is perfect for the task.

Basic Usage

First of all, you must install the CLI via NPM:

npm install -g @comuns-rpgmaker/plugin-metadata

This should make it available on PATH as mz-mtdt. To get usage help, run mz-mtdt --help.

Basically, all you have to do is create a YAML file (let's say plugin-metadata.yaml) like this:

---
target: MZ
author: You
url: https://github.com/me/my-plugin
description: My plugin
help: |-
  My Plugin

  This is my plugin!

Then run the CLI passing it as input:

mz-mtdt -i plugin-metadata.yaml

And it'll print out the resulting comment header:

/*:
* @target MZ
* @author You
* @url https://github.com/me/my-plugin
* @plugindesc My plugin
* @help My Plugin
*
* This is my plugin!
*/

Supported Features

All currently available features of plugin annotations are available for generation with the CLI, altough some have not been thoroughly tested. This includes but is not limited to:

• Multiple languages: You can define localized descriptions for the plugin, its parameters and basically anything else; This is achieved by declaring a languages field on the metadata and (optionally) having a string for each language on text fields. For instance:

  ---
  target: MZ
  author: Masked
  
  languages:
      - pt
  
  description:
      default: A simple internationalized plugin.
      pt: Um plugin internacionalizado simples.
  
  help:
      default: |-
          My plugin.
  
          This plugin does things.
  
      pt: |-
          Meu plugin.
  
          Este plugin faz coisas.

  And the generated output would look like this:

  /*:
  * @target MZ
  * @author Masked
  * @plugindesc A simple internationalized plugin.
  * @help My plugin.
  *
  * This plugin does things.
  */
  /*:pt
  * @target MZ
  * @author Masked
  * @plugindesc Um plugin internacionalizado simples.
  * @help Meu plugin.
  *
  * Este plugin faz coisas.
  */

  Keep in mind that the language codes are limited to those already supported by MZ.
  
• Structs:
  

  ---
  target: MZ
  author: Masked
  description: A simple plugin with structs.
  help: My plugin.
  
  params:
      - name: struct1
        struct: MyStruct
        text: Struct 1
        description: A struct.
  
  structs:
      - name: MyStruct
        params:
          - name: field1
            text: Field 1
            description: A numeric field.
            type: number
  
          - name: field2
            text: Field 2
            description: A text field.
            type: text

  And the output comes out like this:

  /*:
  * @target MZ
  * @author Masked
  * @plugindesc A simple plugin with structs.
  * @help My plugin.
  *
  * @param struct1
  * @type struct<MyStruct>
  * @text Struct 1
  * @desc A struct.
  */
  /*~struct~MyStruct:
  *
  * @param field1
  * @type number
  * @text Field 1
  * @desc A numeric field.
  *
  * @param field2
  * @type text
  * @text Field 2
  * @desc A text field.
  */

• Plugin Commands:

  ---
  target: MZ
  author: Masked
  
  description: A simple plugin with a command.
  help: My plugin.
  
  commands:
      - name: my_command
        text: My command
        description: This is a simple command with arguments
        args:
          - name: arg1
            type: number
            text: Argument 1
            description: This is a simple numeric argument to a command

  And the output comes out like this:

  /*:
  * @target MZ
  * @author Masked
  * @plugindesc A simple plugin with structs.
  * @help My plugin.
  *
  * @command my_command
  * @text My command
  * @desc This is a simple command with arguments
  * @arg arg1
  * @type number
  * @text Argument 1
  * @desc This is a simple numeric argument to a command
  */

• Parameter Nesting: (the @parent thing). I did something a little different on this one, and instead of setting a parent property, this is done by declaring the children
  instead of the parents. The reason I did this is because I think it's more structured and less error prone (and also requires less typing). It works like this:

  ---
  target: MZ
  author: Masked
  
  description: A simple plugin with a command.
  help: My plugin.
  
  params:
      - name: parent1
        text: Parent 1
        description: This is a simple parent parameter
        children:
           - name: child1
              text: Child 1
              description: This is a simple child parameter
  
           - name: child2
             text: Child 2
             description: This is a child parameter with children
             children:
                 - name: child2_1
                   text: Child 2.1
                   description: This is a simple parameter...

  And the output comes out like this:

  /*:
   * @target MZ
   * @author Masked
   * @plugindesc A simple plugin with a command.
   * @help My plugin.
   * 
   * @param parent1
   * @text Parent 1
   * @desc This is a simple parent parameter
   * 
   * @param child1
   * @parent parent1
   * @text Child 1
   * @desc This is a simple child parameter
   * 
   * @param child2
   * @parent parent1
   * @text Child 2
   * @desc This is a child parameter with children
   * 
   * @param child2_1
   * @parent child2
   * @text Child 2.1
   * @desc This is a simple parameter...
   */

JSON Schema

The github repo also provides a JSON Schema specification for the metadata file: https://raw.githubusercontent.com/comuns-rpgmaker/plugin-metadata/master/schema/plugin-metadata.json

This schema can be referenced to provide intellisense on editors such as VS Code. You can also check out the Generated Documentation for it.


License

This is all licensed under Zlib.


Any suggestions are welcome, and please feel free to open issues on Github and/or fork the repository and open pull requests. Thank you for your attention \o

 

[Hudell]

Nice work! Would be cool to have it as a rollup plugin that imports the yaml and use it as the plugin banner automatically.

 

[nio kasgami]

Nice work! Would be cool to have it as a rollup plugin that imports the yaml and use it as the plugin banner automatically.

there's one actually hahah but we use it for the typescript plugin archetype!