Scripting Parsers

Scripting: Mod/Plugin Metadata Parsers

Parser scripts power the per-server Plugins/Mods panel in JustHostMC. For each uploaded jar file, the engine runs the installed parsers until one successfully extracts the metadata (icon, name, version, authors, description, website).

Results are automatically cached per jar, so unchanged jars are never re-parsed. If a parser fails, it is skipped without breaking the mod listing.

Registration & Storage

Built-in parsers (like Fabric, Quilt, Forge, NeoForge, Bukkit) are embedded into the engine. User-imported parsers persist under the data directory's parsers/ folder as .lua files. User-imported parsers start with no permissions granted until the user explicitly consents.

The meta Table

A parser script must declare a global meta table:

meta = {
  id = "parser-example",
  name = "Example Parser",
  formats = { "example.mod.json" },        -- Descriptor files it reads (shown in the UI)
  permissions = {
    { kind = "fs_server", reason = "Read mod jars to extract their metadata" },
  },
}

The parse(ctx) Contract

A parser script must declare a single global parse(ctx) function.

The parse function runs in a fresh sandbox per jar.

function parse(ctx)
  -- ctx.jar is the jar's path relative to the server directory.
  local raw = jhmc.zip_read(ctx.jar, "example.mod.json")
  
  -- If this parser doesn't recognize the format, return nil so the next parser can try.
  if raw == nil then return nil end        
  
  local m = jhmc.json_decode(raw)
  
  -- Returning a table signals a successful match
  return {                                  
    loader      = "example",               -- "fabric"|"quilt"|"forge"|"neoforge"|"bukkit"|"paper"|...
    mod_id      = m.id,
    name        = m.name,
    version     = m.version,
    authors     = { "Alice", "Bob" },       -- Table of strings (or a single string)
    description = m.description,
    website     = m.homepage,
    icon        = jhmc.zip_read(ctx.jar, m.icon),  -- Raw png/jpg bytes (optional)
  }
end

Parsing Details

• Return nil (or nothing) when the jar isn't recognized; the engine will simply run the next parser.
• Every returned field in the table is optional.
• Typical decoders include jhmc.json_decode (fabric/quilt/mcmod.info), jhmc.toml_decode (mods.toml), and jhmc.yaml_decode (plugin.yml).
• A parser may optionally request the network permission to enrich the returned metadata using an online API.

Navigation

• Back to the Scripting Hub