Forem: James Rozee

More than Maps

James Rozee — Mon, 26 Jan 2026 15:26:20 +0000

Overview

In building my retro RPG game, Emberfall, I realized early on that UI was going to be important. Emberfall is inspired by games such as the original Bard's Tale and Dragon Wars.

So, I wanted to pay homage to that era by retaining a simple text interface with a bump in graphics quality.

Dilemma

Game Engines such as Mini Micro, don't have visual tools to build your game and although it does come with a GUI module, it wasn't feature rich enough for my needs. So, the first thing I did was create a generic GUI system that dealt with the basics of event handling and input. And although that was a great achievement, it wasn't going to be the hard part as I was about to find out.

It took several days to code the Guild Hall menu alone and it only had a handful of Widgets. I realized that it would take a very long time to code every Dialog that I needed especially when some, such as the Character Creation dialog, would require over 100 Widgets on screen. Placing each one by code, running the game to see the visual output and iteratively making adjustments, was killing my productivity. I needed to do this visually. Not to mention that my code was getting cluttered with hundreds of lines just for widget creation. It was making my code ugly.

Data Driven

So, I felt the answer was in creating a data driven UI that could be loaded from JSON files. First, I designed a simple Schema based on the meta data that my current Widgets needed:

{
  "type": "Dialog",
  "id": "mainPanel",
  "x": 368,
  "y": 224,
  "width": 192,
  "height": 160,
  "children": [
    {
      "type": "Label",
      "id": "name",
      "x": 296,
      "y": 296,
      "width": 32,
      "height": 16,
      "text": "Name",
      "color": "#100f24",
      "alignment": "left"
    },
   ...
}

I created a single factory class that was dedicated to loading the JSON and generating a single Dialog widget with all of its child widgets attached. And this did improve the code quality. Hundreds of lines of boilerplate code were reduced to a single line.

Abusing Tools

However, this was only the first step. I needed to be able to visually build the UI and generate the JSON from that. I went looking for stable UI tools that would fill this gap. I found lots of tools but mostly in the web design space. The few that were game development related had a price tag that was outside my budget range. I had to two options:

Create a UI tool
Abuse a tool that wasn't meant for UI development

Since creating my own tool would be a significant delay, I decided to look for a tool that I could abuse. Tiled is a well-known level editor that supports various map styles including Object layers which allows the arbitrary placement of objects such as rectangles and text which was perfect for my UI layout needs.

More importantly, Tiled supports custom properties and has a JavaScript API. So, I set about creating a JavaScript command that I could execute from the command palette that could export maps to the JSON needed by my UI.

Here is the code that I used to generate my JSON. It isn't 100% stable but it does work.

/**
 * Tiled UI JSON Exporter for Emberfall
 * 
 * Exports Tiled object layers as Emberfall UI Dialog JSON format.
 * 
 * Setup:
 * 1. Copy this script to your Tiled extensions folder:
 *    - macOS: ~/Library/Preferences/Tiled/extensions/
 *    - Windows: %APPDATA%\Tiled\extensions\
 *    - Linux: ~/.config/Tiled/extensions/
 * 2. Restart Tiled
 * 3. Use menu: File > Export as Emberfall UI JSON (top-level menu item, not Export As)
 * 
 * Tiled Map Structure:
 * - Ignored layers: Background (visual reference only)
 * - Dialog layer: Contains Dialog custom properties (id, x, y, width, height, backgroundImage, isModal)
 * - Child objects: Each with "type" property becomes a widget
 * - Object text field maps to: "label" (Button/Label) or "text" (TextField)
 * 
 * Coordinate conversion:
 * - Tiled uses top-left origin; Emberfall uses bottom-left with center-based coordinates
 * - Conversion: cx = obj.x + obj.width/2, cy = (mapHeight - obj.y) + obj.height/2
 */

// Helper for property fallback (avoids nullish-coalescing which may not be supported)
function getProp(obj, key, fallback) {
    const val = obj.property(key);
    if (val === undefined || val === null || val === "") return fallback;
    return val;
}

function exportUIJson(map, fileName) {
    const asset = map || tiled.activeAsset;
    if (!asset || !asset.isTileMap) {
        tiled.log("Error: No tilemap is currently active.");
        return false;
    }

    tiled.log("Exporting tilemap: " + asset.fileName);

    const mapHeight = asset.height * asset.tileHeight; // Convert to pixel height

    // Find the Dialog layer (skip Background and other layers)
    let dialogLayer = null;
    for (const layer of asset.layers) {
        if (layer.isObjectLayer && layer.name === "Dialog") {
            dialogLayer = layer;
            break;
        }
    }

    if (!dialogLayer) {
        tiled.log("Error: No 'Dialog' object layer found. Create an object layer named 'Dialog' with custom properties.");
        return false;
    }

    // Export the dialog with its children
    const dialog = exportLayer(dialogLayer, mapHeight);

    if (!dialog) {
        tiled.log("Error: Failed to export dialog.");
        return false;
    }

    const json = JSON.stringify(dialog, null, 2);

    // Determine output path - write to Emberfall workspace usr/data/interface folder
    let outputPath = null;
    if (fileName) {
        outputPath = fileName;
    } else if (asset && asset.fileName) {
        try {
            const fi = new FileInfo(asset.fileName);
            // Use the Emberfall workspace path
            outputPath = ".../emberfall/usr/data/interface/" + fi.baseName + "-ui.json";
        } catch (e) {
            // Fallback to manual parsing if FileInfo isn't available
            const file = asset.fileName;
            const lastSlash = file.lastIndexOf("/");
            const lastDot = file.lastIndexOf(".");
            const baseName = (lastSlash >= 0 ? file.substring(lastSlash + 1) : file);
            const nameNoExt = lastDot > lastSlash ? baseName.substring(0, baseName.lastIndexOf(".")) : baseName;
            outputPath = ".../emberfall/usr/data/interface/" + nameNoExt + "-ui.json";
        }
    } else {
        outputPath = ".../emberfall/usr/data/interface/emberfall-ui.json";
    }

    // Write to file (commit if supported)
    try {
        tiled.log("Writing to: " + outputPath);
        const outFile = new TextFile(outputPath, TextFile.WriteOnly);
        outFile.write(json);
        if (typeof outFile.commit === "function") {
            outFile.commit();
            tiled.log("Committed file to: " + outputPath);
        } else {
            outFile.close();
            tiled.log("Closed file: " + outputPath);
        }
        tiled.log("UI JSON successfully exported to: " + outputPath);
        return true;
    } catch (e) {
        tiled.log("Error writing file: " + e.message);
        return false;
    }
}

function exportLayer(layer, mapHeight) {
    // Get layer custom properties for Dialog config
    const dialogConfig = {
        type: "Dialog",
        id: getProp(layer, "id", "mainPanel"),
        x: getProp(layer, "x", 240) + getProp(layer, "width", 320)/2,
        y: (mapHeight - getProp(layer, "y", 160)) - getProp(layer, "height", 240)/2, // getProp(layer, "y", 160)
        width: getProp(layer, "width", 320),
        height: getProp(layer, "height", 240)
    };

    // Add optional Dialog properties
    const backgroundImage = layer.property("backgroundImage");
    if (backgroundImage !== undefined && backgroundImage !== null && backgroundImage !== "") {
        dialogConfig.backgroundImage = backgroundImage;
    }

    const isModal = layer.property("isModal");
    if (isModal !== undefined && isModal !== null) {
        dialogConfig.isModal = isModal;
    }

    // Export child objects with "type" property as widgets
    const children = [];
    for (const obj of layer.objects) {
        const type = obj.property("type");
        if (type) { // Only export objects with "type" property
            const widget = exportObject(obj, mapHeight, type);
            if (widget) {
                children.push(widget);
            }
        }
    }

    dialogConfig.children = children;
    return dialogConfig;
}

function exportObject(obj, mapHeight, type) {
    const widget = { type: type };


    // Standard widget properties from Tiled object
    const id = obj.property("id");
    if (id !== undefined && id !== null && id !== "") {
        widget.id = id;
    }

    // Convert coordinates: top-left (Tiled) to bottom-left center (Emberfall)
    const cx = obj.x + obj.width / 2;
    const cy = (mapHeight - obj.y) - obj.height / 2;
    widget.x = Math.round(cx);
    widget.y = Math.round(cy);
    widget.width = Math.round(obj.width);
    widget.height = Math.round(obj.height);

    // Handle Text property and built-in text formatting - maps to different fields based on widget type
    let textContent = null;
    let textColor = null;
    let textAlignment = null;

    // obj.text is a direct string property (not an object)
    if (obj.text && typeof obj.text === "string") {
        textContent = obj.text;

        // Extract text color if available (direct hex string)
        if (obj.textColor) {
            textColor = obj.textColor;
        }

        // Extract horizontal text alignment from textAlignment number
        // Tiled textAlignment combines vertical and horizontal using Qt flags:
        // Horizontal: Left=1, Right=2, HCenter=4
        // Vertical: Top=32, VCenter=128, Bottom=64
        if (obj.textAlignment !== undefined) {
            const align = obj.textAlignment;
            // Check which horizontal flag is set
            if (align & 4) textAlignment = "center";
            else if (align & 2) textAlignment = "right";
            else if (align & 1) textAlignment = "left";
        }
    }
    // Check for custom text/label properties as fallback
    if (!textContent) {
        const textProp = obj.property("text");
        const labelProp = obj.property("label");
        if (textProp !== undefined && textProp !== null && textProp !== "") {
            textContent = textProp;
        } else if (labelProp !== undefined && labelProp !== null && labelProp !== "") {
            textContent = labelProp;
        }
    }

    if (textContent) {
        if (type === "Label" || type === "TextField") {
            // For Label and TextField, text goes to "text" property
            widget.text = textContent;
        } else if (type === "Button") {
            // For Button, text goes to "label" property
            widget.label = textContent;
        }
    } else {
        // Log warning if text is expected but missing
        if (type === "Label" || type === "Button" || type === "TextField") {
            tiled.log("Warning: Object '" + (id || "unnamed") + "' (type: " + type + ") has no text property");
        }
    }

    // Apply extracted text color if found
    if (textColor) {
        widget.color = textColor;
    }

    // Apply extracted text alignment if found
    if (textAlignment) {
        widget.alignment = textAlignment;
    }

    // Widget-specific properties
    const textProperties = ["text", "placeholder", "options", "shortcut", "label"];
    for (const prop of textProperties) {
        const value = obj.property(prop);
        if (value !== undefined && value !== null && value !== "") {
            // Skip if already set from object text
            if (!(prop === "label" && widget.label) && !(prop === "text" && widget.text)) {
                widget[prop] = value;
            }
        }
    }

    // Optional style properties from custom properties (will override built-in text properties if set)
    const styleProperties = ["font", "color", "alignment"];
    for (const prop of styleProperties) {
        const value = obj.property(prop);
        if (value !== undefined && value !== null && value !== "") {
            widget[prop] = value;
        }
    }

    // Handle color properties from Tiled (if stored as custom properties)
    const colorProps = ["hoverColor", "shortcutColor", "shortcutHoverColor"];
    for (const prop of colorProps) {
        const value = obj.property(prop);
        if (value !== undefined && value !== null && value !== "") {
            widget[prop] = value;
        }
    }

    return widget;
}

// Register the export action
var action = tiled.registerAction("exportUIJson", function() {
    try {
        const result = exportUIJson();
        if (result) {
            tiled.log("Export completed successfully");
        } else {
            tiled.log("Export failed - check active tilemap and Dialog layer");
        }
    } catch (e) {
        tiled.log("Export error: " + e.message);
    }
});

action.text = "Export Emberfall JSON"

// Log load to debug console
tiled.log("Emberfall UI exporter loaded - search 'Export Emberfall JSON' in command palette");

Conclusion

After making all of these changes which only took a couple of days to put together, I was able to build three dialogs in one day (including the one with over 100 widgets) and export them to my game in a matter of seconds.

This has really streamlined my approach to UI development and so I thought I would share. Maybe you might also benefit from using Tiled for more than maps.

DevLog #2: Signals Part I

James Rozee — Thu, 01 May 2025 12:47:52 +0000

"Send me a Signal"
EventManager Class
Add a Listener
Triggering a Signal
Queuing a Signal
Remove a Listener
The Complete Code
What's Next?

Logs: ⬅️

"Send me a Signal"

If you're an old fart like me, you'll probably remember a line from a Chris de Burgh song released in 1982: "Ship to shore, answer my call, Send me a signal, a beacon to bring me home."

What does this have to do with game development? Well, the first thing I code in any game I make is a form of the Observer pattern. It allows you to send signals to trigger events in different parts of your game engine without actually calling the code directly.

⚠️ This technique is only useful in fire-and-forget type situations. If you need a response from your call, you shouldn't use this method. Don't get trapped in the situation where you try to make signals talk to each other. It can become messy and very difficult to bug hunt.

For instance, if you're coding a battle system, there'll be a need to update the health bars of your characters. However, you don't want your battle system to directly update the GUI interface because if the GUI code changes or you want to reuse that battle system code for a different game, then your battle system code will break as soon as the code it depends on changes. Sending signals solves this. (Say that 5 times fast)

At a high level, different objects in your game will register to listen for certain signals. When a particular signal is transmitted, it goes into a queue where it is picked up by the Event Manager and broadcast to every object that registered for that signal. You can even package up some data to send along with the Signal. Let's implement this in the MiniScript language.

EventManager Class

First, let's create the EventManager class that will manage listeners and trigger signals.

EventManager = {
    "listeners": {},
    "queue": [],
}

As you can see, it doesn't take much to define the properties for the manager. The listeners are stored in a map data type named listeners. When an object wants to listen for a signal, they are added to that map.

📚 In MiniScript, map data types are just a form of dictionary or associative array.

As an example, this is what the value of the listeners map might look like after a couple of listeners are added:

"listeners" : {
    "signal_name" : [
        {
            "listener": some_object,
            "callback": some_function,
        },
        {
            "listener": another_object,
            "callback": another_function,
        }
  ]
}

So inside the listeners map, we have a list associated with the signal's name. Each element inside that list, contains a map with data about the listener including the object that is doing the listening and the function to call when the signal is triggered.

📚 In MiniScript, a list data type is the equivalent of an array in most languages.

Add a Listener

Let's code the function to add a listener:

EventManager.addListener = function(eventType, listener, callback)
    if not self.listeners.hasIndex(eventType) then
        self.listeners[eventType] = []
    end if

    if not self.findListener(eventType, listener, callback) then 
        l = {
            "listener": listener,
            "callback": callback,
        }
        self.listeners[eventType].push l
    end if
end function

EventManager.findListener = function(eventType, listener, callback)
    if self.listeners.hasIndex(eventType) and self.listeners[eventType].len > 0 then
        // Loop through each Listener and find the one with the Callback
        place = null
        for i in range(self.listeners[eventType].len-1)
            l = self.listeners[eventType][i]
            if l.listener == listener and l.callback == callback then
                place = i
                break
            end if
        end for
        return place
    end if
    return null
end function

The function addListener ensures a list exists for the signal name and that the listener object and its callback exist only once in that signal's list. If an object tries to register the same callback more than once for a signal, it's ignored.

The findListener function is included here because it helps to do some heavily lifting that will be required again later.

Triggering a Signal / Event

Once a listener has been added, the EventManager will be able to process signals. Signals can be triggered to run either immediately such as in the following code:

EventManager.triggerEvent = function(eventType, data=null)
    if self.listeners.hasIndex(eventType) then
        for l in self.listeners[eventType]
            listener = l.listener
            callback = l.callback

            if data == null then
                listener[callback]
            else
                listener[callback] data
            end if
        end for
    end if
end function

Or they can be added to a queue where they can be processed at the end of the game loop.

In case a signal doesn't have any listeners, then that signal is simply ignored.

Queuing a Signal / Event

To delay triggering a signal to the end of a frame, we can add the signal to a queue and then process that queue as either the first or last thing we do in our game loop. If it is the first thing we do, more than likely any signals queued during your game loop will have to wait until the next loop / frame to process them. This is why I tend to process my event queue at the end of the game loop so that all queued signals are processed in the same loop that they were queued.

Let's take a look at how to enqueue a signal and process the queue:

EventManager.queueEvent = function(eventType, data=null)
    self.queue.push [
        eventType,
        data,
    ]
end function

EventManager.processQueue = function
    if self.queue and self.queue.len > 0 then
        for event in self.queue
            self.triggerEvent event[0], event[1]
        end for
        self.queue = []
    end if
end function

Each time processQueue is called, all signals in the queue list will be triggered and then the queue is emptied.

Remove a Listener

There are times that you will want to remove a listener from a signal's list. The removeListener function will do this for you. Most of the heavy lifting is already done by the findListener function making the removal fairly straightforward.

EventManager.removeListener = function(eventType, listener, callback)
    index = self.findListener(eventType, listener, callback)
    if index != null then
        self.listeners[eventType].remove index
    end if
end function

📚 Just a heads up, MiniScript handles null and 0 values as false. This is why I compare index != null because if I just checked if index was considered a true/false value, 0 would be treated as a false and thus when a listener is stored in the 0th element of the list, it wouldn't get removed.

The Complete Code

Here is the complete code for the event library that I'm using in my game.

import "importUtil"
ensureImport "listUtil"

EventManager = {
    "listeners": {},
    "queue": [],
}

EventManager.findListener = function(eventType, listener, callback)
    if self.listeners.hasIndex(eventType) and self.listeners[eventType].len > 0 then
        // Loop through each Listener and find the one with the Callback
        place = null
        for i in range(self.listeners[eventType].len-1)
            l = self.listeners[eventType][i]
            if l.listener == listener and l.callback == callback then
                place = i
                break
            end if
        end for
        return place
    end if
    return null
end function

EventManager.addListener = function(eventType, listener, callback)
    if not self.listeners.hasIndex(eventType) then
        self.listeners[eventType] = []
    end if

    if not self.findListener(eventType, listener, callback) then 
        l = {
            "listener": listener,
            "callback": callback,
        }
        self.listeners[eventType].push l
    end if
end function    


EventManager.removeListener = function(eventType, listener, callback)
    index = self.findListener(eventType, listener, callback)
    if index != null then
        self.listeners[eventType].remove index
    end if
end function


EventManager.triggerEvent = function(eventType, data=null)
    if self.listeners.hasIndex(eventType) then
        for l in self.listeners[eventType]
            listener = l.listener
            callback = l.callback

            if data == null then
                listener[callback]
            else
                listener[callback] data
            end if
        end for
    end if
end function


EventManager.queueEvent = function(eventType, data=null)
    self.queue.push [
        eventType,
        data,
    ]
end function

EventManager.processQueue = function
    if self.queue and self.queue.len > 0 then
        for event in self.queue
            self.triggerEvent event[0], event[1]
        end for
        self.queue = []
    end if
end function

What's Next?

My game also has the need to delay triggering events longer than one frame and even independent of the frame count. I'll show you how I improved this library to add that feature in my next CO9T DevLog.

Logs: ⬅️

DevLog #1: Cat O'Nine Tales

James Rozee — Thu, 01 May 2025 08:46:11 +0000

Overview
What is Mini-Micro?
What's Next?

Logs: ➡️

Late in 2023, I lost my pet cat to cancer. I was heart broken for a long time and didn't feel like doing much in the way of any thing. However, in January of 2025, I started toying with the idea of making a retro Dungeon Crawler in the vain of Eye of the Beholder, Lands of Lore 1 and Dungeon Master. My only requirement was that it had to contain cats as characters. So, Cat O'Nine Tales was born.

For two months, I studied screenshots of those dungeon crawlers to see how they did it and then designed my game's interface.

Satisfied with what I had created, I thought I would just use something like Godot to make it but that's when I stumbled across a sleek little game engine called Mini-Micro. So, on a whim, I decided to take a look and I'm glad that I did.

What is Mini-Micro?

Let me just say upfront that Mini-Micro isn't suitable for every game development project nor does it claim to be. However, it is great for retro style games.

So, other than its cute mascot, why did I choose Mini-Micro over other available engines? In a word: Simplicity.

Concise
First, the scripting language, MiniScript, is so straightforward, I never have to wonder whether I'm using it correctly or have analysis paralysis due to the language. It is so concise in its features, that you can learn the whole language in one day -- especially if you already have some programming experience.

Easy Unit Testing
Second, MiniScript has a simple way to create unit testing. In other languages, I often get myself into trouble by trying to use my game's code to test a library of functions that I'm building. Invariably, something breaks during the process and/or causes bugs from adding and removing code meant for testing. However, MiniScript has an easy way to let you setup a unit test right in the library itself. If you load your library code in Mini-Micro instead of your game code, the tests will execute. But when running your game, the test code is just ignored. So easy.

Builtin Classes
Third, Mini-Micro's builtin classes and functions give me everything that I need for my game. They are hands-off enough that I'm not limited by them and yet they provide enough features to give me a good foundation so that I'm not bogged down with implementing the basics. The fact is: You can get started very quickly with Mini-Micro. I had a fully animated main menu done in just a couple of hours on my first day of using Mini-Micro.

What's Next?

I have my interface designs, a basic world concept and an engine great for retro games. There is lots more to do but the first thing I always code is a way for the game engine to communicate with itself. Stay tuned for the next Devlog in Cat O'Nine Tales.

Logs: ➡️

Forem: James Rozee

More than Maps

Overview

Dilemma

Data Driven

Abusing Tools

Conclusion

DevLog #2: Signals Part I

Table Of Contents

"Send me a Signal"

EventManager Class

Add a Listener

Triggering a Signal / Event

Queuing a Signal / Event

Remove a Listener

The Complete Code

What's Next?

DevLog #1: Cat O'Nine Tales

Table Of Contents

What is Mini-Micro?

What's Next?