RMMZ Best practices for a plugin using multiple files

Jragyn

JABS codemonkey
Veteran
Joined
Aug 14, 2012
Messages
180
Reaction score
152
First Language
English
Primarily Uses
RMMZ
As the primary author for JABS, I'm extremely proud about how far it has come!
Since about three weeks into the development process (when I made the first visible achievement: a slash appeared when the button was pressed), I've been driving this on with the flames of 1000 excited suns that never thought they'd be able to write something like this!

However, there is one significant pain point I've run into with this big beautiful plugin: it's length. The thing is so dang big! With all the comments/jsdocs/documentation I've written into the code, it just surpassed the 11k-lines-long mark the other day (if you don't really know what that translates to in regards to being a "pain point", go look here and search for the word "battler" and find the logic that checks if the battler is the player or not). As I've mentioned, by day I'm also a developer, doodling up web APIs and stuff for backend servers and sometimes working with frontend apps written in various frameworks. In both of those instances, there is plenty of organization with folder structure and whatnot.

My outstanding question that I haven't really seen anything about:
Is there a best practice for developing a plugin that leverages multiple external files? Not to be confused with adding additional plugins. I know that RPG Maker MZ (and MV) leverages nodejs behind the scenes to spin up the app, so I have tried to create folders and move smaller datacontract-like files back there, but these files seem to lose reference/knowledge of all the rest of the code that makes up RMMZ (presumably because its not included as a "plugin"). I've also debated trying to maybe use typescript and just output my plugins, but that sounds kinda hacky...
 

 Masked 

Assistant
Veteran
Joined
Oct 28, 2015
Messages
111
Reaction score
289
First Language
Portuguese
Primarily Uses
RMMZ
I wouldn't say "best practices", but I made a simple archetype using rollup to build plugins from multiple files using Typescript which might be helpful as a reference: https://github.com/comuns-rpgmaker/typescript-plugin-archetype

There's also a Babel counterpart, if you don't want/need Typescript: https://github.com/comuns-rpgmaker/babel-plugin-archetype

Both work best with VS Code. They have some neat features like generating plugin metadata from a YAML file, running unit tests (although, admittedly, I didn't really use this one a lot haha), generating docs integrated with Github Actions, automatically minifying the generated JS file and whatnot. Ideally, those are all fairly easy to use and customize once you learn a bit about Rollup (which I'm not an expert with in any way).

I'm not very familiar with node as an ecossystem, so there might be some issues with the organization in these, but at the very least I think they serve as a neat reference for what you want.

For usage examples, I have used the typescript archetype to build my pathfinding plugin, which you can find on github too (with added bonus of compiling some WASM with Emscripten and embedding it into the plugin): https://github.com/comuns-rpgmaker/schach-pathfinding
There's also my parser plugin, which is purely Typescript: https://github.com/comuns-rpgmaker/schach-parsing
 

Jragyn

JABS codemonkey
Veteran
Joined
Aug 14, 2012
Messages
180
Reaction score
152
First Language
English
Primarily Uses
RMMZ
Holy crap my dude, that is some impressive work!
Looking at the two projects you've provided, it looks like with a bit of wiggling, I may be able to get that to work. I'll have to give it a whirl and see if I can make that work- being able to write in TypeScript and actually leverage organization for my own sanity would be a great boon!

Thank you kindly, Masked person. I'll have to come back and share my results when I get a chance to test this out. Breaking JABS into a collection of files would be so wonderful! <3
 

Jragyn

JABS codemonkey
Veteran
Joined
Aug 14, 2012
Messages
180
Reaction score
152
First Language
English
Primarily Uses
RMMZ
Alright, a couple weeks later, and I've given both of those repos a whirl (just this morning) and here are my thoughts:

I like the typescript template.
It takes a little bit to get it working, but once it is, having the type safety net is pretty nice. It doesn't appear to have all RMMZ definitions, though. The main plugin I wanted to use it for- JABS- revolves heavily around manipulation of events, and it doesn't seem any definition files are available for mostly anything under Game_Character (including Game_Event). This doesn't make it useless, as I know I can probably go sort out a means to generate the .d.ts files based on the code and all that, but it was more effort than I was willing to put forth at the time.

The javascript template is also nice.
I started with the typescript one, and moved to the javascript one second, so I knew what to do to get it up and running. Probably due to local configuration, my VS Code had one hell of a time trying to get babel and eslint to play nice with eachother in the context of JABS. I have like, 1x ES6+ static property on a class, and so I had to flex my google-fu to figure out how to resolve it (I'm not super versed in rollup/webpack/babel/etc). Eventually I did. I could probably tear apart JABS into a series of tiny files, however, it seems that the ULTRA SLICK AND USEFUL yaml-to-RMMZ-metadata didn't really know what to do with the concept of "@parent" params. Now, this could also be user error, as I didn't read any documentation for it (just followed the errors in my terminal till it stopped whining). I'm also not really sure what to do about custom structs for the metadata, which is used by JABS. But I can't stress enough that YAML is way more readable than the native structure for plugin metadata.

End result:
I think I need more documentation on how to leverage the plugin metadata tool, and/or for its capabilities to be expanded to include the full suite of functionality associated with RMMZ annotations (thats the official term, right?). If they are already there, then I assume I just did something wrong and would doubly ask for documentation that I didn't see. Then I'd revisit this and try again, most certainly. 12k lines of code in 1 file is not really that fun... (though I've gotten pretty good at #region organization and CTRL+F)
 

 Masked 

Assistant
Veteran
Joined
Oct 28, 2015
Messages
111
Reaction score
289
First Language
Portuguese
Primarily Uses
RMMZ
First of all, thanks for taking the time to test them and tell your experience, it's super helpful to have feedback on this stuff \o

The Typescript template is indeed lacking many definitions, unfortunately. We're using the typescript definitions put together by @nio kasgami here: https://github.com/niokasgami/Rpg-Maker-MZ-Typescript, but I haven't had much time to contribute to them (and I imagine he has the same problem). I've seen some oher people building their own type declarations for the rmmz library, so maybe I could try contacting them and figuring out a way to integrate a more complete collection into the template. As a workaround, I've been doing the declarations I need in-loco (e.g. Game_Character on my pathfinding plugin). It has worked fine for me so far, but I imagine for a more complicated system that interacts more deeply with the standard classes (of which an ABS would probably be the worst-case example xd) this would be an issue.

I haven't really put the Babel archetype through much use myself, so maybe there're some rough edges on the configuration there, I'll try looking into the Babel + ESLint issue. If you have the time, it would be very helpful if you could open an issue on the repository with more details.

Regarding the plugin-metadata.yaml: it can actually handle nested (@parent) parameters, but it works the other way around (you specify children instead of parents) xd
For instance, if you have params foo and bar, and foo should be the @parent of bar, your YAML would look like this:

Code:
target: MZ
author: You
url: https://github.com/me/my-plugin
description: Lorem Ipsum
help: |-
  Lorem Ipsum
params:
  - name: foo
    text: Foo
    type: text
    description: This is a Foo
    children:
      - name: bar
        text: Bar
        type: number
        description: This is a Bar

I think this makes it a lot cleaner and avoids much of the repetition you have to do when adding @parent tags to each parameter on a hierarchy, but I could add a parent field on the YAML spec too if you think that would help (maybe it could be useful for flattening deeply nested parameter hierarchies? idk)

I actually posted a more in-depth explanation of the features this tool supports some time ago (there are also some examples for structs and plugin commands), you may want to give it a look: https://forums.rpgmakerweb.com/index.php?threads/rmmz-plugin-metadata-generator-from-yaml.127610/

I hope that helps, and thank you again for your time \o
 

Jragyn

JABS codemonkey
Veteran
Joined
Aug 14, 2012
Messages
180
Reaction score
152
First Language
English
Primarily Uses
RMMZ
I actually posted a more in-depth explanation of the features this tool supports some time ago (there are also some examples for structs and plugin commands), you may want to give it a look: https://forums.rpgmakerweb.com/index.php?threads/rmmz-plugin-metadata-generator-from-yaml.127610/
Ahh, well damn. Maybe I'll have to give it another pass, then. You're not wrong though, YAML definitely makes this look way nicer than that weird... I don't even know what that kind of syntax is called? I don't recognize it, but it feels clumsy comparitively.

Regarding the plugin-metadata.yaml: it can actually handle nested (@parent) parameters, but it works the other way around (you specify children instead of parents) xd
I got it backwards, oof! If only I read that documentation that you wrote out a half year ago... And regarding nesting, I think its fine. I was simply trying to match what I saw in the default annotations format that MZ uses and I've seen in other plugins. The other things worked (defaults, descriptions, etc.), but that didn't. Though, I would say that the @description I don't think should be required (as in, fail to compile without it). Typically when using the nesting, I do it for organization over actually needing some amount of purpose in the parent annotation itself. But... thats also my personal preference. I see that VisuStella often uses parents to put more various options into.

It has worked fine for me so far, but I imagine for a more complicated system that interacts more deeply with the standard classes (of which an ABS would probably be the worst-case example xd) this would be an issue.
I debated doing that as well, but as you're indicating would probably get out of hand fast. :( No worries though, I don't hold it against you! I also grabbed that same package initially from the link you provided, but then I found the Lunalite for MZ intellisense definitions, and that was enough for my intellisense requirements of VS Code and to keep me sane (maybe that can be leveraged somehow?).

First of all, thanks for taking the time to test them and tell your experience, it's super helpful to have feedback on this stuff \o
Last but not least, it is no trouble. As a fellow developer, I recognize that it helps to give things a run through and have some external testing done on it from time to time. I'll see if I can carve out some time now to file an issue against your repo regarding the details of babel and versioning etc.
 

nio kasgami

VampCat
Veteran
Joined
May 21, 2013
Messages
8,965
Reaction score
3,072
First Language
French
Primarily Uses
RMMV
Hi yes i didnt had much time to contribute its very tedious to do haha

I also use the archetype for my game but how i do my stuff is quite special
 

Jragyn

JABS codemonkey
Veteran
Joined
Aug 14, 2012
Messages
180
Reaction score
152
First Language
English
Primarily Uses
RMMZ
Hi yes i didnt had much time to contribute its very tedious to do haha
No worries! You've done great work, its quite lovely albeit incomplete. Maybe sometime in the future I'll get around to it.

I actually posted a more in-depth explanation of the features this tool supports some time ago (there are also some examples for structs and plugin commands), you may want to give it a look: https://forums.rpgmakerweb.com/index.php?threads/rmmz-plugin-metadata-generator-from-yaml.127610/
Not sure if you'd like this here or on the actual thread itself, but I came back to this and decided "why not? I'll try to make this work." and set about using the metadata generator with mostly success. However, I think I'm just being dumb when it comes to syntax or something because your code looks right, but I've got this:
1617836028611.png

Trying to make a command... with args... and one of those args is a select/dropdown thing. Due to the schema, I pretty much can't really enter this much differently, but it seems that the options array isn't getting translated, so I am wondering if I'm missing another property that isn't required but... secretly is maybe? I've tried various permutations of white space, but it seems at the end of the day, this works for other configuration lines, but the output of this looks something like:
1617836162013.png
with all options completely missing. Like I said, I peeked at the code and it _looks right_, but I couldn't really confirm or deny that better than you.

Thoughts?

(I did test this successfully btw, though I manually copy-pasted the plugin settings from my already-made version of the plugin, so even with 13k lines of code, this nifty tool rolls it up nicely!)
 

 Masked 

Assistant
Veteran
Joined
Oct 28, 2015
Messages
111
Reaction score
289
First Language
Portuguese
Primarily Uses
RMMZ
Sorry for taking so long to respond, these weeks have been kinda wild and I ended up not having much time to spare for looking into this.

I've looked into it briefly and the issue seems to be that the script never actually calls the function that was supposed to generate these annotations in particular (this one) xd
It's pretty straighforward to fix, I'll try release a fixed version tomorrow \o

I did test this successfully btw, though I manually copy-pasted the plugin settings from my already-made version of the plugin, so even with 13k lines of code, this nifty tool rolls it up nicely!

That's great to hear! I'm glad it could be of use to someone else.
 

Jragyn

JABS codemonkey
Veteran
Joined
Aug 14, 2012
Messages
180
Reaction score
152
First Language
English
Primarily Uses
RMMZ
I've looked into it briefly and the issue seems to be that the script never actually calls the function that was supposed to generate these annotations in particular (this one) xd
lmao its always the little things that get us. Thanks pal for looking into it. I'll check back in a few days or whenever ya say you've got it fixed and try again.
 

 Masked 

Assistant
Veteran
Joined
Oct 28, 2015
Messages
111
Reaction score
289
First Language
Portuguese
Primarily Uses
RMMZ
@Jragyn It's fixed \o

You may upgrade it on your project by running npm i -D @comuns-rpgmaker/plugin-metadata@0.2.4 (I think just running npm install might do it too)

I also wrote some tests to make sure everything else was working fine and it seems like it is now (the schema for arrays was kinda broken too, good thing I tested it haha)

What's neat is that the test cases now can serve as a reference, so no need to rely entirely on the schema or the documentation (which is admiteddly kinda hard to read haha) anymore. You can check them here if you need: https://github.com/comuns-rpgmaker/plugin-metadata/tree/master/test/cases, they're organized as pairs of YML and JS files, where the .yml would be the input and the .out.js would be the expected output.
 

Latest Threads

Latest Profile Posts

Generate Actors, Dark Fantasy Monsters, & I Heard There Was a Chosen One, | RPG Maker News #42

Work on Cat Quest: The Last Catmancer continues slowly but surely. :kaopride: Today I received the Game Over screen from @Finnuval!
GameOver.png
Hey everyone! No Studio Blue RPG Maker Critiques Stream today! But you can always check the playlist for old streams you've missed!

I ran out of paper sheets to draw, so I guess I'm forced to do digital for a while now...
x778xt8.jpg

Still haven0t found a colouring style that I like :kaoswt:

Forum statistics

Threads
111,443
Messages
1,061,144
Members
144,806
Latest member
HowlingMeteor277
Top