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

Code references: FilesJS
JSON parsing approach inspired by: FancyMenu