DEV Community: BibleClinger

Game Tank 65C02 RESET Pitfalls

BibleClinger — Sat, 13 Jun 2026 00:00:23 +0000

I love the 6500 family of processors. Unfortunately, there aren't many modern systems out there that are equipped with a 6502 or any of its descendants. Enter the Game Tank. It's a new, 8-bit console (equipped with two Western Digital 65C02's) that is, as of the date of this writing, supposed to be brought into production soon this year. "New" and "8-bit" aren't usually heard in the same sentence in the year 2026, but here we are, and I'm completely here for it.

Writing 6502 assembly code can be incredibly difficult, even though the chip is a joy to write for -- at least as far as assembly languages go. The Game Tank does sport a C SDK, a Rust SDK, and even a BASIC SDK if you're into any of those languages. While these can be useful, it is my opinion that any developer that works with 6500 processors should write at least one project in assembly in order to better appreciate what is really going on under the hood. It's also probably going to be mandatory to write at least some of your code in assembly if you want to squeeze out every optimization that you can.

Thankfully, there's lot of information and documentation out there. For programming the 6502 you can visit the 6502.org web site. If you're looking for assemblers, there's the well-documented ca65 assembler. Regarding specifics to the Game Tank itself, there is the Game Tank wiki.

Getting Started

Last year I made an attempt at writing a simple program that bounced a rectangle around on the screen of the Game Tank Emulator.

It's not exactly the game of the century, but as a simple demo to see if I understood how the system worked, it was sufficient.

The Pitfalls

Between getting this demo working last year, and now trying slowly to make a Pong variant, I realized how many things can go wrong.

I present you some common pitfalls in initialization routines for the Game Tank.

Initializing Stack RAM in a Routine

.proc RESET
  ...
  ldx #$ff        ; We init the stack
  txs

  jsr ZeroAllRAM  ; We init RAM to 0
  ...
.endproc

A classic 6502 error.

You wrote a RAM initialization routine to set all RAM values in the range $00-$1FFF to 0 so as not to be surprised by random values. Your intentions are good, but the stack lies in the $0100-$01FF range, and jsr and rts both rely on this very stack. If you initialized this range to 0 in your routine, then you just clobbered your return address, and you're probably scratching your head wondering why you somehow rtsed indirectly into your IRQ handler.

You can fix this in a number of ways. The easiest might be to just zero RAM directly in the RESET handler without using a separate routine.

Using RAM Before Initial RAM Banking

The Game Tank can bank RAM, which is a bit novel to me. Which bank is used at startup should be considered random. It is recommended that you initialize this by writing to the Banking Register at $2005 early on in your RESET routine.

Let's say you remember to bank, but you do it this way:

BANKING_REGISTER = $2005
.proc RESET
   ldx #$ff              ; We initialize the stack
   txs                   
   jsr initValues        ; We initialize our game variables
   stz BANKING_REGISTER  ; We bank ram
   ...
.endproc

The bug is that you initialized the stack pointer and initialized your game variables before you banked RAM. Assuming that the Game Tank happens to boot with RAM Bank 0 active, you're fine; the other 3/4ths of the time, your RAM, including your stack, will appear uninitialized or even corrupted. This goes from absolute chaos to an easy fix if you can identify that you simply got the order wrong.

The solution is to set up RAM banking almost immediately -- certainly before stack initialization and variable initialization.

Using a Subroutine to Bank RAM

Let's say you have some important game variables in RAM Bank 0, and some more important game variables in RAM Bank 1. You want to initialize all of them.

BANKING_REGISTER = $2005
.proc RESET
   stz BANKING_REGISTER  ; RAM Bank 0
   ldx #$ff
   txs                   ; We initialize the stack
   jsr initValuesBank0   ; Initialize Bank 0 variables
   jsr ChangeBank1       ; We want to swap to bank 1
   jsr initValuesBank1   ; Initialize Bank 1 variables
   ...
.endproc

.proc ChangeBank1
   lda #$01000000
   sta BANKING_REGISTER  ; RAM Bank 1
   rts
.endproc

The problem here is that by swapping to Bank 1, you have completely pulled the stack out from underneath you. Bank 1's stack almost certainly doesn't point to the correct return location, so we never return from ChangeBank1. Code execution goes somewhere into the unknown.

The solution might be to avoid RAM banking entirely if you don't really need it. (Note: you should still initialize the banking register!) It has a layer of complexity to it that really must be taken into account in order to make it useful.

If you absolutely want to use RAM banking, then the solution might be to redefine ChangeBank1 as a macro, instead of a subroutine to which to jsr. Don't forget to change back to your main RAM bank immediately afterwards!

Conclusion

The 6500 family of processors can be fun to program, but being that you'll likely need to touch assembly, a lot can go wrong. It's worth coming up with a reusable, RESET routine that does all of the initial housekeeping.

Perhaps the next article will be about the things that can go wrong with attempting to use the Game Tank's Blitter...

Star Voyager's Elusive Star Bomb

BibleClinger — Thu, 04 Jun 2026 12:59:55 +0000

I've written previously about Star Voyager for the Nintendo Entertainment System. I first wrote about the hidden method of triggering the win condition. I then wrote about what I call the hidden Minor Damage system.

There are still some interesting secrets buried within this 40 year old game. Today we're going to talk about Star Voyager's Star Bomb.

The Upgrades

You have 2 upgrades you can find among the 8 planets. One planet will give you the Hyperdrive Engine, and the other will give you the Super Laser Cannon. The rest of the planets have nothing for you to find.

The Hyperdrive Engine gives you much more responsive controls, faster acceleration, and faster warp charging. It's very nice to have, particularly when warping long distances.
The Super Laser Cannon, in addition to changing your laser weapons fire to the cool blue of your Home Base Station, will majorly buff your damage.

There's an additional mysterious upgrade called the Star Bomb. You find it by docking with a monolith in an unknown sector in the 10x10 grid of the galaxy that you're fighting in.

Initial Searches for the Monolith

Since the location of the Star Bomb is randomized, and it's not found on your map, players have had to hunt for it. Over the years, it's been realized that we could eliminate certain possibilities. StrategyWiki notes, "The StarBomb is a stationary object, furthermore it is never occupied by a planet or the enemy. While playing the game you can track which sectors are never occupied by the enemy or planets to help limit your search."

We can also eliminate sectors (B,0), (I,0), (J,0), and (A, 1) from the search. The game is hardcoded to eliminate spawns in those sectors for any stationary object, including the Star Bomb.

This is all nifty, but even eliminating all objects, planetary orbits, and special zones that still leaves about 42 possible locations. How many more can you eliminate by noting which sectors the enemies have traveled in? And if you wait for the enemies to travel across the galaxy, do you have enough time to search for it? This is why people only seemed to find it at random:

https://www.youtube.com/watch?v=eRnVUpK9kRM

Star Bomb Found

As it turns out, the devs wanted you to find it all along. They ended up tucking away the secret location within another location -- the Asteroid Belt. They chose this location for good reason. It's one of those sectors you really don't want to visit normally. You are bombarded by asteroids over and over, and even with the Hyperdrive, you may have to take some Minor Damage in order to escape.

Nevertheless, lying within the Asteroid Belt is the secret of the Star Bomb. Before warping to the Asteroid Belt, I'd personally recommend that you have your shields up. You take damage fairly quickly once inside the belt. I also would recommend that you have the Hyperdrive Engine already equipped for fast warp charging and overall efficiency.

Triggering the Secret

Once you have arrived in the belt, press A or B on Controller 2. Your ship's compass will suddenly snap-align to the location of the Star Bomb. If you can't read it, press Select and look at where your Ship's destination is pointed on the Map. Note this location.

Now go back to the Cockpit view, and warp out of there. You probably want to perform the fastest warp which will give you a jump distance of 1. Right before your warp is engaged, you can swap to the Map location, select where you actually want to go (again, you'll only have a jump distance of 1), and then go back to the Cockpit view. This should hopefully help you avoid anything dangerous nearby.

The Star Bomb Sector

Warp over to the sector your compass had suddenly pointed for you. You'll receive a message, "FAINT SIGNAL RECEIVED." Find the monolith and attempt to dock with it as if it were a planet. It'll rotate, disappear from view, and you'll be informed that you use Controller 2 to fire the Star Bomb.

Firing the Star Bomb

The Star Bomb will not fire in a sector that has a station, an asteroid belt, or a planet. It just won't.

It will, however, fire in an empty sector or in a sector with an enemy. Just press A or B on controller 2, and watch the missile fly away.

In this screenshot, the Star Bomb is the small blue square launched by the player at the mothership. Upon a successful launch, the message, "FIRE STARBOMB!" scrolls dramatically on the ship's computer screen.

StrategyWiki, as of the publication date of this article, incorrectly says that "[...] you will get the one and only Star Bomb in the game." In actuality, you get one shot from the Star Bomb per warp. It's as if the Star Bomb is charged by the warp of the Engines. Perhaps this inaccuracy is an attestation to how rare finding the Star Bomb has been for all of these years.

Conclusion

The developers tucked away this secret, but provided a way for players to find it. It's amazing that I've never found how to use the Asteroid Belt to find the Star Bomb until today. How many more secrets are left to be found in this game?

Star Voyager Damage System

BibleClinger — Thu, 04 Jun 2026 09:26:17 +0000

Recently I wrote a post about discovering a secret way to achieve near-instant victory in the notoriously difficult game Star Voyager for the Nintendo Entertainment System. I've been continuing my efforts at reverse engineering aspects of the game, and so far it's been rather enlightening in explaining quite a lot about why this game is so difficult. Today I'd like to talk about the damage system that the game uses.

Your Ship's Systems

Your ship has the following 5 systems:

Shields
Radar
Laser Cannons
Engine
Life Support System

Each of these systems can be damaged during combat with the enemy aliens. You can also take damage to these systems if you end up in an asteroid belt. When a system is damaged, it'll show on the Map screen on the lower left (unless it's the Life Support System). You'll also see the damaged section flashing on the image of your ship on the right. In this screenshot, everything appears fine...

Shields

Your Shields are your only means of defense outside of your piloting skills. You should immediately leave combat if your Shields are damaged, since they will become disabled. Suffice it to say that working Shields are supposed to negate 50% of the incoming damage completely. That's a good enough reason to leave and live to fight another day when they aren't available. (We'll skip other details about shields for now.)

Radar

The Radar uses the right display of the cockpit to show contacts behind you, and it draws a reticle on your HUD for forward contacts. You are well able to pick off motherships and fighters that aren't even rendering by using this forward marking system.

Laser Cannons

The Laser Cannons are your main means of engaging in combat. Once your Laser Cannons are damaged, they cannot fire. It's time to go get repaired.

Engine

The Engine will operate sluggishly once damaged. In my experience, you can maintain combat status with a damaged Engine. You'll probably want to do this if you're down to the last enemy fighters of an enemy unit with a dead mothership. Otherwise, the enemy you were fighting will regenerate to full health after you warp out, and that isn't fun.

Life Support System

The Life Support System will deteriorate over time once damaged. You do NOT have a lot of time to do much of anything except find a station and repair. Otherwise, the Life Support System is a passive system that does nothing while operational other than helping you breathe.

Damage and Repairs

Your Shields, Radar, and Laser Cannons do not operate once they are considered damaged. As noted above, Engines and Life Support will continue to operate, although you have limited time to repair the Life Support Systems.

You repair these systems by warping to a station and docking with it. All of the friendly stations can repair this damage completely, except for the Shields, Laser Cannons, and Life Support System. These three systems must be repaired at your Home Base Station. Your Home Base is easily distinguished in 3D from the other friendly stations by its bright blue color. It's located at coordinate (A,0).

The Hidden Damage Mechanic

Often it seemed to me that during a playthrough, the same systems would get damaged in the mid-to-late game. It felt like the enemies were targeting specific systems each playthrough, or perhaps my repair crews weren't doing such a good job fixing me up to get back into the fray.

Much to my surprise, this was partly true.

Incoming damage is processed a bit like this:

If Shields are on, use the Random Number Generator to drop 50% of all incoming damage (theoretically, at least).
For the damage that hasn't been dropped, use the Random Number Generator to obtain 1 number with 8 possible values.
If this randomized value is anywhere from 1 to 5 inclusive, then the damage goes to the specific system in that slot. For values outside of this range, congratulations -- the damage was absorbed by plot armor.
Invisible damage to systems is capped per system. Once the system meets its cap, the damage becomes visible. Your Shields will turn off, or your Engines will become sluggish, etc. etc.. This is the kind of damage your ship will report, and the kind that has immediate alerts and consequences.

(The bright side is that after step #4 occurs, damage calculated in step #3 for this slot is now ignored; you have extra plot armor until you repair or die.)

From here on, I'll refer to the invisible damage as Minor Damage and the visible damage (the kind that the game warns you about) as Major Damage.

Minor Damage Table

RNG Value	System Hit	Minor Damage Cap	Major Damage Result
0	N/A	N/A	N/A
1	Shields	5	Disabled
2	Laser Cannons	8	Disabled
3	Radar	5	Disabled
4	Life Support System	8	Disabled. Eventual death.
5	Engine	5	Sluggish
6	N/A	N/A	N/A
7	N/A	N/A	N/A

Repairing Minor Damage

All stations, both Home and friendly, repair only half of all your Minor Damage across every system per repair session. Interestingly enough, this means friendly stations can repair Minor Damage even for systems whose Major Damage they can't.

An Example of Minor Damage

Let's say that you got into a desperate combat and barely survived. You defeated an enemy, but he left you with Major Damage to both Shields and Engines. Your Minor Damage will be capped at 5 for both systems. Let's say you also, unknown to you, obtained 3 hits to your Radar, and 6 to your Laser Cannons, and 5 to your Life Support System.

You know that you can't repair Shields at a friendly station, so you warp to your Home Base and dock with it. This repairs the Shields and Engines. Now you think you're fine, but your ship is still worse for the experience.

System	Minor Damage Before Repair	... After Repair	Hits Left
Shields	5	2	3
Radar	3	1	4
Laser Cannons	6	3	5
Engine	5	2	3
Life Support System	5	2	6

You should be able to see the problem. You think you're fully repaired, but Your Shields and Engines are more susceptible to being damaged again, each requiring only 3 hits instead of the usual 5. Your Laser Cannons, one of the two strongest items in the game, are now just as weak as your Engines used to be when you started the game!

But It Seems Fine

Since Minor Damage is a hidden mechanic, another danger is that you may be inclined to run into multiple battles when you shouldn't. Consider what it would mean if, instead of taking any Major Damage, you took 4 hits to the Shields, 4 to Radar, 7 to your Laser Cannons, 4 to Engines, and 7 to Life Support. Yes, it's improbable, but the point is that you wouldn't see any damage for the time being. The moment you get into the next battle, however, everything on your ship might very well be falling apart!

Strategy

In terms of what Minor Damage means for strategy, you should seek to repair between battles, unless you know you didn't take any Minor Damage. To ballpark it, figure for every time the screen showed you getting hit, you took about half of that amount in Minor Damage spread out among your systems. If you know you got through combat without a scratch, great! If you have the fuel to spare as well, you can continue onward to fight another enemy.

If you took a lot of hits in combat, get to a repair station immediately. If you're going into a tough battle and already have some battle damage, visit two different repair stations. Also, keep in mind, if your Life Support or Laser Cannons have received Major Damage, it'll take four repair sessions to fully repair everything back to new. You may not have time for that.

Conclusion

Star Voyager only tells you about Major Damage, when a system either stops working or begins to work sluggishly. Hidden by the game implementation is what I call a Minor Damage bookkeeping system. Major Damage only occurs to a system once that system takes too much Minor Damage. Every time you dock and repair, only half of each system's Minor Damage is repaired, meaning your may be more likely to sustain Major Damage in subsequent battles unless you repair multiple times.

In my opinion, having a more complicated damage system made the game more interesting. Hiding this mechanic, however, I think may have been the mistake that made this game feel unfair and too difficult. Knowing about the Minor Damage system allows players to better strategize between getting repairs and saving time.

Discovering a Secret in Star Voyager

BibleClinger — Sat, 30 May 2026 01:12:47 +0000

Years ago, I used to play a game for the Nintendo Entertainment System called Star Voyager. The basic premise is simple: you're a pilot of a space fighter, and you need to defeat an armada of aliens who are bent on destroying you and your space station, simply because they are mean.

I wasn't very good at it, but there was a lot to it that kept me coming back to play it again over the years. You could dock at space stations and repair and refuel your spaceship. You could land on the eight planets that actually orbit the center of the galaxy. One of these eight contains an upgraded engine, and one contains upgraded weapons -- both of which feel like necessities when fighting enemies that are very difficult. The euphoric feeling of destroying an alien mothership aside, there were other things to it: the exploration, unknown secrets, nagging questions such as, "How do you escape from a black hole? Can you even do it?" made me keep coming back to try something new. (And yes, apparently you can -- but that isn't what we're discussing today!)

The game itself is notoriously difficult. Even with Game Genie cheats, and your shields up, your ship takes damage from the aliens fairly easily, especially if you have the tendency to fly in predictable patterns. Many people have given up on the game as a relic that was too difficult in the 90's without the manual and without something that gives you a significant edge.

RESET Subroutine

Well, today I think I found the ultimate advantage. While digging into the game with a debugger running, I came across an interesting and noteworthy phenomenon in the code: the game was purposely leaving three bytes uninitialized during a reset -- $07FD-$07FF. Not only that, but two of these values were being read uninitialized and compared against "magic numbers."

This made me think the game was purposely testing memory to distinguish between a "warm reset" where a player would press the Reset button, and a "cold reset" where a player would turn the console on fresh. As it turns out, not only was this going on, but the game was tracking the amount of resets and storing that number in $07FD.

But why?

Conditions for the Dev Secret

The game considers the first time you power on the system with the game as reset one. It was looking specifically for reset number six. If it was in fact the sixth reset, then it would perform an AND against two values in zero page. If the result of that wasn't zero, then it would initialize another value in zero page to zero.

It actually sounds convoluted if you don't know what the values are that are being compared. It took me a little bit of time to figure out what exactly the variables being AND'ed represented. Once I did, however, it became abundantly clear what the game was looking for.

One of these variables was the 2nd player's controller input. Interesting. Another was an entry within a table of possible input values corresponding to A, B, Select, Start, Up, Down, Left, and Right. Also interesting.

The game was checking to see if the following conditions were met:

You had reset the console 5 times since the time you originally turned it on with the game loaded.
You were holding Select on Player Two's controller when the game was loading you into the cockpit.

If these conditions were met, then address $9E, which I dubbed MysteryValue, would be set to zero. If these conditions were not met, then MysteryValue would have its previously-set value of nine.

Trying It Out

Instead of hooking up a second controller, I instead used the debugger to make the above conditions true, right when they needed to be.

And nothing seemed to happen.

I checked the map, and I didn't notice anything different.

I exited the map. A little bit of patience, and soon I got a transmission. The game began to inform me that I had, in fact, already won, despite all of the enemies still being visible on the map.

MysteryValue seems to be how many enemies you have left to destroy before victory. By meeting these conditions, we short-circuited the need to destroy them. A better name for the variable might be EnemiesRemaining.

Why is this here?

In my humble opinion, I think this was a trick way for the devs to test the part of the game after you won. All they had to do was load the game, press reset 5 times, hold down Select on the 2nd controller, and then dock with the space station right next to them. Easy testing.

Duplicate with Game Genie Code

We can write our own Game Genie code to set this variable to 0. (If you want to try to write your own codes, there are web sites that can do the bitwise math for you.) Let's look at the relevant section of code where the game initializes $9E (EnemiesRemaining) to nine during a normal run.

Through the Game Genie, we can change one byte per code. The value of nine is written at address $D546: STX EnemiesRemaining. The problem is that the value of nine is achieved by first performing a LDX #$0A at $D53F and then a DEX at $D545.

This means there's no easy way to load my own value into X. Decrementing X and storing the result is very efficiently performed in three bytes while a LDX opcode would take two bytes just to load an immediate value, and the required STX would take another two.

At the moment when X is being decremented, Y is 0. We can swap STX with STY with a single byte change. Let's try it.

STX with zero page addressing has a value of $86. STY with the same addressing has a value of $84. The Game Genie code to swap out $86 and put $84 in its place at address $D546 is KAKITIVA.

Sure enough, success!

Just start the game, wait for the message congratulating you for winning, and then dock with the station. Enjoy the credits!

Too Easy Now!

Well, yes, fighting no one can be too easy. What shall we do? We can change the condition so that you must fight one enemy mothership and her fleet before victory is achieved.

I attempted this by converting the extra DEX to INY. This, coupled with our previous Game Genie code, succeeded in increasing Y to 1, and then storing it into EnemiesRemaining. Unfortunately, changing Y seemed to have other side effects. Despite killing all of the enemies entirely across the galaxy, the game wouldn't end.

We need to change EnemiesRemaining ($9E) within a span of 3 bytes, without altering registers. Instead, we can have Game Genie overwrite STX EnemiesRemaining with INC EnemiesRemaining, and leave the previous DEX alone. Since EnemiesRemaining is initialized to zero at the reset routine, an increment is guaranteed to bump it up to one.

This approach worked for me, and I achieved victory after destroying one enemy. The Game Genie code is VTKITIVA.

Keep in mind, if you destroy a second enemy with this code activated, then EnemiesRemaining will be decremented again, and that will result in you having to defeat $FF enemies. Since there are only nine to begin with, this is impossible to win.

Conclusion

The developers of Star Voyager included a hidden way of accessing the winning screen.
1. Load the game normally.
2. Reset the NES five times.
3. On the last restart, you need to hold down Select on Controller Two until you're fully loaded in the cockpit.
4. Wait for the victory message, and then dock with the space station.
You can trigger the same win condition with Game Genie code KAKITIVA. There is no need to reset the console nor to use any input on Controller Two.
With Game Genie code VTKITIVA, you can trigger the win condition after you defeat one enemy mothership and her fighters.

Edit to Provide Proper Credits

It's come to my attention that, while I discovered this secret independently, Geoffrey Lovelace deserves credit for discovering it before me. I came across his video from April 6th, 2024 only after I published my results here. I'll link to his video here:

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.