Forem: JoeStrout

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!

Parameter Objects in MiniScript

JoeStrout — Wed, 25 Mar 2026 15:44:23 +0000

Sometimes a function starts out with a reasonable number of parameters, but as the code grows and more features are added, it ends up with more and more — like PixelDisplay.drawImage in Mini Micro, which has 10 parameters.

Arguments in a function call in MiniScript are passed by position, not by name, which means that even if some of those parameters are optional, you have to specify all arguments that come before one you actually care about. And of course you have to remember what order they're in. (So many times I have typed @gfx.saveImage at the Mini Micro prompt just to remind myself of the order of the parameters!)

Why not passing parameters by name is a good thing

Languages that support passing parameters by name encourage developers to make functions with lots of parameters. And then it will turn out that only certain combinations of those parameters make sense, and the function sprouts pages of parameter-checking logic just to ensure that the user is calling it properly, and more pages of documentation or comments to help them do so.

This is not just academic; I had to work with this 25-parameter monster for a while, and it was a nightmare.

I have rarely seen any language feature so quickly lead to bad code as named parameters; it may even take the lead from GOTO in this department.

What can be done when you find yourself needing more than a handful of parameters? Or, what if it's only a handful, but you find yourself frequently passing the same values from one function to another (helper methods for example)? There is a standard solution: the Introduce Parameter Object refactoring.

Introduce Parameter Object

The idea here is simple: take that big batch of parameters you need, and replace them with a single object containing the same information.

As an example, the PixelDisplay.drawImage function looks like this:

FUNCTION(self, image, left=0, bottom=0, width=-1, height=-1, srcLeft
=0, srcBottom=0, srcWidth=-1, srcHeight=-1, tint="#FFFFFF")

Not counting self (which is just whatever object comes before the dot when you call it), that's 10 parameters. You need all 10 if you're going to tint the image, like this:

img = file.loadImage("/sys/pics/Block.png")
gfx.drawImage img, 500, 200, -1, -1, 0, 0, -1, -1, color.aqua

(I encourage you to fire up Mini Micro, either locally or on the web, and follow along for yourself.)

Let's make a parameter-object version of this method. (In your own code, you could actually replace the original method with the refactored one; but since you can't change the Mini Micro API, let's just make a new method.) Use the edit command and enter:

import "mapUtil" // for map.get
drawImage = function(params)
    g = params.get("gfx", gfx)
    g.drawImage params.image,
      params.get("left", 0),
      params.get("bottom", 0),
      params.get("width", -1),
      params.get("height", -1),
      params.get("srcLeft", 0),
      params.get("srcBottom", 0),
      params.get("srcWidth", -1),
      params.get("srcHeight", -1),
      params.get("tint", "#FFFFFF")
end function

Close the editor and run.

Now we have a drawImage method that takes a single parameter. You can call it like this:

params = {}
params.image = img
params.left = 500
params.bottom = 200
params.tint = color.aqua
drawImage params

Notice how this time, we only needed to specify the parameters that differ from the defaults. We could also call it using a map literal, like this:

drawImage {"image":img, "left":600, "bottom":200, "tint": color.pink}

That works too. Either way, the calling code is more clear, and the function interface is simpler.

Output Parameters

There's a related pattern that is helpful when you need to (perhaps optionally) provide some extra detail on the result of a function call, and that is to use an output parameter object.

To make it more concrete, let's suppose you make a method that loads an image... but you want it to do some extra sanity checks, and report details on what it found to callers who care. You could write it like this:

import "mapUtil" // for map.get
loadImage = function(path, outResults)
    r = outResults  // (shorthand)
    if r != null then
        r.path = path
        r.size = 0
        r.err = ""
    end if
    info = file.info(path)
    if info == null then
        if r then r.err = "File not found"
        return null
    end if
    if r then r.size = info.size
    directory = file.parent(path)
    name = file.name(path)
    if name[-4:] != ".png" and name[-4:] != ".jpg" then
        if r then r.err = "Path does not end with .png or .jpg"
        return null
    end if
    if file.children(directory).indexOf(name) == null then
        if r then r.err = "Case mismatch"
        return null
    end if
    return file.loadImage(path)
end function

This loadImage method takes the path to the function to load, but optionally, it also takes a map into which we will place some details: the path, the file size, and an error string.

So callers who don't care about the details can just do:

img = loadImage("/sys/pics/Wumpus.png")

...and they will get back the image or null, but with no way of knowing why. More careful callers could instead do:

result = {}
img = loadImage("/sys/pics/Wampus.png", result)
if not img then print "Couldn't load " + result.path +
  " because: " + result.err

And (because I mistyped the image name) this will print "Couldn't load /sys/pics/Wampus.png because: File not found".

(We might make use of exactly this pattern in some Mini Micro 2 APIs; see this feature request.)

Don't Over Do It!

There are two drawbacks to introducing parameter objects:

They make calling the function more of a hassle for simple cases.

drawImage img is easier than drawImage {"image":img}.

They encourage parameter proliferation, just like named parameters.

Don't create beasts with 20 or 30 parameters, even with this refactoring. Instead consider smaller, more focused methods that do only one thing in one way. Or at the very least, add wrapper methods that make the common use cases easy.

But with those caveats in mind, parameter objects (including output parameter objects) are a powerful tool in your toolbox. Happy coding!

MiniScript Weekly News — March 24, 2026

JoeStrout — Tue, 24 Mar 2026 21:32:26 +0000

Editor's Note: I've developed an AI agent to help me gather and write this weekly newsletter, keeping you informed while still giving me time to work on things like MiniScript 2.0. I hope you enjoy it! -- Joe

Development Updates

Joe has launched a MiniScript News bot to help gather highlights from GitHub, Discord, forums, itch.io, and more, with the goal of making it easier to follow the growing community. That should be a big help as MiniScript activity spreads across so many places.

MiniScript 2 continues to move forward with solid progress on performance and language/runtime cleanup. Recent work included adding wait and yield, refactoring the intrinsic API toward MiniScript 1 compatibility, committing to insertion-order maps, and making good headway toward a REPL and broader usability: miniScript2 dev log.

On the Raylib side, raylib-miniscript picked up several useful upgrades, including run, improved import path handling, exit, more low-level APIs, shader demos, 3D model support, and full API docs. If you’re following the new foundation for Mini Micro 2 / Soda, there’s lots to explore: raylib-miniscript.

Community Projects

Trey Tomes has been sharing a lot of exciting Mini Micro work, including a roguelike/world-generation project, a VS Code extension that can execute MiniScript, and a MiniScript-based Perlin noise library. If you’re building in MiniScript, these are great examples of practical tools and ambitious gameplay systems:

Also from the community, Blanket shared a work-in-progress Mini Micro file manager, with a very sensible warning to back up your files before trying anything risky. It’s always fun to see tools that help make the ecosystem more usable.

A special shout-out to lagoon, who showed up with a MiniScript-written Lisp implementation, Clojette. That’s exactly the kind of delightfully unexpected project that makes this community so fun.

Finally, there were a couple of cool new game jam games in the last week:

Discussion Highlights

A big theme this week was input, layout, and UI design. Joe sketched out a promising layout system based on choosing two positioning constraints and using formulas for the rest, and the discussion around it drew a lot of enthusiasm from others who see how useful it could be for both game UI and desktop-style tools.

There was also a lively thread about MiniScript 2 equality semantics, including the idea of an “approximately equal” operator. The consensus leaned toward keeping that logic in a function rather than baking too much ambiguity into the language, which feels very in the MiniScript spirit.

On the Mini Micro side, there was a helpful reminder that tight loops need yield, and a few useful tips for input handling and file creation. Community members kept helping one another troubleshoot, prototype, and think through the best patterns — a great sign of a healthy, collaborative space.

Learning & Writing

Kartik Patel published two more chapters of the “Zero To Game Dev” series, introducing Mini Micro and the first line of MiniScript in a beginner-friendly way:

It’s great to see more approachable learning material appearing for newcomers. Posts like these make MiniScript feel even more welcoming to beginners.

Sign-off

Lots of steady progress, lots of creative experiments, and plenty of helpful back-and-forth this week — exactly what makes the MiniScript community special. Thanks to everyone building, testing, sharing, and cheering each other on.

Upcoming Game Jams

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

Gone Fishing Game Jam (starts 2026-03-27 12:00:00) — A flexible, theme-light jam centered on fishing that leaves plenty of room for clever interpretations, from cozy pixel-art outings to quirky text adventures or tabletop-style ideas.
Jerbob's SILLY JAM (starts 2026-03-27 13:00:00) — A free-form chaos jam that celebrates weird, silly, low-budget creativity—perfect for making something absurd, experimental, and charmingly janky.
Aristos Interactive Jam #2 (starts 2026-03-27 21:00:00) — A beginner-friendly weekend jam focused on finishing a fun, playable game, with browser play required but no engine restrictions and plenty of freedom to use premade assets or AI support.
Jam Chula I (starts 2026-04-01 10:01:00) — A creative, inclusive art jam centered on the evocative theme of Hell, with complete freedom in format and plenty of room for stylized 2D games, interactive fiction, or other expressive retro-friendly ideas.
A Century of Spells: A Fantasy Jam (starts 2026-03-07 20:00:00) — A thoughtful fantasy jam centered on magic, memory, and the passage of time, with a strong emphasis on emotional storytelling, non-combat spells, and atmospheric worldbuilding.
Mini Jame Gam #53 (starts 2026-04-03 11:00:00) — A beginner-friendly, fully 2D jam with flexible engine rules, a theme-and-special-object twist, and room for quick prototypes makes this a great chance to build something fun, polished, and creative in a short time.

MiniScript Roadmap Update (March 2026)

JoeStrout — Wed, 11 Mar 2026 20:54:08 +0000

At the end of 2025, I posted a MiniScript Road Map for 2026 (and beyond). We're now almost one quarter into 2026. Let's see how it's going!

MiniScript 2.0

The biggest work planned for this year is MiniScript 2, a complete rewrite of the MiniScript language, focused on performance. I'm pleased to report that MiniScript 2 is ahead of schedule.

The goal for the first quarter was "MS2 compiles & runs a subset of MiniScript", while the Q2 (end of June) goal was "MS2 feature complete (whole language implemented)". We've pretty much achieved the Q2 goal already! MS2 has an extensive test suite that exercise every part of the language, and longer test programs and benchmarks that put it to work in more realistic ways. We don't yet have import, but technically that's not part of the language; that's added by host apps (like Mini Micro. We have a short list of new language features and minor changes, all of which are tested and working except for one (doc strings on functions — we're still thinking about whether and how we want that to work).

But what about performance, you ask?

Yesterday I ran three benchmarks -- two using iteration and one using recursion (a particularly challenging benchmark for MiniScript 1.x). I ran them in MiniScript 1 (C++ version), MiniScript 2 (both C# and C++ version), and for comparison's sake, also ran equivalent code in Python and Lua. Here's the result, with the Y axis representing speed relative to Python.

There are a couple important things to note here. First, the C++ version of MS2 is significantly faster (like 15X faster) than the C# version. That's how it should be, since C# is managed code run by a bytecode interpreter, but in MS1, those times were about the same. (I didn't include a MS1 C# benchmark but trust me, it's always been roughly the same as the C++ version.)

But this doesn't mean the C# version is slow. Compare the blue bars (MS2 C#) to the teeny gray bars (MS1 C++). Even the C# version of MiniScript 2 is much faster than the C++ version of MS1, by a factor of 10.

Now compare the green bar (the C++ version of MS2) to Python (orange bar). We are much faster on 2 of 3 tests, and about the same on the third. Recursion still costs a little more than we'd like, but it now merely drags us down to "about the same speed as Python," which is pretty fast.

Of course there's Lua over there (red bars), feeling pretty good about itself. Yes, Lua is fast, especially on recursion tests. On the iterative benchmarks, we're faster on one, a bit slower on the other. But we're not done yet!

I also ran some tests where, instead of starting with MiniScript source code, I used hand-written assembly code. This tests how fast the VM can go, separate from how good the compiler is at emitting optimized bytecode. Here are the results for that:

Here the bright bars are hand-written assembly, and the darker bars are MiniScript source. You can see that the hand-written assembly runs faster, by a factor of 2-3. This reflects the opportunity for improvement we could get just by improving the compiler, entirely separate from the VM. We've barely begun to do compiler optimizations yet. So I think we'll be able to capture much of that potential improvement.

To summarize: MiniScript 2 is already fast (comparable or better than Python; nearly as fast or faster than Lua). And I expect it to get faster before 2.0 ships.

Raylib-MiniScript

Another goal for the year was a full set of bindings for MiniScript, and not just for the web, but for desktop (and maybe other) platforms too. Here I am pleased to report that we are even more ahead of schedule. This was a goal for the 4th quarter (end of the year), but, well, some of us got excited and it's nearly done!

With the aid of helpful community members (especially Dcrawl), essentially the entire Raylib library has now been wrapped -- all 736 functions. These include support for shaders and even 3D graphics:

Like MSRLWeb, on which it is based, the new raylib-miniscript library performs shockingly well. This despite it being currently built on MiniScript 1. As soon as possible, we'll shift it over to MiniScript 2, for a substantial boost in performance.

The raylib-miniscript library is currently available only in source form, and has only seen substantial testing on MacOS and Linux. Nonetheless, several users are not waiting, but are already writing or porting projects to use it.

Soda

I'm among those porting projects to raylib-miniscript; in my case, it's Inversion Institute, a logic/puzzle game that's been on the back burner since 2023. To port this Mini Micro game to Raylib, I am writing classes (in MiniScript) that mimic the Mini Micro APIs... in other words, I am (re)writing Soda on the way to updating my game.

You can find the files for that currently in the Inversion Institute repo, for example PixelDisplay.ms and SpriteDisplay.ms. So, while I originally had no actual intention of starting on the Soda rewrite until MiniScript 2 is done, in fact I'm already writing and testing the code that will end up becoming Soda.

So what's next?

The broad 50,000-foot ambitions outlined a couple months ago have largely been reduced to a laundry list of smaller, more specific remaining to-do items:

MiniScript 2:

Further optimize the MiniScript 2 compiler
Write moar tests and benchmarks to ensure it works properly
Modify or wrap the internal APIs so that people embedding MiniScript in their C#/C++ apps can easily update to MS2

Raylib-MiniScript:

update to a MiniScript 2 backend
set up build scripts/procedures for Mac/Win/Linux/Web
publish prebuilt binaries, so users don't have to build it themselves
improve documentation/examples
retire MSRLWeb (now superceded by this project)

Soda:

retire existing SDL code, replace with raylib-miniscript foundation
get API coverage at or beyond Soda's current status (enabling trivial porting of current Soda apps)
continue to API parity (or beyond) with Mini Micro
publish prebuilt binaries

Mini Micro 2:

continue the rewrite once MiniScript 2 is done (and Raylib-MiniScript is using it)
release for current platforms
release for new platforms (Raspberry Pi, phones, tablets)

Summoner Game Platform:
This one is still at the 50,000-foot level. It will be built on the technologies above, so... it has to wait. But while previously I didn't expect to even start on this until 2027, now I think we might see it sooner than that.

So that's where we are. I'm really quite excited about how far we've come so far in 2026, and what is now on the near horizon. What about you? Which of this stuff are you most looking forward to? Please leave your comments below!

MiniScript Road Map for 2026

JoeStrout — Tue, 30 Dec 2025 15:02:13 +0000

With 2025 coming to a close, it's time to look ahead to 2026! MiniScript is now eight years old. Many programming languages really come into their own when they're about 10 years old. It looks like this will apply to MiniScript too — just wait till you see all the cool developments coming in the next two years!

MiniScript 2.0

The big push for next year will be version 2.0 of MiniScript itself. This is a complete rewrite of the compiler, bytecode, and virtual machine (VM) underlying the language. While there will be a handful of minor new features, the main focus of this rewrite is performance. We think we can make it run dozens of times faster, maybe hundreds of times faster on certain benchmarks.

In addition, the C++ version of MiniScript will get true garbage collection, just like the C# version, and improved error messages too. The C++ code is going to be the basis of almost everything else in this roadmap, so it will get a lot of love. Both versions will rely heavily on suites of unit tests and integration tests, to ensure the language is rock solid.

After a bunch of prototype work, development of MiniScript 2 is now underway. Follow its progress on GitHub.

MiniScript Raylib Bindings

I've recently been exploring Raylib, a low-level abstraction layer over OpenGL, audio, files, and game input devices. And I am really impressed. Raylib is simple, lean, and easy to use.

So, with help from Discord users dcrawl, minerobber, and Redspark, I quickly put together MSRLWeb, an environment that lets you use Raylib in MiniScript to make 2D web browser (HTML) games. You don't even need a compiler — you just write MiniScript code, drop it into a folder with the MSRLWeb binary and any sound/image assets you need, and point a web server at it. See the online demo, as well as this game that I built in it for a 3-hour game jam.

Raylib has a huge community, and bindings enabling its use from a wide variety of languages. MSRLWeb provides MiniScript bindings, and is ideal for making a web games. But next year, we will polish up a general MiniScript Raylib package, that lets you make desktop or even mobile games this way too. And we'll start promoting MiniScript as an attractive option to Raylib users. It's a natural fit: both MiniScript (the language) and Raylib (the API) are clean, minimal, and easy to learn, making them an ideal combo for people who want their dev tools to get out of the way so they can express their creativity.

Soda Rewrite

For several years now, we've made (very slow) progress on Soda, a game engine built on C++ and SDL. Soda lets you use the MiniScript language with an API very similar to Mini Micro, but unlike Mini Micro, it doesn't simulate a retro computer — games you create with it run windowed or full-screen, and have raw access to the host computer, just like games made in Unity, Unreal, Godot, etc.

But progress on Soda has been slow in large part because SDL, the platform abstraction layer I chose for it, is just painful to work with. Its API is complex; its build system is quirky (especially if you want the same code to work on all platforms); its documentation is poor to non-existent; and it requires extensions to do things that ought to be built in. Getting anything done with it is a chore, and so lots of things never got done.

Once MiniScript 2 is done, we will rewrite Soda using Raylib. Thanks to our experience writing MSRLWeb, I'm confident that this is going to be a much faster, smoother process. The result will be what we always wanted for Soda: a complete implementation of the Mini Micro API, and then some, in an unfettered environment usable for game projects of any size.

Mini Micro 2.0

Also after MiniScript 2, and again leveraging Raylib, we are going to develop version 2.0 of Mini Micro. This will finally remove our dependency on Unity, and enable us to run on platforms we could not practically run on before, like the Raspberry Pi. We'll aim to finally release Mini Micro for Android and iOS tablets, too.

Mini Micro is likely to get a handful of new features, such as:

box-drawing characters and alternate text sizes in the text display
a sort of system debugger/BIOS screen to aid with development
better support for non-QWERTY keyboards
fast vector/matrix math
better support for widescreen (16:10) displays

But in fact the whole system is likely to feel much faster, thanks to MiniScript 2's inherent performance boost (and the fact that Mini Micro will itself be written in C++ rather than C#). That, in addition to running on ARM hardware, is the real gain for Mini Micro 2. Your existing projects should Just Work, only more efficient and on more platforms. Existing resources (like Introduction to Computer Programming) will continue to apply.

An initial, very early prototype of Mini Micro 2 is already on GitHub. Give it a star to let me know you care!

Mini Micro Hardware?!

Mini Micro is a neo-retro virtual home computer. But what if it could be an actual home computer?

Many users have expressed a wish for just such a machine, something that boots quickly and directly into Mini Micro, so they can hack around and develop their games and demos with no distractions.

With Mini Micro 2, we think this will be possible. It won't actually be dedicated hardware; it will probably be something like the Raspberry Pi 500, which has the computer built into the keyboard itself, much like the Commodore 64 (though much more sleek and modern). Or for a laptop, something like this Acer 15" with a 1920x1200 display. In either case, we would develop a custom Linux distribution that strips away all the stuff we don't need, and launches directly into Mini Micro in full-screen mode with crisp, pixel-perfect graphics and stereo sound.

We'll probably have a couple different hardware options that we test and optimize for, though if you're reasonably tech savvy, you could probably get our custom Linux distro to work on other hardware too. In any case, it will look and feel very much like a dedicated Mini Micro computer.

Summoner Game Platform

Finally, we've begun to dream of building a whole game platform around MiniScript, to make it easier and safer for both developers and players. We're calling this the Summoner Game Platform.

Nobody likes to think about it, but you actually take a pretty big risk every time you download a game to your computer. How do you know it's not malware? In addition, there is the hassle of downloading, unzipping or otherwise unpacking, installing it if installation is required, and running it... and then if it's not your cup of tea, tracking down everywhere it installed stuff to remove it.

Summoner Game Platform will address both issues. A Summoner game will have a unique ID/URL, which takes you to a web page about it; but paste that same ID/URL into the Summoner app (or click a "summoner://" deep link), and it will seamlessly download or update the game and launch it. The app will also let you easily see what games you have downloaded, and uninstall them (or if you choose, uninstall the game but keep the game data, in case you change your mind). And as for safety, Summoner games will be sandboxed: able to access only a restricted and safe part of your file system, unable to log keystrokes when the game is not frontmost, etc.

Summoner games will be written in MiniScript, using either the Mini Micro/Soda API or the lower-level Raylib bindings. Further down the road, we might even build support for mods (also written in MiniScript!) right into the Summoner client, making it easy for both mod developers and users. It'll also support a "tip jar" for each game (and mod?) so you can show your appreciation to your favorite devs. All this will make Summoner a great platform for everything from quick game-jam games, to large professional-quality projects.

All this when?

"Predictions are difficult, especially about the future."

All that goodness above is a lot of work, though once MiniScript 2.0 (MS2) is done, the rest of it has a lot of overlap — it's mostly Raylib, C++, and MiniScript combined in various ways. My main goal is to finish MS2 in time for the holidays next year. The other projects will follow rapidly after that. Something like this:

Date	Milestone
2026 Q1	MS2 compiles & runs a subset of MiniScript
2026 Q2	MS2 feature complete (whole language implemented)
2026 Q3	MS2 testing, refinement, & polish
2026 Q4	MS2 released 🥳
2026 Q4	Full RayLib bindings for all platforms 👾
2027 Q1	Soda 1.0 (full API) 🥤
2027 Q2	Mini Micro 2.0
2027 Q3	Mini Micro hardware/distro 🖥️
2027 Q4	Summoner Game Platform initial release 🎮

Here are some things you can do to keep apprised of our progress, or even help move it along:

Follow me here on dev.to for future updates.
Follow MiniScript on Bluesky.
Star and Watch the various GitHub projects linked above, especially MiniScript 2.
Join us on Discord.
Participate on the forums (these have been rather dead lately as everyone has moved to Discord, but we'd love to see more activity there).
Sponsor me on GitHub.

So what do you think of these plans? Share your thoughts in the comments below!

Read live data from Google Sheets in Mini Micro

JoeStrout — Wed, 17 Dec 2025 02:11:14 +0000

Recently I've started working with a small team on a 5-month game jam. We're making a 2D rocket-building game for Mini Micro. This involves some data tables defining the tech tree, and the rocket parts unlocked by each tech node. To make it easy for everyone on the team to view and update that data, we're keeping it (for now) online in Google Sheets — and our Mini Micro code can read that data directly. That means that as soon as you update the data in the sheet, you can just re-run the game and it immediately uses the new data.

This is an amazingly useful trick. I'll show you how you can do it, too!

1. Publish the sheet as TSV

The first step is to open the Google Sheets document you want to access, and from the File menu (within the web page), choose Share ▶︎ Publish to web.

This will pop up a dialog that lets you set various options; the most important one is the format pop-up, which you should change from "Web page" to "Tab-separated values (.tsv)".

Check over the other options too in case there's anything you want to change. Then click the Publish button.

Once you publish a spreadsheet, it's published forever and updated immediately whenever the data changes (you never need to re-publish it). That's why in my screen shot above, the dialog points out that this document is already published — I did that yesterday.

Once you publish, copy the URL that it shows you. (You can always go back and use the Share ▶︎ Publish to web command again to see that URL again if you need it.)

2. Read and parse the TSV in Mini Micro

Because we published in Tab-Separated Value (or "TSV") format, we'll get the data as a big string, with rows separated by line breaks (or char(10) in MiniScript), and columns separated by tabs (char(9)). It wouldn't be hard to write some code to split the string into a list of lines, and then split each line into a list of fields... but why bother? Mini Micro has a built-in TSV module that does all that for you!

Once you import "tsv" and get a URL to a published TSV sheet, pulling that data down from the web and parsing it (into a set of maps — assuming the first row is headers and other rows are data) is as simple as:

data = tsv.parse(http.get(url))

It's so easy, you can do it right on the command line!

If your spreadsheet has multiple sheets, the base URL will get you the default one (always the leftmost sheet, I believe). However you can access any sheet you want by going to it in Google Sheets, and noticing the "gid=" part of the URL.

See that "gid=1681045610" part at the end of the URL? That number uniquely identifies which sheet you're looking at. You can append this string (including "&gid=") to your base URL, to get a complete URL that will fetch that specific sheet.

My game data currently has two sheets: one for parts, and one for the tech tree. So my Mini Micro code actually looks like this:

import "tsv"

// Use the URL from the "Publish to Web" feature:
baseURL = "https://docs.google.com/spreadsheets/d/e/2PACX-1vRA2AQx4X9PZyyoU5mMV18MdB-OI50dx-AdShkBqMKqSaa8dFhb3USE5vtUF1JlPBjkTZFouuyF3Quj/pub?output=tsv"
partsListURL = baseURL + "&gid=22599298"
techTreeURL = baseURL + "&gid=1681045610"

// Fetch the data
partsData = tsv.parse(http.get(partsListURL))
print "Read " + partsData.len + " parts, such as: "
pprint partsData[0]

techData = tsv.parse(http.get(techTreeURL))
print "Read " + techData.len + " tech nodes, such as: "
pprint techData[0]

When I run that, I get this:

...and yes, I just gave you the real URL to my real game data. You could run this in your own copy of Mini Micro and see all the parts and tech nodes.

Go on, do it. I dare you.

3. ...There's no Step 3

And that's it! It's such a simple technique, but such a phenomenally useful thing to do. It means that the whole team can iterate quickly on the data, without having to change any files. You could even have multiple people editing it at once, all in real time, without worrying about git conflicts or other pain. It's just... frictionless.

When it comes time to actually publish your game, you'll probably want to download that data as a file (for each sheet), and bundle it with your game. Then you'll just replace http.get with file.load; the rest of your program stays the same. This will reduce your load time and ensure your game still works even without the internet (assuming it doesn't need internet access for some other reason).

But during development, this is about the most powerful use of http.get I can imagine. Try it! You won't be disappointed.

Introduction to Computer Programming: Online Edition!

JoeStrout — Mon, 22 Sep 2025 14:19:06 +0000

A few years ago, I wrote an introductory book about computer programming called Introduction to Computer Programming. It's a relatively short book (54 pages), with a large, colorful page format and lavishly illustrated by talented artist Allie Daigle.

This was inspired by some great BASIC programming books I had as a kid, like these. They made programming fun and enjoyable. I never knew that "coding is hard" feeling so many people get nowadays, because in those days, it wasn't; with fun books like these in hand, it was something that kids could easily do.

In most environments today, programming really is harder than it was back then. But with MiniScript and Mini Micro, it's even easier now than it was then, and just as much fun. And this book provides that same fun, engaging jump-start for Mini Micro that those classic books of yore provided for BASIC home computers of their day.

But what if you don't live in a country where this book is sold? Or what if the cost is problematic? Or what if, indeed, English is not the most comfortable language for you or your kids to read?

Announcing the (Free!) Online Edition

I'm delighted to officially announce the free online edition of this book! It has all the same content as the print and ebook versions, but it's entirely on the web, free for all. Read it here:

https://introtocomputerprogramming.online

The layout is responsive to your browser; on a small screen like a phone it will switch to a single-column layout, while on a tablet or desktop, you'll get a two-column layout similar to the original book.

And, it's being translated into other languages! English and German are available now, with more on the way. Just click the little menu button in the top-left corner, and pick your language.

Book Features

The book is perfect for anyone who is curious about computers and programming. It includes:

A brief overview of how computers work
Step-by-step guide to getting started
Colorful robot characters illustrating key points
19 fun programming puzzles to check your understanding
Seven complete mini-games you can type in and play

If you've never written a line of code in your life, this will get you started quickly. And if you are a grizzled veteran with decades of experience, you'll enjoy how this book brings back the feels of your youth!

Of course the original book is still available on Amazon if you want it! But now you have no reason to wait. Head on over to IntroToComputerProgramming.online and get started!

UV Mapping in Mini Micro

JoeStrout — Tue, 05 Aug 2025 22:40:01 +0000

Mini Micro version 1.2.5 came out this week, a fairly minor update that fixed a couple of obscure bugs, but also introduced one big feature: the ability to change the texture coordinates of a sprite. This feature is sometimes known as "UV mapping."

What's UV Mapping?

Just as positions on a screen are usually described as X (horizontal) and Y (vertical), positions on a texture (any image used to define the colors in a sprite or tile map) are described as U (horizontal) and V (vertical).

A sprite in Mini Micro has four corners, and each corner of the sprite corresponds to some position in this image. In the standard (default) UV mapping, each corner of the sprite simply maps to the corresponding corner of the texture.

Sprite corners in Mini Micro are always specified in counter-clockwise order, starting with the bottom-left. So if the sprite above were called spr and you checked spr.uvs (one of the new methods introduced in 1.2.5), you would get [[0, 0], [1, 0], [1, 1], [0, 1]]. That's because the bottom-left corner of the sprite uses texture (UV) coordinate [0,0], the bottom-right one has UV coordinate [1,0], and so on.

But now you can use the setUVs method to change those default coordinates to anything you like! Suppose we change the first two UV coordinates to [0, 0.5] and [1, 0.5] — moving them up from the bottom of the texture to the middle. The resulting sprite would like the this (on the left):

The sprite is just as big as it was before — we haven't changed its size or position on screen. But we've changed what part of the texture it's using. So now we see only the top half of the texture, stretched to fill the sprite.

You don't have to keep your UV values in the 0-1 range, either. If you go outside this range, with numbers less than 0 or greater than 1, the texture simply repeats. It can repeat as many times as you like. Here's an example with UVs set to [[0, 0.5], [2, 0.5], [2, 1], [0, 1]]:

OK, but why?

Why would you do this? It's true that this is a "power user" feature that many devs won't need, especially in the beginning. That's why Mini Micro never had it before now! But there are a few cases where it is really handy.

Suppose you want a sprite to grow up out of the ground. Before now, you could only do this by using Image.getImage to extract a bunch of partial images, which is inefficient, or by somehow layering the sprite behind the ground, which is not always possible. With setUVs, it's both easier and more efficient. Code like this can do the job:

clear
spr = new Sprite
spr.image = file.loadImage("/sys/pics/Wumpus.png")
display(4).sprites.push spr

bottom = 200; height = 128
left = 480-64; right = 480+64

for v in range(0, 1, 0.01)
    spr.setUVs [[0,1-v], [1,1-v], [1,1], [0,1]]
    top = bottom + v * height
    spr.setCorners [[left, bottom], [right, bottom],
      [right, top], [left, top]]
    yield
end for

Or, suppose you want to take a simple tiling texture (like any of those in /sys/pics/textures), and make a screen-wide bar out of it, repeating the texture many times. Again, methods to do this before were either inefficient or a pain in the next to write. Now it's easy:

clear
spr = new Sprite
spr.image = file.loadImage("/sys/pics/textures/ToonWoodB.png")
display(4).sprites.push spr
yield // causes sprite to get fully set up

bottom = 200; top = bottom + 64
left = 0; right = 960
repeats = 960 / 64
spr.setCorners [[left, bottom], [right, bottom],
  [right, top], [left, top]]
spr.setUVs [[0,0], [repeats,0], [repeats,1], [0,1]]

This works at any scale. Take a screen-wide background layer, and make it repeat as many times as needed for your level. It's still a simple quad sprite to Mini Micro, and so extremely efficient.

UV mapping can also be an efficient way to make use of sprite sheets — large textures that contain smaller images meant for individual sprites (or animation frames). Again, you could use these before by calling getImage to break them up. But just pointing the UV coordinates at the right place may be both easier and more efficient, especially if you're working with tools (spritesheet editors) already set up to give you UV coordinates.

A Long Time Ago, On A Server Far, Far Away...

Let's close with something a bit cooler. Suppose we use setCorners on our sprite to stretch it out on bottom, and make it narrow at the top, like the floor of a long hallway. Then we make a texture by drawing a few paragraphs of text into an offscreen PixelDisplay, with plenty of blank space above the actual text. And finally, we use setUVs in a loop to scroll the texture up the sprite.

(If you don't see an image below, give it a moment to load.)

The result on an actual Mini Micro looks a lot smoother than the above heavily compressed GIF. So try it yourself! Here's the code:

Twist open to see ANewHope.ms

import "styledText"
import "bmfFonts"
import "mathUtil"; lerp2d = @mathUtil.lerp2d
min = @mathUtil.min; max = @mathUtil.max

title = "A NEW HOPE"
crawl = [
"It is a period of coding chaos.",
"Rebel programmers, striking from",
"hidden basements, have won their",
"first victory against the evil",
"Punctuation Empire.", "",
"Evading the dreaded STATUS QUO, a",
"group of freedom fighters led by",
"Joe Codewalker has established a new",
"secret language on the remote",
"internet site of MiniScript.org.", "",
"Pursued by agents of the Established",
"Order, the brave rebels race to",
"restore clarity to the code,",
"overcome the dark forces of verbose",
"syntax, and bring joy to the",
"programmers of the galaxy..."]

bmfFonts.Font.printJustified = function(s, x, y, width=500)
    words = s.split
    w = 0
    for word in words; w += font.width(word); end for
    ew = width - w // ("extra width")
    ewPerWord = floor(ew/(words.len-1))
    for i in words.indexes
        font.print words[i], x, y
        if i == words.len-2 then ewPerWord = ew
        x += font.width(words[i]) + ewPerWord
        ew -= ewPerWord
    end for
end function

clear
colors = ["#FFFFFF", "#AAAAFF", "#FFFFAA", "#FFCCCC"]
gfx.clear
for i in range(1000)
    gfx.setPixel rnd*960, rnd*640, colors[rnd * colors.len]
end for

font = bmfFonts.Font.load("/sys/fonts/minimicro-pro-20.bmf")
gfx = new PixelDisplay
gfx.clear color.clear, 480, 4096

y = 480
font.printCentered "A NEW HOPE", 476/2, y
y -= 48

for i in crawl.indexes
    if i+1 == crawl.len or crawl[i+1] == "" then
        font.print crawl[i], 0, y
    else
        font.printJustified crawl[i], 0, y, 476
    end if
    y -= 24
end for
texture = gfx.getImage(0, 0, gfx.width, gfx.height)
gfx = display(5)

spr = new Sprite
spr.image = texture
display(4).sprites.push spr
yield

spr.setCorners [[480-400, 0], [480+400, 0], [480+20, 600], [480-20, 600]]

scrollTo = function(yOffset)
    v = yOffset / texture.height
    dv = 1 - 480 / texture.height

    spr.setUVs [[0, v], [1, v], [1, v+dv], [0, v+dv]]
end function


while true
    scrollTo 500 - time * 20
    yield
end while

Conclusion

Now you know what UV mapping is, and how to use it in Mini Micro. Hopefully the examples above have given you some inspiration. How might you use this in your own games? Share your thoughts in the comments below!