API Configuration

Script configuration

Lua API / Script configuration

betamoon.config(key, defaults) opens a JSON config file for a script. If the file does not exist, BetaMoon creates it from the default values. The returned value is a Lua table: read and change its fields directly, including nested fields. A config belongs to the Minecraft instance or dedicated server where the script runs.

local config = betamoon.config("mymod", {
    enemyHealth = 1.0,
    showDamageNumbers = true,
    loot = { dropRate = 0.25 },
})

local health = baseHealth * config.enemyHealth

config.loot.dropRate = 0.35
config.save()

Files and keys

Files live in the instance's betamoon/config folder. BetaMoon's own Minecraft mod settings remain in the shared config folder. Keys use lowercase names and cannot contain path traversal.

Key	File under the instance folder
"mymod"	betamoon/config/mymod.json
"mymod:gameplay"	betamoon/config/mymod/gameplay.json

Use the short key for a single config file. A named key lets one script package split settings into several files. Each client or server reads its own local file; changing one machine's file does not synchronize it to other machines.

Values and defaults

The defaults table accepts booleans, finite numbers, strings, nested tables with string fields, and dense arrays. Config files use JSON, so comments and Lua expressions are unsupported. save and reload are reserved top-level field names.

Existing file values override matching defaults. Missing fields receive their defaults in the returned table; extra file fields remain available. A field whose type differs from its default makes the file invalid. If the file is invalid when opened, BetaMoon reports a script error and returns the defaults without replacing the file.

Config values are ordinary table entries. pairs(config) visits the data fields; the save and reload methods are not included. Assigning a field changes the in-memory table until it is saved or reloaded.

config.save()

Writes the current table to its file and returns true. It validates the values, then writes the complete JSON file. If the file changed on disk since the table last loaded it, save() raises an error rather than overwriting those edits. Call config.reload() to accept the disk changes before saving again.

config.reload()

Reads the file again, discards unsaved changes, updates the same config table, and returns true. Existing references to nested tables also receive the new fields. If the file was deleted, reload() recreates it from defaults. An invalid file raises an error and leaves the current table unchanged.

Reloading a config changes the table values; scripts must use those values when applying their behavior. It does not automatically rebuild blocks, world generation, or other declarations already made by the script.