muddy

HEY!

HEY!

Do you love muddler?? ME TOO!!! If you don't, then you it only stands to reason that you are entirely ignorant of the amazing work of @demonnic. And that is inexcusable. Because he is a god and you need to worship at the altar that is his amazing work.

That said, I wish it weren't written in Java, cos I can't help. :'(

But I know a few bars of JavaScript.

I have tried to make muddy work as closely to muddler as I could. Maybe it worked, maybe I failed miserably. idfk, it Works on My Computer™.

My version is a clean-room implementation and I haven't even peeked at demonnic's, because, frankly, as implicated above, I am woefully inadequate for the Java. Which, honestly? I'm fine with.

So, if you want to use muddy, the syntax is the same. The structure it expects is the same. The output is... errr, probably... the same... ish?

I'm not gonna re-teach you how to use an identical cli-based thing, when, to repeat, the amazing god that is demonnic has already strived... strove... striven? to do it already and it's great.

The only difference between invoking muddy over muddler is the cli.

Immediate Invocation

npx @gesslar/muddy --help

Install as a dependency, if you want, you don't have to

npm i -d @gesslar/muddy

Features unique to muddy

Add modules

muddy can scaffold new modules directly from the command line using --add. This creates the type directory (if needed), adds an entry to the {type}.json with all available fields from the schema pre-filled, and creates an empty .lua file — ready for you to fill in.

# Add a named script
muddy . --add script --name "My Script"

# Add an alias with auto-generated temp name (new_alias_1, new_alias_2, ...)
muddy . --add alias

# Short form
muddy . -a trigger --name "Health Warning"

Valid types: alias, key, script, timer, trigger.

Ignore patterns

muddy supports an ignore field in your mfile that lets you exclude files from both module collection and resource injection. This is not available in muddler.

Add an ignore array to your mfile with glob patterns:

{
  "package": "MyPackage",
  "version": "1.0.0",
  "ignore": ["**/drafts/**", "**/wip/**", "**/experimental_*"]
}

Patterns are matched against relative paths within src/. They apply to:

• Module collection — any scripts.json, aliases.json, etc. matching an ignore pattern will be skipped entirely, along with their associated Lua files.
• Resource injection — any files under src/resources/ matching an ignore pattern will not be copied into the .mpackage.

Standard glob syntax is supported (e.g. *, **, ?). If ignore is omitted or empty, all files are included as usual.

Watch mode

Run muddy with -w (or --watch) to build once and then rebuild automatically whenever a file in src/ or your mfile changes.

muddy . --watch

While watch mode is running, a few keys are available:

• r — force a rebuild immediately, without waiting for a file change.
• Ctrl+C / Ctrl+D — quit watch mode and restore the terminal. q is a convenience alias for the same.

Version management

muddy can bump, print, or set the semantic version in your mfile directly, without the clean-tree-and-commit requirements of npm version.

# Bump
muddy version patch          # 1.2.3 -> 1.2.4
muddy version minor          # 1.2.3 -> 1.3.0
muddy version major          # 1.2.3 -> 2.0.0

# Print the current version (plain stdout — friendly to $(…) capture)
muddy version current

# Set explicitly
muddy version set 4.5.6

# Keep a sibling package.json in sync with the version just written
muddy version patch --package
muddy version set 4.5.6 --package

The mfile is rewritten in place via a targeted regex, so existing formatting (quote style, spacing, key order) is preserved. No git commit or tag is created — that's left entirely up to you.

Pass --package to also write the new version into a package.json in the same directory, using the same formatting-preserving rewrite. If there's no package.json (or it has no version key), the mfile is still bumped and you get a warning that nothing was synced; add --no-warn to suppress it.

Unpack an mpackage

muddy also runs in reverse: hand it a built .mpackage and it explodes it back into an editable muddy project — src/<type>/ definitions, their .lua files, nested folders, resources, and a reconstructed mfile. Muddy, but backwards. (Yes, a bit like DeMuddler — imitation is the sincerest form, and all that.)

# Unpack into ./MyPackage (named after the .mpackage)
muddy unpack MyPackage.mpackage

# ...or into a directory you name
muddy unpack MyPackage.mpackage some/where

It reconstructs the project the way you'd expect — definitions, scripts, load-order within each list, folders, resources, and metadata all come back — including pattern types, key chords, trigger highlights, and event handlers. Edit and rebuild like any muddy project.

Two conveniences come along for the ride:

• A ready-to-go helper. By default, unpack drops a <Package>.MuddyHelper.lua beside your mfile, pre-wired to the directory you just unpacked into. Plunk it into Mudlet (below the Muddy package in the Scripts tree) and you're hot-reloading immediately — no hand-rolled watcher required. Pass --no-helper to skip it. If you don't know what I'm talking about, maybe it's because you haven't read ahead. But everything will be okay, because once you've read the next section, you can reverse engineer your brain to complete understanding. This is by design. Are you wanting more? There's more.
• Sensible description handling. The build folds mfile.description (or, if it's empty, your README.md) into the package, and the two are indistinguishable afterwards. By default the description is restored verbatim into mfile; if it's really docs, pass --readme to write it to README.md instead. By intent, never by guesswork.

Muddy the mpackage

You can also hot-reload your packages in Mudlet by installing the Muddy mpackage. Edit your source, rebuild it, or let it rebuild automatically in watch mode, and Muddy will see it, uninstall your current package, and then reinstall it for you. Neat, huh?

To install, simply run:

lua installPackage("https://github.com/gesslar/Muddy/releases/latest/download/Muddy.mpackage")

Once installed in Mudlet, open the package manager (Alt-O) and check out the documentation to see how to use it!

Post Hocktuah

Also, shout out to @Edru2 for DeMuddler which is just sex on a stick.

Which is exactly how everybody likes their sex, yes? Yes. Okay.

Postmate

did you know there's a javascript.com?? I just found that out. holy shit.

License

@gesslar/muddy is released under the 0BSD.

This package includes or depends on third-party components under their own licenses:

| Dependency | License | | --- | --- | | @gesslar/actioneer | 0BSD | | @gesslar/colours | 0BSD | | @gesslar/toolkit | 0BSD | | adm-zip | MIT | | chokidar | MIT | | commander | MIT | | xmlbuilder2 | MIT |