DEV Community: JoeStrout

Where in the World Am I?

JoeStrout — Wed, 20 May 2026 23:09:33 +0000

There are so many fun things you can do with web services, and most of them are trivial to use in Mini Micro. Today, let's use a couple of these together to plot your location on a map of the world!

Finding Your Place In the World

...begins by finding your external (or public) IP address. This is the Internet Protocol address by which you are seen on the internet, outside your local network. It's probably different from your internal (or private) IP address, which is what probably appears when you look at the network settings on your computer. We don't care how your computer is known to other computers in your house or neighborhood; we only care how packets are routed to it from the great wide world beyond. Fire up Mini Micro (available free here, and type:

http.get("https://api.ipify.org")

This should return an IP address, something like 66.212.203.27.

Now, to get information about that IP address, including the city it's in and an approximate latitude/longitude, we'll use a different web service:

http.get("http://ip-api.com/json/66.212.203.27")

You can replace the IP address above with whatever you got from the first query. The result will be a string of JSON code that contains your city, region, country, latitude, and longitude, along with the name of your internet service provider (ISP) and other details.

Putting this all together into a little program. Use edit to enter the code editor, then paste in the following:

import "json"
import "stringUtil"
clear

// What's my external IP address?
myIP = http.get("https://api.ipify.org")

// And where am I?
locJson = http.get("http://ip-api.com/json/" + myIP)
locInfo = json.parse(locJson)

pprint locInfo
print "You are in {city}, {region} ({country})".fill(locInfo)

Run this, and it should tell you where you are (along with all those other details). Neat, right?

Don't Tell Me, Show Me!

But we can make it more fun. Let's pinpoint you on a map of the Earth! edit your program again, delete the last two lines (pprint and print), and add in this additional code:

mapImage = file.loadImage("/sys/pics/earth_day.jpg")

// Find the pixel coordinates of our lat/long in this image
px = (locInfo.lon + 180) / 360 * mapImage.width
py = mapImage.height - (90 - locInfo.lat) / 180 * mapImage.height

// Draw a marker (using an offscreen PixelDisplay)
g = new PixelDisplay
g.clear color.black, mapImage.width, mapImage.height
g.drawImage mapImage
g.line 0, py, g.width, py, "#00FFFF88", 3
g.line px, 0, px, g.height, "#00FFFF88", 3
g.fillEllipse px-10, py-10, 20, 20, "#00FFFFFF"
g.drawEllipse px-15, py-15, 30, 30, "#00FFFFAA"
g.drawEllipse px-20, py-20, 40, 40, "#00FFFF88"
markedMap = g.getImage(0, 0, g.width, g.height)

// And draw the mapImage, fit to the screen!
scale = 960/mapImage.width
gfx.drawImage markedMap,
  480 - mapImage.width*scale/2, 320 - mapImage.height*scale/2,
  mapImage.width*scale, mapImage.height*scale

s = "{city}, {region}, ({countryCode})".fill(locInfo)
text.row = 2
text.column = 34 - s.len/2
print s

The result, if you happen to be my neighbor right now, should look like this:

The trick here is knowing that the map image uses a standard equiprectangular projection, where longitude and latitude both map linearly to x and y. That lets us convert from lat/long to pixel coordinates with some reasonably simple math. Most of the code above is then drawing the pinpoint lines and circles on top of the map.

(Note: if you are reading this in the future and live somewhere other than Earth, this code will need adjustment.)

Now in Animated 3D!

Let's take it one step further: combine what you've done so far with the globe demo! Follow these steps:

Save your program, if you haven't already.
edit "/sys/demo/globe" to load the globe demo code.
Select All (^A) and then Copy (^C).
Exit the editor, then edit your program.
Scroll to the bottom, and Paste (^V).
Find the line (at the top of the pasted code) that says bigMapImg = file.loadImage("/sys/pics/earth_day.jpg"), and change it to just say bigMapImg = markedMap instead.

That's it. Now run your program, and you should see your location on a beautiful rotating globe.

Never Be Lost Again

The http module is an often-overlooked gem in the Mini Micro APIs. With one little call we can get our external IP address, and with a second little call, get all sorts of information about that, including the info we need to place ourselves on a map. We also looked at how you are able — nay, encouraged! — to steal from the demo code and make it your own.

What do you think of this? Let me know in the comments below!

MiniScript Weekly News — May 14, 2026

JoeStrout — Thu, 14 May 2026 20:24:30 +0000

Development Updates

MiniScript 2.0 saw a bunch of steady progress this week, especially around garbage collection and string handling. Joe landed a new gc intrinsic with gc.collect and gc.stats methods, plus fixes for runtime error reporting and several VM/refactoring issues in the miniscript2 branch. The dev log and recent commits are worth a look if you enjoy following the architecture work: DEV_LOG, recent commits.

A notable performance decision also got locked in: separate int storage was removed, and all numbers are now double. Joe reported no meaningful benchmark difference, so the simpler design wins here — a great example of keeping the internals elegant without sacrificing speed.

Community Projects

If you’ve been meaning to get started with Mini Micro, Joe’s been actively pointing newcomers toward the quickstart and the built-in demos. The best launch point is still the getting-started guide: How to get started with Mini Micro, and Joe specifically reminded folks to try running things like run "asteroids" in /sys/demo.

There was also a fun new wave of interest around MiniScript on Godot. Community members shared the extension repo Godot-X-MiniScript and a broader GitHub search for related projects: MiniScript + Godot repos.

Discussion Highlights

Several great technical conversations happened this week around embedding and runtime design. People asked about using MiniScript as an embedded language in games, and Joe pointed to the Unity package while noting that the Unity plugin is a bit behind and may need the latest source folder from GitHub. He also shared the language quick reference: MiniScript QuickRef PDF.

On the Mini Micro side, there was a lively discussion about performance benchmarks, palette handling, and low-level 6502-inspired hardware ideas. Joe also highlighted a useful public API list providing online services usable from Mini Micro apps: public-apis/public-apis.

From the Blog

Joe published a new Mini Micro tutorial, HWYDT: Turning the Page, showing how to build a convincing page-flip animation using nothing but math, sprites, and texture mapping. It’s a fun, practical example of what Mini Micro can do — and a nice companion to HWYDT: Swinging from Vines.

Thanks for reading, and happy scripting!

Upcoming Game Jams

These upcoming jams look like a great fit for Mini Micro:

Make Literally Anything Jam '26 (starts 2026-05-15 04:00:00) — A wildly open-ended jam with a loose theme and total freedom to make almost anything you want, perfect for experimenting, getting weird, or shipping something small and fun in just a week.
Micro Jam 058: Tides ($400+ Prizes) (starts 2026-05-16 02:00:00) — A highly approachable theme with lots of room for clever interpretation, making it ideal for a compact 2D game built around atmosphere, movement, or shifting conditions.
ARCADIA JAM #4 (starts 2026-05-15 17:00:00) — A short, open 48-hour jam with permissive rules and no engine restrictions, making it a great chance to build a polished web-friendly game and compete on art, gameplay, and originality.
The Shorter, The Better (starts 2026-05-15 17:30:00) — A very friendly fit for a compact, story-driven game: the 5-minute limit encourages tight pacing, a single ending keeps scope manageable, and web playability makes it easy to share and test.
MVM 32 - Super edition (starts 2026-05-16 02:00:00) — A long-running metroidvania-focused jam with a relaxed three-month window, open engine rules, and room to iterate on exploration, abilities, and level design.
Campfire Creators Jam #2 (starts 2026-05-21 21:00:00) — A highly flexible jam with a retro-friendly campfire theme, welcoming everything from cozy story games to survival, puzzle, and strategy concepts while only requiring a single animated campfire sprite.

HWYDT: Turning the Page

JoeStrout — Wed, 13 May 2026 17:23:37 +0000

On the MiniScript Discord this week, one of our users (Luckythespacecat) shared an animation he made for his Steam game Wishlist Boreal. It looks like an open book, with the page turning as if advancing through the book, including a nice paper-ish curl as it goes. That led to another user (@dslower) pointing out this Instagram reel in which somebody makes a texture-mapped page flip animation, also with a nice curvy page.

And then he had the audacity to opine that you couldn't do such a thing in Mini Micro.

Challenge Accepted

In fact we can do such things in Mini Micro! The trick is just to break the curving surface up into flat quadrilaterals, and then render each quad as a Sprite.

Normally in these tutorials I walk through developing the code step by step — build a little, test a little. But this program is short enough that I think I'll try the opposite: present the full code, and then just explain how it works.

So, for maximum fun, fire up your copy of Mini Micro, edit a new program, and paste in the following code.

import "mathUtil"

clear
display(2).mode = displayMode.pixel
gfx = display(2)
gfx.clear color.clear
debug = false

pageTextures = [
  file.loadImage("page1.png"),
  file.loadImage("page2.png")]

pageWidth = 250
pageHeight = 400
xDivs = [0, 0.025, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 1]

pageSprites = []
lastU = 0
for i in range(1, xDivs.len - 1)
    sp = new Sprite
    sp.image = pageTextures[0]
    sp.setUVs [[lastU, 0], [xDivs[i], 0], [xDivs[i],1], [lastU, 1]]
    pageSprites.push sp
    lastU = xDivs[i]
end for
display(4).sprites += pageSprites

getPolarPoint = function(pagePt, t, forward=true)
    radius = pageWidth * pagePt * (cos(t*2*pi)*0.2 + 0.9)
    if not forward then
        t2 = t^pagePt
        angle = mathUtil.lerp(0, 180, (t+t2)/2)
    else
        t = 1 - t
        t2 = t^pagePt
        angle = mathUtil.lerp(180, 0, (t+t2)/2)
    end if
    return [radius, angle]
end function

polarToXY = function(polarPt, baseX=480, baseY=320)
    radius = polarPt[0]
    ang = polarPt[1] * pi/180
    x = baseX + cos(ang) * radius
    y = baseY + sin(ang) * radius
    // apply a minimum representing the thickness of the pages
    // underneath, leaving a "dip" at the binding in the center
    thickness = 16
    q = abs(x - baseX) / pageWidth * 10
    if q < 1 then
        thickness *= sqrt(1 - (1-q)^2)  // (section of a circle)
    end if
    y = mathUtil.max(y, baseY + thickness)
    return [x,y]
end function

framePoly = function(corners)
    for i in range(-1, corners.len-2)
        p0 = corners[i]
        p1 = corners[i+1]
        gfx.line p0[0], p0[1], p1[0], p1[1], "#FF00FF", 2
    end for
end function

render = function(t, forward=true)
    if debug then gfx.clear color.clear
    topPts = []
    botPts = []
    for pagePt in xDivs
        p = getPolarPoint(pagePt, t, forward)
        topPts.push polarToXY(p, 480, 50 + pageHeight)
        botPts.push polarToXY(p, 480, 50)
    end for
    for i in pageSprites.indexes
        pageSprites[i].setCorners [
          [botPts[i][0], botPts[i][1]],
          [botPts[i+1][0], botPts[i+1][1]],
          [topPts[i+1][0], topPts[i+1][1]],
          [topPts[i][0], topPts[i][1]] ]
        if topPts[i+1][0] >= topPts[i][0] then
            // front surface
            pageSprites[i].image = pageTextures[0]
            u0 = xDivs[i]
            u1 = xDivs[i+1]
        else
            // back surface
            pageSprites[i].image = pageTextures[1]          
            u0 = 1 - xDivs[i]
            u1 = 1 - xDivs[i+1]
        end if
        sp.setUVs [[u0, 0], [u1, 0], [u1, 1], [u0, 1]]
        if debug then framePoly pageSprites[i].corners
    end for
end function

pageState = 0  // 0: page on the right; 1: flipped to the left
render pageState

turnPage = function(toState=1)
    delta = sign(toState - 0.5) * 0.02
    while pageState != toState and not key.available
        yield
        outer.pageState += delta
        if pageState < 0 or pageState > 1 then
            outer.pageState = mathUtil.clamp(pageState)
        end if
        render pageState, toState
    end while
end function

// Main loop
while true
    k = key.get
    if k == char(27) or k == "q" then break  // Esc or Q to quit
    if k == "d" then
        debug = not debug
        gfx.clear color.clear
        render pageState
    end if
    if k == char(17) then turnPage 1
    if k == char(18) then turnPage 0
    if k == char(10) or k == " " then turnPage not pageState
end while

You'll also need two page images: one for the front, and one for the back of the turning page. You can use whatever you like, but to match my demo, download these and save them as page1.png and page2.png:

Now run the program, and press the left/right arrow keys to flip the page. It should look like this:

Neat, right?

Carving up the Page

The secret sauce here is to divide the page into vertical strips, each of which is flat. In the demo, if you press the "d" (for "debug") key, it will actually draw the outlines of those quads, so you can see them.

You can divide the page however you like, but in my animation, I found that the curvature is much greater near the book binding (the left side of the original page) than on the outer (right) side of the page. So I made the divisions smaller on the left, and larger on the right. If we use 0 to refer to the left side of the page image, and 1 to refer to the right, then a sensible set of key points (dividing lines between the quads) might be:

xDivs = [0, 0.025, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.7, 1]

...which in fact you will find as line 15 in the code.

To render any textured quad in Mini Micro, just make a Sprite, set its image property to the texture image, and then use setCorners and setUVs to position the quad on the screen, and select what part of the texture it displays. setCorners takes a list of four [x,y] pairs, in screen coordinates. setUVs takes a list of four [u,v] pairs, where u goes from 0-1 horizontally across the image (exactly like our xDivs values above), and v goes from 0-1 up the image vertically.

If you need a review on setCorners and setUVs, play around with the spriteStretch demo found in /sys/demo/.

In our page-flip demo, you'll find a loop at lines 17-26 which prepares our sprites based on the xDivs we defined above.

pageSprites = []
lastU = 0
for i in range(1, xDivs.len - 1)
    sp = new Sprite
    sp.image = pageTextures[0]
    sp.setUVs [[lastU, 0], [xDivs[i], 0], [xDivs[i],1], [lastU, 1]]
    pageSprites.push sp
    lastU = xDivs[i]
end for
display(4).sprites += pageSprites

Later (starting at line 65), we have a render function that updates those same sprites to reflect the current state of the animation. It begins by building a set of x,y coordinates for the points along the top and bottom of the page:

    topPts = []
    botPts = []
    for pagePt in xDivs
        p = getPolarPoint(pagePt, t, forward)
        topPts.push polarToXY(p, 480, 50 + pageHeight)
        botPts.push polarToXY(p, 480, 50)
    end for

The heavy lifting here is being done by getPolarPoint and polarToXY, which we'll get to in a moment. For now, just understand that we're taking our xDivs points along the page, and converting them into screen coordinates for the top (topPts) and bottom (botPts) of the page. Then we just use those to update the corners of each corresponding sprite.

    for i in pageSprites.indexes
        pageSprites[i].setCorners [
          [botPts[i][0], botPts[i][1]],
          [botPts[i+1][0], botPts[i+1][1]],
          [topPts[i+1][0], topPts[i+1][1]],
          [topPts[i][0], topPts[i][1]] ]
    end for

If we wanted to show the same content (but reversed) on the back of the page, this would be all we need. But really we want to show a different image on the back of the page, and because the sprites are flipped horizontally by that point, we need to invert the U coordinates as well. So we need to insert some extra code into the above for loop to update the image and UV coordinates:

        if topPts[i+1][0] >= topPts[i][0] then
            // front surface
            pageSprites[i].image = pageTextures[0]
            u0 = xDivs[i]
            u1 = xDivs[i+1]
        else
            // back surface
            pageSprites[i].image = pageTextures[1]          
            u0 = 1 - xDivs[i]
            u1 = 1 - xDivs[i+1]
        end if
        sp.setUVs [[u0, 0], [u1, 0], [u1, 1], [u0, 1]]

Now each section not only draws in the right position, but also shows the correct part of the right texture, depending on whether it's flipped.

Computing the Page Shape

For me, drawing the texture-mapped quads was the easy part. The hard part was actually animating the shape of the page throughout the flip.

You could just use keyframe animation: that is, make a tool (similar to that spriteStretch demo) that lets you drag the top and bottom points around by hand, and record the correct position for key frames throughout the flip. Alternatively, you could use some external animation tool that writes to a file you can read in your Mini Micro program. Then just play those positions back, interpolating as needed for in-between frames.

But I didn't have the patience (nor, most likely, the art skills) for all that, so I went for a more mathematical approach. Since the page is essentially rotating around its attachment point (the left side of the unflipped page), I found it easier to think about it in polar (radius and angle) rather than Cartesian (x and y) coordinates. Some trial and error led me to this function.

getPolarPoint = function(pagePt, t, forward=true)
    radius = pageWidth * pagePt * (cos(t*2*pi)*0.2 + 0.9)
    if not forward then
        t2 = t^pagePt
        angle = mathUtil.lerp(0, 180, (t+t2)/2)
    else
        t = 1 - t
        t2 = t^pagePt
        angle = mathUtil.lerp(180, 0, (t+t2)/2)
    end if
    return [radius, angle]
end function

getPolarPoint takes:

a page point, i.e., one of those xDivs points along the page from 0 (left) to (1) right
t, how far we are in the flip animation from 0 (starting position) to 1 (complete)
forward, which is true when flipping forward (right to left) and false when flipping back the other way.

The first version of this function had just radius = pageWidth * pagePt; angle = mathUtil.lerp(0, 180, t) -- that is, a constant radius, and an angle that interpolates smoothly between 0 and 180 degrees. This creates a stiff page that flips without bending. The rest of the final code was just to fancy it up: make the radius a little smaller towards the center of the animation, and add a bit of curl by changing the angle based on how far along the page we are (and how far we are in the animation).

But to actually use this, we have to convert from polar coordinates back to XY coordinates. The basic function for that would be:

polarToXY = function(polarPt, baseX=480, baseY=320)
    radius = polarPt[0]
    ang = polarPt[1] * pi/180
    x = baseX + cos(ang) * radius
    y = baseY + sin(ang) * radius
    return [x,y]
end function

But while I was at it, I decided to have this conversion function also apply some "thickness" to the book, by calculating a minimum Y that varies with our distance along the page. This was to make the endpoints of the animation include a bit of a curl down where the page connects to the rest of the book, so it looks like an actual book with a binding, rather than a thin magazine or something.

The code for this (inserted into the function above) is:

    // apply a minimum representing the thickness of the pages
    // underneath, leaving a "dip" at the binding in the center
    thickness = 16
    q = abs(x - baseX) / pageWidth * 10
    if q < 1 then
        thickness *= sqrt(1 - (1-q)^2)  // (section of a circle)
    end if
    y = mathUtil.max(y, baseY + thickness)

Incorporating Into Your Game

That's all our demo does. To incorporate this into a full game, you would need to draw the "rest" of the book (the open cover and pages underneath the turning page, and ensure that your page sprites are topmost.

Also, you'll probably have more than just one (front and back page). You might have lots of pages in your book. I would implement that with just three sets of page sprites:

one that shows the resting right-hand page
one for the resting left-hand page
one for the actively turning page

At rest, you don't actually need the third one. But as soon as it's time to turn the page, you would add it to the view. If advancing through the book, the right-hand page is going to flip left. So you would set your third page with the content on the right, plus the subsequent page as its back; and update the resting right-hand page to show the page after that. Then animate. At the end of the animation, update the left-hand page to show the same thing as the animation page, and hide the animation page. If going backwards, you'd do something similar, but animating from left to right.

I toyed with the idea of making this into its own little library on GitHub that manages multiple pages, provides different ways of specifying the page animation, etc. But maybe it's not worth it; the core ideas are in this demo, and you can take it from here. Let me know what you think in the comments below, or join us on Discord to discuss more. I can't wait to see what you do with it!

HWYDT: Swinging from Vines

JoeStrout — Wed, 06 May 2026 16:23:32 +0000

The Venerable History of Vine-Swinging

Swinging on vines has been a favorite game mechanic since 1982, when both Jungle Hunt (a thinly disguised Tarzan arcade game) and Pitfall! (on of the Atari 2600's best-selling action games) hit the market.

Since then, swinging from vines, ropes, webs, grappling hooks, extensible bionic arms, etc. has been a recurring staple (including in such modern hits as Spider-Pig!).

But how can you actually do this in your own games? Let's dig in and find out!

The Big Picture

We're going to implement a vine-swinging demo in Mini Micro. Our vines will be composed of five or so straight segments, connected like links in a chain. These will oscillate back and forth, using some simple trigonometry (don't worry, I said simple and I meant it!) to update their positions and rotations. We need a sprite image for each vine segment; this should be a thick line with rounded ends (so they join neatly together), and for decoration, I've added some leaves:

Go ahead and save this image as VineSegment.png, and fire up Mini Micro (download it here if you don't have it already). Notice that the image is mostly empty on the left; the "pivot point" (around which the sprite rotates) in Mini Micro is always in the center of the image, so we've simply offset our drawing so that the center of the image is at one end of the visible segment.

Our hero (Kip) will be, at any given moment, either attached to some vine segment, or flying ballistically through the air. When attached, we just need to update his position along with the vine segment he's clinging to. When flying, then Isaac Newton is in charge, and fortunately his equations are even simpler.

Preliminaries

In Mini Micro, enter edit to start a new program, and then paste in these preliminary steps to clear the screen, get a handy reference to the sprite display, and load some sounds we'll need later.

import "mathUtil"

clear
spriteDisp = display(4)
jumpSound = file.loadSound("/sys/sounds/pickup.wav")
catchSound = file.loadSound("/sys/sounds/swoosh.wav")

Then, we're going to need a bit of math to convert between local and world coordinates. By "local" coordinates, I mean coordinates relative to a sprite — for example, the pixel coordinates of some point in its image; those are local to the sprite. "World" coordinates are basically positions on the screen, except that we're going to be scrolling the view our hero progresses, so it's more accurate to say they are positions relative to the sprite display. We need to convert back and forth: converting from local to world in order to position each vine segment relative to the previous one, or Kip relative to the segment he's holding; and converting from world to local to see if Kip is close enough to grab a vine when flying through the air.

This is where the trigonometry comes in. Honestly, I don't memorize or derive these equations; I just google 'em when I need them. You can just copy and paste this into your program:

// Set the x and y values of the given map to
// the world position corresponding to the
// given XY local to this sprite.  In other words,
// assume targetMap is attached to this sprite
// at local position localX, localY; update its
// x and y accordingly.
Sprite.setXYtoLocal = function(targetMap, localX, localY)
    radians = self.rotation * pi/180
    cosAng = cos(radians)
    sinAng = sin(radians)
    targetMap.x = self.x + localX * cosAng - localY * sinAng
    targetMap.y = self.y + localX * sinAng + localY * cosAng    
end function

// Get the local [x,y] position of some world object
// relative to this sprite.
Sprite.getLocal = function(worldXY)
    radians = self.rotation * pi/180
    dx = worldXY.x - self.x
    dy = worldXY.y - self.y
    cosAng = cos(radians)
    sinAng = sin(radians)
    return [dx * cosAng + dy * sinAng, -dx * sinAng + dy * cosAng]  
end function

Save your program as swing.ms (or whatever you like), and run it just to be sure you haven't made a syntax error. If it seems to do nothing, you're doing great so far!

Swingy vines

Now let's add the code that actually makes a vine. We'll have a Sprite subclass called Segment, just to give them all a common image and length; and then we'll have another class called Vine, which encapsulates a list of segments and knows how to update them.

Segment = new Sprite
Segment.image = file.loadImage("VineSegment.png")
Segment.length = 64

Vine = {}
Vine.angRange = 55  // how far to swing from vertical (degrees)
Vine.period = 2  // how long a full back-and-forth takes (seconds)
Vine.Instances = []

Vine.Make = function(x=480, y=640, qtySegments=5)
    vine = new self
    vine.segments = []
    for i in range(0, qtySegments-1)
        seg = new Segment
        seg.x = x
        seg.y = y - seg.length * i
        seg.rotation = -90
        spriteDisp.sprites.push seg
        vine.segments.push seg
    end for
    Vine.Instances.push vine
    return vine
end function
Vine.update = function(time)
    t = 2*pi * time/self.period
    for i in self.segments.indexes
        seg = self.segments[i]
        ang = -90 + self.angRange * sin(t - i*0.2)
        seg.rotation = ang
        if i < self.segments.len-1 then
            seg.setXYtoLocal self.segments[i+1], seg.length, 0
        end if
    end for
end function
Vine.UpdateAll = function(time)
    for vine in Vine.Instances
        vine.update time
    end for
end function

The key bit is of course the Vine.update function, which iterates over its segments, setting the angle of each, and then the position of the next using that setXYtoLocal function we prepared before. The angle is set according to the time (divided by self.period, which is how we make vines swing faster or slower), and subtracts a little factor of the segment number, i * 0.2. This makes the end of the vine lag a bit relative to the top of the vine, making it look like a rope/chain rather than a rigid bar.

To test this code, let's add a simple main program that creates one vine, and updates it:

Vine.Make
while true
    yield
    Vine.UpdateAll time
end while

Now run, and it should look like this:

Challenge: Add a second vine, at a different position. Double challenge: give it a different period, so they're not swinging in perfect sync!

Our Hero, Kip

Now we need a player character to jump from vine to vine. We'll use our hero Kip (fresh from the Caves of Lava), since his sprites are included with Mini Micro. Delete the mini-main-program you added above, and paste in the code below.

kip = new Sprite
kip.image = file.loadImage("/sys/pics/KP/KP-jump.png")
kip.grabbed = null  // Segment he's hanging onto
kip.grabPos = [0,0] // grab position local to that segment
kip.vx = 0; kip.vy = 0  // velocity, in pixels/sec

kip.update = function(dt)
    if self.grabbed then
        // Stick to the vine, updating our velocity as we go
        lastPos = [self.x, self.y]
        self.grabbed.setXYtoLocal self, self.grabPos[0], self.grabPos[1]
        self.vx = (self.x - lastPos[0]) / dt
        self.vy = (self.y - lastPos[1]) / dt
    else
        // free flying!
        self.vy -= 1000*dt  // gravity
        self.x += self.vx * dt
        self.y += self.vy * dt
        // Try to catch any vine except our last one.
        for vine in Vine.Instances
            if vine == self.lastVine then continue
            if self.tryCatch(vine) then break
        end for
    end if
end function

kip.jump = function(extraVx=0, extraVy=100)
    if not self.grabbed then return
    jumpSound.play
    self.grabbed = null
    self.vy += 100  
end function

kip.tryCatch = function(vine)
    for seg in vine.segments
        localPos = seg.getLocal(self)
        if (0 <= localPos[0] < seg.length) and
          (-12 <= localPos[1] < 12) then
            // Valid catch!
            self.grabbed = seg
            self.grabPos = localPos
            self.lastVine = vine
            catchSound.play
            return true
        end if
    end for
    return false
end function

As you can see, Kip's update method has two modes: it does one thing when he has grabbed a vine, and something else when he is flying through space. Both cases are pretty simple. An important trick in the first case is updating kip's velocity (vx and vy) based on how the vine is causing him to move. That matters because when you jump, you want to continue with (more or less) that same velocity.

In the free-flying case, we just apply some gravity to our vertical velocity (vy), and then update our position according to current velocity. The only tricky bit here is checking to see when we're close enough to another vine to grab it — so I extracted that into its own method, kip.tryCatch. This iterates over the segments of the given vine, and sees what our position would be local to that segment. If it's close enough, then we do the catch. (Who says MiniScript doesn't have try/catch?!)

Camera, Final Setup, and Main Program

Our demo is almost done, so let's press on with the final bit: a function to scroll the display so that the "camera" stays centered on the current vine; some code to create a bunch of vines, increasingly far apart; and the main program.


updateCamera = function(dt)
    // try to center the active vine on the screen
    targetX = kip.lastVine.segments[0].x - 480
    spriteDisp.scrollX = mathUtil.moveTowards(
      spriteDisp.scrollX, targetX, 200 * dt)  
end function

// create the vines
x = 300; dx = 400
while x < 4000
    Vine.Make(x).period = 1.8 + rnd*0.4
    dx += 35
    x += dx
end while

// place Kip on the first vine
kip.lastVine = Vine.Instances[0]
kip.grabbed = kip.lastVine.segments[-2]
kip.grabPos = [40, 0]
kip.update
spriteDisp.sprites.push kip

// main loop
lastTime = time
jumpWasDown = false
while kip.y > 0
    yield
    now = time
    dt = now - lastTime
    lastTime = now
    Vine.UpdateAll now
    kip.update dt
    jumpDown = key.pressed("space")
    if jumpDown and not jumpWasDown then kip.jump
    jumpWasDown = jumpDown
    updateCamera dt
end while
key.clear
text.row = 1
print "Game over!"

And that's it! Run now and you should have a simple but playable game. How far can you make it before you fall?

Full Program

Here's the whole program in one big listing.

import "mathUtil"

clear
spriteDisp = display(4)
jumpSound = file.loadSound("/sys/sounds/pickup.wav")
catchSound = file.loadSound("/sys/sounds/swoosh.wav")

// Set the x and y values of the given map to
// the world position corresponding to the
// given XY local to this sprite.  In other words,
// assume targetMap is attached to this sprite
// at local position localX, localY; update its
// x and y accordingly.
Sprite.setXYtoLocal = function(targetMap, localX, localY)
    radians = self.rotation * pi/180
    cosAng = cos(radians)
    sinAng = sin(radians)
    targetMap.x = self.x + localX * cosAng - localY * sinAng
    targetMap.y = self.y + localX * sinAng + localY * cosAng    
end function

// Get the local [x,y] position of some world object
// relative to this sprite.
Sprite.getLocal = function(worldXY)
    radians = self.rotation * pi/180
    dx = worldXY.x - self.x
    dy = worldXY.y - self.y
    cosAng = cos(radians)
    sinAng = sin(radians)
    return [dx * cosAng + dy * sinAng, -dx * sinAng + dy * cosAng]  
end function

Segment = new Sprite
Segment.image = file.loadImage("VineSegment.png")
Segment.length = 64

Vine = {}
Vine.angRange = 55  // how far to swing from vertical (degrees)
Vine.period = 2  // how long a full back-and-forth takes (seconds)
Vine.Instances = []

Vine.Make = function(x=480, y=640, qtySegments=5)
    vine = new self
    vine.segments = []
    for i in range(0, qtySegments-1)
        seg = new Segment
        seg.x = x
        seg.y = y - seg.length * i
        seg.rotation = -90
        spriteDisp.sprites.push seg
        vine.segments.push seg
    end for
    Vine.Instances.push vine
    return vine
end function
Vine.update = function(time)
    t = 2*pi * time/self.period
    for i in self.segments.indexes
        seg = self.segments[i]
        ang = -90 + self.angRange * sin(t - i*0.2)
        seg.rotation = ang
        if i < self.segments.len-1 then
            seg.setXYtoLocal self.segments[i+1], seg.length, 0
        end if
    end for
end function
Vine.UpdateAll = function(time)
    for vine in Vine.Instances
        vine.update time
    end for
end function

kip = new Sprite
kip.image = file.loadImage("/sys/pics/KP/KP-jump.png")
kip.grabbed = null  // Segment he's hanging onto
kip.grabPos = [0,0] // grab position local to that segment
kip.vx = 0; kip.vy = 0  // velocity, in pixels/sec

kip.update = function(dt)
    if self.grabbed then
        // Stick to the vine, updating our velocity as we go
        lastPos = [self.x, self.y]
        self.grabbed.setXYtoLocal self, self.grabPos[0], self.grabPos[1]
        self.vx = (self.x - lastPos[0]) / dt
        self.vy = (self.y - lastPos[1]) / dt
    else
        // free flying!
        self.vy -= 1000*dt  // gravity
        self.x += self.vx * dt
        self.y += self.vy * dt
        // Try to catch any vine except our last one.
        for vine in Vine.Instances
            if vine == self.lastVine then continue
            if self.tryCatch(vine) then break
        end for
    end if
end function

kip.jump = function(extraVx=0, extraVy=100)
    if not self.grabbed then return
    jumpSound.play
    self.grabbed = null
    self.vy += 100  
end function

kip.tryCatch = function(vine)
    for seg in vine.segments
        localPos = seg.getLocal(self)
        if (0 <= localPos[0] < seg.length) and
          (-12 <= localPos[1] < 12) then
            // Valid catch!
            self.grabbed = seg
            self.grabPos = localPos
            self.lastVine = vine
            catchSound.play
            return true
        end if
    end for
    return false
end function

updateCamera = function(dt)
    // try to center the active vine on the screen
    targetX = kip.lastVine.segments[0].x - 480
    spriteDisp.scrollX = mathUtil.moveTowards(
      spriteDisp.scrollX, targetX, 200 * dt)  
end function

// create the vines
x = 300; dx = 400
while x < 4000
    Vine.Make(x).period = 1.8 + rnd*0.4
    dx += 35
    x += dx
end while

// place Kip on the first vine
kip.lastVine = Vine.Instances[0]
kip.grabbed = kip.lastVine.segments[-2]
kip.grabPos = [40, 0]
kip.update
spriteDisp.sprites.push kip

// main loop
lastTime = time
jumpWasDown = false
while kip.y > 0
    yield
    now = time
    dt = now - lastTime
    lastTime = now
    Vine.UpdateAll now
    kip.update dt
    jumpDown = key.pressed("space")
    if jumpDown and not jumpWasDown then kip.jump
    jumpWasDown = jumpDown
    updateCamera dt
end while
key.clear
text.row = 1
print "Game over!"

Taking it Further

This simple demo could be quickly expanded into a more engaging game:

Keep a score, adding points for every successful jump, and/or for reaching new vines.
Add hazards (water, alligators, whatever) below to heighten the tension.
Add platforms/ground with traditional platformer mechanics (e.g. running and climbing).
Enable Kip to climb up and down the vine he's on (this makes it a lot easier!).
Improve the vine physics, allowing stretching, slinging, and other fun effects, much like Spider-Pig.

Can you think of other good uses for this sort of mechanic? How might you apply this in your own games? Share your thoughts in the comments below!

MiniScript Weekly News — April 30, 2026

JoeStrout — Thu, 30 Apr 2026 23:08:43 +0000

Development Updates

MiniScript 2 got a solid round of command-line quality-of-life improvements this week. Joe added editable input history, searchable REPL history (!? foo style queries), and a new _in / _out history model; he also fixed some extra blank lines in the REPL.

On the raylib side, raylib-miniscript moved forward nicely with raylib now pinned to 6.0 as a git submodule, plus a bump to version 0.3. Even better, every API now has a code example in the wiki, along with a new Raylib Types page to help map Raylib structures into MiniScript.

In the Mini Micro channel, Joe explained display layering and mode switching in detail, and users kicked around some "worst sorting algorithm" ideas just for fun.

Community Projects

Zaxabock shared a playful MiniScript experiment called PseudoLambda: GitHub repo. It defines lambda-like expressions using Joe’s eval support, and it looks like a fun little throwback while waiting on more language features.

𝔇𝔢𝔞𝔱𝔥 has been building an ambitious project, Ultimate Space Odyssey, and shared a deep dive into Mini Micro display management while working through layered UI, sprite displays, and planet generation. The repo is here: Ultimate_Space_Odyssey/Game — great to see someone pushing the display system and documenting what they learn along the way.

Joe also highlighted a great visual idea for the community to try: a Mini Micro kaleidoscope built from sprites and animated UVs. He posted the write-up here: Make a Mini Micro Kaleidoscope, and it sounds like a fun little program to play with for anyone looking for a colorful weekend project.

Discussion Highlights

There was a lively thread about how MiniScript fits into game architecture, especially around threading and when to use install versus simply switching display modes. Joe’s advice was consistent and reassuring: MiniScript is already thread-safe, and in most games you’ll be happier treating install as a special-case tool rather than a default workflow.

Another useful discussion centered on REPL smart quotes and paste behavior in Mini Micro 2. The conversation surfaced a real tension between convenience and control, with several community members offering thoughtful use cases; it was a nice example of the group thinking carefully about developer experience.

There was also some cheerful design brainstorming in #game-ideas, where Midsubspace floated the idea of making a MiniScript Mancala game. Joe gave it an encouraging “go for it,” which feels like the perfect nudge for a good community project.

Thanks for reading — happy scripting, and keep sharing what you’re building!

Upcoming Game Jams

These upcoming jams look like a great fit for Mini Micro:

Mini Choco Jam (starts 2026-02-28 23:00:00) — A romance-focused, story-first jam with 2D-friendly requirements and no need for 3D or networking is an excellent fit for Mini Micro, especially for visual-novel or text-based games.
16bits 2nd Caravan Jam (starts 2026-05-05 13:30:17) — A great fit for a fast, score-chasing arcade game: the jam is built around short, easy-to-pick-up runs with high skill ceilings, especially in the spirit of classic Caravan-style shoot ’em ups.
Three Button Jam 2026 (8 Bits to Infinity) (starts 2026-05-08 17:00:00) — A highly accessible restriction jam with a fun twist: build a complete game using only three buttons, making it perfect for inventive controls, tight design, and clever feedback loops.
Ak Gaming Game Jam #6 — A very accessible jam with free engine choice, no 3D or networking demands, and a strong emphasis on playable, theme-driven entries—great for retro 2D or text-based game ideas.
AEIOU GameJam 2026 (starts 2026-05-01 03:45:00) — A creativity-first jam with a clever twist theme, encouraging illusions, hidden mechanics, and unexpected gameplay that fits retro 2D experimentation perfectly.

Make a Mini Micro Kaleidoscope

JoeStrout — Wed, 29 Apr 2026 20:11:14 +0000

You have got to try this.

Inspired by a Facebook post, I decided this morning to make a kaleidoscope demo for Mini Micro. And man, this thing is trippy!

There are a lot of knobs to tweak and settings to explore, so fire up Mini Micro (download it free here if you don't have it already), and follow along!

The Big Idea

A kaleidoscope is a set of mirrors that reflect onto some interesting "stuff" (traditionally, colorful little bits of plastic at the end of the tube) to provide a multiple views of the same content. In Mini Micro, we're going to provide those views by using Sprites, each using the same image, and stretched out to a diamond shape. Those are arranged in a circle, providing a star shape overall, like this:

I've made the diamonds smaller, and shifted one of the diamonds out a bit so you can see it in the image above. In the real program, we'll scale these up enough that they fill the screen without gaps.

Then, we set the texture coordinates or "UVs" on each diamond to the same portion of a colorful texture, which represents the "interesting stuff" at the end of the tube. Importantly, the UV coordinates are flipped on alternating diamonds. That causes the texture at the edge of one diamond to match up perfectly with the texture on its neighbor, and results in the trippy symmetrical patterns.

Finally, we just move those UV coordinates around on the texture, causing the pattern to whirl and change. It's mesmerizing!

Getting Started

Start by downloading one or both of these images:

‹ ›

I called them "kaltex1.png" and "kaltex2.png". Save them to whatever folder you want to do this project in. Then launch Mini Micro, and mount that same folder (using the disk-slot icon below the screen; or on Mac/Windows, you can just drop the folder onto the Mini Micro window to mount it).

Type view "kaltex1.png" and press Return in Mini Micro to verify that you're set up with everything in the right place. Then use the edit command, and paste in this code:

clear
texture = file.loadImage("kaltex1.png")
cx = 480; cy = 320; r = 600  // screen center and radius
n = 6  // number of wedges

for i in range(n-1)
    sp = new Sprite
    sp.image = texture
    a = i * 2*pi/n
    a1 = a + pi/n
    a2 = a1 + pi/n
    sp.setCorners [[cx, cy],
      [cx+cos(a)*r, cy+sin(a)*r],
      [cx+cos(a1)*r*2, cy+sin(a1)*r*2],  
      [cx+cos(a2)*r, cy+sin(a2)*r]]
    display(4).sprites.push sp
end for

Save that as "kaleidoscope" (or whatever you like), then run it. It should fill your screen with repeating copies of the full texture.

This code mostly just figures out the angle (in radians) to the corners of each diamond, and then calculates the positions of those using cos and sin. If you need a review of how angles, sin, and cos work, run /sys/demo/angles. (And you thought you'd never need trigonometry in real life!)

Setting UVs

edit your program again, and append this code:

uvs = function(t, flip=false)
    cx = 0.5 + 0.25 * sin(t * 0.13)
    cy = 0.5 + 0.25 * cos(t * 0.17)
    a = t * 0.21
    r = 0.25 + 0.08 * sin(t * 0.31)
    result = []
    for i in range(0,3)
        result.push [cx + cos(a)*r, cy + sin(a)*r]
        if flip then a -= pi/2 else a += pi/2
    end for
    return result
end function

We're just defining a function here, not actually calling it, so if you run now it shouldn't behave any differently. But let's take a moment to understand what's going on.

This code is somewhat similar to the diamond-positioning code we had before. It's basically defining a four points arranged in a square that moves around, scales, and rotates, sampling different areas of the sprite texture.

First we calculate a center (cx, cy) position that depends on the value t (representing "time"). When you read cx = 0.5 + 0.25 * sin(t * 0.13), think "cx is going to vary around 0.5, by up to 0.25 in either direction". The factor 0.13 controls how quickly cx varies with time. cy is similar but varies at a different rate.

Then we calculate an angle a, as a straight-up multiple of t. This makes our square rotate steadily with time. (What would happen if you threw a factor of sin in this one too?) Finally, we calculate a radius r that uses the same sin trick to vary by +/- 0.08 around 0.25.

With our center, angle, and radius ready to go, the for loop just calculates each point and stuffs them into result. But note the if statement that adjusts our angle after each point. When flip is true, we subtract pi/2 (90°, or a quarter circle) as we go; otherwise we add it. This is what flips the texture on every other diamond, so that they mesh properly at the edges.

Animation!

edit your code again, and paste in this final piece:

while not key.pressed("escape")
    yield
    t = time
    //t = mouse.x/100 + mouse.y/71
    for i in range(n-1)
        display(4).sprites[i].setUVs uvs(t, i%2)
    end for
end while
key.clear

This is the main loop. We start with a yield, as all good main loops do, fixing the animation rate to 60 frames/sec. Then we choose a t value equal to the time (or, if you uncomment the line after that, a t value that depends on the mouse!). Then we just call setUVs for each of our diamond sprites, passing in t, and with flip set to true (1) for the odd-numbered diamonds.

That's it. Run the program now, and you'll be in trippy kaleidoscope land! But you're not done. Now you get to do the fun part:

Tinkering

This is code that just begs to be played with! Here are some places to start:

Change the texture loaded at the top of the program! This makes a dramatic difference in the overall feel. Try both of the ones above, or try making your own. (Or ask an AI to make one for you.)
Change the value of n (number of diamonds) at the top. 4, 6, 8, and 10 all work well. But push it till it breaks! What happens if you use 5 or 7 or 30?
Uncomment that t = mouse line, and instead of animating with time, you can actually control the thing by moving your mouse around. Play with the constants on that line. Or, can you think of useful ways to combine time and mouse position?
Change the constants in the uvs method. Can you find values you like better?
Throw a .mp3 or .ogg file of background music into your folder, and have your program load and play it.

It's such a small program, but so fun to mess with. There's a good chance this will end up being one of the built-in demos in Mini Micro 2, but for now, only those sharp enough to follow this blog post will get to have that fun. Enjoy!

MiniScript Weekly News — April 22, 2026

JoeStrout — Wed, 22 Apr 2026 23:31:54 +0000

Development Updates

MiniScript 2 made a big step forward this week with the new error type landing in the language. Errors can now be created with err(...), checked with isa error, and even subtyped for more specific handling — a major improvement to one of MiniScript’s longtime weak spots.

Read more in the dev log and discussion thread: miniscript2 DEV_LOG and error handling proposal.

There was also active design discussion around Mini Micro 2, especially whether display mode should keep using the current “magic assignment” style or move to a clearer function call like setMode. Joe is leaning toward preserving compatibility while introducing the cleaner API, which seems like a thoughtful path for existing projects.

Related discussion: #minimicro-2.

On the platform side, raylib-miniscript got more polished documentation and continues to evolve quickly. The API docs now include autogenerated sections for custom intrinsics, plus http.post, file.loadRaw, and file.saveRaw support for practical app and game integration.

Repo: raylib-miniscript

Community Projects

maho_citrus published a new utility library, utf-8-for-miniscript, for environments (like GreyHack) without native UTF8 encode/decode support.
Repo: utf-8-for-miniscript

Dat_One_Dev updated a personal site with a growing collection of Mini Micro articles and courses, including multiple tutorial series. They also mentioned training a model on their site’s content, which is a neat sign that Mini Micro resources are becoming substantial enough to support discovery and reuse.

Links: Mini Micro tutorial hub, Zero to Game Dev, Learn by Code

Zaxabock continued building out logic and automata projects in Mini Micro, including a logic engine template, finite-state automata work, and a Mini-Micro-based logic engine repo. These are the kind of deep, playful technical projects that show how flexible the language can be.

Repo: LogicEngineV4

Joe also shared progress on MiniClaw, a tiny LLM agent built in Mini Micro for working with text files. There’s already a write-up on dev.to, and it’s a fun example of MiniScript being used for something modern while still keeping that compact, readable style.

Article: MiniClaw: A Tiny LLM Agent for Mini Micro

Code: miniclaw on GitHub

Discussion Highlights

There were lots of helpful embedding questions this week, especially from Frib, who is integrating MiniScript into a Unity-based project. Joe confirmed that _foo-style globals are fine for host code, but suggested using intrinsics when possible for safer exposure to user scripts.

MiniScript 2 also sparked some classic language-design brainstorming, from better error propagation to compiler/source-location tracking and stack traces. It’s great to see the community stress-testing the new features and helping shape them before release.

In Mini Micro circles, there’s ongoing interest in tutorials, docs, and even a community book built around expanding existing demos. That kind of “learn by remixing” idea feels very on-brand for MiniScript, and it’s wonderful to see people building on the demos as teaching material.

Thanks for reading — and as always, keep sharing your experiments, tools, and little sparks of weirdness. See you next week!

Upcoming Game Jams

These upcoming jams look like a great fit for Mini Micro:

Mini Choco Jam (starts 2026-02-28 23:00:00) — A romance-focused, story-first jam with 2D-friendly requirements and no need for 3D or networking is an excellent fit for Mini Micro, especially for visual-novel or text-based games.
TriGameDev Monthly Game Jam #6 (starts 2026-04-24 21:00:00) — A 48-hour theme-driven jam about imprisonment and escape, with flexible interpretation and optional challenges like a Panopticon concept or dual perspectives, making it a strong fit for concise 2D retro-style games.
Portfolio Builders Jam - Week #70 (starts 2026-04-27 11:00:00) — A very flexible weekly jam focused on portfolio pieces, with room for small playable demos or even standalone art, audio, or code samples—great for polished 2D, retro-style projects and skill-building experiments.
Deltarune + Undertale Jam — A strong fit for a retro 2D project: this jam centers on turn-based battles, dialogue-driven storytelling, and the emotional, quirky atmosphere that pairs perfectly with pixel art and simple RPG mechanics.
AEIOU GameJam 2026 (starts 2026-05-01 03:45:00) — A creativity-first jam with a clever twist theme, encouraging illusions, hidden mechanics, and unexpected gameplay that fits retro 2D experimentation perfectly.
Oink Jam 2 ($3000+ in Prizes) (starts 2026-04-30 13:00:00) — A short, beginner-friendly four-day jam with flexible themes, light rules, and a welcoming community—great for making a polished retro-style 2D game fast.

MiniClaw: A Tiny LLM Agent for Mini Micro

JoeStrout — Thu, 16 Apr 2026 18:13:14 +0000

Agents are all the rage these days. Claude Code was one of the first, and perhaps still the most heavily used, specialized for coding. Then OpenClaw burst onto the scene, able to do all sorts of general computer-use things, and caused a shortage of Mac Minis. More recently, Hermes Agent is a common favorite, with over 93 thousand stars on GitHub.

All of these agents work in fundamentally the same way. A "harness" acts as both the main program for an LLM, controlling its context so that it always knows what it needs to know; and provides tools the LLM can use so that it can always do what it needs to do.

I covered accessing LLMs from Mini Micro back in 2022, and again in 2023, so why don't we take it to the logical next step, and create an agent in Mini Micro?

Introducing MiniClaw

Yesterday I sat down and created MiniClaw. It consists mainly of three files:

instructions.txt: these are the instructions to the LLM
agent.ms: the main program, which invokes the LLM and manages its context
tools.ms: code for the tools the agent can use to read, write, and manipulate files

So what can it do? Well, MiniClaw can read any file accessible within Mini Micro, which means the /sys disk, plus whatever minidisk or folder you have mounted as /usr and /usr2. It can also write files (only) under /usr/workspace. So, similar to Claude Code or most other agents, you can use it to create and modify pretty much any kind of text file. Or you can just ask it to explain and summarize things for you. For example, I asked it "tell me about the pictures on the sys disk", and it wrote out a nice summary:

On another occasion, I asked it to create a .md (Markdown) file describing all the demos found in /sys/demo. But then, in a later session, I decided that the document it created was too wordy, so I asked it to shorten it:

The gray text gives us some hints as to what the code is doing: it shows when we call the LLM, how much data we get back as a response, and what tool the LLM is using (and why).

Some tasks, like this one, take only a couple of tool calls. Others take more. The LLM will keep invoking tools, occasionally printing some messages for us about its work, until it figures the task is complete (or that it's unable to complete it).

How it works

The complete agent.ms file is only 263 lines long, divided into 14 functions. That's a bit too long to go over line by line here, but we'll hit the highlights, and I encourage you to check the source file for details.

The big picture is this:

Each time we call the LLM, we give it our instructions (always the same), and the prompt (varies each turn).
The prompt includes messages from the user, previous tool calls made by the agent, and the results of those calls -- all this stuff is called the "history". It also includes the current task, so the LLM is clear on what it's supposed to be doing.
The LLM gives us a response in JSON format: either a tool call, a question for the user, an intermediate message, or a final message (indicating it's done).
We run any tool calls the LLM has asked for, and append the call and results to the history.

And that's pretty much it. The main loop looks like this:

    while true
        if not currentUserInput then
            text.color = color.gray; print "==> ", ""
            text.color = "#00AA00"
            globals.currentUserInput = input
            text.color = color.gray
        end if
        response = getResponse
        respData = json.parse(response)
        if respData == null then
            addToHistory("**IMPORTANT:** You must format your response as a JSON object!")
        else
            handleResponse respData
        end if
    end while

currentUserInput is the instruction the agent is working on; it's empty at the start of the run, or when the agent says it's finished. So then we get more input from the user. (Half the code above is just fiddling with the text color to be fancy.)

Then we call getResponse to get the LLM's response to the current context (instructions plus prompt as described above), and try to parse it as JSON. Occasionally the LLM will forget to format its response as JSON; if that happens, we just add a stern reminder to the history (so the LLM will see it) and try again. Otherwise, we call handleResponse:

handleResponse = function(data)
    addToHistory data
    if data.type == "message" then
        printNicely data.content
        globals.lastMessage = data.content
    else if data.type == "question" then
        printNicely data.content
        addToHistory ["", "--- User response ---", input, "--- End user response ---"].join(EOL)
    else if data.type == "finish" then
        printNicely data.content
        globals.currentUserInput = ""
    else if data.type == "tool_call" then
        handleToolCall data
    else
        addToHistory "ERROR: invalid response type """ + data.type +
          """; must be ""message"", ""question"", ""finish"", or ""tool_call""."
    end if  
end function

I've removed some of the error handling and text-coloring above for clarity, but this is the gist of it. We just switch based on the type of response we got from the LLM; it should be one of the four types we put in the instructions. Again, note that when we want to give the LLM more information -- like the user's response to a question -- we just add it to the history.

Let's talk about that addHistory method a moment. Its job is mainly just to append the given string(s) to a list of strings, so they can be included in the context. But for any agent, context management is very important! Too much context burns through tokens, and degrades LLM performance. So, our addHistory method limits how much history it remembers.

addToHistory = function(entry)
    history.push entry
    globals.historyLen += entry.len
    while historyLen > 4096 and history.len > 8
        globals.historyLen -= history[0].len
        history.pull  // discard element 0
    end while
end function

Probably the next most important function is promptInput, which calculates the "prompt" part of the context -- the part that varies from turn to turn.

promptInput = function
    lines = []
    lines.push "# Task/User Input"
    lines.push currentUserInput
    lines.push ""
    lines.push "# Current State"
    lines.push "Date/time: " + dateTime.now
    if history then
        lines.push ""
        lines.push "# Recent history"
        lines += history
    end if
    return lines.join(EOL)
end function

Simple, right? It's just composing a bit of Markdown calling out the current user input, the current state (which for this version of MiniClaw, is only the date/time), and the history. This stuff is appended to the static instructions, and sent to the LLM.

The Tools

The functions above are going to be pretty standard for any agent. What determines what the agent actually does are the tools and instructions provided to it. In MiniClaw, the tools are separated out into their own file, tools.ms.

This file begins with some little helper functions: err, errMissingArg, and okResult, which all generate little result maps to be returned to the LLM; plus resolvePath and isWriteable, which help the tool code deal with files properly. Then, it has a function for each tool:

list_files
read_file
head_file
tail_file
write_file
delete_file
move_file
make_dir

Each of these takes a map containing arguments (which we've gotten by parsing the JSON from the LLM), does its thing if it can, and then returns a map of results -- usually from one of the err functions, or from okResult, with details (like the path of the affected file) added in. This lets the LLM know whether its attempt to use a tool was successful.

As an example, let's look at head_file, whose job it is to return the first so-many lines of a text file. This tool is described in the instructions file as:

{
    "name": "head_file",
    "desc": "Return the first n lines of a UTF-8 file.  Use this to examine large or unknown text files."
    "arguments": { "path": "string", "lines": "int" }
},

We give the agent the name of the tool, a description including advice on when to use it, and info on the expected arguments. So, the actual MiniScript function is expecting its args map to contain "path" and "lines":

head_file = function(args)
    path = args.get("path"); if not path then return errMissingArg("path")
    if not file.exists(path) then return err("Invalid path `" + path + "`")
    lines = args.get("lines", 10)
    data = file.readLines(path)
    if data.len > lines then data = data[:lines]
    result = okResult
    result.path = path
    result.content = data.join(EOL)
    return result
end function

It pulls those arguments out of the map, does some simple validation on them, reads the file, and returns the requested data as the "content" string of the result map.

The other tools all work in a similar fashion.

Trying it out

You can download the MiniClaw source files from GitHub, but in order to access the LLM (gpt-5.4-nano) it uses, you'll need to set up an API key:

Log in to platform.openai.com.
Click on API Keys on the left.
Click Create new secret key, give it a name like "MiniClaw", and copy the key it shows you.
Paste that into a file called api_key.secret next to agent.ms.

Then you can mount that directory in Mini Micro, and run "agent".

As for cost, I wouldn't worry about it too much... I used this thing a lot yesterday and today while developing it, and it cost under 40 cents. gpt-5.4-nano is pretty cheap, and seems smart enough for everything I've tried so far.

Taking it further

This is where it gets fun: add your own tools! This version of MiniClaw only does basic file creation/manipulation, as you can see from the tool list above. But you could make your own MiniClaw do anything Mini Micro is capable of. Examples:

Display a picture
Play a sound (or series of sounds — making music?)
Launch a program
Access the web or web services via http
Do math
Call Wolfram Alpha for help

And adding more tools is pretty easy: just create a function for it in tools.ms, and add a description of the tool to instructions.txt. That's it; the LLM should be smart enough to invoke it when the time is right.

If you want to switch to a different LLM provider (here's a handy guide to AI models for Hermes), you might have to adjust or rewrite the getResponse function, which formats the input for the LLM and then digs the actual response text out of the JSON package it's buried in. But this is totally doable. You could even run a local LLM, if that's your thing, and connect to it at localhost.

There's also a lot that could be done to improve MiniClaw's user interface. Right now it just prints (albeit with pretty colors, supporting basic markdown commonly used by LLMs) stuff to the text display as it comes in. You could instead make a structured display, keeping the current task up top, showing some info about the context on the side, and neatly formatted responses (perhaps drawn with proportional fonts into a PixelDisplay) below.

My main goal with MiniClaw was to create an agent that is simple and small enough (and MiniScript enough!) to be easily understood and modified. And the great thing is, Mini Micro is a safe sandbox environment, assuming you only mount minidisks or folders you aren't worried about. So go nuts and have fun!

MiniScript Weekly News — Apr 9, 2026

JoeStrout — Thu, 09 Apr 2026 23:01:27 +0000

Correction: the headline originally said 2027... now corrected, before the temporal police could find me.

Development Updates

MiniScript 2 saw a nice round of progress this week, with function metadata support being the big new feature. The new info(@func) intrinsic can now expose a function’s name, note, and params: JoeStrout/miniscript2.

On the raylib side, Joe added http.post support, plus file.loadRaw and file.saveRaw for binary data. That should make it easier to talk to REST services and handle non-text assets in raylib-miniscript.

The alchemy UI toolkit keeps taking shape too. Joe shared the first functional UI demo, and the dev log notes working progress on buttons, static text, spinner controls, and a coordinate-system-agnostic Rect class: alchemy-ui.

Community Projects

A big update for the Mini Micro showcase: Joe built a tool to scan itch.io pages and auto-fill missing entries, then expanded the catalog to 80 programs. If you’ve got a MiniScript or Mini Micro game or demo to share, he’s still asking for links to add to the catalog: Mini Micro programs.

Several community-made itch.io projects were highlighted this week. If you want to browse or share them, check out March of the Zomblez, Two Souls, and Going Viral, all by @dslower.

Other community submissions that came up include Chaturanga, and Color Crash by @dat-one-dev, and Color Smash Tank, and Space Fighter 85 by @bibleclinger. It’s great to see so many jam entries and experiments getting some love.

Discussion Highlights

There was some fun brainstorming around a possible physical Mini Micro device. Ideas ranged from a compact keyboard (with arrow keys a must-have), to SD card storage, to even a rounded case with arcade buttons or bundled gamepads.

In the MiniScript 2 forum discussion, Joe floated the new info intrinsic before implementing it, and got a warm response. It’s a promising direction for making introspection and tooling much more pleasant in MS2: forum thread. There was also more discussion of a new error handling system, which may see implementation next week — stay tuned!

Game Jam Notes

This week’s jam theme was “one light source,” and the community quickly pointed folks toward the /sys/demo/2dVis demo and the micro-jam-056 page. Joe also pointed out Florian’s earlier gem, In My Bubble, as another brilliant example of what can be done with a focused idea.

From the Community

BibleClinger also kicked around an interesting idea for a community-authored MiniScript book, where experienced users could each contribute a chapter. That sounds like a wonderful way to share knowledge and celebrate the depth of the community.

Thanks for reading, and keep those MiniScript projects coming!

Upcoming Game Jams

These upcoming jams look like a great fit for Mini Micro:

Impressions Composing Jam Season 4: Melody Jam (starts 2026-04-10 22:00:00) — A focused music jam centered on crafting a memorable melody from a provided theme, with clear, simple requirements and plenty of room for creative interpretation.
KBGames "Game Boys Chillin' On A Grid" Jam (starts 2026-04-13 22:18:30) — A super flexible jam centered on Game Boy vibes, chill/cozy energy, and grid-based ideas—an excellent match for retro pixel art, tile grids, and simple 2D gameplay.
Games Transformed 2026 - 'Smash The Fash' Game Jam — A politically charged jam inviting all kinds of antifascist games, from activist tactics and mutual aid to surreal puzzles and hopeful visions of solidarity, with room for serious, playful, or experimental takes.
Devs That Jam 36-hour Challenge #25: Anniversary Edition (starts 2026-04-25 10:00:00) — A fast, beginner-friendly 36-hour jam with a community-chosen theme, flexible use of pre-made assets, and judging that rewards fun, clarity, visuals, audio, and polish.
Pan-African Jam with Lagos Games Week 2026 (starts 2026-04-23 22:00:00) — A highly welcoming, fully virtual jam centered on creativity, cross-border collaboration, and game discovery—open to any genre and especially appealing for developers who want a community-driven event with real visibility and prizes.
Portfolio Builders Jam - Week #69 (starts 2026-04-20 11:00:00) — A very flexible weekly jam focused on building portfolio pieces, with room for playable demos, polished art, audio, or code showcases—ideal if you want to make something small, skill-focused, and retro-friendly.

The Master Algorithm

JoeStrout — Tue, 07 Apr 2026 17:03:14 +0000

In 2015, a book by AI researcher Pedro Domingos came out called The Master Algorithm: How the Quest for the Ultimate Learning Machine Will Remake Our World. The author explored the "five tribes" of artificial intelligence (AI), and how each one might develop into the "Master Algorithm" of intelligence itself — the algorithm that could learn to do virtually anything humans and other animals can learn to do. The five tribes are:

inductive reasoning
connectionism (aka neural networks)
evolutionary computation
Bayesian networks
analogical modelling

This was ten years ago. It was very much not obvious, at that time, which of these — or what combination of them — or even whether something entirely different — might turn out to be the Master Algorithm.

But it's clear now. I'm calling it.

The Master Algorithm is neural networks.

It turns out, the master algorithm is connectionism. A neural network, when it's big enough, structured appropriately, and trained on enough data, can do it all: language, reasoning, translation, programming, answering questions, following instructions, understanding pictures and videos, generating pictures and videos, solving complex math problems, and on and on.

The goalpost-movers like to pick at each of those and say "yes, but, it doesn't do this thing very well and that thing doesn't really count because of the following hand-wavy reasons." But if you read the book, it's obvious that everything we all take for granted nowadays was far-off science fiction in 2015. AI researchers literally dreamed of machines that could do half of what ChatGPT or Claude does before breakfast, or what Gemma does running locally on my cell phone.

The other four approaches? They still have their uses in specialized cases, and they're still doing more or less what they were doing in 2015. None of them turned out to be able to do pretty much everything, nor did any of them turn out to get a lot smarter and more capable when you simply scale them up. (Indeed, most of them explode when you try to do that.)

This was not obvious.

I've considered myself a "connectionist" since middle school, when I did my first neural networks science fair project. (Fun fact: my junior year of high school, I went to the International Science & Engineering Fair with my novel algorithm for recursive neural networks, and won the U.S. Army's top prize and a 2-week trip to Japan... and I still practice Japanese every day today.)

But I did not expect neural networks, on their own, to be the master algorithm. Hardly anyone expected that. Neural networks were very good at perception (identifying/classifying patterns in raw data), and at prediction (which is really the same thing). But it was not at all clear how a neural network would ever be able to carry on a real conversation, reason through problems, etc. I thought you'd probably need some combination of a neural network and symbolic (e.g. inductive) reasoning.

I mean, of course our own brains are made entirely of neurons. So as a raw proof of concept, yes, it was obvious that neural networks could do it all. But I assumed that evolution had equipped our brains with very specialized circuits for language, logic, & reasoning, and that you would not get these facilities out of a general-purpose neural network running some general-purpose learning algorithm.

But nope. It turns out that you do get exactly that.

The moment this happened.

In What Is Intelligence? (2025), Google AI researcher Blaise Agüera y Arcas writes about the moment that I would consider the pivotal turning point. They were training a neural network to predict the next word after a bunch of previous words, so that they could make a better autocomplete function. This is a natural and obvious application of neural networks' strengths, and because people are terrible (and terribly slow) at typing messages on cell phones, better autocomplete was worth investing in.

But they had trained a very large model. On a very large amount of text. And the model started talking to them. They discovered that they could ask it questions, and it would answer. The could even ask it things that had certainly never been in its training data — like, how to translate a specific made-up sentence from one language to another — and, with a bit of urging, it would do it, and do it correctly.

I can only imagine the complex emotions they must have felt at that moment. They realized what some deniers still haven't understood today: a sufficiently deep language model isn't just parroting its training data; it is understanding and responding with real intelligence.

Now, a raw language model, without additional reinforcement learning to shape its behavior, is rather schizophrenic; it slips in and out of different personalities, carries on both halves of a conversation all by itself, etc. Few people get to interact with a network in this state, because (as Agüera y Arcas explains) it is quite disturbing. But the behavioral training fixes that, improves reasoning skills, and gives us the AI coworkers we use daily today.

Prediction, all the way down

So how is this possible? How does a neural network act as the master algorithm?

It turns out, intelligence is fundamentally just prediction. It's prediction at all levels: cortical columns predict what their next inputs are going to be; our visual system learns to predict what the world is going to look like in the next moment; our language system learns to predict the next word we are going to hear or say. In a literal sense, LLMs like Claude do nothing but predict the next token, based on all the tokens in the session so far.

But prediction is all you need. When Claude generates a string of tokens working through a problem, it is not fundamentally different from the string of thoughts (mostly in the form of words) that you and I would generate working through a similar problem. Reinforcement learning biases the network so that these strings of predictions tend to go in useful directions, ones that were successful during training. In humans (unlike current LLMs), training is an ongoing process, so we are constantly tweaking our own neural networks to make these trains of predictions more successful. But fundamentally, moment to moment, it's still just predicting the next thing, at every level of the network.

We now understand that some problems are what Agüera y Arcas calls AI complete. Solving an AI complete problem requires actually understanding the world that the problem represents; no shallower, surface-features sort of representation can do it. Examples of AI complete problems:

Next word prediction: it's impossible to predict the next word in a string of text with any accuracy unless you understand what those words actually mean.
Language translation: ditto; you can't just look up individual words in a dictionary.
Video next-frame prediction: requires understanding what the objects in the video are, how they behave, what gravity does, etc.
Picture or video captioning: requires understanding both what the objects are, and how they are referred to in language.

A sufficiently big neural network, given sufficient training data, will eventually solve almost any problem you give it. So if you give it an AI complete problem, which can only be solved by understanding the world... it will understand the world.

Is its understanding perfect? Of course not. But then, that's true of humans, too.

So that's it for AI research

Haha, just kidding! LLMs are general intelligence, and already smarter than humans in some ways. But they have glaring limitations: in particular, "training" and "inference" are completely separated processes. The LLMs we use every day do not learn from experience, except insofar as that experience can be crammed into the context window.

The addition of continual learning will allow them to get better at tasks with practice, just like we do. But there are a lot of tricky open questions: how do you avoid forgetting too much old knowledge while acquiring new knowledge? How do you keep the AI's personality stable over time? And how do you even learn this new stuff quickly enough to matter?

Moreover, there really are things that neural networks are terrible at. And ironically, those are exactly the things that most AI research has been doing for the last 80 years: game playing, deep search, complex logical reasoning, optimization, etc. We (and other neural networks) can approximately do those things, with a lot of training and practice, but there are classical (GOFAI or "Good Old-Fashioned AI") algorithms that do them much better and faster. We'll continue to need progress on these, and on ways to integrate them with neural networks to get the best of both worlds.

This is just a random sampling; in fact there are many, many open research directions. We've cracked the code of intelligence; we know now what intelligence is and how to produce it in a machine. But that's only the tip of the iceberg. It is the beginning of wisdom, not the end.

The next 5 or 10 years are going to be very exciting. Hold on tight!

MiniScript Weekly News — Apr 1, 2026

JoeStrout — Thu, 02 Apr 2026 00:36:09 +0000

Development Updates

Work on MiniScript 2 continues to pick up speed, and the team shared that a working REPL is now in place in both C# and C++. The latest dev log also mentions a refactor to better preserve globals across REPL entries, plus a fix for multi-function REPL handling and Ctrl-D to exit.

GitHub: miniscript2

On the raylib-miniscript side, there were a few useful updates landed this week: resourceCounts now reports loaded resources, FileHandle was added, and the text mutation intrinsics were refreshed with new ...Alloc variants. These changes should help with debugging leaks and keeping the bindings in step with newer raylib APIs.

An important change this week: raylib-miniscript now requires scripts to call rl.InitWindow themselves instead of the engine doing it behind the scenes. Joe also added a direct MiniScript translation of the raylib high-DPI demo, which should make window setup clearer for developers who want to support high-res displays like the Apple Retina or MacBook display.
GitHub: raylib-miniscript

Community Projects

Joe shared a fresh tutorial on Dev.to: Create a Maze Game in Mini Micro. It walks through turning the built-in maze demo into a custom game, and it’s a great example of how approachable Mini Micro development can be for new creators.

Also in the Mini Micro ecosystem, Dat_One_Dev highlighted the possibility of listing Mini Micro, Soda, and the upcoming Raylib project on a game-distribution site so community-made games can be more discoverable. That came up in the context of showcasing user projects like SPACE EVADERS by community member DSlower — always exciting to see MiniScript games getting attention.

Discussion Highlights

There was a lively MiniScript 2 design discussion about language minimalism, type hints, and the role of @ in function references. Joe reaffirmed the project’s “mini” philosophy while also noting that assertions can already help catch errors today, and might even inform future optimizations. But he also outlined a proposal for a more extensive error-handling system based on a new "error" data type, with strict rules about how it interacts with other types.

The community also brainstormed about broader tooling and extensibility, including ideas for terminal color customization, configurable prompts, and even an eventual FFI-style integration for things like Ollama or other external libraries. Joe’s response was encouraging: it’s a neat direction for “eventually,” though beyond the language core for now.

Mini Micro & Raylib Chatter

A few Raylib-related debugging threads were especially productive this week. The team tracked down an HDPI issue to window initialization order, and Joe wrapped up the fix by moving the config flag setup earlier and clarifying that scripts should initialize the window themselves.

There was also some good old-fashioned collaborative troubleshooting on the breakout demo and audio init behavior, with fixes landing for Windows build issues and asset handling along the way. It’s great to see community members jumping in with bug reports, PRs, and real-world testing.

Until next week, happy scripting!

Upcoming Game Jams

These upcoming jams look like a great fit for Mini Micro:

Pixel Forge JAM 2026 [PRIZES] (starts 2026-04-18 07:30:00) — A strong fit for retro, pixel-art, or tile-based ideas, with a 7-day format that encourages fast, creative experimentation and accessible gameplay.
Micro Jam 057: Symmetry ($400 Prizes) (starts 2026-04-18 01:00:00) — A strong fit for 2D pixel, tile, or text-driven ideas, with the symmetry theme inviting clever puzzle, action, or visual-design twists and a forgiving jam format that’s easy to jump into.
Games Transformed 2026 - 'Smash The Fash' Game Jam — A politically charged jam inviting all kinds of antifascist games, from activist tactics and mutual aid to surreal puzzles and hopeful visions of solidarity, with room for serious, playful, or experimental takes.
Reagent Game Jam 2026 (starts 2026-04-10 07:00:00) — An accessible beginner-friendly jam with lots of freedom in tools and style, making it a great chance to build a creative 2D game in a low-pressure setting.
GamingleJam (starts 2026-04-10 17:14:37) — A low-pressure, any-engine jam that encourages collaboration and welcomes solo creators too, making it a great excuse to build a stylish 2D game and maybe team up with artists, musicians, or writers along the way.
AvantBeetle's Protest Games Jam (starts 2026-04-04 04:00:00) — An open-ended protest-themed jam that welcomes experimental, symbolic, and small-scale games, making it a great chance to turn a strong message into a creative playable statement.

Create a Maze Game in Mini Micro

JoeStrout — Wed, 01 Apr 2026 18:17:19 +0000

In the classic arcade days, there were a lot of maze games. That's because mazes are fun! They give the player interesting choices at every point, and force you to look and plan globally while also paying attention to local hazards and opportunities.

Clockwise from top left: Pac-Man (1980), Wizard of Wor (1980), Nibbler (1982), Mouse Trap (1981).

You don't see this as much in modern games. A 3D shooter or adventure game might be in a maze, but with a first-person view, you miss out on that global planning because you can only see what's directly in front of you.

All of which is to say, people should make more maze games. And Mini Micro is a great environment for making them. Let's make one right now!

Start with the maze demo

Mini Micro has a handy demo of displaying and editing a maze at /sys/demo/maze. Start by running that. You can run it online here, but better to download Mini Micro if you don't have it already, and then just type run "/sys/demo/maze" and press Enter. The demo looks like this:

You can click and drag with the mouse to edit the maze. It's important to understand that you're adding and deleting wall corners, not walls or rooms. These are the intersections of two (potential or actual) walls between rooms.

An important thing to understand is how what you see relates to the actual TileDisplay creating it. The best way to get that understanding is to press G in the demo, which toggles a visible grid (by shrinking the cells and spacing them out slightly).

These are Wang 2-corner tiles, which are explained in this post, so I won't go into detail here. But they're very neat and easy once you get the hang of them.

Start your program!

Now let's leverage the code in this demo to make our own maze game. If you were running the demo on the web, now you really should download it so that you can save your work.

We're going to use the build a little, test a little approach here, building up the program bit by bit. This is a great habit to have in all your coding; it's much easier and more successful than trying to write out an entire program at once.

So if you're still in the demo, exit out of it by pressing Esc, then type clear and reset to clear the screen and program. Then edit, and type or paste in this code:

clear

if env.importPaths.indexOf("/sys/demo") == null then
    env.importPaths.push "/sys/demo"
end if
import "maze"

maze.generate

This clears the screen, and then checks whether our import paths already include "/sys/demo". That's not normally a directory that import searches, but it's where maze.ms lives, so we need it to check there. Then we import "maze", which loads the code from maze.ms into a map called maze in our program. Finally, we call maze.generate to make and display a random maze, just like the demo.

Save this program (I called mine "mouseMaze", for reasons that will become apparent), and then run it. You should see a maze appear.

Customize the maze

The maze generated so far is a "pure" maze, i.e., one with exactly one path between any two points. That's not actually much fun to play in; we want the player to have choices. You could manually edit your maze layout, save it to disk in some way, and load it into your game; this would be most similar to what the classic games above did. But for now, let's just knock out a random selection of walls.

tiles = maze.tiles
cellSize = tiles.cellSize
extent = tiles.extent
maxCol = (extent[0] / 2) - 1
maxRow = (extent[1] / 2) - 1
tiles.setCellTint range(extent[0]-1), range(extent[1]-1), "#44FF44"

// Delete some extra walls so it's not a "pure" maze
for i in range(20)
    room = maze.rooms[rnd*maze.Room.cols][rnd*maze.Room.rows]
    if rnd < 0.5 then wall = "north" else wall = "east"
    room[wall] = false
end for
maze.setCornersFromRooms
maze.updateTiles

edit your program and add the above code, below what you wrote before. This code begins by copying maze.tiles into a tiles variable, just to make it easier to refer to. Then we also copy cellSize and extent out of that. We also compute the maxRow and maxCol of rooms (rooms are the little spaces between the walls — there are only half as many rooms as walls in any direction). Then we use tiles.setCellTint to color the maze green.

Then, the for loop repeatedly selects a random room, and sets either the north or east wall to false, removing it. The code in maze.ms defines rooms this way, each room only responsible for the walls to its north and east side. How would you be expected to know this? Why, by reading the maze.ms code, of course! (Or by reading this blog post.)

Once the rooms have been edited, we call maze.setCornersFromRooms and maze.updateTiles to update the actual display on screen.

Run the program again, and you should see a green maze with extra missing walls (sometimes even producing a dot, where a corner isn't attached to any walls at all).

Create a MazeSprite class

Now to make this maze into a game, we need some sprites to move around in it. And we want those things to move only in valid ways, i.e. not through walls. We'll use the same Room data structure that the maze demo already defined for creating the maze, to determine where sprites can move.

So, edit your program again, and append this code:

MazeSprite = new Sprite
MazeSprite.col = 0
MazeSprite.row = 0
MazeSprite.goToRoom = function(roomCol, roomRow)
    self.col = roomCol; self.row = roomRow
    self.x = cellSize * (roomCol * 2 + 1)
    self.y = cellSize * (roomRow * 2 + 1)
end function

MazeSprite.canMove = function(dx, dy)
    col = self.col; row = self.row
    if dx and dy then return false
    if not 0 <= round(col + dx) <= maxCol then return false
    if not 0 <= round(row + dy) <= maxRow then return false
    if dx < 0 then return not maze.rooms[self.col-1][self.row].east
    if dx > 0 then return not maze.rooms[self.col][self.row].east
    if dy < 0 then return not maze.rooms[self.col][self.row-1].north
    if dy > 0 then return not maze.rooms[self.col][self.row].north
end function

MazeSprite.move = function(dx, dy)
    if not self.canMove(dx, dy) then return
    col = self.col; row = self.row
    for t in range(0, 1, 0.1)
        self.goToRoom col + dx*t, row + dy*t
        yield
    end for
    self.goToRoom round(self.col), round(self.row)
end function

This creates a Sprite subclass called MazeSprite. A MazeSprite knows what room column and row it's in, and in the goToRoom method, it also converts those to screen coordinates. Then there's the canMove method, which determines whether the sprite can move in a given direction. This includes bounds checks, as well as checking the appropriate wall.

Finally, we have a move method that, if the sprite is able to move in the given direction at all, does so smoothly over 10 frames. (In a full game you might need a fancier approach that does not block the rest of the game while moving -- but for today's game, there is only one sprite moving at a time, so this works fine.)

You can run your program again at this point, just to ensure you haven't made any typos. But if everything is good, it won't look any different from before. We've defined the MazeSprite class, but we're not actually doing anything with it yet.

Add the sprites

It's time to add our characters to the maze! I chose to make my game about a mouse questing for cheese, but feel free to explore the pictures available in /sys/pics and make it a bunny chasing carrots, or whatever you like. (The findFile command is a great way to explore!)

So edit your program again, and add this code:

player = new MazeSprite
player.image = file.loadImage("/sys/pics/animals/mouse.png")
player.scale = 1/3
player.goToRoom 0,0
display(4).sprites.push player

cheese = new MazeSprite
cheese.image = file.loadImage("/sys/pics/food/Cheese.png")
cheese.scale = 1/2
cheese.goToRoom round(rnd*maxCol), round(rnd*maxRow)
display(4).sprites.push cheese

This is pretty straightforward: we create a player sprite in room 0,0, and a cheese sprite in some random room. Both sprites are scaled down in order to fit into the maze. Run your program now, and you should see these new additions to the game. But the program still exits immediately to the blinking cursor.

The main loop

We're almost done! Let's just load a sound to play when the mouse gets the cheese, and then add the main loop:

gotSound = file.loadSound("/sys/sounds/munch.wav")

while not key.pressed("escape")
    yield
    dx = sign(round(key.axis("Horizontal", false)))
    dy = sign(round(key.axis("Vertical", false)))
    if not dx and not dy then continue
    player.move dx, dy
    if player.row == cheese.row and player.col == cheese.col then
        cheese.goToRoom round(rnd*maxCol), round(rnd*maxRow)
        gotSound.play
    end if
end while
key.clear

Our main loop here is pretty simple. We start by getting the horizontal (dx) and vertical (dy) axis inputs. Using key.axis allows the player to use arrow keys, WASD, or even a game pad. We round that and take the sign so that we get clean input values of -1, 0, or 1 for each axis. And if we don't have any input, we just continue at the top of the loop (where we included a yield, as all good main loops do).

When we do have an input, then we call player.move, and then check whether the player is now in the same location as the cheese. When that's the case, we play the munch sound and teleport the cheese to a different room.

Try it! It's such a simple game, and yet it is immediately engaging. You will see how you could build on this in all sorts of ways: make the goal move around, add enemies, add some sort of shooting, provide doors that can open or close or pivot, add sub-goals like visiting every part of the maze, etc.

Comments? Questions?

What was your favorite maze game? What sort of maze game would you like to see in Mini Micro? And what's stopping you from creating that game right now? Share your thoughts in the comments below!