Settings

Settings#

Overview#

The Shapescape NBT Replacer is a high-performance filter for finding and replacing strings within NBT (Named Binary Tag) files. It supports multiple file formats including .nbt, .mcstructure, and compressed variants (.gz, .zlib).

Configuration Structure#

{
	"filter": "shapescape_nbt_replacer",
	"settings": {
		"rules": [
			{
				"path": "**/*.mcstructure",
				"property": "facing",
				"from": "west",
				"to": "north",
				"regex": false,
				"flags": "g",
				"notify": true
			}
		]
	}
}

Parameters#

rules#

Type: Array<Rule>
Required: Yes
Description: An array of replacement rules. Each rule defines a separate find-and-replace operation on NBT files.

Rule Object Properties#

path#

Type: string
Required: Yes
Description: Glob pattern to match files for processing. Supports standard glob syntax:

  • * matches any characters except path separator

  • ** matches any characters including path separators (for recursive directory matching)

  • ? matches a single character

  • [abc] matches characters in brackets

Examples:

"path": "**/*.nbt"           // All .nbt files in all subdirectories
"path": "structures/*.mcstructure"  // All .mcstructure files in structures folder
"path": "**/*.mcstructure.gz"       // All compressed .mcstructure files
property#

Type: string
Optional: Yes
Default: null (matches all string tags)
Description: Target a specific NBT tag name. When specified, only string tags with this exact name will be processed. If omitted, all string tags matching the search criteria will be processed.

Examples:

"property": "facing"        // Only replace in tags named "facing"
"property": "id"           // Only replace in tags named "id"
"property": "CustomName"   // Only replace in tags named "CustomName"
from#

Type: string
Required: Yes
Description: The string or pattern to search for.

  • If regex is false: performs exact string matching (the entire string value must match)

  • If regex is true: treats this as a regular expression pattern

Examples:

"from": "west"                    // Exact match (when regex: false)
"from": "minecraft:stone"         // Exact match
"from": "^minecraft:.*_log$"      // Regex pattern (when regex: true)
"from": "old_\\w+_name"           // Regex with word characters

Note: Use \\b for word boundaries in regex patterns (it will be normalized internally).

to#

Type: string
Required: Yes
Description: The replacement string. Can include regex capture groups when using regex: true.

Examples:

"to": "north"                          // Simple replacement
"to": "minecraft:oak_log"              // Namespace replacement
"to": "$1_new_$2"                      // With regex capture groups
regex#

Type: boolean
Optional: Yes
Default: false
Description: Determines matching behavior:

  • false: Exact string matching - the entire string value must match from exactly

  • true: Regular expression matching - from is treated as a regex pattern

Important: When regex is false, only complete string matches are replaced, not partial matches within strings.

flags#

Type: string
Optional: Yes
Default: "g" (global)
Description: Regular expression flags (only used when regex is true).

Common flags:

  • g - Global: replace all matches

  • i - Case-insensitive matching

  • m - Multiline: ^ and $ match line boundaries

  • s - Dotall: . matches newlines

Examples:

"flags": "gi"    // Global + case-insensitive
"flags": "g"     // Global only (default)
"flags": "gim"   // Multiple flags combined
notify#

Type: boolean
Optional: Yes
Default: Rule inherits from global notify setting
Description: When true, logs detailed information about each replacement including:

  • File path

  • Tag path (hierarchical location in NBT structure)

  • Old value

  • New value

Output example:

[Replace] structures/house.mcstructure :: palette > [0] > Name :: "minecraft:stone" -> "minecraft:cobblestone"

Complete Example#

{
	"filter": "shapescape_nbt_replacer",
	"settings": {
		"rules": [
			{
				"path": "**/*.mcstructure",
				"property": "facing",
				"from": "west",
				"to": "north",
				"regex": false,
				"notify": true
			},
			{
				"path": "structures/village/**/*.nbt",
				"from": "^minecraft:(.+)_planks$",
				"to": "minecraft:oak_$1",
				"regex": true,
				"flags": "g"
			},
			{
				"path": "**/*.mcstructure.gz",
				"property": "id",
				"from": "minecraft:chest",
				"to": "minecraft:barrel",
				"regex": false
			}
		]
	}
}

How It Works#

1. File Discovery#

The filter uses fast-glob to find all files matching the path pattern for each rule.

2. NBT Parsing#

For each file, the tool attempts to parse it as NBT using multiple strategies:

  • Bedrock Edition format (with optional compression)

  • Java Edition format

  • Little-endian and big-endian variants

  • Gzip, zlib, or uncompressed

3. String Traversal#

The tool recursively traverses the NBT structure:

  • Compound tags: Checks each key-value pair

  • List tags: Processes each element

  • String tags: Candidates for replacement

4. Matching & Replacement#

For each string tag:

  • If property is specified, only tags with that name are considered

  • If regex is true: applies the regex pattern with specified flags

  • If regex is false: performs exact string comparison

  • Replacements are made in-memory

5. Writing#

Modified files are written back to disk using the same NBT format they were read in.

Performance Features#

Adaptive Concurrency#

The tool automatically adjusts concurrent file operations based on disk I/O performance:

  • Monitors task completion times

  • Increases concurrency when tasks complete faster

  • Decreases concurrency when tasks slow down

  • Default concurrency is CPU cores × 2

Optimized Parsing#

Multiple parsing strategies are attempted in order of likelihood:

  • File extension-based heuristics (.mcstructure tries Bedrock format first)

  • Automatic fallback to alternative formats

  • Minimal overhead for successful parses

Tips & Best Practices#

  1. Use property filters: Narrow down replacements to specific tag names for precision

  2. Start with exact matching: Use regex: false until you need pattern matching

  3. Enable notify during development: Verify replacements are working as expected

  4. Use specific glob patterns: Narrow file selection for better performance

  5. Backup your files: Always work on copies when testing new rules

Common Use Cases#

Rotating Blocks#

{
	"path": "**/*.mcstructure",
	"property": "facing",
	"from": "west",
	"to": "north",
	"regex": false
}

Block ID Migration#

{
	"path": "**/*.nbt",
	"property": "id",
	"from": "^minecraft:stone$",
	"to": "minecraft:cobblestone",
	"regex": true
}

Namespace Updates#

{
	"path": "structures/**/*.mcstructure",
	"from": "^mymod:(.*)",
	"to": "mynewmod:$1",
	"regex": true,
	"flags": "g"
}
Contents