promotional bannermobile promotional banner
premium banner

KJSutils

Extend the functionality of KubeJS

Description

KJSutils (KubeJS Integration)

This mod extends the functionality of KubeJS by adding six new features, a total of thirteen methods, and two events.

1. Download Files from the Internet

Supports custom file save paths and file names. Returns true if the download succeeds, and false if it fails. Files can only be saved inside the .minecraft/ directory for security reasons.

Usage:

KJSutils.Download("download_url", "save_path", "save_filename (use null to keep the original filename from the URL)")

Examples:

let download = KJSutils.Download("https://example.com/example.txt", "config/kjsutils", "helloworld.txt")

if (download) {
    console.log("true")
} else {
    console.log("false")
}

2. Parse JSON Files Using Syntax Expressions

Usage:

// Returns: the first matched value as a string, or "null" if no match is found
KJSutils.Analysis("file_path (must be within .minecraft/ for safety)", "json_path")

// Returns: a list of all matched values as strings
KJSutils.AnalysisAll("file_path (must be within .minecraft/ for safety)", "json_path")

JSON Path Syntax Reference

Syntax Type Example Description Example Return Value
Root Object $ Refers to the root of the JSON object The entire JSON content
Force Root Object $$ Force parse as root object name i18n lang key
Object Property $.property
$.nested.property		 Access an object’s property or nested property "value"
"nested_value"
Array Index $[0]
$.items[1]		 Access the first array element or the second element within an object’s array "first_item"
{"id": 2, "name": "item2"}
Quoted Property $['property-name']
$['nested']['property']		 Access properties containing special characters, or nested quoted properties "value"
"nested_value"
Wildcard $.*
$.items.*
$.items.*.name		 Get all root values, all elements in an object array, or specific fields of all objects in an array ["value1", "value2", ...]
[elem1, elem2, ...]
["name1", "name2", ...]
Mixed Path $.data[0].users[2].name
$['config']['items'][1].price		 Combine different syntax types for complex paths "user_name"
15.99

Example JSON

{
  "version": "1.0.0",
  "settings": {
    "difficulty": "hard",
    "cheats": false
  },
  "players": [
    {
      "name": "Steve",
      "level": 42,
      "inventory": [
        {"id": "minecraft:diamond", "count": 5},
        {"id": "minecraft:stone", "count": 64}
      ]
    },
    {
      "name": "Alex", 
      "level": 38,
      "inventory": [
        {"id": "minecraft:wood", "count": 32}
      ]
    }
  ],
  "server-config": {
    "max-players": 20,
    "pvp": true
  }
}
JSON Path Query Description Return Value
$.version Get the version 1.0.0
$.settings.difficulty Get the difficulty setting hard
$.players[0].name Get the first player's name Steve
$.players[1].inventory[0].id Get the ID of the first item in the second player's inventory minecraft:wood
$['server-config']['max-players'] Get the server's max player count 20
$.players.*.name Get all player names ["Steve", "Alex"]
$.players[0].inventory.*.count Get all item counts for Steve [5, 64]
$.players.*.inventory.*.id Get all item IDs from all players ["minecraft:diamond", "minecraft:stone", "minecraft:wood"]
$$.item.minecraft.wood Force parse as root path Wood

3. Use syntax (only partially supported) to modify specific JSON values

Usage:

KJSutils.Analysis("File path (can only read files under the .minecraft/ directory for safety)", "JSON path", "Value to write (be mindful of the value type)")

Examples:

// Modify a root-level property
KJSutils.ModifyJsonValue("config/test.json", "$.name", "New Name");

// Modify a nested property
KJSutils.ModifyJsonValue("config/test.json", "$.player.level", 100);

// Modify a boolean value
KJSutils.ModifyJsonValue("config/test.json", "$.enabled", true);

// Modify a JSON object
KJSutils.ModifyJsonValue("config/test.json", "$.data", '{"key": "value"}');

4. Operating FancyMenu Variables

Usage:

// Set or add a variable
KJSutils.FMsetVariable("variableName", "variableValue", "resetOnLaunch (boolean)")

// Delete a variable
KJSutils.FMremoveVariable("variableName")

// Get a variable’s value
KJSutils.FMgetVariable("variableName") // returns a Variable type

// Check if a variable exists
KJSutils.FMexistsVariable("variableName") // returns a boolean

// Trigger variable initialization
KJSutils.FMinit()

// Delete all variables
KJSutils.FMclearAllVariables()

Example:

// Set the variable "test" to value 1 and make it reset on launch
KJSutils.FMsetVariable("test", "1", true)

// Delete the variable "test"
KJSutils.FMremoveVariable("test")

// Get the value of the variable "test"
let value = KJSutils.FMgetVariable("test")

// Check if the variable "test" exists
if (KJSutils.FMexistsVariable("test")) {
    // Other operations
}

5. Get Client Language

Usage:

// Get Minecraft Language. return String value. Example: en_us
KJSutils.GetClientLanguage()

// Get System Language. return String value. Example: en-us
KJSutils.GetClientLanguage()

Events

This mod adds two new KubeJS events:

// Listen for a player entering a specified dimension
KJSutilEvents.playerLoggedInDimension(extra, event => {})

// Listen for a player leaving a specified dimension
KJSutilEvents.playerLoggedOutDimension(extra, event => {})

Example:

// Listen for a player entering the Nether dimension
KJSutilEvents.playerLoggedInDimension("minecraft:the_nether", event => {
    let playerName = event.player.username
    console.log(`${playerName} entered the Nether`)
})

// Listen for a player leaving the Nether dimension
KJSutilEvents.playerLoggedOutDimension("minecraft:the_nether", event => {
    let playerName = event.player.username
    console.log(`${playerName} left the Nether`)
})

Credits