Scripting Providers

Scripting: Provider Scripts

A provider script defines how JustHostMC installs and launches a specific server type (Vanilla, Paper, Fabric, Forge, etc.).

Built-in providers are located in the engine at engine/internal/scripting/builtin/.

A provider script must define a global meta table and two global functions: versions() and install(ctx).

The meta Table

The metadata table identifies the provider and requests permissions.

meta = {
  id          = "vanilla",                    -- REQUIRED: stable, unique provider id
  name        = "Vanilla",                    -- Display name
  website     = "https://www.minecraft.net",  -- Official website
  description = "The official Minecraft server from Mojang.",
  version     = "1.0.0",                      -- Script version
  author      = "JustHostMC",
  mod_layout  = "none",                       -- "plugins" | "mods" | "none"
  permissions = {
    { kind = "network", reason = "Download Mojang's manifest and server jars." },
  },
}

• id: (Required) Unique identifier. Omitting this causes a load error.
• mod_layout: Instructs the UI on how to present add-ons. Use plugins for Spigot/Paper, mods for Fabric/Forge/NeoForge, or none for Vanilla.
• permissions: Required grants for the script to execute specific host functions. See Scripting Permissions.

The versions() Method

This method is called to populate the version picker in the UI. It should return a list (Lua table) of strings, usually sorted newest-first.

function versions()
  local m = jhmc.http_json("https://piston-meta.mojang.com/mc/game/version_manifest_v2.json")
  local out = {}
  for _, e in ipairs(m.versions) do 
    out[#out + 1] = e.id 
  end
  return out
end

To report that a specific version doesn't exist during an install, you can throw an error: error("version not found: <id>").

The install(ctx) Method

This method downloads the required files into the server directory and returns the launch specification.

The ctx Object

• ctx.dir: Absolute path to the isolated server directory (all filesystem operations are confined here).
• ctx.version: The target version string chosen by the user.
• ctx.step(key, frac): UI progress indicator. key is a localization string, frac is a float from 0.0 to 1.0 (or -1 for indeterminate).
• ctx.log(line): Appends a raw string to the install log.

Return Value (Launch Spec)

Once installation is complete, the script must return a table containing the Java requirement and arguments.

return { 
  java_major = 21, 
  args = { "-jar", "server.jar", "nogui" } 
}

The engine uses this launch spec to prepare the Container Environment.

Importing Custom Providers with Bundled Jars

A user can import a custom provider that ships with a bundled jar (for example, a server jar that does not have a public download URL). The ProviderService.Import method handles uploading both the .lua source and the .jar bytes.

Inside the install(ctx) method, the script can copy this bundled jar directly into the server directory using jhmc.copy_bundled:

-- copy the jar that was bundled at import time into the server dir
jhmc.copy_bundled("my-server.jar", "server.jar")  -- requires fs_server

return { 
  java_major = 21, 
  args = { "-jar", "server.jar", "nogui" } 
}

Navigation

• Back to the Scripting Hub