Scripting API

Scripting: The Host API (jhmc.*)

Because the script interpreter is completely sandboxed, it cannot access the operating system natively. Scripts interact with the outside world strictly through the jhmc global table, which is injected by the engine.

Most of these API calls require explicit Permissions. Calling a function without the appropriate permission raises an ErrPermissionDenied and immediately aborts the script.

---

Network

(Requires Permission: network)

• jhmc.http_get(url) -> string Performs an HTTP GET request and returns the body as a string. (Limited to 64 MiB).

• jhmc.http_json(url) -> table Performs an HTTP GET request and automatically parses the JSON response into a Lua table.

• jhmc.download(url, opts) -> path Downloads a file from a URL, streaming progress to the UI. Returns the absolute destination path.

  • opts.dest: (Required) The destination path relative to the server directory.
  • opts.sha256 or opts.sha1: (Optional) If provided, the engine will verify the downloaded file against this checksum and fail if it doesn't match.

• jhmc.http(opts) -> {status, body, headers} Full HTTP client. opts: url (required), method (default "GET"), body, headers (table), timeout (seconds, default 30), max_body (bytes, default 64 MiB). Non-2xx responses are returned, not raised, so scripts can branch on status. Response headers keys are lower-cased.

---

Filesystem

(Requires Permission: fs_server)

All filesystem paths are relative to the server directory. Accessing files outside the server directory is strictly prohibited (Zip-slip and path traversal protections apply).

• jhmc.fs.read(rel) -> string Reads a file and returns its contents.
• jhmc.fs.write(rel, data) Writes string data to a file, creating parent directories if they don't exist.
• jhmc.fs.exists(rel) -> bool Tests if a file or directory exists.
• jhmc.fs.glob(rel) -> { string, ... } Lists all paths matching a relative glob pattern.
• jhmc.fs.mkdir(rel) Creates a directory and any necessary parents.
• jhmc.fs.remove(rel) Recursively removes a path.
• jhmc.unzip(zipRel, destRel) Safely extracts a ZIP archive into a destination directory within the server folder.
• jhmc.copy_bundled(name, destRel) -> destRel Copies a file that was bundled alongside the script (e.g., a .jar uploaded with a custom provider) into the server directory.
• jhmc.zip_read(zipRel, name) -> string|nil Reads one entry from a zip/jar under the server directory (≤ 16 MiB); nil when the entry is absent.
• jhmc.zip_entries(zipRel) -> { string, ... } Lists all entry names within a zip/jar file.

---

Process / Java

(Requires Permission: install)

• jhmc.resolve_java(major[, useJDK]) -> path Resolves a java.exe binary for the requested Java major version, downloading it automatically if necessary. Set useJDK to true to require the full JDK (needed for compile tools like Spigot BuildTools).
• jhmc.run_jar(opts) Runs an installer .jar (like Forge, NeoForge, or BuildTools) with streaming progress logs.
  • opts.java_major: The required Java version.
  • opts.jdk: Set to true to use the full JDK.
  • opts.args: A list of arguments to pass to the Java process.
  • opts.dir: (Optional) Run the process in a specific subdirectory relative to the server dir.

---

Miscellaneous

(No Permissions Required)

• jhmc.sha256(rel) -> hex Calculates and returns the SHA-256 hash of a file within the server directory.
• jhmc.java_major_for(mcVersion) -> number Maps a Minecraft version string (e.g., "1.20.4") to the standard Java major version required by Mojang (e.g., 21).
• jhmc.json_decode(string) -> value Parses a JSON string into a Lua table/value.
• jhmc.json_encode(value) -> string Serializes a Lua value into a JSON string.
• jhmc.toml_decode(string) -> table Parses TOML into a Lua table (e.g., mods.toml).
• jhmc.yaml_decode(string) -> value Parses YAML into a Lua value (e.g., plugin.yml).
• jhmc.time() -> number Returns the current UTC Unix time in seconds (fractional).
• jhmc.log(line) Appends a raw string directly to the installation/automation log.

---

Persistent Storage

(No Permissions Required. Available for automation and shop scripts)

Each automation script gets an isolated key-value store persisted at <data>/script-data/<scriptID>.json. Keys and values are strings. The store is unavailable during import/meta-parse and in provider scripts.

• jhmc.store.get(key) -> string|nil Reads a key (nil when absent).
• jhmc.store.set(key, value) Writes a key.
• jhmc.store.delete(key) Deletes a key (absent key is a no-op).
• jhmc.store.keys() -> { string, ... } Returns all keys, sorted alphabetically.

Navigation

• Back to the Scripting Hub