DEV Community: BibleClinger

Hunting for a Bug in a Prototype Project

BibleClinger — Tue, 02 Sep 2025 18:52:05 +0000

Every now and then, you have to really wonder how you ended up in a situation where you're hunting for a bug that seems impossible to be happening.

I had decided to submit some pull requests to the prototype project that Joe Strout is working on for MiniScript 2.0. Among the components of the prototype are an assembly language, an assembler, and a VM to run the assembled byte code. (The latest benchmarks are very promising, by the way, indicating that it is very much possible to get MiniScript into a new era of high speed scripting.)

Now I already had added a sample factorial assembly program, as well as support in both the assembler and VM for MULT and DIV opcodes. I thought I was getting a quick sense for how the prototype was designed, and what I would need to do to add anything further. Redspark, from the MiniScript Discord, began adding support for more comparison opcodes to the VM. Today, I added support in the assembler for these same comparison opcodes, but in doing so, this is where I came across the unexpected bug.

I wrote an assembly program to test the opcodes:

# A program that tests the comparison operators.
#  0 -> Working
# -1 -> Not working

@main:
    LOAD r0, 0
    LOAD r1, 1

    IFLT r1, r0, error # Testing <
    IFEQ r0, r1, error # Testing ==
    IFNE r0, r0, error # Testing !=
    IFLE r1, r0, error # Testing <=
    RETURN
error:
    LOAD r0, -1
    RETURN

This program should return 0, but it was returning -1, and only due to the line with IFEQ. The new IFEQ opcode was supposed to test if two registers are equal, and if so, jump to the given label. In this case, it was jumping when the results were clearly NOT equal.

Where to start?

Well, the assembly program was very simple, and it was in fact correct.

I checked the code changes I made to the assembler and couldn't find anything wrong. I checked RedSpark's changes to the VM, and I couldn't find anything wrong there either. I began adding some debug print statements -- quick-and-dirty bug fixing isn't pretty and certainly not proper, but it seemed overkill to start figuring things out with a debugger at this point.

Well, this wasn't right.

Why was it executing IFLT instead of IFEQ? I saw two main possibilities. Either:

the assembler was translating the wrong opcode; or else
the VM was executing the wrong opcode.

Again, I went over both my changes and RedSpark's changes, but I still couldn't find anything wrong. I needed more information.

Well, this was even more puzzling: the opcodes being produced by my code in the assembler were correct, but they were not matching what the VM was executing. I added even more debug printing in the assembler, and turned on the existing debug variable in the VM to get even more output:

I commented out the offending line in the assembly code, and saw the above output. My code was emitting opcodes 7, 9, and 10 correctly, but they were somehow getting to the VM all as opcode 7! Opcode 7 was IFLT, the original comparison opcode. This meant all of the comparison opcodes were somehow being run by the VM as IFLT. Somewhere in between my output from the assembler and the VM's execution, something was going awfully wrong. It was as if something was rewriting my output...

... and that's exactly what was happening. A little bit of background first, though. All of these comparison opcodes take 3 arguments: 2 registers for comparison, and then an offset to jump if the comparison is true. The offset can be either an immediate value (ie. IFEQ r0, r1, 2), or it can take a label (ie. IFEQ r0, r1, someLabel). In this case, I was using a label (ie. "error"). When you use a label, it has to be translated into the other format during assembly.

The bug was actually occurring during the assembler's 2nd pass. When it was translating the label into a direct offset, it was also forcefully rewriting the opcode associated with the line. This part of the code ensured that IFLT was the only comparison opcode that was being sent off in the final rewrite of the line. Since IFLT was the only comparison opcode around when this part of the project was written, there were no consequences until people decided to start adding more opcodes.

Programmers often say that programming is about thinking outside of the box. Troubleshooting can be that way, too. I had started with the assumption that the error was most likely going to be in the new code, but it's worth considering that an error can be in existing code that held to assumptions that aren't true anymore.

Hopefully we see MiniScript 2.0 soon!

Timer for MiniScript

BibleClinger — Tue, 29 Jul 2025 22:29:02 +0000

If you try to write a game for Mini Micro, you'll eventually find the need to write timer code. Perhaps you want the player to shoot projectiles of some sort, but you want to limit the rate of fire. Perhaps you want a bomb to explode after 60 seconds. No matter the case, a timer is going to be what you need if you're trying to do things after a set amount of time.

The essence of a timer is simple. You can do it by storing the amount of time left in the timer, and then subtracting the amount of time passed with each frame from that. This requirement of getting the time passed with each frame means you require a game loop, which I wrote about already.

I wrote a Timer class in my MiniScript library bclib. This has proven to be very useful to me during my two recent game jams.

Example Usage

A simple use of it would be as follows:

import "bclib"

onTimeout = function(timer)
    print "Hello world!"
    engine.quit
end function

timer = bclib.Timer.Create(5, @onTimeout, true)
engine = bclib.Engine.Create(timer)
engine.run

This program waits 5 seconds and then prints "Hello world!" to the screen. Simple!

The arguments to Timer.Create in this example are simple:

The amount of time in seconds before the callback function should be called.
A reference to the callback function, or a map that contains a function called onTimeout. This is what will be called when the timer goes off.
Whether or not the timer is considered started. We want it active right away.

There are other options as well, but this is as simple as it gets.

As for the last two lines, Engine merely supplies the mechanism for the game loop, as I wrote in the article previously mentioned. Our callback function quits the program by calling engine.quit.

By the way, you don't need to use Engine in order to use Timer, but it does make your life easier in my opinion. Otherwise, you need to call Timer.tick on every frame yourself.

Another Example

Let's say you have a class called Fighterjet that can fire missiles. You want to have a 5 second cooldown between missile shots for balancing. How might that look?

Fighterjet = {}

Fighterjet.Create = function
    instance = new self
    instance.canFireMissile = true
    instance.timerCooldownMissile = bclib.Timer.Create(5, @instance)
    return instance
end function

Fighterjet.fire = function(self)
    if self.canFireMissile then
        self.canFireMissile = false
        self.timerCooldownMissile.start
        // Fire missile code goes here
    end if
end function

Fighterjet.onTimeout = function(self, timer)
    canFireMissile = true
end function

Fighterjet.tick = function(self, delta)
    self.timerCooldownMissile.tick delta
end function

Let's assume you have an external mechanic that calls Fighterjet.fire on your Fighterjet instance when the player attempts to fire a missile. Let's further assume that you have an external source (such as Engine) calling Fighterjet.tick every frame.

In this case, we have a variable, canFireMissile that determines if the player can fire the missile. We originally have it set to true. When the player fires, the variable is set to false, and the timer is started. The player is unable to fire another missile until the timer goes off, and the Fighterjet.onTimeout function is called.

As long as Fighterjet.tick is being called every frame, this design should be fairly solid.

Conclusion

Timers are essential for many games, if not most. You should definitely have a Timer class in your arsenal of coding tricks. The library I'm working on is still under development, but feel free to check out the Timer page on the Github wiki for the latest API documentation.

Mini Micro and The Game Loop

BibleClinger — Tue, 29 Jul 2025 16:22:10 +0000

Sometimes the lack of threads in MiniScript makes programmers wonder how to do multiple things. The MiniScript wiki has a good example of how to do this very thing. I'd like to bring your attention to this particular block of code from that example:

lastTime = time
while not key.pressed("escape")
    now = time
    dt = now - lastTime
    lastTime = now
    updateCounter dt   // Update the counter
    ball.update dt     // Update the ball
    yield
end while

The way singlethreaded games work is to employ a single loop just like this one, often called "the main loop" or "the game loop." In the very simplest implementation, you're supposed to be doing all of your game calculations for one frame exactly within the body of the loop, and then sleep for the rest of the frame.

In this example, we need to update both a counter and the ball for each frame. This is handled in the loop by the two lines with comments.

Engine class

The above loop is easy enough code to write, but it can be tedious to write it over and over again as boilerplate in a lot of programs. Also, sometimes you might have more complicated scenarios where you would like a bit more control over what gets updated without having to write all of that out again.

I wrote a class for this that I simply called Engine as part of my MiniScript library called bclib. It provides a mechanism to handle a game loop and provide updates to each object/function that it is given. It can also handle adding and removing from the update list during runtime.

The above code block can be replaced with the following:

import "bclib"

checkEsc = function(dt)
    if key.pressed("escape") then engine.quit
end function

engine = bclib.Engine.Create([@updateCounter, ball, @checkEsc])
engine.run

Example Breakdown

Engine.Create accepts a list. The elements of the list are simply either standalone functions, or else (perhaps preferably) maps that have a tick or update function (searched for in that order). You essentially hand it your code to deal with keyboard input, graphics changes, physics input -- whatever you want your game to do.

In this case, we need two main updates to occur: the updateCounter function and the ball.update function. We pass a function reference directly to updateCounter, but we pass ball directly, since Engine will look for and find its update function. In order to also maintain the condition that the escape key will cause the program to exit, the function checkEsc is written here, and a function reference to it is passed in to Engine.Create as well.

engine.run is where the main loop happens. It blocks while it is running. When engine.quit is called, the engine ceases operations once that entire frame cycle has completed, and engine.run returns.

Other features

Engine also looks for an init function belonging to any update object. This allows for any object initialization that needs to be done. This function is entirely optional, and does not need to be provided. Similarly, it looks for an optional deinit function on any objects that are removed -- or that are still present after Engine.quit has been called.

For more information, please see the Engine wiki page at the github. As the time of this writing, it is still a work in progress, as the library is still being worked on.

Conclusion

In order to do multiple things at once in Mini Micro, programmers need a main loop. The Engine class in the bclib library provides the mechanism to maintain a main loop.

Reflections on Using bclib for Micro Jam #043

BibleClinger — Wed, 16 Jul 2025 12:17:28 +0000

This last weekend, I participated in Micro Jam #043 in which participants had 48 hours to make a video game. The theme for this particular session, open to interpretation, was Colors. The prerequisite was that the player must not stop moving. I wrote my entry in MiniScript for Mini Micro.

Having done two previous game jams last year, I figured this could be another case of stress and deadlines where I might spend more time on the engine than the actual game. In order to mitigate that, I decided to work on my MiniScript library bclib ahead of time. When that was done, I used it to implement Pong as a test, which was simple enough that I could make a basic implementation in an afternoon.

Despite some wonky physics in my Pong clone, I decided my library and I were both ready to venture into Micro Jam #043.

Color Smash Tank

I settled on making a game inspired by an old, arcade classic -- Smash TV. My game is a top-down shooter, where you play as a runaway tank that can turn left or right. Different colored shapes would come out and attack the tank. The player would need to load the correct ammo (associated by color) to eliminate the enemies. I named it Color Smash Tank.

Reflections

I went into coding battle with an arsenal of classes that proved entirely useful to me. The main four I'll address are:

Enum
Timer
TextLabel
Machine

Enum

I wrote about this one previously.

While using this class did help me easily keep track of enumerations, I learned that I needed to be careful about similarly named types. eState.GAMEOVER could be confused for eEvent.GAMEOVER, despite being entirely different enum types altogether. Thankfully, I caught this bug fairly early when nothing happened instead of something.

Timer

If you are developing for Mini Micro, you should probably have a Timer class in your arsenal. I had been writing timer code manually in MiniScript previously. This library gave me the freedom to spin up a timer whenever it made sense.

One interesting thing that I learned is that, in MiniScript, inner functions are very powerful as callbacks. I hadn't been sure when I had designed the Timer class if I wanted to use callback functions or callback objects -- so I decided to support both.

TextLabel

I wrote about this one also previously. Its API has changed a bit, and more changes will probably be on the way in the near future. I took advantage of maps as parameters for TextLabel.Create's parameters, which were growing in number as I was adding more features.

What I learned during the game jam was that I desperately needed alignment options for these TextLabel instances to make the most of them. For example, if you want text centered in the middle of the screen, but you are writing messages of different lengths to the same row and column, then what was once centered in the screen may not be centered later on.

Unfortunately this was something I couldn't address during development of my entry. My text was a bit misaligned, but the TextLabel class proved very handy to me. With alignment added, the next game jam should be even easier.

Machine

Over a year ago, I wrote AXR-100: Operation First Wave which was my first game jam entry in MiniScript for Mini Micro. I ended up writing a lot of state code for it by hand, and it was very messy to me. Without timers, enums, or a state machine, this meant there was a lot of repeat code in order to do similar things all the time.

With the implementation of this state machine class, I was able to model small state machines quite easily in MiniScript. It scaled well enough that I was able to model the basic lifecycle of the game itself as states, such as loading, displaying the title screen, actually playing the game, and displaying a game over message.

What I learned during the game jam is that the code that I supply for my states can be rather complicated. States, transitions, and events should definitely be well thought out -- and indeed this library made it very easy for me to describe what I wanted -- but after that I need also to do my best to keep my state code neat and tidy. Although this might be obvious in theory, in practice this requires the programmer to think very carefully about design choices, such as how certain game objects will interact with other game objects.

Summary

If you'd like to play the game, you can do so here: https://bibleclinger.itch.io/color-smash-tank

If you're developing a game for Mini Micro, and feel that these libraries might help you, feel free to check out the library at: https://github.com/BibleClinger/bclib

Just please be aware that this library is still under development and may change as time goes on.

TextLabel for Mini Micro

BibleClinger — Sun, 29 Jun 2025 08:55:43 +0000

I tested a Mini Micro video game currently being developed for a game jam. A TextDisplay was being used as a combination HUD and debug screen. The health being displayed started at 100%. This was intuitive and made sense. After taking some damage, however, I noticed the player's health became "97%%".

Not only that, but other oddities are happening. "Ammo" is written as "%mmo", for example.

What's going on?

Mini Micro's TextDisplay

Mini Micro's TextDisplay is a graphics layer specifically for text only. It is a two-dimensional grid of cells, with each cell accepting a single character. This grid has 68 columns and 26 rows. When you print to a TextDisplay, the TextDisplay prints the string character by character, starting at the row and column that it has stored internally. The starting row and column can be altered easily by the game, which is what is happening in order to print the HUD.

Let's consider the above screenshot, taken from the MiniScript wiki. If one were to set the TextDisplay's column and row to 30 and 20 respectively and print "Goodbye!" in this state, you would see "Goodbye!orld!" printed on the screen. Printing "Goodbye!" doesn't erase all of the text of "Hello World!" Printing only overwrites the cells that are in its way. In this case, we are only partially overwriting what is on the screen, leaving a mix of new text and old text.

The Problem

In the game, this same issue was happening. "100%" is 4 characters. "97%" is only 3 characters. The 4th character from "100%" (which is the '%' character) is never overwritten when "97%" is printed. This results in the extraneous percent character being left on the screen.

"%mmo" is being written because originally it's written as "Ammo" -- but the string "ZomFrogs left: 100%" line is written chronologically after. When there isn't enough room to write that final '%' character, it gets written to the next line, obliterating the 'A' in "Ammo".

A Worse Problem

These are fairly easy for a player to spot as errors, but what happens when you are dealing with pure numbers? This is where things get much worse.

Imagine if the player must manage the temperature of a critical piece of equipment in a game. Let's say that 150 degrees (in whatever unit) would be too hot, and the player must act quickly and cool the equipment whenever it is reaching this temperature. If it goes over 150 for too long, the facility is in danger, and the player must abandon the equipment and escape.

Now let's further say the player sees "142" printed to the HUD. He recognizes that he must correct the issue by cooling the equipment. He does this successfully by bringing the temperature down to 98 degrees. When the HUD is updated, however, "98" is only 2 characters, whereas "142" is 3 characters. Printing "98" on the same row and column will result in a temperature being displayed of 982 degrees! The player might be convinced that he somehow failed and that he needs to escape immediately. Yet, internally, the game logic is treating the temperature as if it's 98 degrees, well within tolerance.

This sort of mismatch between the internal state of the game vs the feedback given to the player will confuse players endlessly, since it won't always be so clear to them whether the feedback they are receiving is a visual bug or not. If they are able to tell, then this could simply be a major source of frustration.

Solutions

We have a number of potential solutions. We could clear the TextDisplay before we write our data, thereby erasing all text and starting fresh. This is a valid solution in many cases, but it can be a bit expensive in terms of performance to erase the TextDisplay every frame of a game when we really only want to erase parts of it.

We could import the textUtil module (already included in /sys/lib) and use clearRow or clearRect to clear a limited amount of screen space. This is perhaps a better solution in that you're erasing less than the entire screen, but this requires you to keep track of each area that you need to clear.

A third solution could be to write the same amount of characters each time no matter what. Health, for example, in the original game mentioned, would always be written as 4 characters (assuming, of course, that 4 is truly the maximum length it could be). Ninety seven percent would then really be written as "97% " with an extra space appended. This is rather nifty, and relatively efficient if you're dealing with smaller strings whose max lengths you already know.

TextLabel

TextLabel is a new class I've added to my Mini Micro library to address the underlying issue. As it is brand new, it is subject to change in the API, but the concept behind it should remain the same. It tracks where you want to print, and it knows how many characters you wrote the last time, thereby handling the erasure of previous text.

The current implementation, as of July 29, 2025, could be used simply like this:

import "bclib"

health = bclib.TextLabel.Create(text, 55, 25)
health.print "100%"
health.print "97%"

Line 1 is just importing the library.

The next line creates the label. It binds to the TextDisplay pointed to by text, which by default points to the default TextDisplay used by Mini Micro on startup. If you have a custom TextDisplay that you created, you can bind it to that.

The next line prints the message at column 55, row 25 of the TextDisplay pointed to by text, and the line after that updates the text to read "97%". Because it knows the last message was 4 characters long, and the current message being printed is only 3 characters long, it knows to pad the rest of the output with spaces to overwrite only one extra character's worth.

Also, if you want to clear the label, health.clear would do the job.

The Need

This class could be useful because it achieves the results of the other solutions presented while seriously limiting the amount of work the programmer must do. For each update to the value being printed, the programmer only needs to write one print statement, with little to no calculation.

Hopefully this class will be updated and finalized in the near future.

A MiniScript Enum Class

BibleClinger — Mon, 02 Jun 2025 19:51:35 +0000

Given that MiniScript is a very minimalistic scripting language, it purposely lacks an Enum type. Its types are Number, String, List, Map, and funcRef (ie. a function reference) -- and that's it.

That means that when you want to express an Enum type, you may find yourself using magic numbers. You can use Numbers after all -- in fact I would imagine most underlying Enum implementations do in fact use numerical types under the hood -- but if you find yourself writing code like ship.firingMode = 2, you're probably going to be in for a world of hurt when you try to return to your space shooter game after a six month break. You may not be able to remember the significance, nuances, and intricacies of firing-mode 2 off a quick glance.

Alternatively, you can use the String type. ship.firingMode = "MISSILE_MODE" is valid MiniScript and is not a terrible alternative to Numbers, but it could lend itself to some interesting errors if you mistype the string somewhere, since ship.firingMode = "MISSSILE_MODE" is also valid MiniScript.

An Enum class

I decided to implement a simple Enum class in MiniScript. I have just published it to GitHub in a library called bclib[1]. I hope to add more items to this library in the near future.

Let's set up a simple example of how we might use this Enum class in a space shooter. In this theoretical game, our ship can fire off all sorts of different objects, but it can only fire items of one type at a time:

import "bclib"

eShipShootingMode = bclib.Enum.Create("Safety Guns Missile Mines Probe")

eShipShootingMode represents your Enum type. We have chosen five firing modes:

Safety (ie. Weapons off)
Guns
Missile
Mines
Probe

Note: we could have passed a list of strings, but in this example, we used a single string as our argument. Either will work. In the case of a single string, the create function will split the string along spaces.

Now the ship will need to store its firing mode in a variable:

ship = {} // Define your ship properties here
ship.firingMode = eShipShootingMode.Safety // Weapons off

What if the user presses the key for guns? We can switch firing modes easily:

ship.firingMode = eShipShootingMode.Guns

The above line should easily convey to any reader of your code what your intention is: you want the ship to have its firing mode set to fire guns.

Also, trying to set your firing mode to eShipShootingMode.Misssile (ie. a typo with one too many s characters) will crash the program straight up when that line is executed. With a String, that won't happen unless you're doing extra error checking.

Other Functions

bclib.Enum.count: A function that returns how many members the particular enum type has.
bclib.Enum.getName: A function that returns the name instead of the numerical identifier. In our example, eShipShootingMode.getName(eShipShootingMode.Guns) will return "Guns". This can be useful for logging purposes, for example, as you'd want the string instead of the numerical value when logging, or else you'd need to look up what firing mode 2 is all over again.

[1] Short for "BibleClinger Library". Not too original, but straightforward.

Adding Basic Animation to a Mini Micro Game

BibleClinger — Mon, 26 May 2025 05:12:55 +0000

Recently on the MiniScript Discord, Dat_One_Dev posted code he was using for a YouTube video tutorial on making video games for Mini Micro. It was a game where you simply chase a balloon, clicking on it each time it appears. When you click on it, it moves to a new location, waiting for you to repeat the process.

Now this got me thinking. As nice of a simple demo as this was (the code wasn't very long -- about 37 lines in the initial version posted on Discord), something about the balloon seemed off. It wasn't moving at all when it was on the screen. Why not make the balloon move a bit and demonstrate a basic animation technique?

The idea that came to mind first was that we could make the balloon "breathe" -- that is, it would oscillate between shrinking and expanding. Sprites in Mini Micro have a property called scale. We could subtract and add small amounts to this property on the balloon's sprite to achieve each effect respectively.

Variables Required

First we need some variables. Due to how the original script was written[1], I decided to add these as global variables:

breatheTime = 1
currentTime = breatheTime
breatheIncrement = 0.01

breatheTime is the amount of time in seconds for the balloon to perform either a shrink or an expansion.
currentTime is our current timer. It's how much time is left before we swap between shrinking or expanding.
breatheIncrement is how much we want to adjust the scale of the balloon's sprite per tick. In this case, we want to change it by a very small amount, since ticks happen quite frequently -- about 60 times per second.

Breathing Function

breathe = function(dt)
    globals.currentTime -= dt
    if currentTime <= 0 then
        globals.breatheIncrement *= -1
        globals.currentTime = breatheTime
    else
        Balloon.scale += breatheIncrement
    end if
end function

Let's walk through the code. First, our breathe function has one parameter -- the delta time. This is the amount of time that has passed since the last tick or last cycle of the game loop.

We immediately subtract dt -- or delta time -- from currentTime, which is the global timer we just created. We then check to see if our timer is less than or equal to 0. If it is, the timer has been triggered. We have gone far enough in shrinking or expanding. It's time to reverse course!

We reverse course by inverting the sign of breatheIncrement. This is achieved by simple multiplication of -1. We then reset the timer by setting currentTime to breatheTime.

On the other hand, if the timer didn't reach 0, then we continue our current operation by simply adding breatheIncrement to Balloon.scale.

Calculating Time

We have our breathe function, but how do we call it, and how do we pass delta time to it?

First, almost any game in Mini Micro should do something like this for its main game loop:

lastTime = time
while true
    now = time
    dt = now - lastTime

    // Game logic goes here

    lastTime = time
    yield
end while

Within the block where game logic is marked to go, that is where we put code that requires updates per tick -- like breathe. Our new game loop should look something like this:

lastTime = time
while true
    now = time
    dt = now - lastTime

    // Game logic goes here
    breathe dt

    lastTime = time
    yield
end while

The final animation looks like this. Spiffy:

[1] Note: Since we're editing someone else's code, the goal is to accomplish what we want by changing as little as possible. We want to work with what exists, not rewrite it, for our purposes.

MiniScript's locals, outer, and globals

BibleClinger — Sun, 06 Apr 2025 21:09:51 +0000

Just recently on the MiniScript Discord, someone was asking for support with a function of his that was supposed to modify a variable external to his function -- except it wasn't working. Given how this could be a gotcha, I figured it would be a topic worth exploring here in greater detail.

Let's say we have a game where the player has an inventory that can only hold one item. We want to have a function that sets the inventory item, which we'll store in a global.

inventory = "empty" // default item

setInventory = function(item)
    inventory = item
end function

Let's test the code:

print inventory // "empty"
setInventory "key"
print inventory // "empty" ????

What is going wrong? Why is the inventory still empty?

With code this simple, it should be pretty clear that our function is not setting the global inventory variable. We might ask for some help, and someone will tell us to change inventory = item to globals.inventory = item.

Perfect! It works.

But why?

The locals and globals maps

MiniScript has two particular maps worth knowing about right away:

locals
globals

When you set a variable by doing, let's say, x = 5, it's the equivalent of doing locals.x = 5. This locals map is built into MiniScript's inner workings.

globals is the map that contains all of the variables that are set at global scope. When your script begins to run, if you begin executing code without putting it inside any function, and if it's not an imported module, then the globals reference points to the same map as the locals reference.

locals.x = 5
globals.x = 6

print locals.x // prints 6

If this script is run on its own and outside of any function, then locals.x and globals.x are indeed the same variable, because locals and globals are the same map. This is why you can explicitly test if locals == globals in order to run different code, allowing for unit tests in your modules, tests that can be executed on their own but ignored when imported.

Outer

There is a third map available called outer. This one is a bit more niche. It is used for inner functions to access variables local to its outer function.

When your script first starts (again assuming it's being executed on its own and outside of any function) locals == globals and locals == outer and outer == globals will all resolve to true. Easy enough. This is why you don't usually need to be concerned with outer, because often enough, even from within a function, outer == globals will resolve to true.

Reading vs Writing

Let's say you are trying to print a variable named total. How does MiniScript look up the variable?

MiniScript first searches inside the locals map. If it doesn't find it, it tries to find it inside the outer map. If it doesn't find it there, then it tries globals. Finally, it raises a runtime error if it hasn't been found.

This is different from writing, in which case, MiniScript always assumes locals is where you want to write your variables unless you explicitly specify a different map. This is why we can print the value of globals.inventory without explicitly mentioning globals, but we can't write to it without the explicit reference.

Therefore, for reading, you do NOT need to use explicit references to locals, outer, or globals -- unless you are purposely trying to bypass shadowing. (Although if you are trying to do that, perhaps consider if shadowing is really a good idea for you in the first place.) For writing, you must explicitly use a reference to the correct map, if you do NOT wish to use locals.

Summary

The order of variable lookup for reading is locals, then outer, and then globals.
Variables are written to locals by default.
If you want to write to a variable outside of locals, you must specify the map explicitly, whether outer or globals.

MiniScript's Parent-Class Variable Pitfall

BibleClinger — Fri, 14 Mar 2025 05:34:07 +0000

The Scenario

Let's say you're wanting to use MiniScript to write a game for Mini Micro. You're making a Shoot'em Up (or SHMUP for short). This is an older genre of video game that used to be quite popular. Let's say you want to make a bunch of enemy fighters for the player to shoot at in rapid succession as they try to shoot back at the player.

Now let's suppose you have a background in an object oriented programming language like Java. For your enemy fighters, you figure you should make a class like this:

EnemyFighter = { "shotStrength":1, "cargo": [] }

We are defining two properties for an enemy fighter:

The shot strength: how many damage units their shot does to the player ship. By default we want 1 unit of damage.
The cargo that the enemy fighter is carrying. This will translate to what items will drop when the enemy ship is destroyed. This is how the player will pick up loot.

To simplify the loot system, let's just give cargo a list of integers, with each integer corresponding to an item in some lookup table. Let's spawn three enemies:

enemies = []
for i in range (0, 2) // Remember range is inclusive
    e = new EnemyFighter
    e.shotStrength = i+1
    e.cargo.push i
    enemies.push e
end for

We are intending the following:

The first ship has a shot strength of 1 and a single cargo item of id 0.
The 2nd enemy fighter has shot strength 2 and a single cargo item of id 1.
The 3rd and last enemy has a shot strength of 3 and a single cargo item of id 2.

Now adding bullets, collision detection, animations, and the destruction of the enemy fighter are all necessary, but let's bypass that and just test if our code is correct this far. First we'll write a function for EnemyFighter to print its internal variables when destroyed.

EnemyFighter.onDestroy = function(self)
    print "Enemy Fighter destroyed: " + self.shotStrength + "; " + self.cargo
end function

Now let's add some debugging to see what happens when the ship is destroyed.

for e in enemies
    e.onDestroy
end for

This is what prints:

Enemy Fighter destroyed: 1; [0, 1, 2]
Enemy Fighter destroyed: 2; [0, 1, 2]
Enemy Fighter destroyed: 3; [0, 1, 2]

Oh, that's not good. All three enemy fighters are showing that they are carrying three cargo items!

The Problem

At first glance it might look like we made a mistake and added all of the cargo items to each fighter explicitly in our loop, but we didn't; we added one item per fighter. The actual bug is harder to spot. Can you find it?

Let's take a peek at a representation of the EnemyFighter class and the enemies list:

There's only one instance of cargo and it belongs to EnemyFighter. In Java terms, cargo is behaving more like a static class variable than an instance variable. Wow. How did that happen?

A Deeper Dive

MiniScript uses Prototype Inheritance for its implementation of Object Oriented Programming. There is no difference between classes and objects. In fact, both classes and objects are just Maps.

When you use the new keyword, you are making a new map with one entry: __isa. This entry is what MiniScript uses to go up the inheritance chain.

But why did MiniScript duplicate shotStrength for every EnemyFighter instance object? Because we explicitly set it in the child instances. MiniScript adds shadow variables to these instances when we set a variable so we don't have this issue.

But why didn't it duplicate cargo for us? Because we didn't explicitly set the value of cargo for each child instance. Instead we merely pushed another element into the already existing cargo list. Where is that existing list? Inside EnemyFighter.

The Fix

There are multiple ways of fixing this. Here's the simple way to fix this example: explicitly add the line e.cargo = [] directly before you push the cargo index value. This will create a separate cargo list for each enemy fighter. The instancing code becomes this:

enemies = []
for i in range (0, 2) // Remember range is inclusive
    e = new EnemyFighter
    e.shotStrength = i+1
    e.cargo = [] // Fixed shared cargo bug
    e.cargo.push i
    enemies.push e
end for

As an aside, something that might be hard to wrap one's brain around is the fact that the EnemyFighter class could actually be entirely empty of properties, since we aren't using any functionality on this object directly.

Remember EnemyFighter is just a map. It's not inherently an object or a class -- it can be used however we want it to be. The instances of EnemyFighter are also just maps. The problem is simple: if we are editing a list that is actually found in the parent instance, then naturally this will be reflected in all child instances. They are all using the same list, after all.

The Factory Method Pattern

We don't have constructors in MiniScript. Instead, we can make our own factory function that produces objects. Let's rewrite the EnemyFighter class entirely. We want the following features:

EnemyFighter instance creation is handled by a member function that is similar, in Java terms, to a static method on a class.
All instances of EnemyFighter are stored in a list found within the class itself and shared by all instances.
EnemyFighter.onDestroy removes its instance from this internal list.

EnemyFighter = { "Enemies": [] }

EnemyFighter.Create = function(shotStrength=1, cargo=null)
    e = new self
    e.shotStrength = shotStrength
    if not cargo isa list or cargo == null then cargo = []
    e.cargo = [] + cargo
    self.Enemies.push e
    return e
end function

EnemyFighter.onDestroy = function(self)
    print "Enemy Fighter destroyed: " + self.shotStrength + "; " + self.cargo
    EnemyFighter.Enemies.remove EnemyFighter.Enemies.indexOf(self)
end function

Above is the secret internals of the EnemyFighter implementation. If you are writing a sort of game engine for your team to use, they hopefully don't need to know too much about the above code. Rather, they just need to know how to use it.

Now our enemy creation loop might look like this:

for i in range (0, 2) // Remember range is inclusive
    EnemyFighter.Create i+1, [i]
end for

Cleaner! And our debug code to simulate destroying all the enemies could be this:

while EnemyFighter.Enemies.len != 0
   EnemyFighter.Enemies[0].onDestroy
end while

This now prints:

Enemy Fighter destroyed: 1; [0]
Enemy Fighter destroyed: 2; [1]
Enemy Fighter destroyed: 3; [2]

Conclusion

MiniScript's implementation of the OOP paradigm can be a bit tricky. This is especially problematic if you experience something like the above while working hard on a 48 hour game jam where time is a commodity you can't afford to lose much of when tracking down bugs. We can mitigate the difficulties by writing clean instancing code, and adhering to certain programming patterns.

I'll leave you with this last thought: It might be argued that MiniScript's implementation of OOP is actually quite simple, but part of what adds complexity is the baggage we are bringing from other OOP languages into MiniScript.

If you agree or disagree, please let me know in the comments. Alternatively, if you have other ideas on object creation, suggestions for better patterns or practices, or related contemplations on MiniScript, also leave a comment.

Does MiniScript Need Variadic Functions?

BibleClinger — Thu, 13 Mar 2025 08:05:14 +0000

A relatively common question asked at the MiniScript Discord is about variadic functions and why MiniScript lacks this feature.

Variadic Functions

First of all, what even is a "variadic function?" This is a function that takes a variable number of arguments.

For those familiar with C, the standard library function printf is such a function. To a C newbie's surprise, the actual function signature of C's printf is:

int printf ( const char * format, ... );

The ellipsis (the three dots) represents an unknown number of arguments. You can print as many ints, floats, chars, or char *'s, etc. that you would like in one function call.

Why not in MiniScript?

What new MiniScript programmers are usually looking for is a way to process an unknown number of elements. They think variadic functions are the way of solving this, but let's reconsider such problems.

Let's say you have a function that needs to accept an X and a Y coordinate, and then optionally process an unknown amount of numbers. One solution is to write a function with three arguments. The first two can be Numbers, and the last one can be a list. For example:

f = function(x, y, arg_list)
    // arg_list is expected to be a list
end function

This function f can be called like this, assuming the list is already known:

f 102, 215, [5, 6, 10, 4, 2, 6]

You can create the list directly inside the function call as shown above. Such a list can also be obtained at runtime. The simplicity is here. Not only don't we need to fiddle with an unknown amount of arguments, but the question should be -- why would we want to do so when given the above?

Maps as Arguments

Let's say you're building a complicated GUI toolkit for Mini Micro. You want other programmers to be able to use it, so you are making an API. You want a complex function called createWindow that takes in all sorts of properties, such as the width, height, and title of the window in question. Do we need a whole bunch of arguments to accomplish this? Not necessarily. We can use a Map instead to hold our properties.

Although there are probably much better ways of implementing the guts of the function, this is one incredibly straightforward way to write it:

createWindow = function(properties)
    if properties.hasIndex("title") then
        // set title
    end if
    if properties.hasIndex("width") then
        // set width
    end if
    if properties.hasIndex("height") then
        // set height
    end if
end function

This can be called like this by users of your API:

createWindow { "title":"My Window", "width":320, "height":240 }

The map can be hardcoded or built dynamically at runtime. Easy!

Benefits of Maps as Arguments

Now imagine there is a team using your GUI toolkit, and they report back to you that while they love the API, they would like the ability to change the color of the title bar. You agree that this is a needed feature. You can add this in fairly easily, and the function becomes this:

createWindow = function(properties)
    if properties.hasIndex("title") then
        // set title
    end if
    if properties.hasIndex("width") then
        // set width
    end if
    if properties.hasIndex("height") then
        // set height
    end if
    if properties.hasIndex("title_color") then
        // set title bar color
    end if
end function

Here's a serious benefit of this design: your function signature didn't change. It still expects the same number of arguments. This means all of the legacy code already written will still work exactly as before! Interestingly enough, new code for the new version of your toolkit should still run on the old version simply because your function ignores entries in the map that it doesn't recognize! If every property needed its own argument, this could be a nightmare for both you as the developer of this GUI toolkit as well as the users of your API.

Conclusion

Now obviously these examples are contrived, and may not be the best way of implementing GUI code, but the design pattern of using lists and maps in place of variadic arguments has been demonstrated to be incredibly useful within the design philosophy of MiniScript.

Mini Micro and the 6502: Adding Keyboard Input

BibleClinger — Sat, 16 Mar 2024 13:50:29 +0000

As I wrote last time, I had decided to embark on the journey of writing a 6502 microprocessor emulator for the Mini Micro with the intent to try to make a Pong clone written in 6502 assembly. I got as far as being able to write a working "Hello, World!" program in 6502 assembly -- a task that took me 25 lines just in 6502 assembly code alone!

I improved my Hello World example to print the string directly. That is useful, but we already have text output. What we really need right now is input. Let's add some keyboard support.

Mini Micro API

Before we can do that, let's examine the Mini Micro keyboard API, which is written entirely in the fantastic language called MiniScript. We can see from the MiniScript wiki that we have the key class, which lets us obtain keyboard input. Fantastic.

Here are the two functions we'll want to look at first:

key.available
key.get

key.available returns 1 if we have input in the buffer, and 0 otherwise.

key.get returns the next character in the input buffer, but it blocks if no input is immediately available.

In my last post, we discussed memory mapping, which is how the 6502 talks to hardware. We can map an address to each of the above functions. Let's map $4101 to key.available and $4102 to key.get. This means if we read from $4101 in assembly, we'll get the result of key.available, and if we read from $4102 in assembly, we'll get the result of key.get.

The BIT Op Code

Loading the value of $4101 via lda $4101 takes 4 CPU cycles, and it overwrites what is already inside A. Overwriting A is not always ideal. Thankfully, the 6502 has a way of being slightly more efficient.

The BIT opcode allows us to examine bits 7 and 6 of any value stored in memory without actually loading it first into the accumulator. This means we should map key.available specifically to bit 7 (or 6, if we preferred) of $4101 to take advantage of this.

Reading Input

Let's assign names to the addresses $4101 and $4102. Let's call them KEYCTRL and KEYGET respectively. Our assembly code for polling for the next character can look like this:

read:
bit KEYCTRL        ; $4101
bpl read
lda KEYGET         ; $4102

The MiniScript code for this project is already rather lengthy, so we'll just look at some snippets.

Here's the code for reading KEYCTRL ($4101):

KeyboardIO.getKeyCtrl= function(self, memoryAddress, value)
    self.cpu.writeMemory(memoryAddress, key.available * 127, true) // Note: the result goes to bit 7
end function

What about our code for reading KEYGET ($4102)? I was advised on the MiniScript Discord that it would not be in the spirit of the 6502 to block for input, as key.get does when it doesn't have any input available. As a result of conforming to this design philosophy, here's the MiniScript code for reading KEYGET ($4102):

KeyboardIO.getKey = function(self, memoryAddress, value)
    if key.available then self.cpu.writeMemory(memoryAddress, key.get.code % 256, true)
end function

When KEYGET ($4102) is read by the assembly environment, then if and only if key.available returns 1 does the value of key.get become converted into an integer and written to memory for the assembly program to read. Otherwise, the function returns immediately without changing anything, and the assembly program will read whatever was left in KEYGET ($4102) prior to this moment -- which could be the last key entered. If I were to document this behavior in a manual, I would probably write something like, "If the 6502 assembly program reads from KEYGET ($4102) before KEYCTRL ($4101) indicates that there is valid input available, the value read from KEYGET ($4102) is undefined."

Echo

Now I can write a program that takes input from the user and echoes it back to the screen until the user presses the Escape key. Here is the relevant assembly:

KEYCTRL = $4101
KEYGET = $4102
PRINT_BYTE = $4001
PRINT_CHAR = $4002
TEXTDELIM = $4003
STRING_OUT_LOW = $4004
STRING_OUT_HIGH = $4005

ESC = $1B

.CODE

prompt: .byte "Welcome to echo! Type away!", 13, "Press ESC when done...", 13, 13, 0

.proc reset
    lda #<prompt
    sta STRING_OUT_LOW
    lda #>prompt
    sta STRING_OUT_HIGH     ; Print prompt

    ldy TEXTDELIM
    ldx #$00
    stx TEXTDELIM           ; Save old text.delimiter

    read:
    bit KEYCTRL             ; Is key.available true?
    bpl read
    lda KEYGET              ; Read key
    cmp #ESC                ; Compare it to ESC press
    beq done
    sta PRINT_CHAR          ; Print character to screen
    jmp read

    done:
    sty TEXTDELIM           ; Restore old text.delimiter
    sty PRINT_CHAR          ; Adds an extra char. This should be char(13) normally.
    brk                     ; Note, we don't RTS out of reset
.endproc

.segment "VECTORS"
.word reset
.word reset
.word reset

Here's a screenshot of the Echo program in action:

Output of the Echo program

Character Encoding

Without getting into too much detail on character encoding, suffice it to say that characters are encoded here using plain numbers.

Notice how A = 2E in the upper right hand corner of the screenshot. This debug view into the emulation of the 6502 microprocessor shows us the value of the registers in hexadecimal representation.

Since we're performing lda KEYGET every time we have an available key, we're effectively loading the numerical representation of the last character typed into A. Let's look at an ASCII chart, and see if this makes sense. We can see in the chart that hexadecimal 2E, is the numerical representation of the period character. This is, in fact, the last character I had typed in the above screenshot.

A Gif is worth a Million Words

It's more fun to watch this happen live. Here's a gif image of the program execution. Watch how A is always changing to reflect the character typed last. Watch how PC, which is the program counter, is regularly trapped in the loop to bit KEYCTRL until input is available.

Echo output: A and PC are of particular interest

At the end of the program when BRK is executed, A is shown to be 1B in hexadecimal. This is because the last character read from KEYGET was in fact the Escape key which has a hexadecimal value of 1B (which is 27 in decimal). Nothing else overwrote the A register before the BRK caused the program to terminate, so it stays the same.

Final Thoughts

I have a model to connect Mini Micro functionality to the assembly world. My two enemies now are complexity and performance, as I try to map the graphics in an efficient manner. If I can fend off these opponents, I'll have made major progress toward my goal of making a Pong clone in 6502 assembly for the Mini Micro.

Mini Micro and the 6502: Adding retro to the neo-retro

BibleClinger — Tue, 12 Mar 2024 12:53:24 +0000

I couldn't help but feel something was missing in the Mini Micro environment. After all, we are encouraged to poke around and go deeper in this MiniScript-centered ecosystem, but there are practical limits to a "neo-retro virtual computer." Naturally the "virtual" part of that description means there is no hardware to discover. There is no processor for which you can write assembly code in order to squeeze out extra performance.

The Processor

That gave me an idea. Why not give the Mini Micro a virtual CPU for which we could write assembly? It wouldn't provide us with any performance benefit, but it would definitely add some immersion, and it has the potential to be a cool, educational tool.

I had done some dabbling with NES development. While some aspects of the NES are indeed a nightmare, the one thoroughly enjoyable aspect to it is writing assembly code for its 6502-based processor. The 6502 would be my processor of choice to add to the Mini Micro.

Necessary Ingredients

In order to make this happen, we need some components:

A 6502 assembler
A MiniScript program that can read the assembled binary file and execute it
A way for the assembly program to utilize Mini Micro's features
A goal

For #1, yes, I could write my own assembler in MiniScript within the Mini Micro environment, but I decided to choose ca65, at least for now. This assembler is robust, very versatile, and offers some very nice features, not the least of which is the ability to painstakingly describe your memory layout. More on this later!

For #2, that is where the bulk of my project comes into play. My intent is to write more posts on this aspect of the journey as development (hopefully) continues.

For #3, the answer is memory-mapped IO. We'll need a scheme. More on this later as well!

For #4, I'd like to be able to make some sort of Pong clone for the Mini Micro, completely in 6502 assembly.

Memory Mapping

The 1976 Second Edition MCS6500 MICROCOMPUTER FAMILY
PROGRAMMING MANUAL provides a convention for memory mapping

The 6502 has a 16-bit address space, but it has no special way to communicate with other hardware (ie. sound, video, etc. etc..). As a result, in real systems, certain addresses were actually mapped directly to the hardware devices instead of being mapped to RAM.

Did you want to make the sound chip on your system play a tone? Perhaps you'd need to write a value to address $5000 that represents the pitch of the tone you'd like to play. Did you want to change a pixel on the video output? Perhaps you'd need to write the color to $6000, the X coordinate to $6001, and the Y coordinate to $6002. This was different in every system, and it all depended on the hardware components and how they were mapped.

Given that the Mini Micro has no real hardware, but that it has similar functionality (ie. sound and video) tied to native MiniScript objects, we can implement memory mapping to utilize this same functionality. We just need to pick a wise scheme that maps Mini Micro functionality to the assembly world in a smart and efficient manner.

Hello World: 6502 style

Let's see how far I've gotten in about two weeks. Here's a 6502 assembly program that is far from complete, but actually assembles and runs in Mini Micro:

.CODE

msg: .asciiz "Hello, world!"

reset:
ldy $4003   ; Store previous text.delimiter
ldx #$00
stx $4003   ; Disable text.delimiter by setting it to 0

loop:
lda msg, x
beq done
sta $4002   ; print single character of msg[x]
inx
jmp loop
done:
ldx #$0D
sty $4003   ; Enable previous text.delimiter by setting it to char(y)
stx $4002   ; Print the new line
brk

.segment "VECTORS"
.word reset
.word reset
.word reset

And here we have its output when executed on the Mini Micro:

From 6502 assembly to the Mini Micro display: "Hello, world!"

Whew! That's a lot of effort to get a simple message printed to the screen!

But how does it work? How does reading (ie. lda, ldx, ldy) and writing (ie. sta, stx, sty) to memory affect text output?

I mapped addresses $4001 to $4003 to Mini Micro's text functionality for this test:

$4001: Writing a byte to this address outputs it as a number to the screen (ie. Writing 65 will print "65" to the screen)
$4002: Writing a byte to this address outputs it as a character to the screen (ie. Writing 65 will print "A" to the screen)
$4003: Reading or writing a byte to this address gets or sets respectively the value of text.delimiter -- which is the character in Mini Micro that gets printed after every call to print. By default it is the same value as char(13) in MiniScript (or '\r' in C).

The Journey

The important thing so far is that it works -- but is it sufficient for Pong?

As you can see, in this run we've managed to emulate 223 cycles (BRK isn't emulated correctly just yet, so its cycle count isn't accurate) in 0.03506 seconds. That means that the virtual CPU is working at an average speed of ~6.360Khz -- wildly underperforming the real chip that could run between 1Mhz and 3Mhz in the real world. Hopefully we'll explore performance in later updates.

Is it enough? Can we squeeze more performance out of it? Join me on the journey, and let's find out.

Do you have any good 6502 memories? Do you have ideas for this project? Let me know!