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.

---

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.

---

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.log(line) Appends a raw string directly to the installation/automation log.

Navigation

• Back to the Scripting Hub