JsonPatcher Docs beta

Mod Library Symbols

This page contains documentation for symbols in the standard library of the JsonPatcher mod. These symbols interact more directly with minecraft than those found in the language stdlib. Unless something is otherwise stated, everything here should be available to all code ran by the mod.

Namespace events

Library lib : events

This library contains functionality for subscribing to various gameplay events. To use events, begin by obtaining an event container with a unique name:

import "events";

val container = events.container("my-event-container");

You can then use various methods on the container to listen to events.

Requires all(libgroup(jsonpatcher:reflection), libgroup(+jsonpatcher:global_scripts))

Function events.lib.container: (name: string) -> events.Container

Used to obtain an event container. The passed name can be any string, but should be the same between executions. This allows for hotswapping, when newer executions replace handlers from previous ones.

Type Container based on object

Holds event handlers for events.

Function events.Container.registerFabric: (class: string, field: string, handler: function) -> null

Registers a listener to a Fabric API event. The event may also be defined by other mods.

The class and field parameters specify the field holding the event. These must be passed as strings. In order for registration to succeed, the field must be of type net.fabricmc.fabric.api.event.Event and have a properly defined generic parameter.
The handler parameter accepts a function, which is converted into the appropriate handler type for the event.

Registering to the same event twice will override the first handler with the second. This only happens if the hotswap_events config option is enabled, as allowing hotswapping leads to worse performance at runtime.

Namespace metapatch

Library lib : metapatch

A special library available to metapatch patches. Provides tools to create, query and remove files on a higher level.

Function metapatch.lib.addFile: (path: string, content: object) -> null

Creates a file at the specified path with the specified content, converted to json.

Function metapatch.lib.deleteFile: (path: string) -> null

Deletes the file at the specified path.

Function metapatch.lib.deleteFiles: (target: patch.PatchTarget) -> null

Deletes files matching the specified target selector. The syntax of the selector is the same as is used in the @target metadata, except that only one target is supported.

Function metapatch.lib.getFile: (path: string) -> object

Reads the file at the specified path and returns its content as json.

Function metapatch.lib.getFiles: (path: string) -> object[]

Reads the file at the specified path as well as all overriden versions, and returns their contents as json.

Function metapatch.lib.searchFiles: (target: patch.PatchTarget) -> object{}

Searches for files matching the specified target selector. The syntax of the selector is the same as is used in the @target metadata, except that only one target is supported.

The returned data is a map of file paths to their contents.

This method is most performant when the target has a path specified, as it allows minecraft to skip ahead when looking for files.

Metadata tag @metapatch: null

Turns the current script into a metapatch script. This allows the script to create, query and remove files on a higher level trough the "metapatch" library. The library must be imported, unlike on older versions.

Requires any(libgroup(jsonpatcher:minecraft_data), libgroup(jsonpatcher:minecraft_assets))

Namespace patch

Metadata tag @target: patch.PatchTarget | patch.PatchTarget[]

Specifies which files a patch modifies. When this metadata is found on scripts loaded from suitable locations, they are loaded as patches and get to modify json files.

Can either be set to a single target, or an array of targets. When set to an array, files are patched when any of the targets match.

Requires any(libgroup(+jsonpatcher:minecraft_data), libgroup(+jsonpatcher:minecraft_assets))

Type ObjectTarget based on object

An object describing an advanced target. All present properties must match for this target to match.

Property patch.ObjectTarget.namespace: string

The namespace of the file, matched exactly.

This property is optional and may not be present

Property patch.ObjectTarget.path: string | patch.TargetPath

Either a string to match the path of the file exactly, or an object describing the path as a beginning and end.

This property is optional and may not be present

Property patch.ObjectTarget.regex: string

A regular expression to match the entire path of the file including namespace.

This property is optional and may not be present

Type TargetPath based on object

An object describing the path of the file as a beginning and end. The beginning is matched against the start of the path, and the end is matched against the end of the path. Both properties must be present and must match exactly.

Property patch.TargetPath.begin: string

The beginning of the path, matched against the start of the path. Can be set to an empty string to always match.

Property patch.TargetPath.end: string

The end of the path, matched against the end of the path. Can be set to an empty string to always match.

Type alias PatchTarget = string | ObjectTarget

A single target can be a string or an object. When set to a string the whole path of the file must match it exactly. When set to an object, the path is matched against the properties of the object. See patch.ObjectTarget for details.

Namespace program

Metadata tag @enabled: boolean

The @enabled metadata tag can be used to disable scripts. When set to false, the script will not run at all and in some cases not even parsed. This is useful for debugging, providing an alternative to commenting out code.

Metadata tag @library: null | script.LibraryMetadata

Makes a program available to others as a library that can be imported. When imported, the program will be executed with an empty root object, which will then be provided to the importing program.

If the program is loaded from the jsonpatcher/scripts folder within the minecraft instance folder, the library location gains the scripts:global: prefix. If the script is loaded from within a mod, it gains the mod:MOD_ID: prefix, where MOD_ID is the mod's id. For example mod:jsonpatcher:example.

If the program is loaded from a resource file, the library location will be equal to the namespaced file location of the program.

Unless the shared option is specified, each caller gets their own copy of this library.

Metadata tag @priority: number

Specifies order in which programs are loaded. Programs with higher priority run after programs with lower priority. The default priority is 0.

Note that priority only applies between scripts that are ran for the same reason. For example, you cannot change the ordering between a "client" init script and a "main" init script.

Type LibraryMetadata based on object

Optional options for describing how a library should behave.

Property program.LibraryMetadata.shared: boolean

If specified, this option make all users share a single copy of a library.

Care should be taken to ensure the thread safety of shared libraries, as multiple programs will be able to access shared libraries in parallel. JsonPatcher objects and arrays are not thread safe and must be externally synchronized. Any exposed objects should be frozen whenever possible.

This property is optional and may not be present

Namespace script

Metadata tag @init: string

Makes a script execute while the game is loading. Depending on the value, scripts are executed at different points in time:

  • "main": Causes the script to run during mod init.
  • "client": Causes the script to run during client init.
  • Any other value is considered invalid
Requires libgroup(+jsonpatcher:global_scripts)