Docs
Powered by

Hooks

Hooks are what give your plugin functionality. They are essentially custom event handlers that can be written in any language. They can run code whenever something happens, or inject new items into some of the data-driven parts of Nitrolaunch. Handlers for hooks are defined in the plugin manifest.

Parts of a Hook

  • ID: Every hook has a unique ID used to identify it
  • Argument and Result: These are the inputs and outputs of the hook. They can be any JSON type, such as a string or object, and depend on which hook you are handling.

How Hooks are Run

Most of the time when Nitrolaunch calls a hook, it will check every plugin that supports that hook, and call the hook on each one to create a final list of results. Handlers are not exclusive; multiple plugins can subscribe to the same hook. However, some hooks are only called on specific plugins. For example, the on_load hook is only called on a specific plugin once it is loaded.

General Hooks

on_load

Called when this plugin is loaded. Can be used to set up state and such.

  • Argument: None
  • Result: None

subcommand

Called whenever one of the subcommands that this hook registers are run. The arguments are the list of arguments that were provided to the subcommand, including the subcommand itself. Note that this hook also takes over output, meaning anything coming from stdout will be output to the console instead.

  • Argument:
{
	"args": string[],
	"instances": {
		"id": InstanceConfig,
		...
	}
}
  • Result: None

add_versions

This hook allows you to add extra Minecraft versions to the version manifest, allowing them to be specified in instance configuration and automatically downloaded. Versions that already exist in the list with the same ID will be replaced, and if they don't already exist, they will be appended to the front as the newest possible version.

  • Argument: None
  • Result:
[
	{
		"id": string,
		"type": "release" | "snapshot" | "old_alpha" | "old_beta",
		"url": string,
		"is_zipped": bool
	},
	...
]

add_translations

Adds extra translations to Nitrolaunch

  • Argument: None
  • Result:
{
	"language": {
		"key": "translation",
		...
	},
	...
}

custom_action

Runs an arbitrary custom action, basically allowing you to define your own hooks. Used often by the GUI.

  • Argument:
{
	"id": string,
	"payload": any
}

  • Result: any

  • id: The custom identifier for this action (can be whatever you want)

  • payload The custom argument for this action run (can also be whatever you want)

Configuration Hooks

add_instances

Adds new instances to the config

  • Argument: None
  • Result:
{
	"inst1": InstanceConfig,
	"inst2": InstanceConfig,
	...
}

add_templates

Adds new templates to the config

  • Argument: None
  • Result:
{
	"prof1": TemplateConfig,
	"prof2": TemplateConfig,
	...
}

save_instance_config

Adds or updates config for an editable custom instance from this plugin, whatever that means for your custom instance

  • Argument:
{
	"id": string,
	"config": InstanceConfig
}
  • Result: None

save_template_config

Adds or updates config for an editable custom template from this plugin, whatever that means for your custom template

  • Argument:
{
	"id": string,
	"config": TemplateConfig
}
  • Result: None

delete_instance

Deletes a plugin instance and it's files

  • Argument:
{
	"id": string,
	"config": InstanceConfig
}
  • Result: None

delete_template

Deletes a plugin template

  • Argument:
{
	"id": string,
	"config": TemplateConfig
}
  • Result: None

add_instance_icons

Adds new options for instance and template icons in the UI

  • Argument: None

  • Result: string[]

The strings can be filesystem paths (often using ${PLUGIN_DIR} for plugin-relative paths) or web links

Instance Setup Hooks

on_instance_setup

Called when an instance is being set up, for update or launch. Can return modifications to make to the launch parameters resulting from installing a certain modification

  • Argument:
{
	"id": string,
	"side": "client" | "server",
	"game_dir": string,
	"version_info": {
		"version": string,
		"versions": [string]
	},
	"old_version": string,
	"loader": Loader,
	"current_loader_version": string | null,
	"desired_loader_version": string | null,
	"config": InstanceConfig,
	"internal_dir": string,
	"update_depth": "shallow" | "full" | "force",
	"jvm_path": string,
	"game_jar_path": string
}
  • Result:
{
	"main_class_override": string | null,
	"jar_path_override": string | null,
	"classpath_extension": [string]
}

add_supported_loaders

Adds extra loaders to the list of supported ones for installation. This should be done if you plan to install these loaders with your plugin.

  • Argument: None
  • Result: Loader[]

get_loader_versions

Gets a list of available versions for a loader. Feel free to make network requests if you need.

  • Argument:
{
	"loader": string,
	"minecraft_version": string
}
  • Result: string[]

remove_loader

Called when the loader of an instance changes, to allow cleaning up old or invalid files. Will be given the loader that needs to be removed.

  • Argument:
{
	"id": string,
	"side": "client" | "server",
	"game_dir": string,
	"version_info": {
		"version": string,
		"versions": [string]
	},
	"loader": Loader,
	"custom_config": {...},
	"internal_dir": string,
	"update_depth": "shallow" | "full" | "force"
}
  • Result: None

Launch Hooks

on_instance_launch

Called whenever an instance is launched

  • Argument: InstanceLaunchArg
  • Result: None

while_instance_launch

Also called when an instance is launched, but is non-blocking, and runs alongside the instance. Can be used for periodic tasks and such.

  • Argument: InstanceLaunchArg
  • Result: None

on_instance_stop

Called when an instance is stopped. This happens when Minecraft is closed or crashes. This hook will not be called if Nitrolaunch crashes while the instance is running.

  • Argument: InstanceLaunchArg
  • Result: None

update_world_files

Called when shared world files are updated on an instance.

  • Argument: InstanceLaunchArg
  • Result: None

Instance Logging Hooks

get_instance_logs

Gets logs for an instance with custom_logging_plugin set. Returns a list of unique log IDs (whatever that means to your plugin) that will be used later with the get_instance_log hook. Returned logs should be ordered oldest to newest if possible.

  • Argument:
{
	"id": string,
	"config": InstanceConfig
}
  • Result: string[]

get_instance_log

Gets the contents of a log for the given instance with an ID returned from the get_instance_logs hook

  • Argument:
{
	"instance_id": string,
	"log_id": string,
	"config": InstanceConfig
}
  • Result: string

Package Hooks

custom_package_instruction

Handles custom instructions in script packages.

  • Argument:
{
	"pkg_id": string,
	"command": string,
	"args": [string]
}
  • Result:
{
	"handled": bool,
	"addon_reqs": [
		{
			"id": string,
			"file_name": string | null,
			"kind": "resource_pack" | "mod" | "plugin" | "shader" | "datapack",
			"url": string | null,
			"path": string | null,
			"version": string | null,
			"hashes": {
				"sha256": string | null,
				"sha512": string | null
			}
		}
	],
	"deps": [
		{
			"value": string,
			"explicit": bool
		}
	],
	"conflicts": [string],
	"recommendations": [
		{
			"value": string,
			"invert": bool
		}
	],
	"bundled": [string],
	"compats": [[string, string]],
	"extensions": [string],
	"notices": [string]
}
  • handled: Whether this instruction was handled or not. Should be false if this instruction is not for your plugin.

Account Hooks

add_account_types

Adds new custom account types

  • Argument: None

  • Result:

[
	{
		"id": string,
		"name": string,
		"color": string
	},
	...
]

handle_auth

Handles authentication with custom account types

  • Argument:
{
	"account_id": string,
	"account_type": string
}
  • Result:
{
	"handled": bool,
	"profile": {
		"name": string,
		"id": string,
		"skins": [
			{
				"id": string,
				"url" string,
				"state": "active" | "inactive",
				"variant": "classic" | "slim"
			}
		],
		"capes": [
			{
				"id": string,
				"url" string,
				"state": "active" | "inactive",
				"alias": string
			}
		]
	} | null
}
  • profile.id: The UUID of the account

get_account_cosmetics

Gets the cosmetics available on a custom account

  • Argument:
{
	"id": string,
	"kind": string
}
  • Result:
{
	"skins": [
		{
			"id": string,
			"url": string,
			"state": "ACTIVE" | "INACTIVE",
			"variant": "CLASSIC" | "SLIM"
		},
		...
	],
	"capes": [
		{
			"id": string,
			"url": string,
			"state": "ACTIVE" | "INACTIVE",
			"alias": string
		},
		...
	]
}

upload_skin

Uploads and activates a new skin for a custom account

  • Argument:
{
	"id": string,
	"kind": string,
	"data": number[],
	"variant": "CLASSIC" | "SLIM"
}

  • Result: None

  • data: The skin data as PNG bytes

activate_cape

Activates or deactivates a cape for a custom account

  • Argument:
{
	"id": string,
	"kind": string,
	"cape": string | null
}
  • Result: None

add_skin_repositories

Adds a repository to search for skins from

  • Argument: None

  • Result:

[
	{
		"id": string,
		"name": string
	}
]

search_skin_repository

Searches a custom skin repository

  • Argument:
{
	"repository": string,
	"search": string | null
}
  • Result:
[
	Skin,
	...
]

Instance Transfer Hooks

add_instance_transfer_formats

Adds information about new transfer formats that this plugin adds support for. Returns a list of formats, including information about features that they support and don't support.

  • Argument: None
  • Result:
[
	{
		"id": string,
		"name": string,
		"import": {
			"modloader": "supported" | "format_unsupported" | "plugin_unsupported",
			"mods": "supported" | "format_unsupported" | "plugin_unsupported",
			"launch_settings": "supported" | "format_unsupported" | "plugin_unsupported"
		} | null,
		"export": {
			"modloader": "supported" | "format_unsupported" | "plugin_unsupported",
			"mods": "supported" | "format_unsupported" | "plugin_unsupported",
			"launch_settings": "supported" | "format_unsupported" | "plugin_unsupported"
		} | null
	},
	...
]

export_instance

Hook called on a specific plugin to export an instance using one of the formats it supports

  • Argument:
{
	"format": string,
	"id": string,
	"config": InstanceConfig,
	"minecraft_version": string,
	"loader_version": string,
	"game_dir": string,
	"result_path": string
}
  • id: The instance ID
  • result_path: The desired path to the output file
  • Result: None

import_instance

Hook called on a specific plugin to import an instance using one of the formats it supports

  • Argument:
{
	"format": string,
	"id": string,
	"source_path": string,
	"result_path": string
}
  • id: The desired ID of the resulting instance
  • source_path: The path to the instance to import
  • result_path: Where to place the files for the imported instance
  • Result:
{
	"format": string,
	"config": InstanceConfig
}

migrate_instances

Hook called to migrate all instances from another launcher using one of the formats this plugin supports

  • Argument: string

  • This is the transfer format to use

  • Result:

{
	"format": string,
	"instances": {
		"id": InstanceConfig,
		...
	}
}

Custom Repository Hooks

add_custom_package_repositories

Adds new package repositories that can be queried and searched

  • Argument: None

  • Result:

[
	{
		"id": string,
		"is_preferred": bool,
		"metadata": RepoMetadata
	},
	...
]
  • is_preferred: Whether this repository should be loaded before or after repositories like std and core
  • metadata: RepoMetadata

query_custom_package_repository

Asks for a package from a custom repository that this plugin registered with add_custom_package_repositories.

  • Argument:
{
	"repository": string,
	"package": string
}
  • Result:
{
	"contents": string,
	"content_type": "script" | "declarative",
	"flags": [
		"out_of_date" | "deprecated" | "insecure" | "malicious", ...
	]
} | null

search_custom_package_repository

Searches / browses for packages from a custom repository that this plugin registered with add_custom_package_repositories.

  • Argument:
{
	"repository": string,
	"parameters": {
		"count": integer,
		"skip": integer,
		"search": string | null,
		"types": PackageType[],
		"minecraft_versions": string[],
		"loaders": Loader[],
		"categories": PackageCategory[]
	}
}
  • Result:
{
	"results": string[],
	"total_results": integer,
	"previews": {
		"package": [PackageMetadata, PackageProperties],
		...
	}
}
  • previews: Limited data about packages used to make quick previews. Useful if your API returns them, as it makes browsing much faster.

search_custom_package_repository

Synchronizes the cache for a custom repository that this plugin registered with add_custom_package_repositories. Should remove all cached packages associated with the repository so that new versions of packages can be used.

  • Argument:
{
	"repository": string
}
  • Result: None

Control Hooks

add_instance_config_controls

Defines additional schema for instance or template configuration

  • Argument:
{
	"id": string,
	"kind": "instance" | "template" | "base_template",
	"plugin": string | null
}
  • Result:
{
	"controls": [
		Control,
		...
	]
}

add_plugin_config_controls

Defines additional schema for configuring this plugin globally

  • Argument: None

  • Result:

[
	Control,
	...
]

Modpack Hooks

add_modpack_formats

Add new formats for modpacks

  • Argument: None

  • Result:

[
	{
		"id": string,
		"name": string,
		"transfer_format": string | null
	}
	...
]
  • transfer_format: The instance transfer format associated with this modpack format. It is necessary to implement instance transfer if you want to be able to import a modpack instance from a file or package.

install_modpack

Installs a modpack on an existing instance. Use instance transfer for supporting importing an instance.

  • Argument:
{
	"format": string,
	"path": string,
	"old_path": string | null,
	"target_path": string,
	"side": "client" | "server"
}
  • Result:
{
	"name": string,
	"packages": string[],
	"addons": [
		{
			"kind": "mod" | "resource_pack" | "datapack" | "shader" | "plugin",
			"file_name": string,
			"original_path": string | null,
			"target_paths": string[],
			"source": string | null,
			"hashes": {
				"sha256": string | null,
				"sha512": string | null
			}
		}
	]
}
  • path: Path to the modpack file
  • old_path: Path to the previous version of the modpack. Will not be passed if it is equal to the path.
  • target_path: The instance directory to install files in
  • name: The name of the modpack
  • packages: List of packages that this modpack provides that can be suppressed in package resolution
  • addons: List of addons, like mods or resource packs, that this modpack provides and can be used to prevent duplicates and manage updates

GUI Hooks

inject_page_script

Called whenever certain pages in the GUI are opened. Runs whatever the result of the hook is as Javascript on the page.

  • Argument:
{
	"page": "instances" | "instance" | "instance_config" | "template_config" | "base_template_config" | "packages" | "plugins",
	"object": string | null
}

  • Result: string

  • object: The identifier for whatever 'thing' this page is representing. Could be an instance, template, anything else, or nothing.

add_sidebar_buttons

Adds custom buttons to the sidebar

  • Argument: None

  • Result:

[
	{
		"html": string,
		"href": string,
		"selected_url": string | null,
		"selected_url_start": string | null,
		"color": string
	},
	...
]
  • html: The inner HTML of the button
  • href: Where the button leads to, likely a custom page
  • selected_url: What the current URL should equal to select this item
  • selected_url_start: What the current URL should start with to select this item

get_page

Lets you add custom pages. The page will be available at /custom/yourcustompagedata. You can include custom data like a specific ID in the data section of the URL as well.

  • Argument: string

This is the custom page data in the URL

  • Result: string | null

This is the resulting page as HTML. Only include things that would be in a <body> tag.

add_themes

Adds custom themes for the GUI

  • Argument: None

  • Result:

[
	{
		"id": string,
		"name": string,
		"description": string | null,
		"css": string,
		"color": string,
	},
	...
]

add_dropdown_buttons

Adds custom buttons to certain dropdowns in the UI

  • Argument: None

  • Result:

[
	{
		"plugin": string,
		"location": "add_template_or_instance" | "instance_launch" | "instance_update" | "instance_more_options",
		"icon": string,
		"text": string,
		"color": string | null,
		"tip": string | null,
		"action": string | null,
		"on_click": string | null
	},
	...
]
  • plugin: The plugin this button is from
  • location: Which dropdown to add the button to
  • icon: SVG icon for this button
  • tip: An optional tooltip for this option
  • action: A custom plugin action to run when this button is clicked
  • on_click: JavaScript to run when this button is clicked

add_instance_tiles

Adds custom tiles to the instance page in the GUI

  • Argument: None

  • Result:

[
	{
		"id": string,
		"contents": string,
		"size": "small" | "large"
	},
	...
]
  • id: A unique ID for this tile. Ensures consistent location.
  • contents: The HTML contents of the tile. Script tags will not be called, so it is important to include a page script as well to hook into the tile if you want functionality.
  • size: About how much space this tile needs to take up. Will be taken into account by the layout algorithm.

add_instance_icons

Adds extra options for instance icons for the user to choose from. Returns a list of absolute image file paths.

  • Argument: None

  • Result: string[]

Java Hooks

add_java_types

Adds new Java types that will be installed with install_custom_java

  • Argument: None

  • Result:

[
	{
		"id": string,
		"name": string,
		"color": string
	},
	...
]

install_custom_java

Installs a custom Java installation added with add_java_types.

  • Argument:
{
	"kind": string,
	"major_version": string,
	"update_depth": UpdateDepth
}
  • Result:
{
	"path": string,
	"version": string
}
  • kind: The ID of the Java matching the one from add_java_types
  • major_version: The major version of Java that is being installed
  • path: Path to the resulting installation, which contains a bin directory with the java executable in it
  • version: The version of the resulting installation of whatever Java flavor you are using

Common Types

InstanceLaunchArg

{
	"id": string,
	"side": "client" | "server",
	"dir": string,
	"game_dir": string,
	"version_info": {
		"version": string,
		"versions": [string]
	},
	"config": InstanceConfig,
	"pid": integer | null,
	"classpath": string | null,
	"stdout_path": string | null,
	"stdin_path": string | null
}

Note: The pid, classpath, stdout_path, and stdin_path fields will all be null for the on_instance_launch hook, and are only available in the other hooks.