DEV Community: Sebastian Nozzi

Bad and good onboarding

Sebastian Nozzi — Fri, 26 Dec 2025 15:00:28 +0000

"The alternative to good design is always bad design. There is no such thing as no design."

Adam Judge, author of design books

The same way bad design is the alternative to good design, the alternative to good onboarding is bad onboarding.

Bad onboarding processes happen not as a result of poor planning, but often because the process is neglected altogether.

The problem is, again, a matter of subjective perspective. The existing project members are already onboarded, and especially the most senior ones have seen the project emerge from the beginning. They know all the details and intricacies inside and out. Additionally they have been immersed for a long time in everyday details and problems. Inevitably, they lose the perspective of the newcomer, of the one that stands before the system for the first time, and tries to figure out how everything fits together.

It is not due to bad intentions, it is because they now are in a different position. Drastically different position from a newcomer.

Bad Onboarding

If "onboarding" as such is not considered as a necessary process, then it happens by accident. Newcomers are given some minimal details to get started and are asked to figure the rest out. Learning-by-doing. Or "learning-on-the-job". "Do tell if you get stuck" and "if something is missing from the (outdated and/or poorly written) documentation feel free to improve on it".

Potential problems I see with these requests:

Newcomers don't know what they don't know. Often they do not know if something is not working because something is not working, or they did something wrong. Additionally, if a clear plan is missing, they don't know if they now know "enough".
Newcomers often want to cause a good impression and prefer to solve their challenges on their own before asking for help (because the seniors are so important and seem to have better things to do).
Newcomers might lack the insight and/or expertise to complete the documentation in a meaningful way.

The result is an "onboarding" process that is erratic, accidental, full of traps and frustrations, and take longer than need to be.

What would a good onboarding process look like?

Good Onboarding

A good onboarding process, in my view, consists of a clear roadmap and is a mixture of good documentation and automation. My motto here goes: automation where you can, documentation where you must.

First, the roadmap: it consists of a clear, finite, non open-ended, easy to understand, non-overwhelming list of things to do.

The "things to achieve" consist of things to read or "do".

The things to "do" can either be done automatically (preferred) or manually. If they are to be done manually, see point "reading".

The things to "read" either give you insight about key aspects of the project (setup, architecture, codebase, etc.) or how to achieve things to "do" which could not be automated.

But how to achieve "good onboarding" if everyone is so busy?

Achieving Good Onboarding

First, it needs to be recognized as something necessary. Something that, if done right, will save the company real money (by having the newcomer produce results earlier instead of still struggling longer than necessary).

Second, in my view it is a process that need to be "owned" by somebody in the team. It cannot be left to chance or the goodwill of the "group".

Natural candidate for this is of course the project manager, but it can be delegated to a senior developer or technical lead.

At each important feature development or architectural change (latest in a sprint-review) it needs to be discussed if there was an onboarding-relevant change. Then the onboarding documents and processes need to be revisited accordingly.

Final words

If done iteratively, if owned, and if kept in check, this approach should minimize (ideally eliminate, but "minimize" is a good-enough outcome) onboarding friction.

Newcomers to the project would feel empowered, welcomed and cared-for, and the momentum gained during the onboarding process would carry to the first feature developments.

Dreams of a Mini Micro machine

Sebastian Nozzi — Sat, 25 Oct 2025 10:11:58 +0000

In my previous post I explained the reasons why I like Mini Micro so much, being (for me) the right combination between simplicity and power.

But something still does not feel right when I code in Mini Micro. And it is not related to Mini Micro itself but rather to "everything else". And that while coding in Mini Micro can be an immersive experience, especially when on "full-screen", my head still knows the truth: everything else still exists. The distraction-filled complex apps and operating systems, with notifications, YouTube, tons of buttons, windows and what-not, is an Alt-Tab away. Sometimes it is very convenient (e.g. looking for information while coding, downloading some image I need for a project) but other times knowing that these things are still there, very near, kills part of the experience.

It is the same feeling I get when wanting to be in nature, walking from the streets into the near-by woods and pretending to be lost in nature, only to hear a loud helicopter passing by, or still hear the roar of the cars in a near-distant highway, or still see part of the city if there happens to be an opening between the trees. Not the same.

You want to be "free", to get "away", but the escape is not real.

That got me thinking: wouldn't it be great to have a machine where something Mini Micro (or something similar) would run exclusively? With no distraction, no other apps, windows, etc.

In my ideal world, Mini Micro would run on something like this ...

After some consideration I came to the conclusion that the most practical way to do this would be:

Have have a Linux installation (Mini Micro runs also on Linux)
Have a dedicated user. Log-in automatically.
Start Mini Micro in full-screen as an "X" application.
No desktop-environment. No other apps.
Nothing Alt-Tab could lead you to.

Recently I tried some of the steps necessary for this on an already existing Linux installation. I tried the "start Mini Micro full-screen" part.

For that I created another user, logged in to the console, and tried to start Mini Micro directly with "startx". Something like:

startx MiniMicro.x64

This would start Mini Micro directly as an "X" app, without even a window-manager. But it would not work properly: I was not be able to type anything, and there was no mouse cursor!

To this day I don't know why, but it seems that Mini Micro, which is based on Unity, is not so "X" friendly out of the box. Firefox worked "fine", but not so Mini Micro.

While trying to find a solution to this I kept reading again and again that this kind of thing should be done through a window-manager, not directly.

I was not entirely happy, I did not want to be able to Alt-Tab to anywhere! Not even a window-manager.

Still, I decided to try. At least to see if it would work.

I worked fine with openbox, but I was still able to alt-tab back to it. But at least I knew that I needed a window-manager to make keyboard and mouse-support work.

Fortunately for me I came across a very minimalistic window-manager perfectly suited for my needs:

https://github.com/astier/xswm

From the description:

xswm is a minimal stacking and non-reparenting window-manager for X with only one task. Open every window maximized. Zero configuration required. Due to its limited scope it is very minimal and performant (~550 SLOC). No built-in:

Hotkeys
Notifications
Statusbar
Window-Decorations
Window-Switcher
etc.

It was like a godsend.

It requires you to compile it yourself, but it is extremely simple. Just "make" and that's it (it requires "sudo make" for it to install to a system-wide location; the "libX11" headers and of course a C-compiler have to be installed).

This simple window-manager would be started with

startx xswm

Upon starting it looks for an "autostart.sh" script in the location "$XDG_CONFIG_HOME/autostart.sh". Problem for me was that the "XDG_CONFIG_HOME" environment variable was not set.

I created a launch script to set the variable and perform the "startx xswm" command.

Now it worked! Keyboard, mouse, and nowhere to run to. No alt-tab, no windows menu, not even alt-ctrl-backspace working (which usually is used to kill your X session). I was happy.

But a couple of things still bothered me:

startx was writing a lot of noise to the console
In the X session, before Mini Micro was loaded (which took a couple of seconds) for some reason a "xterm" window would open. There the Mini Micro (or rather Unity) output / noise would be visible, and only then Mini Micro would take over the uglyness.

So I redirected all output both from "startx" and the "autostart.sh" scripts to oblivion ("/dev/null"). Still, the maximized and undecorated, but sill present xterm window would open and be visible for some seconds.

It seemed I had to live with it. But as the saying goes: when life gives you lemons, make lemonade. So, I adapted my autostart-script to write "Loading Mini Micro ...".

Now the xterm window, and the delay, served a noble purpose.

Future work

In the future I would like to have a dedicated Linux installation which would boot directly to Mini Micro (my experiment was tried in a parallel virtual console, the whole desktop-environment still living on tty7). I will try this first on an emulator before committing to real hardware.

Getting rid / hiding the initial xterm window would also be great, if possible.

If everything goes well I would like this setup to be reproducible for others. I would like to publish these steps. Not sure how yet. Vagrant? Image? Linux-distro? Instructions?

Final words

Anyway, I am now one step further pretending to have a machine where Mini Micro is THE operating system. My creativity-driven inner-child and simplicity-yearning adult are both happy.

Cheers!

Why Mini Micro

Sebastian Nozzi — Sat, 25 Oct 2025 09:29:02 +0000

As many people today I miss the simplicity of earlier times.

True, many things are easier today, more accessible and more powerful. On the other hand, in some areas the price to pay is complexity. Or one could say: too many choices.

The computing experience is no exception.

In contrast to today's computers, computers in the 80's were refreshingly simple. You turned it on, and you were in the middle of a BASIC prompt, in which you could type in some program. Graphics were simpler. Games were simpler. Everything was simpler, but no less intriguing and "magical".

(image from https://www.blendernation.com/2020/12/11/behind-the-scenes-commodore-64-nostalgia/)

The experience seemed more approachable and direct. The computer felt really "personal". It really felt like a "dialogue", an interaction, between two parts. Transparent. Without distractions.

We should not fool ourselves however. While at that time it felt "magical" to print some strings (even colored ones) on the screen or, if I was lucky, be able to plot some lines or circles on the screen, the BASIC interpreters of that era were not particularly "powerful". There was a limit, both in terms of performance and capabilities, of what you could do in BASIC.

Since I was too young and too unaware, I never got into assembly language in the 8-bit computers I had access to (Commodore 16, 64 and an MSX machine). I did not attempt making any serious program for a while until much later in Quick Basic. I remember coding a UFO-shooting game (you would shoot an invading flying saucer which would drop bombs on you) and a painting program. Fond memories.

Time went by and I tried learning some "serious" languages, like C and C++. Later came HTML, PHP and Java. And later other languages like Ruby, Scala and Python. From DOS I moved (as most of us) to advanced versions of Windows (later to Mac OS and Linux). The world of computing and programming was becoming more powerful, but at the same time more complex, more distracting, and less direct and creative.

Today it is of course possible make very simple games and animations using PyGame, any JavaScript game library, even game engines like Unity or Godot, or simply in Java (Swing, let's say, or any suitable library). There are a lot of choices, good choices, powerful choices. Too many to list here.

Image from https://www.gamingonlinux.com/2023/07/godot-engine-4-1-brings-a-detachable-script-editor-vulkan-pipeline-cache/

Still, the directness and simplicity of earlier days is completely gone.

It seemed to me that you are either stuck in the powerful but complex languages and environments of today or go the nostalgic "retro" route of coding for retro-platforms. Which give you either the simple but underpowered BASIC interpreters of past decades, or the slightly more powerful but very complex and nuanced world of direct hardware access via assembly (which again is less direct because no sane person would code assembly directly on the host machine).

If only there was an environment that:

Rescued the simplicity and directness of the past
Offered powerful APIs and capabilities at your fingertips

I must not have been the only one feeling this way, and recognizing and unmet need. These environments somehow started emerging. They come in the form of "fantasy computers" or "fantasy consoles".

After some searching I found the one I felt in love with: the Mini Micro.

Which, I want to state publicly, I consider both a work of love and a work of art.

Mini Micro for me really rescues the directness and simplicity of earlier (8-bit-era) computers. You interact with it either by typing in commands at a prompt, even trying things out in its REPL) or writing your program in the built-in editor (one one program, one file at a time - I mention this as a nice feature and part of the "distraction free" philosophy).

On the other hand it gives you "power" I could not have dreamt of in my young days having an 8-bit computer:

A simple yet modern a powerful language. Not BASIC but MiniScript. MiniScript is in an of itself a work of both art and love. It is what I call "a language that fits in your head". Yet powerful enough to write just about anything you can think of. It deserves its own articles, or series.
Built-in editor with the usual features: copy-paste, find/replace, automatic indenting, syntax-highlighting.
Sprites. Unlimited in amount and size. Rotation, color-tinting and even pseudo-3D transformations.
Access to drawing primitives. Basic shapes, thickness, colors.
A "tile" display like in 8-bit computers but more powerful (no limitations in size or amount of different tiles, for example)
Up to 8 different display "layers", which you can set-up as you want. Display-types can be: sprite, pixel, tile, text and solid-color.
Modern sound capabilities. Playing of sampled and FM sounds.
Ability to share with others (major platforms and web).

I could go on and on. But you get the picture: simplicity, directness, lack-of-distraction experience of the past with modern capabilities.

I spent many hours coding different things in Mini Micro and I could not be happier.

Some of my Mini Micro creations

For me it is the perfect distraction-free environment for exploring ideas, do "serious" or "casual" coding and, most important: having fun.

Thanks for reading this far. If you feel like me and want to revive the simplicity of the past without sacrificing "power" I invite you to give Mini Micro a try.

Plus, the community is very welcoming and its creator is a great guy always willing to help.

Cheers!

Movement-events on Mini Micro (part 1)

Sebastian Nozzi — Wed, 01 Oct 2025 22:46:14 +0000

In this post I want to share with you different ways to check for (sprite) "movement" events in Mini Micro.

This is partly inspired by Joe's comment at my "Coin Collector" tutorial. He suggested to use the key.axis function instead of checking for concrete key-codes (like for the arrow keys).

First, I want to categorize the firing of "movement events" into two main types:

Continuous firing
Discrete firing

(I came up with these names, apologies if there are more known or accepted names out there).

"Discrete firing" is when only one movement event is fired when the user presses an arrow key. This will be discussed in a future post. For this post, let's focus on "continuous firing" ...

Continuous firing

In "continuous firing" the player's object keeps moving in one direction as long as the corresponding arrow-key (or joystick axis) is being pushed.

The movement only stops when the key is released (or the joystick returns to neutral position).

An example of one of my projects that I could bring up is the spaceship from my "Letter Shooter" game. It moves with the arrow keys, and keeps moving when a key is being held down.

A reduced / simplified form would look like this:

So, does one code continuous-firing of movement events in Mini Micro?

Arrow-keys

A first version, checking for arrow keys, could look like this:

clear

while true
    if key.pressed("up") then print "^", ""
    if key.pressed("down") then print "V", ""
    if key.pressed("left") then print "<", ""
    if key.pressed("right") then print ">", ""
    wait 0.01
end while

(By the way, if you ever need to know the "names" of the keys available for the key.pressed function, try pprint key.keyNames on the console).

Try it! When run, the code will print the corresponding "direction" characters as long as an arrow-key is pressed.

A short delay was introduced so that the screen is not filled-up too quickly with characters, making it difficult to see what's going on. Experiment with different values, replacing it with yield or removing it entirely.

Enter the Spaceship

Let's make the above example more interesting by actually adding the "spaceship" and moving it on the screen:

clear

// Display 4 is our default sprite-display
sprDisp = display(4)

s = new Sprite
s.image = file.loadImage("/sys/pics/Fighter.png")
// Place on the center of the screen
s.x = 960 / 2
s.y = 640 / 2
// Make it face up, and smaller
s.rotation = 90
s.scale = 0.5

sprDisp.sprites.push s

// Velocity. Spaceship will move this amount of pixels
// for each "key-down" event.
v = 5

while true
    if key.pressed("up") then s.y += v
    if key.pressed("down") then s.y -= v
    if key.pressed("left") then s.x -= v
    if key.pressed("right") then s.x += v
    wait 0.01
end while

Now this works, but "only" supports arrow-keys. Personally, this is what I do in most of my projects. But one could generalize this by using the key.axis function (thanks Joe Strout for pointing this out). This would support both arrow-keys and gamepads / joysticks with one codebase.

Using `key.axis`

The key.axis function returns values between -1 and 1 (and typically 0) depending on the state of one of its "axis" (which can be "Horizontal" or "Vertical"). As mentioned, it reacts both to arrow keys and gamepads / joysticks.

A re-worked while-loop with key.axis would look like this:

while true
    if key.axis("Vertical") > 0 then s.y += v
    if key.axis("Vertical") < 0 then s.y -= v
    if key.axis("Horizontal") < 0 then s.x -= v
    if key.axis("Horizontal") > 0 then s.x += v
    wait 0.01
end while

Factor to velocity

While trying things out for this post there is something I noticed. When exploring the returned values of key.axis, it does not just return -1 or 1. Even when using arrow keys. It also returns values in-between when the firing is "starting" to take place. As if "warming up". This nicely simulates a gamepad / joystick slowing leaving the neutral position while reaching one of the extremes of a direction (going all the way "left" or "up").

This code snippet showcases this fact:

clear

while true
    vAxis = key.axis("Vertical")
    hAxis = key.axis("Horizontal")
        // Only print if any of the values is not 0
    if vAxis or hAxis then 
        print "V:" + vAxis + " - H:" + hAxis
    end if
    wait 0.02
end while

Armed with this information, one could further adapt the spaceship-movement example to use the axis-values as "factors" (in a multiplication) to the velocity. And while we are at it, let's replace our wait with a yield.

Our while-loop would look like this:

while true
    vAxis = key.axis("Vertical")
    hAxis = key.axis("Horizontal")
    s.x += hAxis * v
    s.y += vAxis * v
    yield
end while

Notice how we don't need "ifs" anymore. Just take the current values, multiply and add to the current position (of course multiplying by 0 results in 0, and adding 0 to current coordinates does nothing).

The change in movement is subtle. You should notice the space-ship slowly starting to move in one direction and the acquiring constant speed. Nice.

Conclusion

This post showed how to detect movement-firing events "continuously" and also how to apply that information to moving a sprite.

In a further post we will talk about "discrete" movement-events and see some applications.

Have fun with Mini Micro!

Codebase Onboarding Documentation

Sebastian Nozzi — Fri, 02 May 2025 21:53:57 +0000

I've often faced the problem of getting familiar with existing big, complex, codebases.

The size and complexity seem insurmountable, it is not clear how things work and are related to each other, one does not know where to start learning and getting clarity.

Some projects have at best a README file, and maybe one or two additional files. Others have a Wiki, but often talking about conceptual aspects and therefor don't help so much in understanding the code itself.

More often than not, code is poorly documented, if documented at all. Even if individual methods or classes are documented, it does not always help in understanding the "big picture" and knowing how everything fits together.

This situation, together with the accompanying frustration, lead me to look for solutions. One of them very extreme.

Enter ...

Literate Programming

What if we were doing the whole thing wrong?

When I initially read about literate programming I was hooked. I thought: this is it!

For those unfamiliar with it, the idea of literate programming is that you don't start with code, which you then "document".

You start with a "document" through which you explain your program, one code-snippet at a time. That document takes the form of a complex book, with pages and chapters. The code-snippets themselves, which are initially part of the document, are inter-related themselves.

Then, you run a typical "literate programming" tool, which does two things:

It produces a beautiful, pleasant to read document (often as a PDF or a webpage, together with images, fonts, table of contents, links and so on).
It assembles your final codebase from the inter-related snippets. After that, you are free to compile your code to produce your executable, or whatever deliverable your code produces.

The strength of this approach is that you, as the "book author" can decide what to explain when. Our programming languages and frameworks often dictate how files and folders are to be structured in a codebase. But if you start with a document, you are free to introduce "files" and code-snippets in any order you want.

I could talk more about this approach, but I will end this for now.

Suffice to say that, while the approach seems to have many advantages, and be a good fit to my "onboarding problem", it does impose big sacrifices:

One can kiss our familiar tool-integration (IDEs) goodbye
Refactoring becomes much harder
Code navigation becomes much harder
Maintenance becomes harder / slower (maybe a good thing?)

Realistically, I could not imagine this being the ultimate solution. I must admit that I never seriously tried it on a big project, and maybe I should. But the cost-benefit outcome did not seem quite right to me.

Nevertheless, the spirit of the approach seemed good, and it contained good ideas and noble goals.

What if there was an hybrid approach, or something inspired by it ...?

I think I found an approach that might be just that ...

What about Wikis?

Earlier I mentioned that some projects do contain Wikis.

The nice thing about Wikis is that they are easy to use. Documents are "cheap". Creating new pages is easy. Editing existing pages is easy. Especially if one is using Markdown.

But I didn't like the fact that most Wikis "live" separate from the codebase.

What I wanted is to navigate a codebase, and have a series of documents, IN the codebase, telling me about important aspects of the code I was dealing with.

Local "Wikis"?

At some point I became aware of a "trick" (is it really) that some open-source projects sometimes use: interlinking of Markdown documents.

Typical examples would be having a "README.md" file, and have it link to a "LICENCE.txt" file or a "Contributing.md" or "Installation.md" files, and so on ...

The linking per-se is part of the equation, however. The viewing environment at hand is the one which has to honor the links, and make the navigation possible. Fortunately, both GitHub (the webpage) and ~~IDEs~~ code editors like VSCode support this feature.

Armed with this knowledge I had this idea: one could strategically put Markdown files in the appropriate places and have them linked. One could navigate them from within a code-editor (or repo viewer like GitHub) and they would provide context-sensitive meta-information.

Think for example:

Documenting the deployment process
Documenting installation
Documenting architecture
Documenting packages / modules / subprojects

I think it's a worthy idea. And for some projects I would use it as is. But I still was missing something lost from the "literate programming" approach.

I was missing "beauty".

In search of Beauty Lost

Let's go back in time to my experiments with "literate programming".

Remember that I previously mentioned one of the outputs, apart from the resulting codebase, was "beautiful content"?

But what do I mean by "beautiful"? What I mean is "more than just plain text". Think: different font styles, images, diagrams, colors, footnotes, admonitions, table-of-contents, etc. Things we are used to from (technical) books, documentation and webpages. Markdown (if rendered beyond its plain-text version) does support some of that, but not all ...

When first conceived, the first "literate programming" tools used have LaTeX as its content-generation language. That is: the produced document was LaTeX-based, with all that it implies (personal summary: very powerful features, not so friendly to write, geared more towards print media, especially academic papers).

But when exploring "literate programming", my idea of the final document was never a PDF or LaTeX file, but a webpage. More specifically a modern, navigable online documentation. That is: HTML based.

One tool for producing HTML-based technical documentation is Sphinx. It originates and is very widespread in the Python world, but can be used for whatever purpose one sees fit.

Fortunately I found out that there have been "literate programming" extensions for Sphinx.

That alone made me familiar with Sphinx as a document-authoring and generator tool. Remember: one writes Sphinx pages in "code" itself. The variants being reStructuredText or Markdown.

So there I was. One the one hand having me realization about the ability to interlink Markdown pages. On the other hand missing advanced features found in document-generators like Sphinx.

Until I had an idea ... what if I combined the interlinked Markdown-pages approach with Sphinx-generated documentation ...?

"Embedded Doctree"

For lack of a better name, I call this the "embedded Doctree" approach. Let me explain ...

Through some trickery (which I am not going to go into detail right now) I managed to have a codebase be both:

The project codebase, with its normal file structure
A Sphinx project codebase, with its document pages

The code files and the documentation files are intermixed. They live in the same file-hierarchy.

Thus, I can put Sphinx/Markdown files wherever I want, have them linked however I want, and they will produce a nice HTML-based technical page. The nice-to-read HTML-based documentation can be read and navigated on the browser (even be published somewhere).

And on the other hand, Sphinx/Markdown files are developer-friendly when exploring a codebase. They can still be viewed and edited as plain text and even still support the direct linking mentioned earlier (with some minor exceptions).

Conclusion

I think I found an interesting middle-ground between the beautifully produced final-documents promised by the "literate programming" approach and useful, pragmatic, and IDE-friendly context-relevant local (document) files.

With this approach one gets to keep using existing IDEs and the usual code-navigation, while having interlinked local in-depth explanations for vital aspects of a codebase - both as plain-text (Markdown) files and pleasant-to-read navigable online documentation.

Coin Collector Game

Sebastian Nozzi — Sat, 04 May 2024 14:11:51 +0000

In this post we'll create a "coin collector" game for the Mini Micro.

The idea is taken from the book Computer Coding Python Games for Kids.

Rules

The game works as follows:

There is a fox and a coin on the screen.
You move the fox with the arrow keys.
When the fox collects the coin, the score is increased and a new coin is placed somewhere else on the screen.
You have a certain amount of time to collect as many coins as possible.
When the time is up the game is over and you are shown the final score.

By the way, if you are already Mini Micro expert you might try implementing the game with these rules and then comparing with the implementation on this post! Otherwise, keep reading ...

Assets

I'll be using the assets made available for readers of the book (which I borrowed from my local library).

I didn't read anywhere that they could not be used for other languages other than Python. As I understand it, we'll be using these assets for personal / fair use - as they are freely available on the Internet.

What I will not be doing is re-publishing these assets somewhere else; nor claiming these to be my own. Neither should you. So I think we all should be fine.

Project setup

Download the assets file.

Create a project folder and navigate there. Alternatively create a new "usr" folder and mount it.

Put the two images (fox and coin) of the coin collector game in your project folder.

Within Mini Micro, save an empty file "game.ms" on your project location.

Placing the fox

Let's start by loading the fox's image and placing it as a sprite on the screen:

// Fox Sprite

foxImg = file.loadImage("fox.png")

fox = new Sprite
fox.image = foxImg
fox.x = 200
fox.y = 200

// Game setup

clear

gfx.clear "#308A37"
sprd = display(4)

sprd.sprites.push fox

Note the following:

We created to "sections" to organize our code ("Fox Sprite" and "Game setup")
We are making use of the pre-defined SpriteDisplay at slot 4
We are making use of the pre-defined PixelDisplay accessible via the global "gfx". We only use it to fill (clear) it with a background color (same as in the original implementation)

Running this should show the fox on the screen.

Moving the fox around

Modify the fox-sprite block to add a "speed" property:

fox = new Sprite
fox.image = foxImg
fox.speed = 10
...

And at the end of the program add the following while-loop:

// Game Loop

while true

    if key.pressed("left") then
        fox.x -= fox.speed
    else if key.pressed("right") then
        fox.x += fox.speed
    else if key.pressed("up") then
        fox.y += fox.speed
    else if key.pressed("down") then
        fox.y -= fox.speed
    end if

    yield
end while

When running the program the fox should now move with the arrow keys.

(In order to keep this post short and the program simple we won't be checking if the fox leaves the screen. It's up to you to keep it inside!)

Showing the coin

Now it's turn to show the coin somewhere on the screen.

Let's add this new section after the "Fox Sprite" one, before the "Game Setup":

// Coin Sprite

coinImg = file.loadImage("coin.png")

coin = new Sprite
coin.image = coinImg
coin.x = 500
coin.y = 500

And we should not forget to add the coin sprite to the sprite-display. In the "Game Setup" section add this line:

sprd.sprites.push coin

This should give you a movable fox and a static coin.

Collision detection

As a next step we need to add local bounds so that collision detection works.

First we add local bounds to the fox sprite. These lines could go right after assigning the image:

fox.localBounds = new Bounds
fox.localBounds.width = foxImg.width
fox.localBounds.height = foxImg.height

Same thing for the coin sprite:

coin.localBounds = new Bounds
coin.localBounds.width = coinImg.width
coin.localBounds.height = coinImg.height

Let's test if collision detection works. Add this check inside the while-loop, before the "yield":

if fox.overlaps(coin) then
    print "Fox gets coin!"
end if

Try it out. You should see the text written many times (as the collision is detected many times per second).

Placing the coin randomly

Now, let's start fleshing out the proper game logic. Replace the above lines with these ones:

if fox.overlaps(coin) then
    coin.moveToRandomLocation
end if

We of course need to write this new method moveToRandomLocation for the coin object. Add this to the "Coin Sprite" section:

coin.moveToRandomLocation = function
    self.x = floor(rnd * 960)
    self.y = floor(rnd * 640)
end function

Note the usage of the "rnd" and "floor" intrinsic functions.

Try it out. You will see that except for the score and timer it looks like the game we want to have!

Score

Let's add a new section "Score" before "Game Setup". We will write a small object to take care of the score.

// Score

score = {}
score.value = 10

For printing the score we will use the pre-allocated TextDisplay. Because we will be updating the score text on the screen many times, we will also some way of deleting the old content.

Let's start by creating a new section with these helper functions:

// Text helper functions

eraseText = function(row,column,length)
    text.row = row
    text.column = column
    // Print "length" amount of spaces, with no "newline"
    print " " * length, ""
end function

printTextAtPosition = function(txt,row,column,txtColor)
    // Save current color and set color from parameter
    previousColor = text.color
    text.color = txtColor
    // Move to position and print text
    text.row = row
    text.column = column
    print txt
    // Restore previous color
    text.color = previousColor
end function

With these helper functions we can easily implement the score-rendering. Add this method to the "Score" section:

score.print = function
    eraseText 25, 5, "SCORE: 999999".len
    printTextAtPosition "SCORE: "+self.value, 25, 5, color.white
end function

As you can see we reserve an area for quite a big score number, which we'll probably never reach.

Finally, add a first "score.print" call at the end of the "Game Setup" section:

score.print

// Game Loop 
...

Try it out.

Updating the score

The score now appears on the screen, but is not is not yet updated when coins are collected. We will now change that.

Let's add a method to increase and update the score on screen:

score.increase = function
    score.value += 10
    score.print
end function

Of course this alone is not enough. The method needs to be invoked when the fox collects a coin. Modify the corresponding if-block in the game-loop to read like this:

if fox.overlaps(coin) then
    coin.moveToRandomLocation
    score.increase
end if

Displaying the countdown

The fox can now collect coins at leisure ... but that's about to change. Now we'll add a timer to put some pressure.

We will start slow and just showing a countdown on screen.

Let's create a "Countdown" section right after the "Score" one, initially with these lines:

// Countdown

countdown = {}
// Countdown value in seconds
countdown.value = 0

As a first step, let's write a "start" method with which we can start / initialize the countdown:

countdown.start = function(initialValue)
    self.value = initialValue
    self.print
end function

Accordingly we'll add the method to render the countdown text on screen:

countdown.print = function
    eraseText 25, 50, "TIME: 9999".len
    printTextAtPosition "TIME: "+self.value, 25, 50, color.white
end function

Again, for reserving a printable area (erasing the previous text) we are choosing a very generous time value.

Now let's add an invocation to this "start" step when setting up the game. In the "Game Setup" section add this:

countdown.start 20

Feel free to decide the amount of seconds which best work for you.

If you try this out you should see the countdown being displayed on screen. But it does nothing yet. We'll change that in the next section.

Counting down

At this point we need to stop and think: how would the countdown logic work?

We can do the following:

The countdown starts with an initial value (of seconds)
Inside the game-loop we'll call an "update" method on the countdown object
The method will check how much time it elapsed since it has last decreased its value
If more than one second elapsed, the countdown will decrease its value and register this new "last decrease timestamp".

The strategy is clear, but some important pieces are missing. Besides the obvious "update" method we need to add a new property to keep track of "decrease events".

Add this after the "value" property to the countdown object:

countdown.lastDecreaseTs = -1

We use some weird value like "-1" to make clear that it needs to be initialized. We will do just that now. Modify the "start" method to read like this:

countdown.start = function(initialValue)
    self.value = initialValue
    self.lastDecreaseTs = time
    self.print
end function

By initializing it to the current timestamp we will have one full second before we need to decrease its value for the first time.

Now we are in position to implement our countdown logic inside the "update" method. Add this method to the countdown object:

countdown.update = function
    currentTs = time
    elapsed = currentTs - self.lastDecreaseTs
    // A second elapsed since last check
    if elapsed > 1 then
        self.decrease
        self.lastDecreaseTs = currentTs
    end if
end function

It references a "decrease" method which we do not yet have. That method should decrease the value internally and update it on screen. Let's add it now:

countdown.decrease = function
    self.value -= 1
    if self.value < 0 then self.value = 0
    self.print
end function

Because we do not want negative numbers in our countdown, we add a corresponding check.

Finally we need to update our game-loop to regularly call the "update" method. We can put that invocation right at the top of our while-loop:

while true

    countdown.update

    if ...

When you try it out you will see that our game is almost done!

Stopping the game

If you play the game in its current state you will merrily be able to still collect coins even if the time is up. Time to change that.

Let's add a small method to the countdown to indicate that it is finished:

countdown.isFinished = function
    return self.value <= 0
end function

And now let's add a check in the game loop. Right after decreasing the countdown we will add this line:

if countdown.isFinished then break

This will effectively get us out of the while-loop when the countdown is done. As it is, the game just ends. You can of course see your final score on the screen.

But we should be able to make it nicer.

A better ending

First, let's add this function to our "Text helper functions" section which will allow us to print text centered on the screen:

printTextCentered = function(txt,row,txtColor)
    totalColumns = 68
    column = totalColumns / 2 - txt.len / 2
    printTextAtPosition txt,row,column,txtColor
end function

With this let's print the final score and ask the user to play again or not. Add this outside (after) our game-loop:

// Game ending

printTextCentered "FINAL SCORE: " + score.value, 16, color.white
printTextCentered "Do you want to play again? (y/n)", 14, color.white

The user should press either key "y" or key "n". Because the user will probably still fiercely holding an arrow key, we need to "consume" these until we detect any of the keys we want.

Add this next to our section:

while true
    k = key.get.lower
    if k == "y" then run
    if k == "n" then break
end while

If the user presses "y" the program will be run again.

But if the user presses "n" this while-loop is exited and the program is over. Before that happens, let's add a short farewell message. Add this after this while-loop:

print
print "Bye!"

And you could say we are done!

Try it out and have fun!

Final words

Glad you made it this far. Did you like this game tutorial? Did you learn something new? How many coins can you collect? Let us know in the comments.

Happy coding in Mini Micro!

Mini Micro Web-Runner CLI

Sebastian Nozzi — Sat, 06 Jan 2024 00:32:38 +0000

After some days of work I finished re-working the MMWR (Mini Micro Web-Runner, more details about this in another post) so that it is driven by two powerful and handy (Node.js-based) command-line tools ...

Serve

The first one is mmwr-serve ... which would be used when developing. One just navigates to one's Mini Micro project, issues the aforementioned command, and a local HTTP server is started which "serves" the project to be run on the browser. That's it. If one changes something in the code, just reload and the change should be there.

No additional "index.html", CSS or JavaScript files needed. The server tool takes care of all the details behind the scenes.

Package

The second one is mmwr-package ... which one would use to package a Mini Micro project to deploy somewhere, for example itch.io. Same thing: navigate to the Mini Micro project and issue the command. An Archive.zip file is produced with everything needed. Including a whole "sysdisk". More on this below.

Config File

Both tools can make use of a webrunner.config.json file if present. One can specify the HTML page title, one should specify the main ".ms" file of the project, and optionally additional files / folders.

For example:

{
  "pageTitle": "Sliding Puzzle - Mini Micro Web Runner",
  "mainFile": "game.ms",
  "otherEntries": [
    "animation.ms",
    "game-images"
  ],
  ...
}

Sysdisk Entries

One interesting aspect is that one can filter (out) "sysdisk" entries, making the end-product (Archive.zip) slicker than it would be, resulting in faster downloads (from itch.io) and thus quicker start-up times.

Consider this:

{
  "pageTitle": "Mini Micro - LetterShooter (Web Runner)",
  "mainFile": "game.ms",
  "sysDisk": {
    "useOnly": [

      "/sys/pics/Heart.png",
      "/sys/pics/Fighter.png",

      "/sys/sounds/airburst.wav",
      "/sys/sounds/airburst.wav",
      "/sys/sounds/hit.wav",
      "/sys/sounds/ting.wav",
      "/sys/sounds/bling.wav",
      "/sys/sounds/fanfare.wav"
    ]
  }
}

In this case we include only some pics and sounds from the "sysdisk", greatly reducing the final size from 13 Mb to 2.4 Mb.

Final Words

This is the initial version of these tools. Some things might change. But in general this is the direction I want to take the MMWR. It should be both:

A handy tool for local development
A handy tool for sharing one's creations with others

As mentioned, the new CLI tools cover both these areas.

Upcoming Global Day of Code Retreat

Sebastian Nozzi — Thu, 02 Nov 2023 23:05:16 +0000

Just a quick reminder that the next Global Day of Code Retreat is about to take place next Saturday.

From their website:

Coderetreats are free day-long, intensive practice events, focusing on the fundamentals of software development and design. By providing developers the opportunity to take part in focused practice, away from the pressures of "getting things done", the coderetreat format has proven itself to be a highly effective means of learning and nurturing software development skills.

All over the world, people are coming together in small communities of practices to learn, explore and grow.

After a COVID19 forced break, and personal reasons, I intend to participate in the one nearby.

It's always nice to meet other developers, and it's inspiring to work on one's skills (both hard and soft skills).

Combined Undo Actions

Sebastian Nozzi — Thu, 02 Nov 2023 20:37:37 +0000

Recently I quickly described how I implemented complex undo-actions in a game I developed. That game is a Sokoban clone, which I implemented in the Mini Micro neo-retro fantasy computer.

TLDR: the challenge of executing multiple small undo-actions was solved by combining many anonymous functions into a bigger one, finally pushing the latter into an undo-stack.

A first approach

A first naive approach could be like this:

When the user makes a move
Push the opposite move on a stack
When the user wishes an "undo"
Pop the stack and perform the popped operation

This works "good enough" as long as we are just moving the worker. But it fails as soon as box-pushing is involved. For the reason alone that the approach above completely ignores boxes.

Boxes and directions

In addition to failing to consider boxes, the approach above fails to capture another additional detail: worker facing-directions. That is: the worker (in my implementation) does not always "look" in a fixed direction. Rather he turns left, right, up, down depending on where he's trying to go or push.

So now we have two more aspects which should be "undone" when undoing a step:

Box position (if this changed due to a push)
Worker turning to a new direction

As we see a single user-event (wanting to go "left" one step) can result in many things happening:

The worker turning to a new direction
The worker changing position
A box changing position

Box state

If we think possible outcomes of an action further, another very important change can happen:

A box changing its "state"

Remember, the goal of Sokoban is to "place" boxes in special "target" or "goal" tiles. A level is solved when all boxes are placed in such tiles.

So a box can change from "unplaced" to "placed". And vice-versa (from "placed" to "unplaced", this is often temporarily needed for tactical reasons before the level is solved completely).

To recap, this would be the a complete list of things that can happen in a user "turn":

The worker turning to a new direction
The worker changing position
A box changing position
A box changing state

Complex undo actions

Intuitively, using an "undo" stack makes sense. But what would we push onto it, so that we can properly undo an user "turn"?

Let's say a user "turn" results in these steps:

Turn worker to the "left"
Move worker (from [3,2]) to [2,2]
Change box position (from [2,2]) to [1,2]

Would I want to push in the stack what happened and then figure out the opposite action? Or push the opposite action to begin with? I opted for the latter.

So I would push this, in this order:

Change box position (from [1,2]) to [2,2]
Move worker (from [2,2]) to [3,2]
Turn worker to the "right"

For example, here is the implementation of moving an element (worker or box) and registering the opposite "undo" action:

LevelSprite.moveTo = function(position)

  // Only do this if sprite already placed and the new
  // position is different than the current one.
  if self.position and self.position != position then

    previousPosition = obj.position
    previousX = obj.x
    previousY = obj.y

    // Register corresponding "undo" action ...
    // (Capture "self" so that it's "fixed" when executing)
    obj = self
    undoAction = function()
      obj.position = previousPosition
      obj.x = previousX
      obj.y = previousY
    end function
    // Note the function reference
    Actions.queue @undoAction

  end if
end function

But I needed a way to "group" actions, so that when the user wants to undo his last keystroke all of the three are popped from the stack and executed. But not more! (the stack could well have previous undo-actions pushed into it).

Enter transactions

I solved the problem by grouping actions belonging to a "turn" and pushing them as-one into the undo-stack.

That is, my undo-stack always has ONE entry per turn. Those three entries shown in the previous section are grouped into one and pushed into the stack.

When the user wants to perform an undo, the composite action is popped and executed.

But how do I group the smaller actions into a bigger one to begin with?

I solved this by simulating "transactions".

When the user presses a direction key, thus issuing a game event, a transaction is started in the "undo manager".

The different parts of the code that change game-state are responsible of pushing their "undo actions" into a temporary (transaction) stack. For example the part that moves a box due to a push is responsible for registering the opposite move.

When all game-state changing logic is executed, the transaction is "closed". Then the undo-manager groups all registered "undo actions" and makes one bigger single action, which is pushed in the undo-stack.

In terms of code, it looks like this:

WorkerSprite.move = function(direction)
  Actions.beginTransaction

  self.rotateInDirection direction
  nextPosition = self.nextPositionInDirection(direction)

  objectAtNextPosition = LEVEL.getLevelObjectAt(nextPosition)
  objectAtNextPosition.move direction

  if LEVEL.hasFreeTileAt(nextPosition) then
    super.move direction
  end if

  Actions.endTransaction
end function

The relevant parts are the beginTransaction and endTransaction in the move method. The rest is the normal logic for a movement in a Sokoban level.

Functions

What are those undo-actions really?

The actions, small and combined, are anonymous functions.

After that, pressing undo is just a matter or popping the stack, and executing the top-most function (which returns the game state to one step before).

For example in one transaction all of this could happen:

Worker changes direction to the right
Worker advances one position
A box is pushed in direction "right"
A box changes its "placed" state from "unplaced" to "placed" (green)

All of this would require ONE undo-action which:

Moves the worker one step to the left
Moves the box one step to the left
Rotates the worker to whichever direction it was facing before
Sets the box to "unplaced"

And how to combine many function-references into one that calls them all? Something like this:

fn = function()
  for qa in queuedActions
    qa()
  end for
end function
// Register composite action
self.actions.push @fn

This takes place within endTransaction. A new anonymous function that executes other anonymous functions stored in a list. Then pushed to a stack, ready to be retrieved and executed later.

Going into more detail would blow up the length of this blog post. Readers so inclined can take a look directly at the source code. Questions are welcome.

Conclusion

Undo-actions were modeled using anonymous small functions which would restore the game-state to a previous step.

By using a "transaction" per user turn / action all relevant game-state changes could be registered and combined.

The small anonymous functions were then combined into a bigger one, and pushed into the undo-stack. This makes the latter execution of an undo step trivial.

Happy coding!

Maintainable Software Development

Sebastian Nozzi — Thu, 17 Aug 2023 13:35:34 +0000

In the course of my time as a software developer I came to some realizations about how to write maintainable code in a professional setting. By this I mean: in long-term projects, usually for a customer, where maintainability is a key requirement. This in contrast to short-lived, personal, hobby projects where many of the requirements of a professional setting don't apply.

Layer-based Code Organization

Something that I see happening over and over again in codebases (mine included) is the tendency to "code solutions" instead of "modelling the problem".

By this I mean writing whatever code that solves the problem (makes the computer do what you intend it to do). Which is fine. Initially.

The problem is that meaning gets often lost in the process. Either partially or totally.

This makes it very difficult to understand what the code was about and adapt it to new requirements.

An alternative might be to use code to express the problem at hand. By coding and using the necessary "abstractions", a so-called "top-level" part of the codebase should be able to express the problem, while at the same instructing the computer to execute the solution.

Below that theoretical "top-level" would come the next level, which solves different problems (using the abstractions needed at that level). That level would in turn rely upon abstractions one level below it. And so on.

While this approach might need more effort and discipline it should pay long-term where projects are long-lived, involve many team members and maintainability is an issue.

De-Coupled Tests

When firstly introduced the idea of writing "unit-tests" or pieces of code that "test" your "production" code seemed alien and even a waste of time.

Decades later, practices like TDD are a well established standard. The professional projects that don't use some sort of automated testing are rather the exception.

However, in many projects (mine included) I discovered an aspect of automated testing that turned automated-tests into a liability rather than an asset.

The more tests a codebase had (usually but not necessarily resulting in more coverage) the bigger this problem presented itself: the design of the codebase became more rigid.

That is: code was increasingly more difficult to change, not less.

And that is because the way tests were written was by being tied directly to whatever design decisions happened to be present in the code being tested at that time.

This creates high-coupling not within the production code (which the experts usually advocate against and focus their energy on) but between production code and tests (which are supposed to be independent from production code and only be there to help you).

As a result, the code-design would be increasingly unable to improve. Overall the whole codebase would grow in complexity. By not being able to re-design to better abstractions the codebase would be stuck with unsuitable design decisions and abstractions.

The solution to this problem of course would be to de-couple automated-tests from implementation details. Abstractions used in production code would not appear in the test-code, but in a "bridge" / "adapter" layer.

Instead the tests would be written using an internal DSL (written only for in test-code; never in production). This would not only make tests easier to read, but allow production code to evolve 1) at all and 2) faster by being independent of test-code.

Updating the Documentation

One particular area which is usually a second class citizen in software projects is ... apart from security: documentation.

Often developers don't have time, are not given the time, or do not care (or are not told to care) about documentation.

Until it's too late and one either has no documentation or fragmented, incomplete, inconsistent or outdated one.

Because documentation does not "run" and is purely a "human" activity the solution in my opinion has to be a "human" one. But both technology and methodology can and should help.

My proposal here is to make writing or updating the corresponding documentation a requirement either at the pull-request level, or even better, at the issue level (reviewed by the customer).

That is: whenever a feature changes, whenever the code is modified, if applicable, a documentation change is also required. The issue or PR is not considered complete until the documentation is reviewed to have been changed satisfactorily.

Bonus: Security - Ownership approach

And because I mentioned it in the section before, let's also talk about security.

Security, maybe together with documentation, is an aspect that developers usually don't enjoy.

I might expand on this on a future post, but I think the approach is to appoint a security "owner" and have this person be a required reviewer of all PRs.

Final words

Hope these points here made motivated you to think about best-practices in a professional software-development setting.

I hope to be able to expand on these thoughts in the future.

Random numbers

Sebastian Nozzi — Sun, 12 Mar 2023 22:26:45 +0000

In this blogpost we are going to take a look on how to produce random numbers within a certain range in MiniScript / Mini Micro.

The `rnd` function

In MiniScript (and by extension Mini Micro) the way to get random numbers is by using the rnd intrinsic function.

Calling this function gives you a floating-point random number between 0 and 1.

> print rnd
0.147535
> print rnd
0.421682

Bigger range

If we want a bigger range of random numbers all we have to do is multiply the result of rnd by some other number. For example: if we want random numbers between 0 and 20 we evaluate rnd * 20:

> print rnd * 20
15.439491
> print rnd * 20
19.455438
> print rnd * 20
8.460014

The `floor` function

Often we need random integers (whole numbers). One way to convert a floating-point number to an integer is by calling another intrinsic function: floor. Applying this function to a floating-point number will effectively strip it from the decimal digits, leaving only the "integer" part.

> print floor(0.14)
0
> print floor(42.9)
42

Situation so far

Combining these three things:

... calling rnd for random numbers between 0 and 1
... multiplying rnd by a factor
... applying floor to the result

... will produce random integers between 0 and the desired factor.

For example:

> print floor(rnd * 20)
13
> print floor(rnd * 20)
6

Numbers in any range

What if we wanted to have random numbers for a certain range starting above 0?

what we need to do is to sum some fixed number to the result. When doing so we are "shifting" the range of results, so we need to be careful about the end of the range, which is also shifted. We usually need to compensate for that by subtracting from the factor, which corrects the range-size.

For example, let's say we want random numbers between 100 and 300.

What is the solution?

Maybe floor(rnd * 300)? No, this would give us numbers from 0 to 300.

Maybe 100 + floor(rnd * 300)? No. Because floor(rnd * 300) gives us numbers from 0 to 300, adding 100 to it would give us numbers from 100 to 400 (not what we want).Remember: the end-range is also shifted.

Because the end-range is shifted, we need to compensate by subtracting from the factor (to correct the range size).

The correct answer is general terms:

RANGE_SIZE = END_RANGE - START_RANGE
START_RANGE + floor(rnd * RANGE_SIZE)

And in our case:

100 + floor(rnd * (300-100))

Or, simplified:

100 + floor(rnd * (200))

Some examples:

> print 100 + floor(rnd * 200)
282
> print 100 + floor(rnd * 200)
102
> print 100 + floor(rnd * 200)
183

Summary

With this we learnt how to generate random whole-numbers (integers) in a range between two arbitrary numbers in Mini Script.

In a future posts we will put this knowledge to use and have some fun with it.

Happy coding!

Counting word lengths (map approach)

Sebastian Nozzi — Wed, 26 Oct 2022 21:59:07 +0000

In a previous post we saw already how to solve the problem by using an array.

Specifically we had a 12-length array, and each position was used to increase a counter according to the current word's length. We had to convert from word-length to array-index by subtracting 1 from the first number.

This solution worked perfectly fine and given the constraint of only considering word-lengths up to 12, I would go this route.

But it is worth looking at a map-based approach (in other languages "map" is known as "dictionary"). Some other problems are better solved with this approach.

Recap

The complete array-based solution looked like this:

import "listUtil"

words = file.readLines("/sys/data/englishWords.txt")

word_length_counters = [0] * 12

for word in words
    word_length = len(word)
    if word_length > 12 then continue
    counter_index = word_length - 1
    current_count = word_length_counters[counter_index]
    word_length_counters[counter_index] = current_count + 1
end for

max_count = word_length_counters.max
max_count_index = word_length_counters.indexOf(max_count)
max_word_length = max_count_index + 1

print "The most common word length is " + max_word_length

Indeed, most of the code can remain the same. But some key changes need to be made.

First changes

First, instead of storing the counters in an array we will use a map. It will be a generic empty map, like this:

word_length_counters = {}

One advantage of using maps is that we can use "human" numbers as keys. That is: we can use directly the word-lenghts (which go from 1 to 12) without having to subtract 1 as we did for array indexes.

In particular MiniScript allows you to use pretty much anything as map-indexes, which is very convenient. It even allows you to use numbers as keys - which we will be doing here.

The first part of the for-loop remains the same:

for word in words
    word_length = len(word)
    if word_length > 12 then continue

But then it gets interesting. We don't need this:

counter_index = word_length - 1

We can access the current_count by word_length as mentioned:

current_count = word_length_counters[word_length]

And store it back, also using word_length as the key of the map:

word_length_counters[counter_index] = current_count + 1

Problem found

Putting it all together, this is how the for-loop would look like:

for word in words
    word_length = len(word)
    if word_length > 12 then continue
    current_count = word_length_counters[word_length]
    word_length_counters[word_length] = current_count + 1
end for

Looks ok, right? But what happens when you run it?

Runtime Error: Key Not Found: '1' not found in map [line 11]

Why is that? Problem is, the map is initially empty! So, the first time the "current_count" wants to be retrieved, nothing is found. We need to handle the case where the map does not yet have a counter for a given word-length.

We need to ask: does this map have the key "word_length"? If not, add an entry for it with a 0. This will have the effect that retrieving the "current_count" in the next line will find something (a 0 value) to add 1 to.

First-time access

How do we ask if a map has a certain "key"? In MiniScript this is solved at the "collection" level. That is: there is a method that is called the same and acts similarly for strings, lists and maps. That method is hasIndex.

With that in mind, this is the line we need:

if not word_length_counters.hasIndex(word_length) then word_length_counters[word_length] = 0

Putting that before the first access gives us then this (fixed) for-loop:

for word in words
    word_length = len(word)
    if word_length > 12 then continue
    if not word_length_counters.hasIndex(word_length) then word_length_counters[word_length] = 0
    current_count = word_length_counters[word_length]
    word_length_counters[word_length] = current_count + 1
end for

The result-calculation

Now is the time to adapt the result-calculation.

In the array-based approach word_length_counters already contained the word-lengths. But because we are using a map (which maps from word-length to word-counts) we need to look at the values of our map.

The first line would thus change from:

max_count = word_length_counters.max

to:

max_count = word_length_counters.values.max

Because the keys of the map are already word-lengths, we don't need to convert from "index" to "word-length". Even if MiniScript is talking about "index", it really means "key" in the context of a map.

Therefor the next lines can be simplified from:

max_count_index = word_length_counters.indexOf(max_count)
max_word_length = max_count_index + 1

to:

max_word_length = word_length_counters.indexOf(max_count)

The final print remains the same.

Complete solution

Finally, the complete map-based solution looks like this:

import "listUtil"

words = file.readLines("/sys/data/englishWords.txt")

word_length_counters = {}

for word in words
    word_length = len(word)
    if word_length > 12 then continue
    if not word_length_counters.hasIndex(word_length) then word_length_counters[word_length] = 0
    current_count = word_length_counters[word_length]
    word_length_counters[word_length] = current_count + 1
end for

max_count = word_length_counters.values.max
max_word_length = word_length_counters.indexOf(max_count)

print "The most common word length is " + max_word_length

Hopefully it was clear how to use maps in general, and in particular in this case (interestingly, using numbers as keys).

DEV Community: Sebastian Nozzi

Bad and good onboarding

Bad Onboarding

Good Onboarding

Achieving Good Onboarding

Final words

Dreams of a Mini Micro machine

Future work

Final words

Why Mini Micro

Movement-events on Mini Micro (part 1)

Continuous firing

Arrow-keys

Enter the Spaceship

Using key.axis

Factor to velocity

Conclusion

Codebase Onboarding Documentation

Literate Programming

What about Wikis?

Local "Wikis"?

In search of Beauty Lost

"Embedded Doctree"

Conclusion

Coin Collector Game

Rules

Assets

Project setup

Placing the fox

Moving the fox around

Showing the coin

Collision detection

Placing the coin randomly

Score

Updating the score

Displaying the countdown

Counting down

Stopping the game

A better ending

Final words

Mini Micro Web-Runner CLI

Serve

Package

Config File

Sysdisk Entries

Final Words

Upcoming Global Day of Code Retreat

Combined Undo Actions

A first approach

Boxes and directions

Box state

Complex undo actions

Enter transactions

Functions

Conclusion

Maintainable Software Development

Layer-based Code Organization

De-Coupled Tests

Updating the Documentation

Bonus: Security - Ownership approach

Final words

Random numbers

The rnd function

Bigger range

The floor function

Situation so far

Numbers in any range

Summary

Counting word lengths (map approach)

Recap

First changes

Problem found

First-time access

The result-calculation

Complete solution

Using `key.axis`

The `rnd` function

The `floor` function