Utilities - Minecraft Creator Tools

Overview

The Utilities class provides a comprehensive collection of static utility methods for common operations in Minecraft Creator Tools, including string processing, JSON manipulation, UUID generation, encoding/decoding, and Minecraft-specific name formatting.

String Manipulation

humanifyMinecraftName

Converts a Minecraft technical name to a human-readable format.

name

string | boolean | number

required

The technical name to convert

doNotReverse

boolean

If true, preserves the original order (doesn’t reverse namespace.name to “name namespace”)

return

string

Human-readable name

import { Utilities } from '@minecraft/creator-tools';

const readable = Utilities.humanifyMinecraftName('minecraft:iron_sword');
// Returns: "Iron Sword"

const entity = Utilities.humanifyMinecraftName('custom:my_cool_entity');
// Returns: "My Cool Entity custom"

dehumanifyMinecraftName

Converts a human-readable name to a Minecraft technical name.

name

string | boolean | number

required

The human-readable name

return

string | boolean | number

Technical name with minecraft: namespace

const technical = Utilities.dehumanifyMinecraftName('Iron Sword');
// Returns: "minecraft:iron_sword"

javascriptifyName

Converts a string to a valid JavaScript identifier.

name

string

required

String to convert

capitalizeFirst

boolean

Whether to capitalize the first character

return

string

Valid JavaScript identifier

const jsName = Utilities.javascriptifyName('My Cool Name', true);
// Returns: "MyCoolName"

const varName = Utilities.javascriptifyName('item-type:test', false);
// Returns: "itemTypeTest"

humanifyJsName

Converts a JavaScript identifier to a human-readable string.

name

string | boolean | number

required

JavaScript identifier

return

string

Human-readable string

const readable = Utilities.humanifyJsName('myVariableName');
// Returns: "My Variable Name"

replaceAll

Replaces all occurrences of a token in a string.

content

string

required

String to process

fromToken

string

required

Token to find

toToken

string

required

Replacement token

return

string

Processed string

const result = Utilities.replaceAll(
  'hello world, world!',
  'world',
  'universe'
);
// Returns: "hello universe, universe!"

JSON Processing

fixJsonContent

Fixes common JSON issues like comments and trailing commas.

jsonString

string

required

JSON string to fix

options

object

Options object with whitespace and trailingCommas boolean flags

return

string

Fixed JSON string

const fixed = Utilities.fixJsonContent(`{
  // Comment
  "name": "value",
  "array": [1, 2, 3,]
}`);
// Returns valid JSON without comments and trailing commas

consistentStringify

Stringifies an object with consistent property ordering.

value

any

required

Object to stringify

return

string

Consistently formatted JSON string

const json = Utilities.consistentStringify({
  z: 3,
  a: 1,
  m: 2
});
// Properties are always in the same order

parseJson

Safely parses a JSON string.

jsonString

string

required

JSON string to parse

return

object | undefined

Parsed object, or undefined on error

const obj = Utilities.parseJson('{"name": "value"}');
if (obj) {
  console.log(obj);
}

getJsonObject

Parses JSON with automatic comment/comma fixing.

contents

string

required

JSON string (may contain comments)

return

any | undefined

Parsed object, or undefined on error

const obj = Utilities.getJsonObject(`{
  // This is a comment
  "name": "value"
}`);

UUID Generation

createUuid

Generates a random UUID v4.

return

string

UUID string (e.g., “550e8400-e29b-41d4-a716-446655440000”)

const uuid = Utilities.createUuid();
// Returns: "550e8400-e29b-41d4-a716-446655440000"

canonicalizeUuid

Normalizes a UUID to lowercase and trimmed.

uuidString

string

required

UUID to normalize

return

string

Normalized UUID

const uuid = Utilities.canonicalizeUuid(' 550E8400-E29B-41D4-A716-446655440000 ');
// Returns: "550e8400-e29b-41d4-a716-446655440000"

uuidEqual

Compares two UUIDs for equality (case-insensitive).

uuidStringA

string

required

First UUID

uuidStringB

string

required

Second UUID

return

boolean

True if UUIDs are equal

const equal = Utilities.uuidEqual(
  '550E8400-E29B-41D4-A716-446655440000',
  '550e8400-e29b-41d4-a716-446655440000'
);
// Returns: true

Encoding and Conversion

uint8ArrayToBase64

Converts a Uint8Array to base64 string.

bytes

Uint8Array

required

Byte array to convert

return

string

Base64-encoded string

const bytes = new Uint8Array([72, 101, 108, 108, 111]);
const base64 = Utilities.uint8ArrayToBase64(bytes);
// Returns base64-encoded "Hello"

base64ToUint8Array

Converts a base64 string to Uint8Array.

base64buffer

string

required

Base64-encoded string

return

Uint8Array

Decoded byte array

const bytes = Utilities.base64ToUint8Array('SGVsbG8=');
// Returns Uint8Array representing "Hello"

readStringUTF8

Reads a UTF-8 encoded string from a DataView.

buf

DataView

required

Buffer containing the string

byteOffset

number

required

Offset to start reading from

bytesToRead

number

required

Number of bytes to read

return

{ str: string, byteLength: number }

Object with the decoded string and bytes read

const result = Utilities.readStringUTF8(dataView, 0, 10);
console.log(result.str);

Date and Time

getDateStr

Formats a date as a compact string (YYYYMMDDHHmmss).

date

Date

required

Date to format

return

string

Formatted date string

const dateStr = Utilities.getDateStr(new Date('2024-03-15T10:30:00'));
// Returns: "20240315103000"

getDateFromStr

Parses a compact date string (YYYYMMDDHHmmss).

dateStr

string

required

Date string to parse

return

Date

Parsed Date object

const date = Utilities.getDateFromStr('20240315103000');
// Returns: Date object for 2024-03-15 10:30:00

getFriendlySummaryHoursMinutes

Formats a date as friendly time (HH:MM 12-hour format).

date

Date | null

required

Date to format

return

string

Formatted time string

const time = Utilities.getFriendlySummaryHoursMinutes(new Date());
// Returns: "10:30" (in 12-hour format)

Validation

isNumeric

Checks if a string contains only numeric characters.

candidate

string

required

String to check

return

boolean

True if numeric

Utilities.isNumeric('123.45'); // true
Utilities.isNumeric('abc');    // false

isAlphaNumeric

Checks if a string contains only alphanumeric characters.

candidate

string

required

String to check

return

boolean

True if alphanumeric

Utilities.isAlphaNumeric('abc123'); // true
Utilities.isAlphaNumeric('abc-123'); // false

isValidUuid

Checks if a string is a valid UUID format.

uuidString

string

required

String to validate

return

boolean

True if valid UUID

const valid = Utilities.isValidUuid('550e8400-e29b-41d4-a716-446655440000');
// Returns: true

String Formatting

ensureEndsWithSlash

Ensures a path ends with a forward slash.

pathSegment

string

required

Path to process

return

string

Path with trailing slash

const path = Utilities.ensureEndsWithSlash('my/path');
// Returns: "my/path/"

ensureStartsWithSlash

Ensures a path starts with a forward slash.

pathSegment

string

required

Path to process

return

string

Path with leading slash

const path = Utilities.ensureStartsWithSlash('my/path');
// Returns: "/my/path"

frontPadToLength

Pads a value to a specific length with a character.

val

string | number

required

Value to pad

length

number

required

Target length

pad

string

required

Padding character

return

string

Padded string

const padded = Utilities.frontPadToLength(42, 5, '0');
// Returns: "00042"

trimEllipsis

Truncates a string and adds ellipsis if too long.

text

string

required

Text to truncate

length

number

required

Maximum length

return

string

Truncated text with ellipsis if needed

const short = Utilities.trimEllipsis('This is a very long text', 15);
// Returns: "This is a ver…"

Random Generation

createRandomId

Generates a random alphanumeric ID.

length

number

required

Length of the ID

return

string

Random ID string

const id = Utilities.createRandomId(8);
// Returns something like: "aB3xK9mZ"

createRandomLowerId

Generates a random lowercase alphanumeric ID.

length

number

required

Length of the ID

return

string

Random lowercase ID

const id = Utilities.createRandomLowerId(8);
// Returns something like: "ab3xk9mz"

Usage Examples

Processing Minecraft Names

import { Utilities } from '@minecraft/creator-tools';

// Convert technical names to readable
const items = [
  'minecraft:diamond_sword',
  'custom:my_custom_entity',
  'minecraft:redstone_wire'
];

for (const item of items) {
  console.log(Utilities.humanifyMinecraftName(item));
}
// Output:
// Diamond Sword
// My Custom Entity custom
// Redstone Wire

Safe JSON Processing

// Handle JSON with comments
const jsonWithComments = `{
  // This is a comment
  "format_version": "1.20.0",
  "minecraft:entity": {
    "description": {
      "identifier": "custom:mob" // inline comment
    }
  }
}`;

const obj = Utilities.getJsonObject(jsonWithComments);
if (obj) {
  console.log('Parsed successfully:', obj);
}

Working with UUIDs

// Generate and compare UUIDs
const newId = Utilities.createUuid();
const existingId = '550e8400-e29b-41d4-a716-446655440000';

if (Utilities.isValidUuid(newId)) {
  console.log('Valid UUID:', newId);
}

if (Utilities.uuidEqual(existingId, existingId.toUpperCase())) {
  console.log('UUIDs match (case-insensitive)');
}

String Formatting

// Create safe identifiers
const userInput = 'My Cool Entity!';
const identifier = Utilities.javascriptifyName(userInput, false);
// Result: "myCoolEntity"

// Format dates
const timestamp = Utilities.getDateStr(new Date());
console.log(`Backup_${timestamp}.zip`);

Constants

MAX_JSON_SAFE_INTEGER

const MAX_JSON_SAFE_INTEGER = 2_000_000_000;

Maximum safe integer for .NET Int32 compatibility in JSON.

MIN_JSON_SAFE_INTEGER

const MIN_JSON_SAFE_INTEGER = -2_000_000_000;

Minimum safe integer for .NET Int32 compatibility in JSON.

Core

Minecraft Definitions

World & Data

Storage

Validation

​Overview

​String Manipulation

​humanifyMinecraftName

​dehumanifyMinecraftName

​javascriptifyName

​humanifyJsName

​replaceAll

​JSON Processing

​fixJsonContent

​consistentStringify

​parseJson

​getJsonObject

​UUID Generation

​createUuid

​canonicalizeUuid

​uuidEqual

​Encoding and Conversion

​uint8ArrayToBase64

​base64ToUint8Array

​readStringUTF8

​Date and Time

​getDateStr

​getDateFromStr

​getFriendlySummaryHoursMinutes

​Validation

​isNumeric

​isAlphaNumeric

​isValidUuid

​String Formatting

​ensureEndsWithSlash

​ensureStartsWithSlash

​frontPadToLength

​trimEllipsis

​Random Generation

​createRandomId

​createRandomLowerId

​Usage Examples

​Processing Minecraft Names

​Safe JSON Processing

​Working with UUIDs

​String Formatting

​Constants

​MAX_JSON_SAFE_INTEGER

​MIN_JSON_SAFE_INTEGER

​See Also

Build docs developers (and LLMs) love

Overview

String Manipulation

humanifyMinecraftName

dehumanifyMinecraftName

javascriptifyName

humanifyJsName

replaceAll

JSON Processing

fixJsonContent

consistentStringify

parseJson

getJsonObject

UUID Generation

createUuid

canonicalizeUuid

uuidEqual

Encoding and Conversion

uint8ArrayToBase64

base64ToUint8Array

readStringUTF8

Date and Time

getDateStr

getDateFromStr

getFriendlySummaryHoursMinutes

Validation

isNumeric

isAlphaNumeric

isValidUuid

String Formatting

ensureEndsWithSlash

ensureStartsWithSlash

frontPadToLength

trimEllipsis

Random Generation

createRandomId

createRandomLowerId

Usage Examples

Processing Minecraft Names

Safe JSON Processing

Working with UUIDs

String Formatting

Constants

MAX_JSON_SAFE_INTEGER

MIN_JSON_SAFE_INTEGER

See Also