RMMZ Plugin metadata generator from YAML

 Masked 

Assistant
Veteran
Joined
Oct 28, 2015
Messages
90
Reaction score
258
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,530
Reaction score
3,681
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,039
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

I'm going to schedule my shuttle to the train station today... after I vote. It's not a pleasant thing to do, since I hate politics. So much negative talk. I can see why it's not allowed here. But about the shuttle. My county has a service called PalmTran, and it's really convenient. They pick you up at your home and drop you off where you need to be. Just give them a date and time.
Titlescreen idle movie player, play some videos if the player sits on the titlescreen too long! [free plugin]
"Alert, alert, there is nothing there. Wake up, there is nothing there. This is not a drill, there is nothing there. Oh hey, I see you're awake early on your day off, let's go for a run."~if dogs could talk.
I love October. It starts out with a lighthearted chillvibes. Near the end of the month, it becomes somewhat dreamy and the days feel slower. Maybe because October is the beginning of rainy season in my country. :D
Ami
--- Surprise Part 2 ---

F.Healer: Look,i'm the Cute White Ghost!
F.Mage: And,im the Scary Witch!
M.Archer: I'm The Handsome Vampire!
M.Fighter: AWOOOOOOO!!!
(Suddenly,The Electricity Is Turned Off. Then Turned On 10 Seconds Later)
Hero: (With Scream Mask & Bloody Knife) Hey,how about my Costume?
Entire Party: (Screaming Until Faint)

Forum statistics

Threads
104,505
Messages
1,006,777
Members
136,009
Latest member
Jaeger
Top