KUBELOADER - KubeJS Content Pack Loader User Guide

I. Overview

KubeLoader is an add-on mod for KubeJS, currently supporting Forge 1.20.1. It provides a "Content Pack" mechanism for organizing and loading KubeJS scripts and resource collections.

II. Installation and Configuration

1. Content Pack Storage Location

• Folder Format: Under the kubejs/contentpacks/ directory.

  • The directory will be automatically created when the game starts (if it doesn't exist).
  • Supports folder or ZIP archive formats.

• Mod Built-in: Packaged in the contentpacks/ directory of the mod's resources.

III. Content Pack Structure Specification

1. Folder Type Structure

[namespace]/  ← Must use a unique namespace name
    ├── server_scripts/    # Server-side scripts
    ├── client_scripts/    # Client-side scripts
    ├── startup_scripts/   # Startup scripts
    ├── assets/            # Resource files
    ├── data/              # Data files
    └── contentpack.json   # PackMetaData file (required)

2. ZIP Archive Type Structure

[Custom Name].zip
    ├── ...        # Same as the folder structure above
    └── contentpack.json

3. Mod Type Structure

Resources
    ├── assets/
    ├── data/
    └── contentpacks/        # Under the mod's Resource folder
            ├── server_scripts/    # Server-side scripts
            ├── client_scripts/    # Client-side scripts
            ├── startup_scripts/   # Startup scripts
            └── contentpack.json

IV. PackMetaData File Configuration

1. Basic Fields

{
  "id": "pack_identifier",
  "name": "display_name",
  "description": "description_information",
  "version": "version_number",
  "authors": ["author1", "author2"]
}

• id: Unique identifier for the content pack (lowercase letters, numbers, underscores).
• version: Recommended to use semantic versioning (e.g., 1.0.0).

2. Dependency Management

"dependencies": [
  {
    "type": "dependency_type",
    "id": "dependency_target_content_pack_ID",
    "versionRange": "version_range",
    "reason": "explanatory_text (optional)"
  }
]

Dependency Type Description Table

Type	Description	Loading Behavior
REQUIRED	Required dependency	Prevents loading if missing
OPTIONAL	Optional dependency	Can still run if missing
RECOMMENDED	Recommended dependency	Can still run if missing
DISCOURAGED	Discouraged dependency	Outputs a warning
INCOMPATIBLE	Incompatible dependency	Prevents loading if present
MOD	Mod dependency	Requires the corresponding mod as a prerequisite

Version Range Syntax

Syntax	Example	Description
Exact Match	[1.0.0]	Must be version 1.0.0
Range Match	[1.0.0,2.0.0)	From 1.0.0 (inclusive) to 2.0.0 (exclusive)
Minimum Version	[1.0.0,)	1.0.0 and above
Any Version	*	No version restriction

3. Complete Example

{
  "id": "rpg_expansion",
  "name": "RPG Expansion Pack",
  "description": "Adds magic weapons and monsters",
  "version": "1.2.0",
  "authors": ["DeveloperA"],
  "dependencies": [
    {
      "type": "REQUIRED",
      "id": "star_lib",
      "versionRange": "[6.0.0,)"
    },
    {
      "type": "RECOMMENDED",
      "id": "mystic_mobs",
      "versionRange": "[10.0.0]",
      "reason": "Adds new monsters"
    }
  ]
}

V. JavaScript Functionality

1. Content Pack Communication

Implemented through the following fields: ContentPacks

ContentPacks.isLoaded(id) // Determines whether a ContentPack with a specific ID is loaded
ContentPacks.getMetaData(id) // Gets the metadata of a ContentPack with a specific ID, returns null if not found
ContentPacks.putShared(id, o) // Puts 'o' into "global" data, ContentPacks of the same script type can retrieve it based on the ID
ContentPacks.getShared(id) // Reads "global" data, essentially the data previously put in by ContentPacks of the same script type
ContentPacks.getAllSharedFor(scriptType)
ContentPacks.getShared(type, id) // Reads across script types, but writing across script types is not allowed

PackMetaData data can be accessed in ContentPacks, and communication between content packs can be achieved by putting and getting information.

2. KubeJS Enhancements

NBT Item Registration

event.create("nbt_item", 'nbt').nbt({custom_data: true})

Custom Bow Registration

event.create('magic_bow','bow')
    .callSuper("onCustomArrow", false) // Prevents calling the bow's super method
    .onCustomArrow(proj => {
        proj.setNoGravity(true)
        return proj
    })

VI. Important Notes

1. Namespace Specification:

   • Must be unique and cannot use "kubejs".
   • Recommended to use lowercase letters and underscores.

2. ZIP Packaging Requirements:

   • The root directory must contain one and only one namespace folder.
   • No other irrelevant files should be present.

3. Resource Paths:

   • All resources are automatically stored in the pack_resources folder.

VII. Troubleshooting

If loading fails, check:

1. Whether the namespace conforms to the specification.
2. Whether the ZIP archive structure is correct.
3. Whether the PackMetaData file exists and is in the correct format.
4. Whether the dependencies are met.