RMMZ Plugin metadata generator from YAML

 Masked 

Assistant
Veteran
Joined
Oct 28, 2015
Messages
90
Reaction score
261
First Language
Portuguese
Primarily Uses
RMMZ
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:
Bash:
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:
YAML:
---
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:
Bash:
mz-mtdt -i plugin-metadata.yaml
And it'll print out the resulting comment header:
JavaScript:
/*:
* @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:
    YAML:
    ---
    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:
    JavaScript:
    /*:
    * @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:
    YAML:
    ---
    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:
    JavaScript:
    /*:
    * @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:
    YAML:
    ---
    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:
    JavaScript:
    /*:
    * @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:
    YAML:
    ---
    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:
    JavaScript:
    /*:
     * @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
 
Last edited:

Hudell

Dog Lord
Veteran
Joined
Oct 2, 2014
Messages
3,544
Reaction score
3,714
First Language
Java's Crypt
Primarily Uses
RMMZ
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

VampCat
Veteran
Joined
May 21, 2013
Messages
8,949
Reaction score
3,042
First Language
French
Primarily Uses
RMMV
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!
 

Users Who Are Viewing This Thread (Users: 0, Guests: 1)

Latest Threads

Latest Posts

Latest Profile Posts

Tomorrow is Thanksgiving, and I'm so excited! I've been exploring MZ a little, and I just downloaded Effekseer to make new animations. I have experience in 3D animation software, so I'll be pretty good at the whole "particle" thing. My first game on MZ will be Fantasy Force--starring a griffin, a dragon, and a pegasus fighting against the Dragon of Darkness.
currently listening to Driftwood Gaming streaming some MZ dev time and it's delightful! had no idea they were this entertaining, love it
In quarantine, will be tested soon. This year is really something... special.
I was at another orientation yesterday and I realized I'll be working with an old friend! We met at the local water park a few years back and it was so nice to see her again! We had a chat, and next week when I officially start, I'll see if maybe we can trade our Zoom IDs so we can talk!
I made some sideview closets for MV!
You can find them in my MV resource thread.

Forum statistics

Threads
105,512
Messages
1,014,337
Members
137,198
Latest member
mmc1980
Top