⚙️ Advanced Letter Blocks Configuration¶

⚠️ This guide is for advanced users and developers who want to create custom letter blocks with their own fonts, colors, and backgrounds.

If you're a teacher looking to use Letter Blocks in your classroom, see:

Letter Blocks - Getting Started for basic usage
More Letter Blocks Extension for ready-made expansion packs

Overview¶

This guide explains how to create custom letter block sets by editing the pack's configuration files and adding your own fonts and background images.

Prerequisites:

Understanding of JSON file format
Access to the Educator Tools source code
Familiarity with the Development Setup
Basic image editing skills

Before You Begin¶

Requirements¶

✅ Review the Contributing Guide to understand the development workflow

✅ Set up your development environment following Development Setup

✅ Locate your working directory:

regolith/filters_data/modular_mc/letter_blocks/

File Structure¶

letter_blocks/
├── scope.ts              ← Configuration file (you'll edit this)
├── fonts/                   ← Place custom font files here (.ttf)
│   ├── AzeretMono-Black.ttf
│   └── YourCustomFont.ttf
├── rainbow.block.png        ← Background images go here
├── star.block.png
└── your_background.png

Step 1: Prepare Your Assets¶

Custom Font Files¶

Obtain a TrueType font file (.ttf format)
Place it in the fonts/ subdirectory
Note the exact filename for use in configuration

Example:

fonts/AzeretMono-Black.ttf
fonts/MyCustomFont.ttf

Background Images¶

Create or obtain a square PNG image (recommended: 64×64 pixels)
Place it directly in the letter_blocks/ directory
Note the exact filename for use in configuration

Example:

letter_blocks/rainbow.block.png
letter_blocks/my_background.png

Image Tips:

Use square dimensions (64×64, 128×128, 256×256)
PNG format with transparency support
Design should work well when repeated on all 6 block faces
Test with different colors to ensure text is readable

Step 2: Open the Configuration File¶

Locate and open the scope.ts file:

regolith/filters_data/modular_mc/letter_blocks/scope.ts

This file contains an array named letter_sets. Each object within this array defines a distinct set of letter blocks.

Step 3: Understanding the JSON Structure¶

Basic Structure¶

{
  "letter_sets": [
    {
      "id": "main_letter_set",
      "font_size": 48,
      "text_color": [10, 10, 10, 255],
      "image_size": [64, 64],
      "font_path": "fonts/AzeretMono-Black.ttf",
      "background_image_path": "letter_blocks/rainbow.block.png",
      "suffix": "rainbow",
      "antialias": true,
      "letters": [
        {
          "char": "A",
          "safe_name": "A",
          "group": "letter"
        }
      ]
    }
  ]
}

Property Definitions¶

Property	Type	Description	Example
`id`	String	Unique identifier for debugging and reference	`"my_custom_set"`
`font_size`	Number	Font size in pixels	`48`
`text_color`	Array	Text color in RGBA format [R, G, B, A]	`[10, 10, 10, 255]` (black)
`image_size`	Array	Texture dimensions [width, height] - must be square	`[64, 64]`
`font_path`	String	Path to font file relative to project root	`"fonts/MyFont.ttf"`
`background_image_path`	String	Path to background image	`"letter_blocks/bg.png"`
`suffix`	String	Required suffix for item names (must be unique)	`"custom"`
`antialias`	Boolean	Enable smooth edges on text	`true`
`letters`	Array	List of characters to generate (see below)	`[...]`

Letter Object Structure¶

Each letter in the letters array has these properties:

{
  "char": "A",           // The actual character to render
  "safe_name": "A",      // Filename-safe identifier (no special chars)
  "group": "letter"      // Category: "letter", "number", "symbol", "punctuation"
}

Examples:

// Regular letter
{
  "char": "A",
  "safe_name": "A",
  "group": "letter"
}

// Number
{
  "char": "5",
  "safe_name": "5",
  "group": "number"
}

// Symbol (using unicode escape)
{
  "char": "\u2665",      // ♥ heart symbol
  "safe_name": "heart",
  "group": "symbol"
}

// Special character
{
  "char": "!",
  "safe_name": "exclamation",
  "group": "punctuation"
}

Step 4: Adding a New Letter Set¶

Insert your new letter set as an object within the letter_sets array:

Example: Custom Rainbow Set¶

{
  "letter_sets": [
    {
      "id": "main_letter_set"
      // ... existing properties
    },
    {
      "id": "my_custom_rainbow_set",
      "font_size": 48,
      "text_color": [255, 255, 255, 255],
      "image_size": [64, 64],
      "font_path": "fonts/AzeretMono-Black.ttf",
      "background_image_path": "letter_blocks/rainbow.block.png",
      "suffix": "rainbow",
      "antialias": true,
      "letters": [
        {
          "char": "A",
          "safe_name": "A",
          "group": "letter"
        },
        {
          "char": "B",
          "safe_name": "B",
          "group": "letter"
        },
        {
          "char": "1",
          "safe_name": "1",
          "group": "number"
        },
        {
          "char": "+",
          "safe_name": "plus",
          "group": "symbol"
        }
      ]
    }
  ]
}

Color Reference (RGBA Format)¶

Colors are specified as [Red, Green, Blue, Alpha] with values from 0-255:

[0, 0, 0, 255]         // Black
[255, 255, 255, 255]   // White
[255, 0, 0, 255]       // Red
[0, 255, 0, 255]       // Green
[0, 0, 255, 255]       // Blue
[255, 255, 0, 255]     // Yellow
[128, 128, 128, 255]   // Gray
[0, 0, 0, 128]         // Semi-transparent black

Step 5: Creating Image-Only Blocks¶

To create blocks using a single image for all faces (no text), omit the letters array:

{
  "id": "star_block",
  "background_image_path": "letter_blocks/star.block.png",
  "suffix": "star"
}

This creates blocks that display only the background image, useful for decorative blocks or symbols that don't need text overlays.

Step 6: Unicode Characters and Special Symbols¶

You can include any Unicode character using escape sequences:

Common Unicode Characters¶

// Math symbols
{ "char": "\u00D7", "safe_name": "multiply", "group": "symbol" }  // ×
{ "char": "\u00F7", "safe_name": "divide", "group": "symbol" }    // ÷
{ "char": "\u221A", "safe_name": "sqrt", "group": "symbol" }      // √

// Arrows
{ "char": "\u2190", "safe_name": "arrow_left", "group": "symbol" }   // ←
{ "char": "\u2191", "safe_name": "arrow_up", "group": "symbol" }     // ↑
{ "char": "\u2192", "safe_name": "arrow_right", "group": "symbol" }  // →
{ "char": "\u2193", "safe_name": "arrow_down", "group": "symbol" }   // ↓

// Checkmarks and crosses
{ "char": "\u2713", "safe_name": "check", "group": "symbol" }     // ✓
{ "char": "\u2717", "safe_name": "cross", "group": "symbol" }     // ✗

// Currency
{ "char": "\u20AC", "safe_name": "euro", "group": "symbol" }      // €
{ "char": "\u00A3", "safe_name": "pound", "group": "symbol" }     // £

Finding Unicode values:

Visit Unicode Character Table
Search for your character
Copy the \uXXXX escape sequence

Step 7: Save and Build¶

JSON Validation¶

Before building, validate your JSON:

Check syntax - Ensure all brackets, braces, and commas are correct
Unique suffixes - Each letter set must have a unique suffix value
Valid paths - Confirm font and image paths are correct
No trailing commas - Remove commas after the last item in arrays/objects

Tools for validation:

JSONLint
VS Code JSON validation (built-in)

Building the Pack¶

Save the scope.ts file
Run the build command (see Development Setup)
The pack will generate textures and item definitions based on your configuration

Testing¶

Load the built pack into Minecraft Education
Open Creative inventory
Search for your letter blocks using the suffix name
Place blocks and verify appearance
Check game logs for any errors

Troubleshooting¶

Problem: Blocks don't appear in inventory¶

Solutions:

Verify suffix is unique (not used by another set)
Check JSON syntax for errors
Ensure paths to fonts and images are correct
Rebuild the pack completely

Problem: Text is cut off or positioned poorly¶

Solutions:

Adjust font_size (try smaller values)
Check image_size matches background image dimensions
Ensure font file is valid and not corrupted
Try a different font with better character sizing

Problem: Background image looks stretched or wrong¶

Solutions:

Use square dimensions (64×64, 128×128, etc.)
Verify image path is correct
Check image format is PNG
Ensure image isn't corrupt

Problem: Build fails with JSON error¶

Solutions:

Validate JSON syntax using JSONLint
Check for missing commas between objects
Remove trailing commas after last items
Ensure all strings are properly quoted

Advanced Examples¶

Example 1: Bilingual Letter Set (English + Spanish)¶

{
  "id": "bilingual_set",
  "font_size": 44,
  "text_color": [0, 0, 0, 255],
  "image_size": [64, 64],
  "font_path": "fonts/AzeretMono-Black.ttf",
  "background_image_path": "letter_blocks/white.block.png",
  "suffix": "bilingual",
  "antialias": true,
  "letters": [
    { "char": "A", "safe_name": "A", "group": "letter" },
    { "char": "Á", "safe_name": "A_acute", "group": "letter" },
    { "char": "É", "safe_name": "E_acute", "group": "letter" },
    { "char": "Í", "safe_name": "I_acute", "group": "letter" },
    { "char": "Ñ", "safe_name": "N_tilde", "group": "letter" },
    { "char": "Ó", "safe_name": "O_acute", "group": "letter" },
    { "char": "Ú", "safe_name": "U_acute", "group": "letter" },
    { "char": "Ü", "safe_name": "U_umlaut", "group": "letter" }
  ]
}

Example 2: Math Symbols Set¶

{
  "id": "advanced_math",
  "font_size": 52,
  "text_color": [255, 255, 255, 255],
  "image_size": [64, 64],
  "font_path": "fonts/MathFont.ttf",
  "background_image_path": "letter_blocks/chalkboard.block.png",
  "suffix": "math",
  "antialias": true,
  "letters": [
    { "char": "+", "safe_name": "plus", "group": "symbol" },
    { "char": "-", "safe_name": "minus", "group": "symbol" },
    { "char": "\u00D7", "safe_name": "multiply", "group": "symbol" },
    { "char": "\u00F7", "safe_name": "divide", "group": "symbol" },
    { "char": "=", "safe_name": "equals", "group": "symbol" },
    { "char": "\u221A", "safe_name": "sqrt", "group": "symbol" },
    { "char": "\u03C0", "safe_name": "pi", "group": "symbol" },
    { "char": "\u2264", "safe_name": "less_equal", "group": "symbol" },
    { "char": "\u2265", "safe_name": "greater_equal", "group": "symbol" }
  ]
}

Best Practices¶

✅ Start small - Create a test set with just a few characters before making a full alphabet

✅ Test incrementally - Build and test after adding each letter set to catch errors early

✅ Use descriptive IDs - Choose clear, meaningful IDs for easier debugging

✅ Document your sets - Add comments (outside TypeScript) explaining each custom set's purpose

✅ Backup before editing - Keep a copy of the original scope.ts

✅ Version control - Use Git to track changes and revert if needed

✅ Share your creations - Consider contributing custom sets back to the project

Contributing Custom Letter Blocks¶

If you create custom letter blocks that would benefit other educators:

Follow the Contributing Guide
Submit a pull request with your letter set configuration
Include sample images showing the blocks in use
Provide fonts (if openly licensed) or instructions for obtaining them

Development Setup - Set up your development environment
Contributing - How to contribute to Educator Tools
Extensions - Learn about creating extensions
Letter Blocks - Getting Started - Basic usage guide for teachers
More Letter Blocks Extension - Ready-made expansion packs

Need Help? Visit Getting Help or create an issue on GitHub.

⚙️ Advanced Letter Blocks Configuration¶

Overview¶

Before You Begin¶

Requirements¶

File Structure¶

Step 1: Prepare Your Assets¶

Custom Font Files¶

Background Images¶

Step 2: Open the Configuration File¶

Step 3: Understanding the JSON Structure¶

Basic Structure¶

Property Definitions¶

Letter Object Structure¶

Step 4: Adding a New Letter Set¶

Example: Custom Rainbow Set¶

Color Reference (RGBA Format)¶

Step 5: Creating Image-Only Blocks¶

Step 6: Unicode Characters and Special Symbols¶

Common Unicode Characters¶

Step 7: Save and Build¶

JSON Validation¶

Building the Pack¶

Testing¶

Troubleshooting¶

Problem: Blocks don't appear in inventory¶

Problem: Text is cut off or positioned poorly¶

Problem: Background image looks stretched or wrong¶

Problem: Build fails with JSON error¶

Advanced Examples¶

Example 1: Bilingual Letter Set (English + Spanish)¶

Example 2: Math Symbols Set¶

Best Practices¶

Contributing Custom Letter Blocks¶

Related Documentation¶