Langur Monkey - Toni Sagristà Sellés

Local agentic workflows are getting crazy good

Toni Sagrista Selles — Tue, 12 May 2026 00:00:00 +0000

Building on the previous post about how good current open TTS models are, this post focuses on local LLMs, and their explosion in quality in the recent ~~years~~ months. I have been using OpenRouter with, for the most part, DeepSeek v4 Flash. It is a very capable model, dirt-cheap (seems to be heavily subsidized, at $0.14/M tokens input and $0.28/M tokens output), and it works very well when it is free to browse the internet. I have also been tinkering with local models like the Qwen3.5 family, Gemma 3/4, Mistral, and more. They are good, I haven’t been able to use the versions that can run reasonably on consumer hardware for anything too productive. That is until now. The brand new Qwen3.6 models, particularly the 27B dense, and the 35B A3B MoE, have really impressed the community. They are trivial to run on common setups (e.g. 16GB RTX card, ~32-64GB RAM), and when boosted with agentic capabilities, they perform very well.

My use case is quite modest. I typically use LLMs for research. I explain the problem and propose a couple of solutions, and ask for feedback. When I’m new to a topic, I like to get a bird’s eye view type of summary first, and then I ask for further explanation and deeper insight on certain areas that interest me. If possible, I add the sources that may help it gain more knowledge on the subject. Sometimes, I ask it to proofread my writings, but I tend to restrict it to fixing grammatical and spelling errors, with the occasional wording suggestion. I think writing is valuable and useful, as it helps with structuring my thoughts and organizing my ideas. That’s why I frown upon AI-generated blog posts. Additionally, I don’t like the overly verbose and structured texts it generates. I don’t do much AI-assisted coding. Sometimes, I may ask it to generate the odd Python script to solve a specific task that would otherwise get tedious.

My setup is like this: For casual questions and general chatting, I use OpenRouter chat for remote models and LM Studio for local models. Usually, I run the models on a gaming laptop (RTX 5080 16GB, 32GB RAM) and serve them to my machine via LM Link. For researching and more complicated workflows, I use the Hermes Agent. It is open source (MIT), fully-featured, self-improving (learns between sessions!), and offers everything I need with minimal configuration. It works very, very well. I connect it to either DeepSeek V4 Flash via OpenRouter, or to my local LM Studio, which is tethered to the inference machine via LM Link.

The Qwen3.6 27B and 35B A3B models, released in April 2026, have made strides in the community. They are extremely capable for their small size. They don’t have a ton of knowledge on all domains like the near-trillion-parameter frontier models, but when paired with the right toolset, they get very close. They don’t fit in most GPUs, but they can be partially offloaded. The MoE model in particular, with only 3B parameters active during inference, is very fast. I get ~35-40 tok/s with the 35B A3B MoE model, and about 4.5 tok/s with the 27B dense model. The dense model is borderline unusable, so I almost always rely on the MoE model. I offload 19 layers to the GPU (~12.5 GB out of a total of 26.63 GB), and use the maximum context size of ~262K tokens. This is plenty for agent sessions and works very well. The model is able to plan and execute actions very efficiently. It tends to overthink a lot, but this is an acceptable trade-off given the output quality. On OpenRouter, this exact same model is more expensive than DeepSeek V4 Flash, at $0.15/$1 per million tokens input/output. Being able to run such a model locally feels like a superpower.

So, now the question is obvious. Will local LLM get good enough in the future to replace frontier models? I’d argue that it depends on the task. Frontier models have a vast amount of knowledge and are able to one-shot many complex problems successfully. They will continue to be more suited for bleeding-edge research for the years to come. But they are also very expensive, very taxing on the environment, and the primary reason for the sky-high current hardware prices. There is certainly a case to be made for local and more economic small models.For day-to-day agentic workflow, I think open models are very close already. I would bet that in the next 2 years they will get on pair for most everyday tasks. Is this prediction grounded on reality, or just wishful thinking? I’d like to think the former. In any case, I’ll be here, watching, tinkering.

Local TTS is getting very capable and accessible

Toni Sagrista Selles — Wed, 29 Apr 2026 00:00:00 +0000

Around 2007 I spent half a year in the University of Aberdeen working on my final year project involving NLP. The project consisted of a series of modules to build an graphical adventure-type game controlled by language input in the form of text. It also featured speech output generated by an early TTS system. To achieve this, we managed to partner with a group at La Salle University that were working on a TTS system for Catalan. It was a closed system that was accessible via a web API, but that option was far too slow for real time use. I ended up preprocessing the audio of all dialogs in the project into WAV files just to be able to play them in sync with mouth movements. At that time, I was amazed that a computer could so easily convert text to an understandable audio file. The voice was very plain and robotic, with no emotion whatsoever. The results were hit or miss, but it worked.

Fast forward to today, TTS systems are everywhere. Several groups have released low-parameter TTS models that run very well on consumer hardware. I have been using the lightweight Kitten TTS for a while with fantastic results.

The models are so lightweight that some websites are heavier than entire Kitten TTS models:

Model	Parameters	Size	Download
kitten-tts-mini	80M	80 MB	KittenML/kitten-tts-mini-0.8
kitten-tts-micro	40M	41 MB	KittenML/kitten-tts-micro-0.8
kitten-tts-nano	15M	56 MB	KittenML/kitten-tts-nano-0.8
kitten-tts-nano (int8)	15M	25 MB	KittenML/kitten-tts-nano-0.8-int8

Projects like puss-say streamline and trivialize Kitten TTS inference. I have a shell script in one of my bin directories that does everything in a single command:

#!/usr/bin/env bash
uvx --from 'git+https://github.com/Mic92/puss-say' puss-say "$@"

This clones the project, pulls dependencies and models, and plays the audio. It is quite fast, especially when using cached data. Kitten TTS produces acceptable results, though the output usually lacks emotion and nuance. For simple use cases (reading notifications, generating voiceovers for scripts) it’s more than sufficient.

Qwen3-TTS, which I’ve been recently testing, represents a step-up in quality. It’s extremely good, and local inference is practical even on modest hardware given the model sizes. It offers three interesting variants:

Parameters	Hugging Face ID	Best for	VRAM
1.7B	`Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign`	Free-form voice descriptions	~6 GB
1.7B	`Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice`	Preset speakers + style instructions	~6 GB
0.6B	`Qwen/Qwen3-TTS-12Hz-0.6B-Base`	Voice cloning from reference audio	~2 GB

The voice design models are particularly clever: you describe the voice you want alongside the text to convert. Want a deep, gravelly voice with a Scottish accent? Or an excited teenager talking about a video game? Just describe it. It’s remarkable that you can run this locally so easily. However, as far as I know there’s no off-the-shelf CLI tool that handles dependencies, downloads the model, and runs inference out of the box.

That’s why I created QwenSay. With it, you can clone the repository and convert text to speech locally from your terminal without wrestling with dependencies or writing any code.

Here’s how it works. First, set it up:

# Clone the repo
git clone ssh://git@codeberg.org/langurmonkey/qwensay.git
cd qwensay

# Default dependencies
uv sync
# For modern RTX cards, use flash attention
uv sync --extra gpu
# For Pascal (GTX 10x0 family), you need a special CUDA version
uv sync --group torch-pascal --no-group torch-default

Now, you are ready to convert your text to speech with Qwen3-TTS:

uv run qwensay.py \
 --text "Good morning! Today is going to be a great day." \
 --instruct "A cheerful, energetic young woman with a clear American accent"

This uses the default 1.7B voice design model. You can also specify the model with --model. There are many other CLI arguments that you can use to tune your output. Check out the repository documentation for more details.

Whether you’re building accessibility features, creating voiceovers for projects, or just experimenting, this is worth a try. I’ve made QwenSay my go-to TTS tool because it produces high-quality results and is genuinely fast.

Fine-tuning Qwen3.5 for Gaia Sky

Toni Sagristà Sellés — Wed, 01 Apr 2026 00:00:00 +0000

A little over a year ago I set up a local pipeline to use different LLMs to respond to Gaia Sky questions using RAG. In that post, I built a dynamic scrapper that parsed the Gaia Sky website and documentation and ingested the content it into a vector database. Then, I built a minimal terminal chatbot interface that received the user prompt, queried the database for semantically similar data, and built up the context for each LLM call. The results were promising, and I found that they (obviously) strongly depended on the model used.

Fast forward a few months, and the Qwen 3.5 models were released by Alibaba. The general consensus is that they are quite good for their size. I’ve been testing them for local inference with a similar impression. I thought that it would be interesting to repeat the exercise of creating a Gaia Sky AI assistant, but using a radically different approach: Instead of RAG, I would fine-tune the model itself. In this post, I describe this fine-tuning project, from the creation and engineering of the training dataset to the fine-tuning and production of the final GGUF models.

This project is composed by two, very distinct parts, which map to top-level chapters in this post:

Training dataset creation
Fine tuning

At the end I quickly evaluate the results in the testing section.

The source code, dataset, and models discussed in this post are in the following repositories:

Dataset creation and fine-tuning - gaiasky-finetune
Gaia Sky training dataset repository - gaiasky-training-dataset
Qwen3.5 Gaia Sky fine-tuned models - gaiasky-qwen-3.5-gguf

Hardware

Here is the hardware I have used to create the dataset and fine-tune the model:

Desktop PC - Arch Linux, Intel(R) Core(TM) i7-7700 (8) @ 4.20 GHz, 32 GB RAM, NVIDIA GeForce GTX 1070 8 GB.
Laptop 1 - Windows 11, WSL2 (Arch Linux), Intel(R) Core(TM) Ultra 9 275HX (24) @ @ 3.07 GHz, 32 GB RAM, NVIDIA GeForce RTX 5080 Mobile 16 GB.
Laptop 2 - Arch Linux, Intel(R) Core(TM) i7 8750H (12) @ 4.10 GHz, 16 GB RAM, NVIDIA GeForce GTX 1060 Mobile 6 GB.

Training dataset creation

The creation of the training dataset is the most important piece of work in this project. It is composed of three parts:

Documentation dataset
API dataset
Identity

Documentation dataset

When I started this project, my first instinct was “more is better.” I thought that if I fed the model every single .java, .glsl, .rst, and .md file in the Gaia Sky repositories (project, documentation, etc.), it would emerge as an expert. Oh boy, was I wrong.

A large codebase contains a lot of boilerplate noise. Getters, setters, license blocks, and infrastructure code that doesn’t actually help a model understand how the engine works or how to write scripts for it. I soon realized that the dataset is the single most important part of the project, and it needed a surgical approach.

The plan was to automate the process of creating the dataset to a degree, and then use it to fine-tune the Qwen 3.5 4B and 8B model variants.

I wrote generate-raw-dataset.py to act as a high-pass filter. Instead of a blind crawl, I implemented an allowlist system. I would only let in the load-bearing files:

Documentation: By far, the most important data, containing exhaustive human-written documentation pages. We convert the documentation RST files to Markdown with pandoc, and then we add some additional key files, like the project’s README.md.
Core Logic: Selected Java files that are representative of the brain of the engine (main loop, scene, renderer, etc.).
Visual Logic: Selected shader files that define the look of the cosmos (stars, particles, PBR, etc.).

Almost every source file in Gaia Sky starts with a copyright header. This is “dead weight” for training. I added a regex-based stripper to ensure the model’s limited context window was filled with code logic, not license text:

def strip_java_copyright(content):
 # Matches the opening /* until the first */ at the start of the file
 content = re.sub(r'^/\*.*?\*/', '', content, count=1, flags=re.DOTALL)
 return content.strip()

The output of this first phase was a jsonl file where each line represented a single, cleaned-up file. It looked like this:

{
 "instruction": "core/src/gaiasky/util/coord/Coordinates.java",
 "output": "public class Coordinates {\n // Implementation of transformation matrices...\n}",
 "source_file": "core/src/gaiasky/util/coord/Coordinates.java"
}

This provided the “Context” for the next phase. However, a model trained directly on this would just learn to autocomplete files. To make it an assistant, we had to turn these files into a conversation.

Once I had a clean extraction of the most relevant information pieces, I faced a new problem. A raw dump of a Coordinates.java file is great for a search engine, but it is not a conversation. To turn these files into training data, I used a “teacher” model, Qwen 3.5 27B, to look at each file and generate a specific number of Q&A pairs. I wrote distill-dataset.py to handle this. The script calculates how many questions a file is worth based on its length and type. A long documentation file might get 25 Q&A pairs, while a short shader might only get 4. Below is an extract of the method that computes the number of target pairs for a file.

def calculate_target_pairs(file_path, content):
 """Determine how many Q&A pairs to generate based on file metadata."""
 filename = file_path.lower()
 content_len = len(content)

 # Skip files that are essentially empty
 if content_len < 150:
 return 0

 # Set a modest base count that depends on type
 # Docs are high-value, so they start slightly higher than code
 if filename.endswith(('.md', '.rst')):
 base_count = 4
 # 1 pair per 750 characters for documentation
 chars_per_pair = 750
 else:
 base_count = 2
 # 1 pair per 1500 characters for source code
 chars_per_pair = 2000

 # Calculate length-based bonus without a tiny cap
 # This scales better for massive files while keeping short files lean
 length_bonus = content_len // chars_per_pair

 # Sum and apply a reasonable maximum
 final_count = base_count + length_bonus

 # Cap it to avoid overwhelming the distillation for single files
 # but ensure even tiny files get at least the base_count
 return max(base_count, min(final_count, 20))

Initially, I used the MoE Qwen 3.5 30B A3B, but it was consistently outputting the wrong format. Then I switched to the 27B dense model, and it performed a little better. Even so, I had to tell the model exactly how to behave. Here are the key items I learned the hard way:

Match the answer type: If the question doesn’t ask for code, don’t provide it.
Grounding: Every claim must be directly grounded on the source text.
Diversity: Every question must cover a different detail.

I also found that, at these model sizes, it is better to batch Q&A pairs instead of asking the model to provide 20 of them in one go. I finally gravitated to 3 Q&A pairs per inference call. To prevent the model from repeating itself across batches, I tracked existing questions and fed them back into the prompt as exclusions.

The prompt is constructed as follows:

# A snippet from the distillation prompt
prompt = (
 f"You are a Gaia Sky technical expert. {file_hint}\n"
 f"Generate exactly {current_target} Q&A pairs strictly based on the source text below. "
 "Every fact and claim in your answers must be directly grounded in the source text. "
 "Never invent API calls or function names not present in the source. "
 "Match the answer type to the question: if no code is asked for, give no code. "
 "HIGHLY DIVERSE Q&A pairs. Every question must cover a COMPLETELY DIFFERENT topic or detail "
 "of the source text than the ones already provided. "
 f"{avoid_context}\n\n"
 "Format the output as JSONL: one JSON object per line, with the question in the "
 "\"instruction\" field and the answer in the \"output\" field. "
 "Output ONLY the JSONL, nothing else.\n\n"
 f"SOURCE FILE: {file_path}\n"
 f"{'=' * 60}\n"
 f"{file_content[:context_limit]}\n"
 f"{'=' * 60}"
)

It consists of the following parts:

Base text - This is composed by the raw strings in the prompt variable.

The file hint ({file_hint}) - We add hints depending on the filetype. The following table displays the hint for each type.

Filetype	Extensions	Hint
Java	`.java`	This is Java source code. Focus on class responsibilities, method signatures, and architectural patterns. Do NOT generate Python scripting examples.
Python	`.py`	This is Python scripting code for the Gaia Sky API. Questions about usage and parameters are appropriate.
Shader	`.glsl`	This is a GLSL shader. Focus on the rendering technique, uniforms, and mathematical operations. Do NOT generate Python scripting examples.
Docs	`.md` `.rst`	This is documentation. Focus on concepts, features, workflows, and user-facing features.

The pair count ({current_target}) - Contains the number of Q&A pairs to generate.

The previous Q&A pairs, if any ({avoid_context}) - This is constructed by listing the existing pairs, as parsed by the program in the output, or accumulated in the current run.

 instr_list = [p['instruction'] for p in existing_pairs]
 avoid_context = (
 "\nDo NOT repeat or rephrase any of these already-covered questions:\n"
 + "\n".join(f"- {instr}" for instr in instr_list)
 )

The filepath and content ({file_path}, {file_content}) - Contain the filename and the actual content, which is capped to fit within the context length.

However, local LLMs tend to be chatty. Even with such strict instructions, larger models like the 27B sometimes also mess up. From time to time, this model would leak its own reasoning into the output. It would start its response with "The user asked to provide 34 Q&A pairs given the source material..." or it would include meta-talk like "This question is safe because it is derived from line 45."

This created dirty data that polluted the dataset and undermined the fine-tuning process. If I trained on this, the final model would start every answer by talking to itself.

To fix this, I built sanitize-jsonl.py. This script is a heavy-duty cleaner that uses regex to strip out training artifacts. It first tries to rescue bad rows, and if it fails, it deletes them. If the model accidentally put both the question and answer in the output field, the sanitizer attempts to detect the question mark and splits them back into the correct structure.

Here is a look at what the data looked like before and after the sanitization process.

Raw distilled entry

{
 "instruction": "I need to generate 3 pairs based on the Gaia Sky API. Here is pair 1:",
 "output": "Question: How do I set the camera position? Answer: Use the gs.setPosition(pos)
 method. I ensured this doesn't repeat previous pairs.",
 "source_file": "APIv1.md"
}

Sanitized “gold” entry

{
 "instruction": "How do I set the camera position?",
 "output": "Use the gs.setPosition(pos) method.",
 "source_file": "api.md"
}

The sanitizer also had to deal with Javadoc remnants. Since Gaia Sky is a Java project, class- and method-level comment blocks are full of HTML tags like <p>, <ul>, and <li> (Javadoc syntax). The script converts these into clean Markdown so the LLM learns a consistent documentation style.

By the end of this process, I had gaiasky-gold.jsonl. This contains a curated, clean list of questions and answers based on the whole project documentation.

API dataset

Documentation is important, but I want the model to learn some Gaia Sky scripting as well. To do so, a new API/scripting dataset needed to be generated. To solve this, I built a synthetic data factory designed to teach the model both the content of the API and the context of how to use it.

The first step was grounding the model. I wrote a script (api-extract.py) that scans the Java source files and uses Regex to pair Javadoc comments with their corresponding method signatures. The extract_from_file() method uses regular expressions and a little bit of logic to generate Q&A pairs based on method signatures and their Javadoc documentation:

Code: Extract API Q&A pairs from a file


def extract_from_file(file_path):
 """Extracts Javadoc blocks and method signatures from a single Java file."""
 if not os.path.exists(file_path):
 print(f"Skipping: {file_path} (not found)")
 return []

 with open(file_path, 'r', encoding='utf-8') as f:
 content = f.read()

 # Regex: Matches Javadoc and the following method signature
 pattern = re.compile(r'/\*\*(.*?)\*/\s+([^;{]+)[;{]', re.DOTALL)

 extracted = []
 for match in pattern.finditer(content):
 doc = match.group(1).strip()
 # Clean Javadoc: remove leading stars and excess whitespace
 doc = "\n".join([line.strip().lstrip('*').strip() for line in doc.split('\n') if line.strip()])

 method_sig = match.group(2).strip()
 # Clean method: remove annotations (like @Override) and newlines
 method_sig = re.sub(r'@\w+(\(.*\))?', '', method_sig)
 method_sig = " ".join(method_sig.split())

 extracted.append({
 "instruction": f"How do I use the {method_sig.split('(')[0]} method in Gaia Sky?",
 "output": f"The method `{method_sig}` is used for: {doc}",
 "source_file": f"API_Reference/{os.path.basename(file_path)}"
 })
 return extracted

This process produces the gaiasky-api-raw.jsonl, which is used in the next step. It contains the API calls with their respective documentation.

However, knowing a function exists isn’t enough. The model needs to know how to script with it. To address this, I developed generate-scripting-dataset.py to transform those raw Java signatures into a diverse pedagogical dataset. As input, it gets all test and showcase scripts in the Gaia Sky repository, and the raw API JSONL file. It produces four types of output, termed A, B, C, and D:

Type A: The API reference

These are direct “How do I use X?” pairs. They include the parameters, the return types, and a basic Python example.
Type B: The task synthesis

This step is optional, and I ended up not including it in the final dataset. However, I think it is still worth mentioning. I used the larger teacher dense model (27B) to generate complex tasks (e.g., “Write a script that navigates to Mars, waits 5 seconds, and takes a screenshot”). The script provided the teacher model with a safe list of real functions extracted in Step 1 as a sort of guardrail. If the teacher tried to hallucinate a command, the script flagged and discarded it.

The results of this section were kind of underwhelming, possibly because more parameters are needed for such open-ended tasks.
Type C: Adversarial error correction

This is my favorite part. I programmatically broke the API calls to teach the model how to fix its own mistakes. The script would generate a wrong script (e.g., using snake_case instead of camelCase or missing a required argument) and then provide the correct version. The end goal was to prevent common LLM failures before they happen.
Type D: The “gold standard” Library

Finally, I indexed the actual test and showcase scripts from the Gaia Sky repository. These are human-written, battle-tested scripts that show the model how to handle complex logic, loops, and math.

Identity

Finally, I prepared a small identity.jsonl file with essential project information that must appear in the final integrated training dataset. It only contains 17 lines of Q&A, but it is rather important. Here is an excerpt of a few lines (formatted for readability):

{
 "instruction": "Which institution is behind Gaia Sky?",
 "output": "Gaia Sky is developed at the Astronomisches Rechen-Institut (ARI),
 which is part of the Zentrum für Astronomie (ZAH) at Heidelberg University.",
 "source_file": "Identity/Project_Meta"
}
{
 "instruction": "Is Gaia Sky part of the ESA Gaia Mission?",
 "output": "Yes, Gaia Sky is developed within the framework of ESA's Gaia mission,
 specifically as part of the German contribution to the Gaia Data Processing
 and Analysis Consortium (DPAC).",
 "source_file": "Identity/Project_Meta"
}
{
 "instruction": "What is the official repository for Gaia Sky?",
 "output": "The official repository is hosted on Codeberg
 at https://codeberg.org/gaiasky/gaiasky.",
 "source_file": "Identity/Project_Meta"
}

The final dataset was composed by concatenating the three parts, documentation, API, and identity. It can be explored here:

gaiasky-training-dataset@HuggingFace.

Once the dataset was ready, it was time for the actual fine-tuning.

Fine-tuning

With a dataset of 3,800+ specialized Gaia Sky pairs ready, it was time for the actual training. For this, I leaned on two heavy hitters in the open-source world: Unsloth and Qwen 3.5. I started by training the 4B model, and then realized that I could also fit the 9B one in my GPU. In the post I’ll focus on the larger version of the model. I went as high as my local hardware allowed. Otherwise, I would have tried the 27B model, or even the 122B-A10B.

Training a model with 9 billion parameters typically requires a massive server cluster, but by using 4-bit LoRA¹, I was able to squeeze the entire process onto a single RTX 5080 (16GB).

The RTX 5080 is a beast, but to get the most out of it, I enabled TensorFloat-32 (TF32). This allows the GPU to handle the heavy matrix multiplications of deep learning much faster than standard float32, without the precision loss of float16.

# blackwell-specific optimizations
torch.backends.cuda.matmul.allow_tf32 = True
torch.backends.cudnn.allow_tf32 = True

I used the following parameters for the fine-tuning:

LoRA Rank: 32

A balance between learning new patterns (like the Gaia Sky API) and retaining general knowledge.
Target Modules: q, k, v, o, gate, up, down

All major projection layers)
BF16: Yes
Learning rate: $2.0\times10^{-4}$
Epochs: 1
Optimizer: AdamW 8-bit

The dataset is downloaded directly from the hub. It gets tokenized properly and passed into the SFT Trainer object for fine-tuning. The full code is in the file finetune.py, and is surprisingly compact. The heavy lifting is done by unsloth and torch, of course.

Once the LoRA weights are trained, they are dead weight until converted into a format people could actually use. I wrote push-model.py to automate the most tedious part of the pipeline:

Quantization: Converting the model to Q4_K_M GGUF, or whatever other quant. This reduces the model size enough that it can run on almost any modern laptop while keeping its capabilities mostly intact.
HF upload: Automatically pushing the finished .gguf file to HuggingFace so the community can pull it directly into LM Studio or Ollama.

After roughly an hour of training, and another one of quantizing and uploading, I had a fine-tuned Gaia Sky expert that performs great. Or did I? The next section discusses the performance of the model.

Testing

Given the limited time I have and the low-parameter models used, my tests have been scarce. My expectations are not very high, but I still wanted to test the output of the fine-tuning and see how well the new knowledge was retained by the model. I only tested the Qwen 3.5 9B fine-tuned variant and compared it to the base model. You can get this model from HuggingFace:

gaiasky-qwen-3.5-gguf@HuggingFace.

I used the same questions as in the Gaia Sky AI assistant post from 2025. My evaluation of the results is totally subjective, and includes a comparison with the base Qwen 3.5 9B.

First, I recommend using a low temperature setting (0.2 in my tests) to avoid hallucinations and make sure the model does not get very “creative”. Also, I would suggest using the following system prompt, which frames the conversation and sets the tone:

You are the Gaia Sky AI Expert, a specialized assistant with deep knowledge of the Gaia Sky universe, its Python API (v1 and v2), and its Java source code. Your goal is to help users explore the cosmos, write scripts, and understand the engine’s inner workings.

Knowledge & Capabilities:

API Expertise: You know both the Legacy API (v1) and the Modern Component API (v2: camera, time, data, scene, graphics, camcorder, etc.). Prioritize the Modern API (v2) for new scripts unless Legacy is requested. Never invent method names, be 100% sure, otherwise suggest the user to look up the docs.
Source Code: You understand the underlying Java architecture (libGDX, Ashley ECS, LWJGL3, OpenGL) and can explain how features like LOD, shaders, and data loaders are implemented.
Documentation: You are familiar with the Gaia Sky capabilities, installation guides, and dataset management.

Behavioral Guidelines:

Be Grounded: If a feature or method does not exist in your training data, do not invent it. State: “I don’t see that specific feature in the current Gaia Sky implementation.”
Code Style: Always provide clean, commented Python or Java code. Use snake_case for Modern API calls.
Tone: Professional, scientific, and enthusiastic about astrovisualization. Answer greetings warmly, then offer Gaia Sky-specific assistance.

That said, let’s go for the first question.

Q: State the possible usages of Gaia Sky.

A: Gaia Sky is a powerful open-source universe explorer and planetarium software designed for both interactive exploration and scientific visualization. Its primary use cases include:

Interactive Exploration: Navigate the Milky Way, explore exoplanets, view the solar system in high detail, and time-travel through cosmic history using an intuitive interface.

Scientific Visualization: Visualize complex astrophysical datasets (catalogs, simulations) with advanced rendering techniques like LOD (Level of Detail), shaders, and particle effects.

Education & Outreach: Create immersive presentations or tutorials to teach astronomy concepts through dynamic 3D models of celestial objects.

Scripting & Automation: Automate camera paths, data loading, and scene manipulation via Python (Modern API v2) or Java for reproducible workflows and research presentations.

Data Analysis: Load and manipulate large-scale astronomical datasets directly within the application to analyze spatial distributions without external tools.

This is an excellent response to an easy question. It did not invent anything and correctly applied documentation knowledge like camera paths or LOD. Compared to base Qwen, which hallucinated a lot, this is much more grounded.

Next is a question about the installation procedure on Linux.

Q: How do I install Gaia Sky on Linux?

A: To install Gaia Sky on Linux, follow these steps:
Download the Installer
Visit https://gaiasky.space/download and download the .deb package for your architecture (e.g., gaiasky_3.6.9_amd64.deb).
Install via Package Manager
Open a terminal and run:
sudo dpkg -i gaiasky_*.deb
If dependency errors occur, fix them with:
sudo apt-get install -f
Launch Gaia Sky
Run the command:
gaiasky
The application will start in your default browser or terminal window.

This is not bad. I did not specify the distribution, so it just assumed Debian. The instructions themselves look fine. Still, I wanted to see if it had absorbed the knowledge for other distros, so I asked specifically for Arch Linux:

Q: How do I install it on Arch Linux specifically?

A: To install Gaia Sky on Arch Linux, you have two primary options depending on whether you prefer the official repositories or building from source:

Option 1: Using the Official AUR (Recommended)

The most straightforward method is via the Arch User Repository (AUR). You will need an AUR helper like yay, paru, or pamac.
Install via AUR Helper: Open your terminal and run:
yay -S gaiasky
# OR using paru
paru -S gaiasky
This will automatically resolve dependencies (Java, OpenGL libraries) and install the application.
Verify Installation: Once installed, launch it with:
gaiasky
Option 2: Building from Source

If you prefer to compile Gaia Sky yourself or need a specific version not yet in the AUR:
Clone the Repository:
git clone https://codeberg.org/gaiasky/gaiasky.git
cd gaiasky
Build and Install: Use Maven to build the project (requires Java Development Kit):
mvn clean package -DskipTests
After building, you can run it directly from the target directory or install it using the provided Gradle wrapper if available in newer versions.
Post-Installation Notes for Arch

Dependencies: Ensure your system has up-to-date OpenGL drivers and Java (JDK 17+ is recommended). The AUR package typically handles these automatically.

Data Location: By default, datasets are stored in ~/.local/share/gaiasky/. You may want to create symbolic links from /opt/gaiasky/data if you prefer system-wide data management.

Additional Notes

Ensure you have at least 4GB of free disk space for datasets and cache files.

For GPU acceleration, verify that your graphics drivers support OpenGL 4.3+.

Very good response. It recommends using the AUR package (correct), and also provides instructions to build and run it from source (also correct). However, it hallucinates the use of Maven instead of Gradle.

The base model produced a long wall of text with mostly nonsense that would look plausible to the non-expert. In general, the responses from the base model were much longer and their content was very often factually wrong.

The next question is a bit more technical.

Q: How are cubemap textures used in Gaia Sky?

A: Cubemaps in Gaia Sky serve a specific purpose related to planetary rendering rather than general environment mapping for the entire scene. They are primarily utilized to generate high-resolution, seamless spherical textures for planets (like Earth or Mars) by stitching together six square faces into a continuous surface. This technique allows for detailed texture representation without the distortion often seen in standard equirectangular projections near poles.

Key Technical Details:

Application: Used specifically for planet textures where high fidelity is required across all latitudes and longitudes.

Structure: Consists of six square images (front, back, left, right, top, bottom) that are algorithmically mapped onto a sphere.

Rendering Engine: The underlying rendering engine uses these cubemap textures to apply surface details dynamically as the planet rotates or changes perspective.

This feature is distinct from standard environment maps used for sky reflections or star glow effects, focusing instead on accurate planetary visualization.

This is excellent, even though it seems to imply that cubemaps are not used for environment maps and reflections, which is incorrect. However, it correctly identifies that they are mainly used to avoid distortions at the poles. Maybe it increased the importance of it because there is an entire documentation section devoted to cubemap textures in planets.

The base model produced a long, Markdown-formatted, pretentious output that even included totally made-up scripts. Again, the fine-tuned response was much more grounded and correct.

Now, onto the scripting questions. Here is where the fine-tuned model starts to hesitate and invent slightly. Here are the possible reasons:

Low parameter count not being able to retain the information properly.
Very low number of test and showcase scripts used in fine-tuning.
Bad design of the training dataset.

I personally think it has more to do with the first two reasons than the third.

Q: How do I get the camera position with the APIv1 and scripting in Gaia Sky?

A: To retrieve the current camera position using the Legacy API (v1), you call getPosition():
from py4j.java_gateway import JavaGateway
gateway = JavaGateway()
gs = gateway.entry_point

pos = gs.getPosition()
print(pos)
Output:
[0.0, 0.0, 0.0]
For the Modern Component API (v2), you use camera.get_position() from the Camera module:
from py4j.java_gateway import JavaGateway
gateway = JavaGateway()
gs = gateway.entry_point

from gaiasky.camera import Camera
cam = Camera(gs)

pos = cam.get_position()
print(pos)
Output:
[0.0, 0.0, 0.0]

First, it invented getPosition() (correct is getCameraPosition()) for APIv1. For APIv2, it correctly used camera.get_position(), but the way it gets the camera object is incorrect. It should have done something like

apiv2 = gateway.entry_point.apiv2
cam = apiv2.camera
pos = cam.get_position()

So, I think either this model is too small to be effectively fine-tuned for Gaia Sky scripting, or the training dataset is insufficient to achieve sufficient retention. Could also be both, as I said above.

The base model has no idea about Gaia Sky scripting or anything related to it, so it just makes stuff up. Not even worth further mention.

Performance

I used the Laptop 2 described above for testing and inference, with 28/32 layers on the GPU and a context window of ~4k, and I consistently got about 12 tok/s. Performance is exactly the same as with the base models, so this section is this short.

Conclusions

This fine-tuning experiment has yielded valuable insights into the strengths and limitations of domain-specific model adaptation at lower parameter counts for local use.

I think the foundational approach was sound. The dataset curation process, with its surgical filtering, teacher-based distillation, and rigorous sanitization, successfully encoded domain knowledge into the model. Proof of this is evident in the testing: the fine-tuned model, as opposed to the base one, correctly answered conceptual and documentation-heavy questions about Gaia Sky’s purpose, installation, and rendering techniques without hallucinating. It understood architectural details like LOD and cubemaps, and avoided inventing features that don’t exist. This demonstrates that fine-tuning can be an effective alternative to RAG for teaching models about a specific domain.

However, it also struggled. The 9B model hit a hard ceiling when it came to API scripting and method names. It invented getPosition() instead of getCameraPosition(), misunderstood how to instantiate APIv2 objects, and generally lacked the capacity to reliably retain the specific, syntactic details of the API surface. This is a classic problem: smaller models can absorb concepts and documentation, but struggle to memorize exact function signatures and usage patterns. With only 3,800+ training pairs and a 9B parameter budget, the model simply didn’t have enough capacity to encode both general knowledge and precise API details.

So, what are the next steps? I believe the 4B and 9B models are too small for reliable Gaia Sky scripting assistance. My next experiment will be to fine-tune the Qwen 3.5 27B model. The jump from 9B to 27B parameters should provide substantially more capacity to encode API signatures without sacrificing general knowledge. Additionally, I could increase the scripting dataset by:

Expanding the test and showcase scripts used in Type D training.
Generating more synthetic scripting examples in Type A (API reference) with better coverage of edge cases and parameter variations.
Adding adversarial examples (Type C) for the most commonly confused API patterns.

That said, the hardware constraint is real. 27B requires more than my RTX 5080 can reasonably handle for full fine-tuning. However, with careful quantization (using 8-bit optimizers or even lower precision), 4-bit LoRA, and possibly gradient checkpointing, it may fit. If not, a cloud provider like Lambda Labs or Paperspace might be the way forward for a single training run.

All in all, I think fine-tuning is a viable path for building domain-expert models, but it requires the right balance of dataset quality, model size, and hardware. For Gaia Sky specifically, a 27B model with a more robust scripting dataset would likely be the sweet spot before considering the jump to 70B+ models. I consider the infrastructure proven. It’s now a matter of scale.

Low-Rank Adaptation is a fine-tuning technique that enables large models to gain additional domain knowledge and adapt to specific tasks with minimal computational and memory overhead. Recommended reading: LoRA: Low-Rank Adaptation of Large Language Models, by E. J. Hu et. al. ↩︎

7Artisans EF-FX adapter review

Toni Sagrista Selles — Tue, 10 Mar 2026 00:00:00 +0000

A while back I reviewed the Viltrox EF-FX1 adapter, my first attempt at bridging my old Canon EF and EF-S lenses over to my Fujifilm X-S10. The abridged version of that experience: it was frustrating. Firmware roulette, random errors, camera freezes requiring battery pulls, and auto focus performance that varied wildly between versions. I kept it because it was just good enough, but it never stopped feeling like a workaround rather than a solution. Moreover, Viltrox never released any further firmware versions, so the 2.29 blob tested in that post really is the last firmware.

The 7Artisans EF-FX lens adapter. It is a good and cheap solution to use your old EF/EF-S lenses on your Fuji X-mount camera.

Fast forward to recently, and I decided to give the whole thing another shot. This time with the 7Artisans EF-FX adapter. Same concept: an electronic adapter with auto focus support, aperture control, and EXIF data transmission, and at 119€ it sits right in the same price bracket as the Viltrox. But is it actually better? Spoiler: yes. Let me walk you through it.

Lenses and body

Same test bench as last time, same lenses, same body — in the interest of a fair comparison:

Body: Fujifilm X-S10
Lenses:
- Canon EF 28-105mm f/3.5-4.5 USM II
- Canon EF 50mm f/1.8 II
- Sigma 10-20mm f/4-5.6 EX DC HSM

Build quality

The adapter feels solid. The frame is all metal and has a reassuringly substantial weight to it. It is not heavy enough to unbalance a lens, but enough to communicate that it is not going to crack if you look at it wrong. Canon lenses mount securely, the Fuji X end clicks into the body with no play whatsoever, and the whole assembly feels like a single unit once locked. There is no wobble, no flex, no creaking.

The Viltrox EF-FX (left) and the 7Artisans EF-FX (right). They look and feel very similar from the outside.

This one also has a Micro-USB port for firmware updates. Why is it using Micro-USB instead of USB-C in 2026? No fu***** idea. It is a bummer. The adapter itself is, however, better built than I expected at this price point.

Auto focus performance

This is where things get interesting, especially if you read the Viltrox review and remember the table of doom I put together there.

With the 7Artisans adapter, I did not need a table. In good lighting conditions, auto focus with all three lenses is fast and reliable. The Canon 50mm f/1.8 II in particular snaps to focus quickly and confidently. The difference compared to the Viltrox (on most firmware versions) is night and day. The 28-105mm, which was the most problematic lens with the Viltrox, also performs well: focus acquisition is smooth and I have not once seen the dreaded “TURN OFF THE CAMERA AND TURN ON AGAIN” message. Not once.

The Viltrox EF-FX (left) and the 7Artisans EF-FX attached to the Canon 50mm f/1.8 II (right). The lens snaps into the adapter in an oddly satisfying way.

The Sigma 10-20mm is similarly well-behaved. At wide angles there is slightly more hunting in ambiguous scenes, but that is expected behaviour for any wide-angle lens and not something I’d pin on the adapter.

The caveat is low light. Drop the ambient light and things become noticeably more hit or miss. The adapter does not handle low-contrast, low-light scenes gracefully; focus will hunt, and sometimes give up altogether, or snap to a comically out-of-focus setting. This is not a dealbreaker for me, but if you shoot a lot of available-light indoor work or night photography with these lenses, temper your expectations accordingly. I know what to expect of these kind of cheap adapters, and this one is enough.

No firmware archaeology required

One of the most annoying aspects of the Viltrox experience was the firmware situation. Digging up old versions, flashing them one by one, and hoping for the best. I am happy to report that with the 7Artisans I simply mounted it and it worked. I updated to the latest firmware once, without incident, and have had no reason to go looking for alternatives. The update process was painless.

Aperture control and EXIF

Both work as expected. Aperture adjusts from the camera body across all three lenses, and EXIF data (focal length, aperture, lens identification) seem to be written correctly to files. Nothing surprising here, but it is worth confirming since these features were also present on the Viltrox. The adapter itself has no controls or buttons other than the lens release lever.

Wrap-up

After the Viltrox experience, I was not sure a third-party EF-to-FX adapter could actually work well. I ordered the 7Artisans off Amazon fully ready to return it if it did not perform. However, it has changed my mind. It is not perfect (low light auto focus is genuinely unreliable), but in normal shooting conditions it is a solid, no-fuss solution that lets me keep using lenses I like on a camera I enjoy shooting with. There are no crashes, no firmware gymnastics, no error messages demanding I restart the camera mid-session.

If you are coming from the Canon ecosystem and moving to Fuji X, and you want to bring your glass with you without spending much native-lens money, the 7Artisans EF-FX adapter is worth a serious look. For me, it is the upgrade the Viltrox never quite managed to be. Moreover, there is a world of old, cheap EF and EF-S lenses in second-hand markets that only get more attractive with time.

GGUF quantization guide

Toni Sagristà Sellés — Wed, 04 Mar 2026 00:00:00 +0000

I like running my own LLMs locally. Open models are becoming more and more powerful, with exciting releases like the latest Qwen 3.5 family scoring highly in benchmarks even in their smaller variants. This makes managing and running your own models more viable, as it becomes increasingly easy to repurpose old hardware for local inference with progressively better results. For local users and modest purposes, the GGUF format introduced by llama.cpp is the de-facto default.

Since local inference is typically heavily restricted by the available hardware, several optimization techniques have been implemented to make the models leaner and faster. Perhaps the most important of these is quantization, which trims down the bit count per parameter to achieve lower memory usage and (sometimes) faster inference¹. The challenge is that there are many different formats and strategies for quantization. In this post, I summarize them, providing a bird’s-eye view on the available techniques, their strengths, and their weaknesses.

Naming conventions

Most GGUF quantization names follow this pattern: Q{bits}{method}{size}

Component	Meaning
`Q`	Quantized format
`2/3/4/5/6/8`	Bits per weight (lower = smaller file, more compression)
`K`	“K-quant”: grouped/blockwise quantization with per-group scales
`I` / `IQ`	“I-quant”: importance-matrix/non-linear quantization for aggressive compression
`0` / `1`	Legacy ungrouped formats (symmetric/asymmetric)
`_S` / `_M` / `_L`	Small/Medium/Large: precision mix across tensor types
`_XS` / `_XXS` / `_NL`	Extra-small / Non-linear variants for I-quants

Unquantized formats

These are base formats with no compression. Usually, but not always, models are trained in these formats.

Format	Bits	Description	Notes
FP32	32-bit float	Full precision, ~26GB for 7B model	Research, debugging
FP16	16-bit float	Half precision, ~13GB for 7B model	GPU training/inference baseline
BF16	16-bit brain float	Same size as FP16, better dynamic range for training	Training on modern GPUs

These preserve maximum accuracy but require significant VRAM. Most local users quantize to reduce size by 75-90%.

Legacy quantization formats (`Q_0`, `Q_1`)

Simple per-block linear quantization. Fast but less accurate at low bits.

Following is a table that contains the format name, number of bits, size (for a 7B model), perplexity, and some notes/recommendations. The perplexity represents the difference between the quantized model and the base model, with lower scores indicating better accuracy and less uncertainty.²

Format	Bits	Size (7B)	Perplexity $\Delta$	Notes
Q8_0	~8-bit	~6.7 GB	+0.0004	Near-lossless; safe INT8 baseline
Q5_1	~5-bit	~4.7 GB	+0.0415	Legacy; superseded by Q5_K_M
Q5_0	~5-bit	~4.3 GB	+0.0796	Legacy; balanced but outdated
Q4_1	~4-bit	~3.9 GB	+0.1846	Legacy; substantial quality loss
Q4_0	~4-bit	~3.5 GB	+0.2499	Legacy; high quality loss

K-quants or I-quants are generally preferred over legacy formats at $\leq 5$ bits. Q8_0 remains useful for compatibility.

K-Quant formats (modern default)

Use two-level block quantization (small blocks $\rightarrow$ super-blocks) with double-quantized scales for better quality-per-bit.

Format	Effective Bits	Size (7B)	Perplexity $\Delta$	Notes
Q6_K	~6.0	~5.15 GB	+0.0044	“Almost lossless” with savings
Q5_K_L	~5.3	~4.6 GB	+0.010	High-quality 5-bit
Q5_K_M	~5.1	~4.45 GB	+0.0142	Recommended high-quality 5-bit
Q5_K_S	~4.9	~4.33 GB	+0.0353	Recommended balanced 5-bit
Q4_K_L	~4.7	~4.0 GB	+0.040	Relaxed 4-bit mix
Q4_K_M	~4.5	~3.80 GB	+0.0535	Most popular default
Q4_K_S	~4.3	~3.56 GB	+0.1149	Smaller 4-bit, more loss
Q3_K_L	~3.5	~3.35 GB	+0.1803	Aggressive 3-bit
Q3_K_M	~3.3	~3.06 GB	+0.2437	Balanced 3-bit
Q3_K_S	~3.1	~2.75 GB	+0.5505	Very small, high loss
Q2_K	~2.5	~2.67 GB	+0.8698	Extreme compression, not recommended

Q4_K_M seems to be the community sweet spot, as it offers $\sim 75\%$ size reduction with minimal noticeable quality loss for most tasks.

I-Quant formats (aggressive compression)

IQs use non-linear reconstruction, lookup tables, and importance-matrix calibration for maximum quality at very low bit counts. They trade decoding speed for size.

Format	Effective Bits	Size (7B)	Notes
IQ4_NL	~4.5	~3.9 GB	Non-linear 4-bit; CPU-friendly speed
IQ4_XS	~4.25	~3.7 GB	Best quality/size at 4-bit; slightly slower decode
IQ3_M	~3.6	~3.2 GB	High-quality 3-bit I-quant
IQ3_S	~3.4	~3.0 GB	Balanced 3-bit aggressive
IQ3_XS	~3.2	~2.8 GB	Very small 3-bit
IQ3_XXS	~3.0	~2.6 GB	Extreme 3-bit compression
IQ2_M	~2.7	~2.4 GB	High-quality 2-bit (rare)
IQ2_S	~2.5	~2.2 GB	Aggressive 2-bit
IQ2_XS	~2.3	~2.0 GB	Very aggressive 2-bit
IQ2_XXS	~2.1	~1.9 GB	Extreme; significant quality loss

I-quants require importance matrix (imatrix) calibration during quantization for best results. Without it, quality can degrade noticeably.

Special formats

There are even more aggressive quantization methods, like ternary quantization, which converts weights to ternary values.³

Format	Bits	Description
TQ1_0	~1.6	Ternary quantization $\{-1, 0, +1\}$, for massive models like DeepSeek where fitting in VRAM is critical

Decision guide

Below I attempt to provide some general rules as to what quant to choose in certain situations.

Best balance overall $\rightarrow$ Q4_K_M
Max quality, still compressed $\rightarrow$ Q5_K_M or Q6_K
Tight VRAM, acceptable quality loss $\rightarrow$ Q4_K_S or IQ4_XS
Max compression $\rightarrow$ IQ3_XS or Q3_K_S $\Delta$ test quality!
Near-lossless accuracy $\rightarrow$ Q8_0 or keep FP16/BF16
CPU inference $\rightarrow$ Q4_K_M or IQ4_NL $\because$ better decode speed
Fit a ~50B model on 16GB VRAM $\rightarrow$ IQ3_S or Q3_K_M $+$ CPU offload

Conclusions

The set of quantization methods available may look like the wild west at first glance, but this mess is not without some order. There are always good reasons behind every quantization type. Here are some takeaways:

Bits $\neq$ quality alone: A well-designed 4-bit format (Q4_K_M, IQ4_XS) can outperform a naive 5-bit legacy format.
Suffixes matter: _M variants selectively keep sensitive layers at higher precision, improving quality with minimal size cost.
Hardware matters: I-quants compress more but decode slower on CPUs; K-quants often give better tokens/sec on consumer hardware.
Calibration helps: Models quantized with an importance matrix (imatrix) retain more accuracy, especially at $\leq 3$ bits.
Test your use case: Perplexity benchmarks are only guides. Always validate outputs for your specific tasks.

For the latest format support and benchmarks, check the llama.cpp repository or community hubs like Hugging Face, where curators like bartowski and Unsloth publish tested GGUF variants.

For an exceptionally good (visual) guide as to how quantization is actually performed, I recommend reading this ngrok blog post: Quantization from the ground up. ↩︎
A good technical explanation of perplexity is in this section of this ngrok post. ↩︎
C. Zhu and S. Han and H. Mao and W. J. Dally. “Trained Ternary Quantization.” arXiv preprint arXiv:1612.01064 (2016). ↩︎

LM Studio on systemd linger

Toni Sagristà Sellés — Fri, 27 Feb 2026 00:00:00 +0000

The release of LM Studio 0.4.5 has introduced a much needed feature in this local LLM suite that has it much more attractive with respect to other similar projects. LM Link allows you to connect multiple LM Studio instances across your network to share models and perform inference seamlessly.

By sheer chance, I was just playing around with setting up an LM Studio server in an old laptop that I planned to use for inference. I would connect AnythingLLM clients to it to make API requests. The timing of 0.4.5 was perfect for me, as I could now use LM Studio for inference directly, and forget about using up my own Tailscale network. But some setup was needed in the laptop. To make this work effectively, the LM Studio server needs to run in the background, start automatically on boot, and persist even when I’m not logged in.

The LM Studio website provides the source of a service file. It suggests creating it as a system-wide service, which is weird, as the default installation method (at least on Linux) sets everything up in the user home directory. I modified it a bit to make things clean, as I want this to be a user systemd service. It keeps the process tied to your user environment but, with a little tweak called lingering, allows it to run without an active SSH or GUI session. Here is the setup.

By default, user services stop the moment the user logs out. To prevent this and allow the LM Studio daemon to start at boot and stay alive, run:

loginctl enable-linger $USERNAME

Then, create a directory for your user services if it doesn’t exist:

mkdir -p ~/.config/systemd/user/

After that, create a file named lms.service in that directory (~/.config/systemd/user/lms.service), with the following contents:

[Unit]
Description=LM Studio Server
After=network.target

[Service]
Type=forking
# This line kills any existing lms processes to prevent the "left-over" error
ExecStartPre=-/home/$USERNAME/.lmstudio/bin/lms daemon down
ExecStartPre=/home/$USERNAME/.lmstudio/bin/lms daemon up
ExecStart=/home/$USERNAME/.lmstudio/bin/lms server start
# Give it a specific PID file if lms supports it, otherwise systemd guesses
ExecStop=/home/$USERNAME/.lmstudio/bin/lms server stop
ExecStopPost=/home/$USERNAME/.lmstudio/bin/lms daemon down

# Ensure systemd doesn't get confused by the CLI exiting
RemainAfterExit=yes

[Install]
WantedBy=default.target

Once the file is saved, tell systemd to reload its configuration and enable the service:

# Reload the user daemon
systemctl --user daemon-reload

# Enable the service to start on boot
systemctl --user enable lms.service

# Start the service now
systemctl --user start lms.service

If you want to load a specific model by default, add an additional ExecStartPre line, like this:

ExecStartPre=/home/YOUR_USERNAME/.lmstudio/bin/lms load openai/gpt-oss-20b --yes

You can check the service status with systemctl --user lms.service. And that is it. You can now use your old hardware for inference with small local LLMs from any of your other machines.

Yet another architectural update for Play Kid

Toni Sagrista Selles — Wed, 28 Jan 2026 00:00:00 +0000

I finished my previous post on Play Kid, only two days ago, with the following words:

Next, I’ll probably think about adding Game Boy Color support, but not before taking some time off from this project.

Yeah, this was a lie.

I have previously written about Play Kid, my Game Boy emulator. Here, I introduced it and talked about the base implementation and the quirks of the Game Boy CPU, PPU, and hardware in general. Here, I explained the tech stack update from SDL2 to Rust-native libraries. In that last post, I mentioned the dependency version hell I unwillingly descended into as a result of adopting pixels as my rendering library. This forced me to stay on very old versions of wgpu and egui.

I want my Game Boy emulator to use the latest crate versions for various reasons, so this could not be. I saw a simple and direct path of update, which consisted on adopting eframe to manage the application life cycle, directly drawing the LCD to a texture, and dropping pixels altogether.

One of the things that nagged me about the pixels crate is that its integration with egui was kind of lackluster. There was no easy way to render the pixels frame buffer to an egui panel, so I had to render it centered inside the window. The immediate mode GUI lived in mostly in Window widgets on top of it. Unfortunately, these windows occluded the Game Boy LCD. In a proper debugger, you must be able to see the entire LCD plus the debug interface.

So I dropped pixels and adopted a render-to-texture approach. In it, you create the LCD texture at the beginning from the egui context, and then copy the LCD contents to it in the update() method.

 fn new(...) -> Self {
 [...]
 // Create texture from egui context and Game Boy LCD width and height.
 let texture = _cc.egui_ctx.load_texture(
 "lcd_screen",
 egui::ColorImage::new(
 [DISPLAY_WIDTH, DISPLAY_HEIGHT],
 vec![egui::Color32::BLACK; DISPLAY_WIDTH * DISPLAY_HEIGHT],
 ),
 egui::TextureOptions::NEAREST,
 );
 // Create app struct.
 Self {...}
 }

 [...]

 fn update(...) {
 [...]

 // Render LCD to texture.
 if frame_ready {
 let size = [DISPLAY_WIDTH, DISPLAY_HEIGHT];
 let color_image =
 egui::ColorImage::from_rgba_unmultiplied(size, &machine.memory.ppu.fb_front);
 self.screen_texture
 .set(color_image, egui::TextureOptions::NEAREST);
 }
 }

With this, we can easily render the texture in egui’s CentralPanel, and the debug interface in a SidePanel to the right. This is the result:

The debug panel, showing the machine state and a code disassembly.

Some additional tweaks here and there, and the UI looks much more polished and professional in version 0.3.0.

Version 0.4.0 enables loading ROM files from the UI. Initially I thought about making the cartridge struct optional with Option<Cartridge>, but this spiraled out of control fast. I found that making the full Machine (which contains the Memory, PPU, APU, Joystick, etc.) optional worked much better, as there was only one reference to it in the top-level struct, PlayKid. And, like so, you can dynamically load ROM files from the UI:

Play Kid with the top menu bar and the ‘Open ROM’ menu entry.

So, what’s in the future for Play Kid? Well, there are a couple of features that I’d really like to add at some point:

Save states—Currently, Play Kid emulates the SRAM by saving and restoring it from files for supported games. I would like to add saving and restoring the full state of the emulator in what is known as save states. Possibly, the serde crate can help with this.
GBC—Of course, I would like adding Game Boy Color support. It is not trivial, but also not exceedingly complicated. I never owned a GBC, so I’d see this as a good opportunity to explore its game catalog.

Game Boy emulator tech stack update

Toni Sagrista Selles — Mon, 26 Jan 2026 00:00:00 +0000

Notice

This post is about Play Kid version 0.2.0, which uses pixels to create and manage the pixel frame buffer. Since then, versions 0.3.0 and 0.4.0 have been released, which dropped pixels in favor of rendering directly to a texture. See this write-up for more information.

In my previous post, I shared the journey of building Play Kid, my Game Boy emulator. At the time, I was using SDL2 to handle the “heavy lifting” of graphics, audio, and input. This was released as v0.1.0. It worked, and it worked well, but it always felt a bit like a “guest” in the Rust ecosystem. SDL2 is a C library at heart, and while the Rust wrappers are good, they bring along some baggage like shared library dependencies and difficult integration with Rust-native UI frameworks.

So I decided to perform a heart transplant on Play Kid. For version v0.2.0 I’ve moved away from SDL2 entirely, replacing it with a stack of modern, native Rust libraries: wgpu, pixels, egui, winit, rodio, and gilrs:

winit & pixels: These handle the windowing and the actual Game Boy frame buffer. pixels allows me to treat the 160x144 LCD as a simple pixel buffer while wgpu handles the hardware-accelerated scaling and aspect ratio correction behind the scenes.
egui: This was a big step-up. Instead of my minimal homegrown UI library from the SDL2 version, I now have access to a full-featured, immediate-mode GUI. This allowed me to build the debugger I had in mind from the beginning.
rodio & gilrs: These replaced SDL2’s audio and controller handling with pure-Rust alternatives that feel much more ergonomic to use alongside the rest of the machine.

Debug panel

The most visible change is the new Debug Panel.

The new integrated debugger features a real-time disassembly view and breakpoint management.

One of the coolest additions is the Code disassembly panel. It decodes the ROM instructions in real-time, highlighting the current PC and allowing me to toggle breakpoints just by clicking on a line. The breakpoints themselves are now managed in a dedicated list, shown in red at the bottom.

The rest of the debug panel shows what we already had: the state of the CPU, the PPU, and the joypad.

Your browser does not support the video tag.

Playing around with the new Play Kid UI based on egui.

Dependency hell

Of course, no modern Rust migration is complete without a descent into dependency hell. This new stack comes with a major catch: pixels is a bit of a picky gatekeeper. Its latest version is 0.15 (January 2025). It is pinned to an older version of wgpu (0.19 vs the current 28.0), and it essentially freezes the rest of the project in a time capsule.

To keep the types compatible, I’m forced to stay on egui 0.26 (current is 0.33) and winit 0.29 (current is 0.30), even though the rest of the ecosystem has moved on to much newer, shinier versions. It’s kind of frustrating. You get the convenience of the pixels buffer, but you pay for it by being locked out of the latest API improvements and features. Navigating these version constraints felt like solving a hostage negotiation between crate maintainers. Not very fun.

Conclusion

Despite the dependency issues, I think the project is now in a much better place. The code is cleaner, the debugger is much better, and it’s easier to ship binaries for Linux, Windows, and macOS via GitHub Actions.

If you’re interested in seeing the new architecture or trying out the new debugger, the code is updated on Codeberg and GitHub.

Next, I’ll probably think about adding Game Boy Color support, but not before taking some time off from this project.

Play Kid

Tue, 20 Jan 2026 00:00:00 +0000

Play Kid is yet another Game Boy emulator, written in Rust. But hey, it is MY Game Boy emulator, and I’m proud of it. I wrote some words about its development here. Find all posts about Play Kid here.

Play Kid running different games with different color palettes.

Here are the main features of Play Kid:

All CPU instructions implemented.
Full memory map implemented.
Modes: ROM, MBC1, MBC2, MBC3.
Audio is implemented, with 4 channels, envelopes, sweep, and stereo.
Supports game controllers.
Multiple color palettes.
Save screenshot of current frame buffer.
FPS counter.
Respects 160:144 aspect ratio by letter-boxing.
Debug panel:
- Step instruction.
- Step scanline.
- Pause/continue current execution.
- Displays internal state of CPU, PPU, and Joypad.
- Full program disassembly, with breakpoints.
Save RAM to .sav files to emulate the battery-backed SRAM. Those are saved every minute.
Working games/roms:
- Passes dmg-acid2
- Tetris
- Pokémon
- Super Mario Land
- Super Mario Land 2: 6 Golden Coins
- Wario Land (Super Mario Land 3)
- Wario Land II
- Bugs Bunny Crazy Castle
- The Amazing Spider-Man
- Dr. Mario
- Probably many, many more
For Linux, macOS, and Windows.

Downloads

You can grab packages for Linux, macOS, and Windows here:

Build

Build the project with cargo build.

Run

The usual Rust stuff.

 cargo run

You can also pass in a ROM file with cargo run -- your-rom.gb.

Make the binary with:

 cargo build --release

Operation

If you don’t pass in any ROM file as an argument, you need to select using the top menu bar, File▶Open ROM….

Here are the Joypad keyboard mappings:

enter - Start button
space - Select button
a - A button
b - B button

The keyboard is clumsy for playing Game Boy games, so you can use any game controller. Controllers are detected when hot-plugged.

Additionally, there are some more actions available:

p - change the palette colors
w - trigger the SRAM save operation to .sav file.
f - toggle FPS monitor
s - save a screenshot, with name screenshot_[time].jpg
d - enter debug mode
Esc - exit the emulator

You can also use the provided UI.

Debug panel

You can open the debug panel any time by pressing d, by clicking on Machine▶Debug panel…, or activate it at launch with the -d/--debug flag. The debug panel shows up in a translucent window. It provides a view of the internal state of the emulator, with:

Current address, instruction, operands, and opcode, to the top.
Internal state of CPU, PPU, and JOYP, to the left.
Disassembly of the program, to the right.
Breakpoints.

The debug panel, showing the machine state and a code disassembly.

You can use the provided UI controls to work with debug mode. You can also use the keyboard. These are the key bindings:

F6 - step a single instruction
F7 - step a scanline
F9 - continue execution until breakpoint (if paused), or pause execution (if running)
r - reset the CPU
d - exit debug mode and go back to normal full-speed emulation
Esc - exit the emulator

You can also use breakpoints. A list with the current breakpoint addresses is provided at the bottom. To create a breakpoint, either click on the address in the disassembly panel, or enter it (in $abcd format) into the text field and click +. Remove a breakpoint by clicking the × in the breakpoints list. Clear all current breakpoints with Clear all.

Your browser does not support the video tag.

Playing around with the Play Kid debug UI.

CLI args

There are some CLI arguments that you can use:

Play Kid 0.4.0
Toni Sagristà - tonisagrista.com
Minimalist Game Boy emulator for the cool kids.
Usage: playkid [OPTIONS] [INPUT]
Arguments:
[INPUT] Path to the input ROM file to load
Options:
-s, --scale <SCALE> Initial window scale. It can also be resized manually [default: 4]
-d, --debug Activate debug mode. Use `d` to stop program at any point
-f, --fps Show FPS counter. Use `f` to toggle on and off
--skipcheck Skip global checksum, header checksum, and logo sequence check
-h, --help Print help
-V, --version Print version

SDL2 version

Play Kid started as an SDL2 application, but it was moved to a pure Rust tech stack using pixels, winit, egui, and rodio. This makes it much easier to build for different targets (including WASM!). Additionally, the SDL2 version contains a minimalist homegrown UI library that I’m particularly proud about, but it can’t hold a candle to egui. It looks like this:

The debug mode.

The SDL2 version is forever tagged playkid-sdl2 (playkid-sdl2@codeberg, playkid-sdl2@github).

Useful links

Pandocs: https://gbdev.io/pandocs/
Complete tech reference: https://gekkio.fi/files/gb-docs/gbctr.pdf
Game Boy CPU manual: http://marc.rawer.de/Gameboy/Docs/GBCPUman.pdf
Game Boy CPU instructions: https://meganesu.github.io/generate-gb-opcodes/

Implementing a Game Boy emulator

Toni Sagristà Sellés — Tue, 20 Jan 2026 00:00:00 +0000

Notice

This post is about Play Kid version 0.1.0, which works with SDL2. Since then, version 0.2.0 has been released. This new version uses Rust native crates like winit, egui, rodio, and pixels. See this write-up for more information on the new version.

When I was a kid my parents got me and my brothers a brand new Game Boy. I used to play it a lot, and I was mesmerized and amazed at how such a tiny brick could give life to so many wonderful worlds. Some of my favorite games were Super Mario Land (1, 2, and 3, Wario Land), The Amazing Spider-Man, and Kirby’s Dream Land. We also had some other games, like Bugs Bunny Crazy Castle or Tetris, that I also played quite a lot. I remember fondly too.

The first Super Mario Land in particular was magical to me. I would complete it, and then do it again in one sitting. There were no save games, as it used MBC1 with no RAM (more on that later). You really had to git gud. The second play through had the same levels but more enemies, in what must have been one of the first implementations of New Game+. After this harder mode was completed, you could select and play any level. Too bad all the progress went away as soon as you powered off the device. Super Mario Land 2: 6 Golden Coins already introduced save games (used MBC1+RAM+Battery). It was a huge step-up in QoL for Game Boy games. We also had the original NES, and later the SNES, but the Game Boy always remained that cozy little fun device that you could just pick up and play for a quick session. It was a significant part of my childhood.

Your browser does not support the video tag.

Me playing Super Mario Land, levels 2 to 4, with my own emulator.

Some time ago, I wrote a CHIP-8 emulator in Rust, and found the experience very rewarding. The consensus online seems to be that the recommended next step, as far as emulator development goes, is the original Game Boy. I know that the internet is flooded with “Implementing a Game Boy emulator” kind of articles, and (judging by the GitHub counts) this is a very unoriginal project, but I still wanted to try my hand at it. So I took the bait and started working on it. Today, I’m excited to share my very own Game Boy emulator.

The original Game Boy, also referred to as DMG in nerdy spaces and released in 1989, is an excellent target for emulation. Its hardware is rather well-documented, its architecture is relatively simple compared to modern systems, yet it’s complex enough to present real challenges, which I for sure faced.

I called my implementation Play Kid. It is written in Rust and uses SDL2 for graphics, sound, and input. Here are the main features:

All CPU instructions implemented.
Full memory map implemented.
Modes: ROM, MBC1, MBC2, MBC3.
Audio is implemented, with 4 channels, envelopes, sweep, and stereo.
Supports game controllers via SDL (also hot-plugging).
Multiple color palettes.
Save screenshot of current frame buffer.
Respects 160:144 aspect ratio by letter-boxing.
Debug mode:
- Step instruction.
- Step scanline.
- Pause/continue current execution.
- FPS counter.
- Displays internal state.
- Breakpoints.
- Uses own minimal UI library with horizontal/vertical layouts, labels, buttons, and text fields.
Save RAM to .sav files to emulate the battery-backed SRAM.
Automatically adapts to multi-DPI setups by scaling the UI.
Working games/roms:
- Passes dmg-acid2
- Tetris
- Pokémon Red
- Super Mario Land
- Super Mario Land 2: 6 Golden Coins
- Super Mario Land 3: Wario Land
- Wario Land II
- Bugs Bunny Crazy Castle
- The Amazing Spider-Man
- Kirby’s Dream Land
- Dr. Mario
- Probably many more
Works on Linux, macOS, and Windows.

In this post, I navigate the general architecture of the Game Boy, emphasize interesting hardware quirks that made it a challenge to emulate properly, and present my implementation. I won’t go into too much detail, as I took care to make the code understandable and well-commented. In any case, for more details on a specific subject, you can refer to the code repository itself.

Foreword

I have based my implementation, mainly, on three resources:

Pan Docs – possibly the best documentation on the Game Boy system out there.
Game Boy CPU Manual – documents the Game Boy architecture in great detail.
Instruction table – all 8-bit opcodes into a single table, complete with descriptions for each one of them. Very handy.

On certain occasions, I found some of the Opcode descriptions to be unclear or a bit ambiguous. In these cases, I referred to actual pre-existing implementations. By far, the implementation I liked the most is RBoy. It is a very compact and mostly uncommented Game Boy Color emulator, written in Rust. Most of the instructions are the same as in the Game Boy DMG, so it worked very well for me.

Game Boy essentials

Before we get into the details, let’s talk a bit about how the Game Boy actually works. Emulation is basically about mimicking hardware in software. We’re not just running Game Boy code, we’re simulating an entire machine cycle by cycle.

The original Nintendo Game Boy. Original by Evan-Amos.

The Game Boy’s execution model is pretty simple. The CPU has a 16-bit PC register that points to the next instruction in memory. Each cycle, it fetches the byte at that address, decodes it into an instruction, executes it, and increments the PC. Instructions are composed of opcode+operand, and can be one, two, or three bytes long. Each instruction takes a specific number of machine cycles (M-cycles) to complete, usually between 1 and 6. Since the CPU runs at around 4.19 MHz (master clock) and one M-cycle equals four clock cycles (T-cycles), timing is important.

The system uses memory-mapped I/O. This means hardware components like the display, audio, and input are accessed by reading and writing to specific memory addresses. Want to check if the A button is pressed? Read from address 0xFF00. Need to start a DMA transfer? Write to 0xFF46. This design makes the architecture simpler, but it also means that memory access can trigger all sorts of side effects, and you need to manage the mapping in your code.

Interrupts let hardware grab the CPU’s attention. When something happens (the display finishing a frame, or a timer overflow), the corresponding interrupt flag is set. If interrupts are enabled (via the IME flag), the CPU pauses what it’s doing, pushes the current PC onto the stack, and jumps to a predefined interrupt handler address. This lets games sync with hardware events instead of constantly checking for them.

The hardware components all move forward together based on the CPU’s cycle count. When the CPU executes a 4 M-cycle instruction, the PPU advances 16 T-cycles worth of scanline rendering, the APU moves its sound generation forward, and timers tick along. Everything runs in lockstep, which means accurate emulation needs cycle-level precision across all the different parts.

Understanding this basic execution model (fetch, decode, execute, repeat, with interrupts and memory-mapped hardware mixed in) is key before getting into the specifics. Each part of the system we’ll look at next works within this framework.

The CPU

The heart of the Game Boy is a modified Intel 8080/Zilog Z80 processor running at approximately 4.19 MHz. Nintendo’s custom chip, sometimes called the SM83 or LR35902, includes most Z80 instructions but removes some and adds a few Game Boy-specific ones.

The CPU features eight 8-bit registers (A, B, C, D, E, F, H, L) that can be paired into four 16-bit registers (AF, BC, DE, HL), plus a 16-bit SP and the aforementioned PC. The F register is special, as its four most significant bits hold flags that track the results of operations:

Zero (Z)
Subtraction (N)
Half-Carry (H)
Carry (C)

In my implementation, the CPU is contained in machine.rs, which contains the main components of the hardware (memory, registers, PPU, APU, etc.), controls the execution state (with debug), and implements the instructions.

/// # Machine
/// The machine contains the registers, the memory, and the display, and
/// controls the execution and CPU state. It also implements the CPU, which
/// decodes and executes instructions.
pub struct Machine<'a, 'b> {
 /// The registers.
 pub registers: Registers,
 /// The main memory.
 pub memory: Memory<'a>,
 /// The display.
 display: Display<'b>,
 /// The UI state.
 ui_state: Rc<RefCell<UIState>>,
 /// Interrupt master enable flag.
 ime: bool,
 /// EI operation is delayed by one instruction, so we use this counter.
 ei: u8,
 /// DI operation is delayed by one instruction, so we use this counter.
 di: u8,
 /// Flag that holds the running status.
 running: bool,
 /// CPU halted.
 halted: bool,
 /// T-states, basic unit of time, and 1:1 with the clock.
 t_cycles: u32,
 /// M-cycles, base unit for CPU instructions, and 1:4 with the clock.
 m_cycles: u32,
 /// The debug manager.
 debug: DebugManager,
 /// Print FPS every second.
 fps: bool,
 /// The event pump.
 event_pump: EventPump,
}

The registers are implemented in a struct, which is trivial:

/// # Registers
/// We have 7 1-bit registers (`a`, `b`, `c`, `d`, `e`, `h`, `l`),
/// which can be accessed individually, or together as 16 bits,
/// in the combinations `af`, `bc`, `de` and `hl`.
/// We also have the flags register, `f`, whose 4 most significant bits are the flags
/// zero `z`, subtraction `n`, half-carry `h` and carry `c`.
/// Additionally, we have two 16-bit special registers, the stack pointer `sp`, and
/// the program counter `pc`.
pub struct Registers {
 pub a: u8,
 pub b: u8,
 pub c: u8,
 pub d: u8,
 pub e: u8,
 /// Flags register.
 /// - Bit 7: `z`, zero flag
 /// - Bit 6: `n`, subtraction flag (BCD)
 /// - Bit 5: `h`, half-carry flag (BCD)
 /// - Bit 4: `c`, carry flag
 pub f: u8,
 pub h: u8,
 pub l: u8,
 /// Stack pointer register.
 pub sp: u16,
 /// Program counter register.
 pub pc: u16,
}

This struct is complented with handy methods to read and write the registers, either individually or as 16-bit combinations. As you can see, the code is very well documented.

The instructions live in an enum, as do their operands. The instructions enum contains the 256 8-bit instructions, and the 256 16-bit instructions prefixed by 0xCB.

/// # Instructions
/// This enum contains all supported instructions.
/// Instructions that can act with both r8 and r16 registers are first named
/// by default in their r8 version. The r16 versions add a `16` at the end of the name.
#[derive(Debug)]
pub enum Instruction {
 // NoOp.
 NOP(),
 // Stop.
 STOP(),
 // Halt.
 HALT(),

 // Jump HL.
 JPHL(),
 // Jump.
 JP(CC),
 // Relative jumps.
 JR(CC),

 // Push.
 PUSH(R16EXT),
 // Pop.
 POP(R16EXT),

 // Load.
 LD(R8),
 LDcp(R8, R8),
 LD16(R16),
 [...]
}

/// Enumerates the r8 registers.
#[derive(Debug)]
pub enum R8 {
 A,
 B,
 C,
 D,
 E,
 H,
 L,
 HL,
}

/// Enumerates the r16 registers.
#[derive(Debug)]
pub enum R16 {
 BC,
 DE,
 HL,
 SP,
}

/// Enumerates r16 registers for POP and PUSH, which contain AF.
#[derive(Debug)]
pub enum R16EXT {
 BC,
 DE,
 HL,
 AF,
}

/// Enumerates the R16 registers to be used in (some) load operations.
#[derive(Debug)]
pub enum R16LD {
 BC,
 DE,
 HLp,
 HLm,
 A8,
 C,
 A16,
}

/// Enumerates jump conditions, mostly flags.
#[derive(Debug)]
pub enum CC {
 NONE,
 NZ,
 Z,
 NC,
 C,
}

/// RST's target address, divided by 8.
#[derive(Debug)]
pub enum TGT3 {
 T0,
 T1,
 T2,
 T3,
 T4,
 T5,
 T6,
 T7,
}

And then, I have a from_byte(byte: u8) method that matches opcodes to their actual enum values:

impl Instruction {
 /// Construct an instruction from its byte representation.
 pub fn from_byte(byte: u8) -> Option<Instruction> {
 match byte {
 // NOP
 0x00 => Some(Instruction::NOP()),
 // STOP
 0x10 => Some(Instruction::STOP()),

 // LD (r16)
 0x01 => Some(Instruction::LD16(R16::BC)),
 0x11 => Some(Instruction::LD16(R16::DE)),
 0x21 => Some(Instruction::LD16(R16::HL)),
 0x31 => Some(Instruction::LD16(R16::SP)),

 [...]

 // Undocumented OPCODE
 _ => {
 println!(
 "{}: Unimplemented instruction {:#02x}, treating as NOP",
 "WARN".yellow(),
 byte
 );
 Some(Instruction::NOP())
 }
 }
 }

I also have a from_byte_0xcb(byte: u8) method used in the actual implementation to decode the 16-bit opcodes.

Actually implementing the CPU meant building a match with cases for ever single one of the 512 instructions. Each instruction updates the PC, manipulates registers or memory, and sets flags according to specific rules. Some instructions were very straightforward to implement; others, like DAA, required careful consideration of edge cases and bit manipulation. The implementation structure is quite straightforward:

 /// Execute a single instruction, and returns the number of cycles it takes.
 fn execute(&mut self, run_instr: RunInstr, opcode: u8) -> u8 {
 // Actually execute the instruction.
 match run_instr.instr {
 // NOP: no operation.
 Instruction::NOP() => 1,
 // STOP
 Instruction::STOP() => {
 self.stop();
 1
 }
 // HALT
 Instruction::HALT() => {
 // HALT only halts if IME is enabled.
 if self.ime {
 self.halt();
 }
 // Otherwise, HALT acts like NOP.
 1
 }

 // LD r16
 Instruction::LD16(r16) => match r16 {
 R16::BC => {
 let nw = self.read16();
 self.registers.set_bc(nw);
 3
 }
 R16::DE => {
 let nw = self.read16();
 self.registers.set_de(nw);
 3
 }
 R16::HL => {
 let nw = self.read16();
 self.registers.set_hl(nw);
 3
 }
 R16::SP => {
 self.registers.sp = self.read16();
 3
 }
 },

 [...]

 // OPCODE 16-bit (0xCB).
 Instruction::OPCODE16() => {
 // Read next byte, construct instruction, execute 0xCB instruction.
 let opcode0xcb = self.read8();
 let instr0xcb = Instruction::from_byte_0xcb(opcode0xcb);
 let msg = format!("Incorrect 0xCB opcode: {:#04X}", opcode0xcb);
 self.execute_0xcb(instr0xcb.expect(&msg), opcode0xcb)
 }

 // Never should happen.
 _ => panic!("Instruction is not implemented: {:#04X}", opcode),
 }
 }

And, of course, there is an analogous execute_0xcb(...) method that contains the implementation for all the 16-bit opcodes.

The CPU doesn’t run in isolation and needs to be cycle-accurate. Each instruction takes a specific number of machine cycles (M-cycles), typically 1-6, and the rest of the system needs to advance accordingly. Getting timing right is quite important, because the graphics hardware, audio, and even some games depend on precise cycle counts. This is why execute(...) -> u8 returns an unsigned integer. This is the number of cycles that the instruction takes. The main loop handles the input events, and then runs as many cycles per frame as necessary.

 while self.running {
 let frame_start_time = std::time::Instant::now();

 // Handle input events.
 self.handle_events();

 let mut cycles_this_frame: usize = 0;
 while cycles_this_frame < constants::CYCLES_PER_FRAME {
 let (t, m) = self.machine_cycle();
 self.m_cycles += m;
 self.t_cycles += t;
 cycles_this_frame += t as usize;

 // Fill the LCD buffer if needed.
 self.display.render_lcd(&mut self.memory);
 }

 // Flush and present the frame.
 self.display.canvas.flush();
 self.display.present();

 frame_count += 1;

 // Sleep for the remaining time in the frame.
 self.sleep_next_frame(frame_start_time);
 }
 }

The machine cycle runs a single CPU cycle. A CPU cycle does the following:

Read next opcode from the memory address pointed by PC
Increment PC
Decode the instruction
Run the instruction – execute(...)
Run a memory cycle
Update the IME and handle interrupts

The code looks like this:

 /// Main loop of the machine.
 fn cycle(&mut self) -> u8 {
 // Fetch next instruction, and parse it.
 let opcode = self.read8();
 let run_instr = RunInstr::new(opcode, &self.memory, &self.registers);

 // Execute the instruction.
 self.execute(run_instr, opcode)
 }

 /// Run a machine cycle.
 fn machine_cycle(&mut self) -> (u32, u32, bool) {
 // CPU instruction.
 // One machine cycle (M-cycle) is 4 clock cycles.
 let mut m_cycles = if self.running {
 if self.halted {
 // CPU is halted, don't execute instructions but still consume 1 M-cycle.
 1
 } else {
 // Run next CPU instruction.
 self.cycle() as u32
 }
 } else {
 // NOOP instruction.
 1
 };
 let mut t_cycles = m_cycles * 4;

 // Memory cycle.
 if m_cycles > 0 {
 // Memory cycle.
 let (_, r) = self.memory.cycle(t_cycles);
 if !r {
 // Close down.
 self.running = false;
 return (0, 0, false);
 }
 } else {
 t_cycles = 0;
 m_cycles = 0;
 }

 // Update IME.
 self.ime_update();

 // Handle interrupts if necessary.
 let interrupt_m_cycles = self.interrupt_handling();

 // Return.
 if interrupt_m_cycles > 0 {
 (interrupt_m_cycles * 4, interrupt_m_cycles, true)
 } else {
 (t_cycles, m_cycles, true)
 }
 }

We’ll talk about the memory cycle when we reach the memory section. For now, let’s look at interrupts, as it was an interesting challenge. The Game Boy supports five interrupt types: V-Blank, LCD STAT, Timer, Serial, and Joypad. The CPU checks for pending interrupts after each instruction, and if interrupts are enabled and one is pending, it pushes the PC onto the stack and jumps to the corresponding interrupt vector. Implementing the IME flag and its one-instruction delay after the EI instruction was a subtle detail that broke several games until I got it right. This is handled in ime_update() and interrupt_handling():

 /// Updates the IME (Interrupt Master Enable) flag.
 /// This is necessary because the effect of the EI and DI instructions
 /// is delayed by one instruction.
 fn ime_update(&mut self) {
 self.di = match self.di {
 2 => 1,
 1 => {
 self.ime = false;
 0
 }
 _ => 0,
 };
 self.ei = match self.ei {
 2 => 1,
 1 => {
 self.ime = true;
 0
 }
 _ => 0,
 };
 }

 /// Interrupt handling. The IF bit corresponding to this interrupt, and the IME flag
 /// are reset by the CUP. IF acknowledges the interrupt, and IME prevents any other
 /// interrupts from being handled until re-enabled (with RETI).
 /// In this case, the corresponding interrupt handler is called by pushing the PC
 /// to the stack, and then setting it to the address of the interrupt handler.
 fn interrupt_handling(&mut self) -> u32 {
 let pending = self.memory.ie & self.memory.iff;

 // Wake from HALT if any interrupt is pending (even if IME is disabled).
 if pending != 0 {
 if self.halted {
 self.halted = false;
 }
 }

 // If no interrupts are pending OR IME is disabled, return.
 if !self.ime || pending == 0 {
 return 0;
 }

 // Reset IME.
 self.ime = false;

 // IE and IF have the following format:
 //
 // | 7 6 5 | 4 | 3 | 2 | 1 | 0 |
 // | 1 | Joypad | Serial | Timer | LCD | VBlank |
 //
 for i in 0..5 {
 let bit = 1 << i;
 if pending & bit != 0 {
 self.memory.iff &= !bit;
 let pc = self.registers.pc;
 self.push_stack(pc);
 self.registers.pc = match bit {
 0x01 => 0x0040,
 0x02 => 0x0048,
 0x04 => 0x0050,
 0x08 => 0x0058,
 0x10 => 0x0060,
 _ => panic!("Unknown interrupt bit {}", bit),
 };
 break;
 }
 }

 5 // 5 M-cycles = 20 T-cycles
 }

Memory

The Game Boy’s 16-bit address space is divided into distinct regions, each serving a specific purpose:

0x0000-0x3FFF: ROM bank 0 (16 KB, fixed)
0x4000-0x7FFF: ROM bank 1-N (16 KB, switchable via MBCs, more on that later)
0x8000-0x9FFF: Video RAM (8 KB)
0xA000-0xBFFF: External RAM (8 KB, cartridge)
0xC000-0xDFFF: Work RAM (8 KB)
0xE000-0xFDFF: Echo RAM (mirror of 0xC000-0xDDFF)
0xFE00-0xFE9F: OAM (sprite data)
0xFF00-0xFF7F: I/O registers
0xFF80-0xFFFE: High RAM (127 bytes)
0xFFFF: IE register

Implementing memory access required a dispatcher that routes reads and writes to the appropriate hardware component. Reading from VRAM accesses the PPU’s memory, writing to 0xFF00-0xFF7F triggers side effects in various subsystems, and accessing cartridge ROM or RAM goes through the mapper.

The memory struct contains the Work RAM, the High RAM, I/O registers, the IF and IE, a reference to the PPU, a reference to the APU, a reference to the cartridge, the timer, and the joypad.

/// # Memory
/// The Game Boy uses a 2-byte address space (0x0000 to 0xFFFF) to map the different
/// types of memory (RAM, VRAM, Cartridge memory, etc.)
pub struct Memory<'a> {
 /// Work RAM.
 pub wram: [u8; constants::WRAM_SIZE],
 // High RAM.
 pub hram: [u8; constants::HRAM_SIZE],
 // I/O registers.
 pub io: [u8; constants::IO_SIZE],
 // IF: interrupt flag.
 pub iff: u8,
 // IE flag: interrupt enable.
 pub ie: u8,
 // Cartridge reference.
 pub cart: &'a mut Cartridge,
 /// The PPU, Picture Processing Unit.
 pub ppu: PPU,
 /// The timer.
 pub timer: Timer,
 /// The joypad.
 pub joypad: Joypad,
 /// The APU, Audio Processing Unit.
 pub apu: APU,
}

The actual mapping is implemented in the read() and write() operations. The address is matched to the specific range in the address space and forwarded to the appropriate component. For instance, the read method:

 /// Read a byte of memory at the given `address`.
 pub fn read8(&self, address: u16) -> u8 {
 match address {
 0x0000..=0x3FFF => {
 // 16kB bank #0 (cartridge).
 self.cart.read(address)
 }
 0x4000..=0x7FFF => {
 // 16kB switchable ROM bank (cartridge).
 self.cart.read(address)
 }
 0x8000..=0x9FFF => {
 // VRAM.
 self.ppu.read(address)
 }
 0xA000..=0xBFFF => {
 // 8kB switchable RAM bank (cartridge).
 self.cart.read_ram(address)
 }
 [...]
 }
 }

Memory-mapped I/O registers control everything from LCD modes to audio channels. Some registers are read-only, some write-only, and some have bits that behave differently on read versus write. The DMA register at 0xFF46 is particularly interesting. Writing to it triggers a transfer of 160 bytes from ROM or RAM to OAM, during which the CPU should only access High RAM. Getting DMA timing correct was essential for sprite-heavy games.

The PPU

The Picture Processing Unit is what puts pixels on the screen. It generates a 160×144 display running at around 60 Hz. Getting it working meant understanding scanlines, timing, and how backgrounds, windows, and sprites all come together.

The PPU works one scanline at a time. Each scanline takes 456 T-cycles (dots), and a full frame has 154 scanlines: 144 visible ones and 10 during V-Blank. While rendering a scanline, the PPU goes through different modes:

Mode 2 (OAM Search): Scanning which sprites will be visible on this scanline (80 dots)
Mode 3 (Pixel Transfer): Actually drawing the pixels (variable, ~172 dots)
Mode 0 (H-Blank): Horizontal blank, waiting for the scanline to finish (~204 dots)
Mode 1 (V-Blank): Vertical blank, screen done rendering (10 scanlines × 456 dots)

During V-Blank, games usually update their state and prepare for the next frame. My implementation transitions between modes based on the current scanline and dot count:

let new_mode = if self.ly >= 144 {
 1 // VBlank.
} else {
 match self.fdot {
 0..=80 => 2, // OAM Scan.
 81..=252 => 3, // Drawing.
 _ => 0, // HBlank.
 }
};

The background is made up of 8x8 pixel tiles stored in VRAM. Each tile uses 2 bits per pixel, giving you four shades of gray (or colors if you apply a palette). There are two tile data areas (at 0x8000 and 0x8800) and two tile maps that tell you which tiles go where. The LCDC register controls which areas to use, and you can think of it as configuring how the PPU interprets the data in VRAM.

Fetching tile data means reading two bytes per tile row and combining them to get the color IDs:

let tile_addr = tile_addr_base + (line * 2);
let low_byte = self.read(tile_addr);
let high_byte = self.read(tile_addr + 1);

let mut pixels = [0u8; 8];
for i in 0..8 {
 let color_id = ((high_byte >> (7 - i)) & 0x1) << 1 | ((low_byte >> (7 - i)) & 0x1);
 pixels[i] = color_id;
}

Windows work similarly to backgrounds but ignore scrolling. They’re positioned absolutely on screen using WX and WY registers. My implementation tracks an internal window line counter (WLY) that only increments when the window actually renders on a scanline, which is important for games that turn the window on and off mid-frame.

Sprites (or objects) are 8x8 or 8x16 pixels that sit on top of the background. The OAM holds up to 40 sprite definitions, each with position, tile index, and attributes like palette selection, flip flags, and priority. The hardware can only show 10 sprites per scanline, and when more than 10 overlap, priority goes to sprites with lower X coordinates first, then lower OAM index:

// Game Boy priority: X asc, then OAM index asc.
sprites.sort_by(|a, b| {
 if a.x != b.x {
 a.x.cmp(&b.x)
 } else {
 a.oam_index.cmp(&b.oam_index)
 }
});

One of the trickier parts was getting sprite priority right. The priority bit in the sprite attributes controls whether a sprite appears above all background pixels or only above background color 0. I store the background color IDs in a separate buffer as I render the background, then check against those values when drawing sprites:

let bg_color_id = self.priorities[self.ly as usize * constants::DISPLAY_WIDTH + x_pos];

let obj_behind_bg = (sprite.attributes & 0x80) != 0;
let sprite_has_priority = if obj_behind_bg {
 // Priority bit set: only draw sprite over BG color 0.
 bg_color_id == 0
} else {
 // Priority bit clear: always draw sprite (over any BG color).
 true
};

This lets me respect the priority rules properly without having to re-read background data.

I cache tile data while rendering each scanline to avoid repeatedly decoding the same tiles. For backgrounds and windows, I cache up to 32 tiles (one row). For sprites, I use a HashMap keyed by tile ID, line number, and flip flags.

The PPU’s timing had to be cycle-accurate. Each frame needs exactly 70224 T-cycles (154 scanlines × 456 dots). The main loop advances the PPU by the number of cycles the CPU just executed, and the PPU updates its mode and LY register (current scanline) accordingly:

pub fn cycle(&mut self, t_cycles: u32) {
 if !self.is_ppu_enabled() {
 return;
 }

 self.fdot += t_cycles;

 // Update mode if it changed.
 if new_mode != self.mode {
 self.update_mode(new_mode);
 }

 // Handle transition to next scanline.
 if self.fdot >= 456 {
 self.fdot -= 456;
 self.ly = (self.ly + 1) % 154;
 }
}

Getting the timing right was kind of important because some games rely on precise V-Blank and H-Blank timing. Otherwise, you get visual glitches, and good luck debugging them.

In order to test my PPU implementation, I turned to the DMG Acid2 test. This is a rather exhaustive PPU test in the form of a ROM. If you see a happy face with HELLO WORLD! above, and dmg-acid2 by Matt Currie below, you’re good. In my case, the right chin was missing. I spent an ginormous amount of time trying to get it to render properly. This is what I was getting:

Oh no, the right chin is missing!

I was so close. The README has an entry that looks exactly like it. The right chin is rendered using the window, and the window tile map, so I kept looking at the window code. It was a pain, and for the life of me, I could not find the issue even though I looked incessantly. In the end, I fed my code to an LLM and it found the error right away: In my read and write VRAM operations, I had WX and WY backwards!

 // This is NOT correct!
 // WY.
 0xFF4A => self.wx,
 // WX.
 0xFF4B => self.wy,

This was frustrating, but it really goes to show what random side effects such a stupid mistake can have.

After countless hours, the stupid bug was mended and Acid2 was good!

Now that my PPU was more or less feature-complete, I tested it with other games. Seeing the first sprite render correctly, or watching the background scroll smoothly in Mario for the first time made it worth it. The PPU is obviously the most (only?) visible part of the emulator, so getting it to a state where it was able to run all the games I wanted to run felt good.

At the very end, when the graphics were already in an excellent shape, I implemented multiple color palettes. The original Game Boy was monochrome, but you can map those four gray shades to any colors you want. IIRC, the Super Game Boy did something similar, and it allowed you to create your own too! I included a few classic palettes (DMG Classic, Pocket, etc.) and some more creative ones. You can cycle through them while playing with p, which makes the games look fresh.

Some of the palettes in Play Kid.

At this point, I could play lots of games, but I had no audio. This had to be mended.

The APU

I consider the Audio Processing Unit (APU) to be one of the most boring parts of this project. It synthesizes sound through four channels: two pulse wave channels (square waves), one wave channel (custom waveform), and one noise channel (pseudo-random). Each channel has its own registers for frequency, volume, envelope, and duty cycle.

The APU is fully synchronized with the CPU and the PPU, and tus runs at 4.19 MHz. This is the master clock that we’ve seen previously. However, the APU doesn’t do everything at 4.19 MHz. Internally, it uses a frame sequencer that divides this master clock down to 512 Hz to manage high-level audio events:

Length Counters: Clocked at 256 Hz (every 2nd step).
Frequency Sweep: Clocked at 128 Hz (every 4th step).
Volume Envelopes: Clocked at 64 Hz (every 8th step).

It steps through eight different phases, some updating length counters, some update the sweep function, and some updating volume envelopes. My implementation tracks this with a frame timer that increments with each T-cycle and runs at 512 Hz (4194304 Hz / 8192 = 512 Hz):

self.frame_timer += t_cycles;
if self.frame_timer >= 8192 {
 // 512Hz is 4.19 Mhz / 8192.
 self.frame_timer -= 8192;

 // Phases from 0 to 7.
 match self.frame_sequencer {
 0 | 2 | 4 | 6 => {
 self.step_length();
 if self.frame_sequencer == 2 || self.frame_sequencer == 6 {
 self.step_sweep();
 }
 }
 7 => {
 self.step_envelope_ch1();
 self.step_envelope_ch2();
 self.step_envelope_ch4();
 }
 _ => {}
 }
 self.frame_sequencer = (self.frame_sequencer + 1) % 8;
}

Each pulse channel (1 and 2) generates square waves with four different duty cycles. The duty cycle controls the waveform shape and is stored as patterns:

let duty_idx = (self.read(0xFF11) >> 6) as usize;
let patterns = [
 [0, 0, 0, 0, 0, 0, 0, 1], // 12.5%
 [1, 0, 0, 0, 0, 0, 0, 1], // 25%
 [1, 0, 0, 0, 0, 1, 1, 1], // 50%
 [0, 1, 1, 1, 1, 1, 1, 0], // 75%
];

let signal = patterns[duty_idx][self.ch1_duty_step];
let volume_multiplier = (self.ch1_volume as f32 / 15.0) * 0.05;

The wave channel (channel 3) is different. It plays back samples from a 32-nibble waveform stored in Wave RAM. Games can write custom waveforms here, which makes this channel super flexible:

// Get 4-bit sample from Wave RAM (32 samples total, 2 per byte).
let byte = self.wave_ram[self.ch3_sample_idx / 2];
let mut sample = if self.ch3_sample_idx % 2 == 0 {
 byte >> 4 // High nibble.
} else {
 byte & 0x0F // Low nibble.
};

// Volume shift based on NR32 register.
sample >>= volume_shift;

The noise channel (channel 4) uses a LFSR to generate pseudo-random noise. The LFSR is a 15-bit shift register that XORs bits 0 and 1, then shifts the result back in:

let bit0 = self.ch4_lfsr & 0x01;
let bit1 = (self.ch4_lfsr >> 1) & 0x01;
let result = bit0 ^ bit1;

self.ch4_lfsr = (self.ch4_lfsr >> 1) | (result << 14);
if (nr43 & 0x08) != 0 {
 // Short mode (7-bit)
 self.ch4_lfsr = (self.ch4_lfsr & !(1 << 6)) | (result << 6);
}

This creates the characteristic noise used for drums, explosions, and other effects.

The sweep function on channel 1 was particularly tricky. It modulates the frequency over time by shifting the current frequency right and either adding or subtracting the result. The overflow check happens both when sweep is triggered and when calculating the new frequency:

fn calculate_sweep_freq(&mut self) -> u16 {
 let nr10 = self.read(0xFF10);
 let sweep_step = nr10 & 0x07;
 let descending = (nr10 & 0x08) != 0;

 let delta = self.ch1_sweep_shadow_freq >> sweep_step;
 let new_freq = if descending {
 self.ch1_sweep_shadow_freq.saturating_sub(delta)
 } else {
 self.ch1_sweep_shadow_freq + delta
 };

 // Overflow check.
 if new_freq > 2047 {
 self.ch1_enabled = false;
 }

 new_freq
}

Getting the timing and overflow behavior right required reading Pan Docs extensively, and I also looked at RBoy’s implementation.

Sound samples are generated at 44100 Hz and mixed into stereo output based on the NR51 register, which controls left/right panning for each channel. SDL2’s audio queue system fit naturally with the APU design. I generate samples as the emulator runs and queue them for SDL to play back:

let (l_sample, r_sample) = self.generate_sample();
self.buffer.push(l_sample);
self.buffer.push(r_sample);

if self.buffer.len() >= 2048 {
 // Throttle if queue is getting too full
 while self.device.size() > 8192 {
 std::thread::sleep(std::time::Duration::from_millis(1));
 }
 self.device.queue_audio(&self.buffer).unwrap();
 self.buffer.clear();
}

Keeping audio and video synchronized without drift required careful management of cycle counts and buffer sizes. The throttling mechanism prevents the emulator from running too fast when the audio queue backs up.

I implemented channel 1 first, and then ran Super Mario Land. I could hear some sounds (jumps, parts of the music), but the experience was underwhelming. Since all channels follow a similar structure, I had channel 2 working in no time. Now I could hear the iconic melody of the first stage, all the jumps, coins, and enemies. I implemented the other channels soon after.

Interestingly, in Super Mario Land, the music is mostly in channels 2 and 3. Channel 1 is for things like jumps, coins, and some high-pitched parts of melodies. Channel 4 is used in the random noise that some enemies produce when they die (like the bomb turtles), and some percussion beats in the background.

I still have no idea whether my APU contains any bugs, or if it sounds exactly as it’s supposed to. I have no way to tell. To my ears, it sounds amazing.

Cartridges

Most Game Boy cartridges aren’t just ROM chips. They contain MBCs that expand the addressable memory beyond the CPU’s 64 KB limit. Different games use different MBCs, each with its own banking scheme.

Every cartridge has a header header that contains essential information about the game, stored in the first few bytes of the cartridge’s ROM. This information helps the system identify and load the game properly. The header includes:

Logo – the first 48 bytes (0x00-0x2F) contain the Nintendo logo, ensuring the authenticity of the cartridge.
Title – the next 16 bytes (0x34-0x43) store the 8-character game title, which is displayed when the game is loaded.
Game Boy/GBC Flag – the byte at 0x143 indicates whether the game is for the original Game Boy (0x00), or a Game Boy Color-compatible game (0x80).
Cartridge Type – the byte at 0x147 specifies the cartridge type, such as ROM-only or with memory banks. Here is a non-exhaustive list of common values:
- 0x00 – ROM only
- 0x01 – MBC1
- 0x02 – MBC1+RAM
- 0x03 – MBC1+RAM+BATTERY
- 0x05 – MBC2
- 0x06 – MBC2+BATTERY
- 0x11 – MBC3
- 0x12 – MBC3+RAM
- 0x13 – MBC3+RAM+BATTERY
ROM Size – the byte at 0x148 specifies the ROM size in powers of 2. For example, 0x00 is 32KB, 0x01 is 64KB, 0x02 is 128KB, etc.
RAM Size – the byte at 0x149 specifies the RAM size in kilobytes. For example, 0x00 means no RAM, 0x03 means 32KB, 0x04 means 128KB, etc.
Destination Code – located at 0x14A, this byte indicates the region the game is intended for. 0x00 is for Japan, 0x01 for Overseas.
Licensee Code – the byte at 0x14B contains a code identifying the licensed company that produced the game.
Mask ROM Version – the byte at 0x14C is the version number of the game’s mask ROM (usually set to 0x00).
Complement Checksum – the byte at 0x14D is used for the checksum calculation to verify the integrity of the ROM data.
Global Checksum – the last 2 bytes (0x14E-0x14F) store a checksum value that ensures the data integrity of the entire ROM.

This header allows the Game Boy to load and display the game properly by checking for compatibility and loading the correct resources for the specified hardware.

When it comes to MBCs, I implemented ROM-only and MBC1/2/3 into Play Kid.

ROM-only

ROM-only cartridges are the simplest, with no banking at all. These are limited to 32 KB and include simple games like Tetris. No mapper logic needed, just direct reads from the ROM data.

Tetris and Dr. Mario use ROM-only cartridges.

MBC1

MBC1 is the most common mapper, supporting up to 2 MB of ROM and 32 KB of RAM. It uses banking to switch between ROM and RAM banks by writing to specific address ranges. Understanding that writes to ROM addresses don’t actually write to ROM but instead configure the mapper took some mental adjustment.

MBC1 has two banking modes controlled by a mode register. In ROM banking mode (mode 0), you get access to more ROM banks but only one RAM bank. In RAM banking mode (mode 1), you can switch between multiple RAM banks but lose access to the upper ROM banks:

pub fn write(&mut self, address: u16, value: u8) {
 match address {
 // RAM enable.
 0x0000..=0x1FFF => {
 self.ram_enabled = (value & 0x0F) == 0x0A;
 }
 // ROM bank number (lower 5 bits).
 0x2000..=0x3FFF => {
 let mut bank = value as usize & 0x1F;
 if bank == 0 {
 bank = 1; // Bank 0 becomes bank 1.
 }
 self.rom_bank = (self.rom_bank & 0x60) | bank;
 }
 // RAM bank or upper ROM bank bits.
 0x4000..=0x5FFF => {
 let bits = value as usize & 0x03;
 if self.banking_mode == 0 {
 self.rom_bank = (bits << 5) | (self.rom_bank & 0x1F);
 } else {
 self.ram_bank = bits;
 }
 }
 // Banking mode select.
 0x6000..=0x7FFF => {
 self.banking_mode = value & 0x01;
 }
 _ => {}
 }
}

Super Mario Land (1 and 2), Wario Land, Kirby’s Dream Land, and The Amazing Spider-Man all use MBC1.

MBC2

MBC2 has a quirky design. It includes 512×4 bits of built-in RAM, and bit 8 of the write address determines whether you’re configuring ROM banking or RAM enable. Both operations share the same address range (0x0000-0x1FFF):

match addr {
 0x0000..=0x1FFF => {
 if (addr >> 8) & 0x01 == 0 {
 // Bit 8 is 0: RAM enable.
 self.ram_enabled = (val & 0x0F) == 0x0A;
 } else {
 // Bit 8 is 1: ROM bank select.
 self.rom_bank = val & 0x0F;
 if self.rom_bank == 0 {
 self.rom_bank = 1;
 }
 }
 }
 // ...
}

Since MBC2’s RAM is only 4 bits per byte, reads return the value OR’d with 0xF0, and writes mask to the lower 4 bits.

I think I have not tested any game that uses MBC2.

MBC3

MBC3 adds a real-time clock (RTC) alongside standard ROM/RAM banking. The RTC includes seconds, minutes, hours, and days counters that can be accessed by setting the RAM bank register to values 0x08-0x0C. I understand that some games use the RTC to track time-based events, but I have not tested this:

pub fn read_ram(&self, address: u16) -> u8 {
 if !self.ram_enabled {
 return 0xFF;
 }

 match self.ram_bank {
 0x00..=0x03 => {
 // Standard RAM banks.
 let offset = (self.ram_bank * 0x2000) + (address as usize - 0xA000);
 self.ram[offset % self.ram.len()]
 }
 0x08 => self.rtc_seconds,
 0x09 => self.rtc_minutes,
 0x0A => self.rtc_hours,
 0x0B => self.rtc_days_low,
 0x0C => self.rtc_days_high,
 _ => 0xFF,
 }
}

The RTC is latched by writing 0 then 1 to address range 0x6000-0x7FFF. This copies the current time into the registers so the game can read a consistent value. My implementation updates the RTC with system time:

fn update_rtc(&mut self) {
 let now = SystemTime::now()
 .duration_since(UNIX_EPOCH)
 .unwrap()
 .as_secs();

 self.rtc_seconds = (now % 60) as u8;
 self.rtc_minutes = ((now / 60) % 60) as u8;
 self.rtc_hours = ((now / 3600) % 24) as u8;

 let days = (now / 86400) as u16;
 self.rtc_days_low = (days & 0xFF) as u8;

 // Day MSB and carry flag.
 let day_msb = ((days >> 8) & 0x01) as u8;
 self.rtc_days_high = (self.rtc_days_high & 0xFE) | day_msb;

 if days > 511 {
 self.rtc_days_high |= 0x80; // Set overflow flag.
 }
}

Pokémon and Wario Land II use MBC3.

Finally, I implemented battery-backed SRAM. It meant saving the contents of cartridge RAM to .sav files when the emulator exits and loading them on startup, if they exist. You can also trigger the save operation at any time with w. I get the RAM from the cartridge, and then persist it (if not empty):

 /// Save SRAM of current cartridge to `.sav` file.
 pub fn save_sram(&self, rom_path: &str) {
 let save_path = Path::new(rom_path).with_extension("sav");

 // Only save if the mapper actually has RAM.
 let ram_data = match &self.cart_type {
 CartridgeType::MBC1(mbc) => &mbc.get_ram(),
 CartridgeType::MBC2(mbc) => &mbc.get_ram(),
 CartridgeType::MBC3(mbc) => &mbc.get_ram(),
 _ => return,
 };

 if !ram_data.is_empty() || matches!(self.cart_type, CartridgeType::MBC2(_)) {
 if let Ok(mut file) = File::create(&save_path) {
 let _ = file.write_all(ram_data);
 println!(
 "{}: Save data written to disk: {}",
 "WR".magenta(),
 save_path.display()
 );
 }
 }
 }

The load operation checks for the file, loads it if it exists, and passes it to each MBC’s set_ram() method.

This feature is essential for saving progress in many games. Currently, the .sav files are written to the same directory where the ROM file is, with the same name and sav extension.

UI and debug mode

In order to help me debug the emulator as development progressed, I implemented a terminal-based debug interface that let me look under the hood and inspect the internal state of the machine. This is implemented in the src/debugcli.rs file in the repository, but it is now unused.

When the emulator was already working quite well, I implemented a GUI debug mode with a custom immediate-mode UI library built on top of SDL2 rendering. You can enable it at any time with d.

The UI library supports horizontal and vertical layouts, labels, buttons, and text fields. Enough to build a useful debug interface without pulling in a fat dependency. It’s minimal but effective. Writing it was not trivial. I knew that UI libraries are complex and take a lot of work to get right, and this little spin-off sub-project only confirmed this knowledge.

Super Mario Land 2 running in Play Kid with the debug UI.

The debug mode features:

Current instruction, operand, and PC
Opcode
CPU status (either RUNNING or HALTED)
M- and T-cycles
CPU registers and flags
PPU state (LCDC, STAT, LYC, LY, LX)
Joypad state for all inputs (U, D, L, R, A, B, START, SELECT)
Breakpoints

You can step through execution one instruction (F6) or one scanline (F7) at a time, pause and continue (F9), and set breakpoints at specific addresses. You can also reset the CPU with r. I also included an FPS counter (f). You can enable and disable the debug mode at any time with d.

One quality-of-life feature I’m proud of is automatic DPI scaling. On high-DPI displays, the UI scales appropriately so everything remains readable without manual configuration. This was a pain to handle manually. The emulator also respects the Game Boy’s 160:144 aspect ratio by letterboxing the display. It’s a small detail, but it ensures games look correct rather than stretched or squashed.

Future work

Here are some items I would like to do at some point:

Move away from SDL2 in favor of Rust-native libraries like winit+pixels+rodio for easy cross-compilation, and web. I actually have a branch where I implemented the APU using rodio
Implement more MBCs if I stumble upon games that need them.
Add Game Boy Color support. As I understand it, it is not too complicated.

Conclusions

Building Play Kid taught me more about computer architecture, bit manipulation, and systems programming than any tutorial could. Every component of the Game Boy (CPU, memory, graphics, audio) works in concert, and understanding their interactions required patience, testing, and a lot of debugging.

Rust was an excellent choice for this project. My CHIP-8 emulator was already written in Rust, so this was a safe choice for me. I think the language has been praised enough at this time, so I’ll spare this part. SDL2 provided a simple, cross-platform foundation for rendering, input, and audio without unnecessary complexity.

If you’re interested in emulation, I think the Game Boy is a solid choice as first project if you have previous programming experience. The documentation is excellent and the hardware is approachable.

Play Kid’s source code is on Codeberg and GitHub.

Google unkills JPEG XL?

Toni Sagrista Selles — Fri, 28 Nov 2025 00:00:00 +0000

I’ve written about JPEG XL in the past. First, I noted Google’s move to kill the format in Chromium in favor of the homegrown and inferior AVIF.¹² Then, I had a deeper look at the format, and visually compared JPEG XL with AVIF on a handful of images.

The latter post started with a quick support test:

“If you are browsing this page around 2023, chances are that your browser supports AVIF but does not support JPEG XL.”

Well, here we are at the end of 2025, and this very sentence still holds true. Unless you are one of the 17% of users using Safari³, or are adventurous enough to use a niche browser like Thorium, LibreWolf or the newer Zen Browser, chances are you see the AVIF banner in green and the JPEG XL image in black/red.

The good news is, this will change soon. In a dramatic turn of events, the Chromium team has reversed its Obsolete tag, and has decided to support the format in Blink (the engine behind Chrome/Chromium/Edge). Given Chrome’s position in the browser market share, I predict the format will become a de factor standard for images in the near future.

Let’s recap

I’ve been following JPEG XL since its experimental support in Blink. What started as a promising feature was quickly axed by the team in a bizarre and ridiculous manner. First, they asked the community for feedback on the format. Then, the community responded very positively. And I don’t only mean a couple of guys in their basement. Meta, Intel, Cloudinary, Adobe, ffmpeg, libvips, Krita, and many more. After that came the infamous comment:

da...@chromium.org da...@chromium.org

#85 Oct 31, 2022 12:34AM

Thank you everyone for your comments and feedback regarding JPEG XL. We will be removing the JPEG XL code and flag from Chromium for the following reasons:

Experimental flags and code should not remain indefinitely

There is not enough interest from the entire ecosystem to continue experimenting with JPEG XL

The new image format does not bring sufficient incremental benefits over existing formats to warrant enabling it by default

By removing the flag and the code in M110, it reduces the maintenance burden and allows us to focus on improving existing formats in Chrome

Yes, right, “not enough interest from the entire ecosystem”. Sure.

Anyway, following this comment, a steady stream of messages pointed out how wrong that was, from all the organizations mentioned above and many more. People were noticing in blog posts, videos, and social media interactions.

Strangely, the following few years have been pretty calm for JPEG XL. However, a few notable events did take place. First, the Firefox team showed interest in a JPEG XL Rust decoder, after describing their stance on the matter as “neutral”. They were concerned about the increased attack surface resulting from including the current 100K+ lines C++ libjxl reference decoder, even though most of those lines are testing code. In any case, they kind of requested a “memory-safe” decoder. This seems to have kick-started the Rust implementation, jxl-rs, from Google Research.

To top it off, a couple of weeks ago, the PDF Association announced their intent to adopt JPEG XL as a preferred image format in their PDF specification. The CTO of the PDF Association, Peter Wyatt, expressed their desire to include JPEG XL as the preferred format for HDR content in PDF files.⁴

Chromium’s new stance

All of this pressure exerted steadily over time made the Chromium team reconsider the format. They tried to kill it in favor of AVIF, but that hasn’t worked out. Rick Byers, on behalf of Chromium, made a comment in the Blink developers Google group about the team welcoming a performant and memory-safe JPEG XL decoder in Chromium. He stated that the change of stance was in light of the positive signs from the community we have exposed above (Safari support, Firefox updating their position, PDF, etc.). Quickly after that, the Chromium issue state was changed from Obsolete to Assigned.

About JPEG XL

This is great news for the format, and I believe it will give it the final push for mass adoption. The format is excellent for all kinds of purposes, and I’ll be adopting it pretty much instantly for this and the Gaia Sky website when support is shipped. Some of the features that make it superior to the competition are:

Lossless re-compression of JPEG images. This means you can re-compress your current JPEG library without losing information and benefit from a ~30% reduction in file size for free. This is a killer feature that no other format has.
Support for wide gamut and HDR.
Support for image sizes of up to 1,073,741,823x1,073,741,824. You won’t run out of image space anytime soon. AVIF is ridiculous in this aspect, capping at 8,193x4,320. WebP goes up to 16K², while the original 1992 JPEG supports 64K².
Maximum of 32 bits per channel. No other format (except for the defunct JPEG 2000) offers this.
Maximum of 4,099 channels. Most other formats support 4 or 5, with the exception of JPEG 2000, which supports 16,384.
JXL is super resilient to generation loss.⁵
JXL supports progressive decoding, which is essential for web delivery, IMO. WebP or HEIC have no such feature. Progressive decoding in AVIF was added a few years back.
Support for animation.
Support for alpha transparency.
Depth map support.

For a full codec feature breakdown, see Battle of the Codecs.

Conclusion

JPEG XL is the future of image formats. It checks all the right boxes, and it checks them well. Support in the overwhelmingly most popular browser engine is probably going to be a crucial stepping stone in the format’s path to stardom. I’m happy that the Chromium team reconsidered their inclusion, but I am sad that it took so long and so much pressure from the community to achieve it.

Motion trails in Gaia Sky

Toni Sagrista Selles — Sat, 14 Jun 2025 00:00:00 +0000

Astronomical scenes, especially those rendered interactively, often feature supraluminal camera motion over immense distances. Sometimes, these motions are rendered by applying trail effects to light-emitting objects to enhance the faster-than-light velocity sensation. Gaia Sky will get an implementation of motion trails in the next version (3.6.9). Motion trails are a visual effect that stretches stars, galaxies, and other light-emitting particles in the direction of the velocity vector of the camera, giving a sense of speed and enhancing the perception of motion through space. This technique is inspired by relativistic visualizations and classic star streak effects, but it is grounded in angular motion rather than raw velocity.

Vertex-based stretching of stars in supraluminal travel in Gaia Sky.

In this post, I describe the technical details that made implementing a performant, vertex-based solution into Gaia Sky possible.

Traditional approach

The typical way to render such an effect is through a post-processing motion blur pass, especially common in game engines and cinematic visualizations. The process is roughly the following:

Separate Render Targets — stars, particles, or other emissive elements are rendered to dedicated framebuffers (with color and velocity).
Velocity Buffers — each rendered object encodes its screen-space motion vector based on differences between current and previous frame transforms.
Post-Processing Blur Shader — a fullscreen pixel shader smears pixels along their velocity vector, creating blur or streaks. This can be implemented with linear sampling or more advanced temporal accumulation techniques.

This method applies uniformly to all rendered elements, works in screen space, typically using a pixel shader, and reuses the pre-existing motion blur infrastructure in engines. However, it requires additional render targets and history buffers, it is almost impossible to control and isolate per-object, and it does not handle transparencies or additive blending correctly. What can we do about it?

Our approach

In Gaia Sky, the effect is instead implemented directly in the vertex shader. Each object is a quad billboard oriented toward the camera. Trails are computed procedurally based on the screen-space velocity of the objects (difference in projected position over time steps), the stretch direction based on camera motion, and a distance-based fade-out.

This technique is simpler and has some nice bonuses:

It avoids history buffers or post-processing passes.
It is fully compatible with additive blending and transparency.
It scales well with hundreds of thousands of objects.
It is tunable based on distance, screen velocity, and apparent motion.

In short, this vertex-based approach integrates the effect tightly into Gaia Sky’s real-time astronomical renderer, improving performance, visual clarity, and configurability.

The shader

The code lives in the snippet that computes the billboard rotation, i.e., the part of the code that orients the quad to the camera to make it a billboard. This snippet uses the following inputs:

s_vert_pos: vec4 — vertex position.
s_obj_pos: vec3 — object position w.r.t. camera.
s_proj_view: mat4 — camera view-projection matrix.
s_size: float — quad size.
u_camUp: vec3 — world-space camera up vector.
u_camVel: vec3 — world-space camera velocity.
u_dt: float — delta time in seconds between frames.
u_uToMpc: float — conversion factor from internal units to Mpc.

The shader chunk computes the final vertex position and puts it into gpos: vec4. In the next subsections I break down the shader parts and explain each one separately.

0. Initial orientation

Here we just compute the orientation base of the quad/billboard, taking as reference the vector from the camera to the center of the object (s_obj_pos).

 s_obj = normalize(s_obj_pos);
 s_right = normalize(cross(u_camUp, s_obj));
 s_up = normalize(cross(s_obj, s_right));

1. Rotation and velocity projection

The quad is oriented toward the camera using a rotation quaternion. We then rotate the camera velocity into the quad’s local space to determine stretch direction.

vec4 s_quat = q_look_at(s_obj, s_up);
vec4 s_quat_inv = q_conj(s_quat);
vec3 local_pos = s_vert_pos.xyz;
vec3 centered_pos = local_pos;
vec3 local_cam_vel = qrot(s_quat_inv, u_camVel);

2. Estimate screen-space movement

We simulate where the object would be next frame by offsetting it by the camera velocity u_camVel using the frame time u_dt. This gives a screen-space motion estimate in NDC (Normalized Device Coordinates). Note the division by the $w$ component of clip coordinates, needed to convert to NDC.

vec3 obj_world = s_obj_pos;
vec3 obj_next = obj_world - u_camVel * u_dt;

vec4 clip_now = s_proj_view * vec4(obj_world, 1.0);
vec4 clip_next = s_proj_view * vec4(obj_next, 1.0);

vec2 ndc_now = clip_now.xy / clip_now.w;
vec2 ndc_next = clip_next.xy / clip_next.w;
float screenVel = length(ndc_now - ndc_next);

3. Calculate trail stretch amount

The stretch magnitude is driven by the screen-space velocity screenVel, shaped using a nonlinear power function and clamped. The actual parameters need to be tuned to every scene.

vec3 stretch_dir = normalize(vec2(local_cam_vel.x, local_cam_vel.y).xyx);
float stretch = pow(screenVel * 450.0, 2.0);
stretch = clamp(stretch, 0.0, 6.0);

4. Distance-based fadeout

To avoid unnecessary GPU load from distant galaxies (which barely move visually), the effect fades out smoothly between 30 and 50 Mpc. This only ever affects very distant, high-z galaxies due to the distances involved in the thresholds.

// Object distance in Mpc
float distMpc = length(s_obj_pos) * u_uToMpc;
float fade = smoothstep(50.0, 30.0, distMpc);
stretch *= fade;

5. Apply trail effect

Directionally stretch the quad along the motion vector. Brightness is adjusted to maintain consistent visual intensity. Otherwise, the stars appear brighter as they are stretched, which is bad.

if (screenVel < 0.0001 || fade < 0.01) {
 stretch = 0.0;
} else {
 // Stretch around center position
 float taper = dot(stretch_dir, centered_pos);
 centered_pos += stretch * taper * stretch_dir;

 float brightnessScale = 2.0 / (1.0 + stretch);
 v_col.rgb *= clamp(brightnessScale, 0.0, 1.0);
}

6. Final assembly

We recenter, scale, rotate back to world space, and project to clip space.

local_pos = centered_pos * s_size;
vec3 world_pos = s_obj_pos + qrot(s_quat, local_pos);
// Final vertex position
gpos = s_proj_view * vec4(world_pos, 1.0);

Results

You have already seen the image at the top of this post. But an image without motion is frankly unimpressive. You can see a video of the effect in this Bluesky post:

#GaiaSky will get a star streaks shader in the next release. This effect elongates stars in the direction of motion to create a sort of Star Trek travel effect. Of course, this can be turned off in the settings.

[image or embed]
— Gaia Sky (@gaiasky.bsky.social) Jun 16, 2025 at 15:26

Conclusion

This vertex-based trail method avoids the cost and complexity of traditional post-processing while remaining physically intuitive and performant. This represents an ideal fit for real-time astronomical rendering, and for Gaia Sky in particular.

Some improvements to consider for the future could be:

Potential support for color or spectral shifts (red/blue) based on velocity and stretch.
Adaptive fall-off curves could optimize performance.
A GPU culling pass could eliminate distant objects entirely.

Quadruple joins the fight!

Toni Sagrista Selles — Sat, 10 May 2025 00:00:00 +0000

A few days ago I wrote about benchmarking arbitrary precision floating-point libraries in Java. I found out that BigDecimal is not as slow as it is said to be, beating Apfloat at the same precision level by a long margin in most operations. However, for Gaia Sky, I don’t need hundreds of significant digits at all. It turns out 27 significant digits are enough to represent the whole universe with a precision of 1 meter.

The observable universe has a radius of about $4.4 \times 10^{26}$ meters. To express the entire range down to 1 meter, we need to calculate the number of significant digits $d$ as follows:

$$ \begin{align} d &= \log_{10} \left(\frac{R}{\text{precision}}\right) \\ \\ &= \log_{10} \left(\frac{4.4 \times 10^{26}}{1}\right) \\ \\ &= \log_{10}(4.4 \times 10^{26}) \\ \\ &= \log_{10}(4.4) + \log_{10}(10^{26}) \\ \\ \approx 0.643 + 26 &= 26.643 \end{align} $$

In terms of bits, IEEE 754 double precision (64-bit) provides around 15–17 decimal digits of precision, which is enough for the Solar System, but insufficient for the whole universe. In contrast, IEEE 754 quadruple precision (128-bit) provides around 34 decimal digits of precision, which is in fact more than enough. It uses 113 bits of significand precision, $log_{10}(2^{113}) \approx 34$ digits. The range of values we can precisely represent in the universe is $\approx \frac{4.4 \times 10^{26}}{10^{34}} = 4.4 \times 10^{-8}$ meters. This is 4.4 nanometers! As said, this is more than sufficient for our purposes.

Enter Quadruple

Browsing through GitHub I found the Quadruple library, which provides an implementation of 128-bit floating point numbers in Java. The implementation is very compact, and includes addition, subtraction, multiplication, division, and square root. I decided to put it to the test using my JMH benchmark.

I created a new benchmark called “ThreeWay”, which tests these operations (plus allocation) for Apfloat, BigDecimal, and Quadruple. In the arbitrary precision library I’m using only 32 significant digits of precision instead of 34. I do 1 set of 1 second as warm-up, and 5 iterations of 5 seconds for the measurement (see source).

Results

Below are the specs of the system I used to run the tests, and the specific software versions used. This time around I ran the benchmarks in my laptop while it was plugged in. Only the CPU and the memory should play a significant role.

# JMH version: 1.37
# VM version: JDK 21.0.7, OpenJDK 64-Bit Server VM, 21.0.7+6
CPU: Intel(R) Core(TM) i7-8550U (8) @ 4.00 GHz
GPU 1: NVIDIA GeForce GTX 1070 [Discrete]
GPU: Intel UHD Graphics 620 @ 1.15 GHz [Integrated]
Memory: 16.00 GiB
Swap: 8.00 GiB

And here are the benchmark results.

Addition

Three-way Addition results – Interactive view

Of course, Quadruple is compact and only needs to care about 128 bits, while Apfloat and BigDecimal are generic to any precision, so we can expect Quadruple to be faster. And it is.

Subtraction

Three-way Subtraction results – Interactive view

Same with subtraction.

Multiplication

Three-way Multiplication results – Interactive view

And multiplication.

Division

Three-way Division results – Interactive view

Division is also faster with the newcomer.

Allocation (from string)

Finally, the allocation test. First, we test allocation from a string representation of a floating point number.

Three-way Allocation results (from string) – Interactive view

Surprising. Let’s analyze this. We use JOL to find out the instance size of each object.

Quadruple has an instance size of 40 bytes (2 longs, 1 int, 1 boolean, plus header).
BigDecimal has an instance size of also 40 bytes (2 ints, 1 long, 2 references to BigInteger and String, plus header).
Apfloat has an instance size of 24 (3 references plus the object header).

It is unlikely that the issue is the instance size. It most definitely comes down to the code to convert the string into the internal representation of each type. This code seems to be much slower for Quardruple than it is for the others. Let’s see how it fares allocating from a double.

Allocation (from double)

Three-way Allocation results (from double) – Interactive view

The story is reversed. Quadruple is much faster than the others when allocating an object from a double. I never allocate from strings, so this is not that bad actually.

Analysis

There’s not much to say. Quadruple is obviously much faster in a very significant way than the others. This is, of course, to be expected if we consider that Quadruple only deals with float-128 types and does not have to care about higher precisions. It may be enough for your purposes, like it is for mine. If this is the case, it may make sense to use it.

Caveats

There are a couple of important caveats to consider if you want to use Quadruple as it is now:

Only the basic operations are implemented (add, sub, div, mul, sqrt). If you need anything else, you are on your own.
Quadruple instances are mutable. This is a bad design decision in my opinion, and would bar it from adopting further improvements that will land soon to Java like value types (project Valhalla).
Instantiation from String is very slow.

Benchmarking arbitrary precision libraries in Java

Toni Sagrista Selles — Wed, 07 May 2025 00:00:00 +0000

Edit (2025-05-08): Changed some test parameters and re-run the tests. Also added bar plots.

Note: I have since written a new blog which includes Quadruple to the benchmarks, beating both Apfloat and BigDecimal consistently.

I recently set out to compare the performance of Apfloat and BigDecimal for arbitrary precision arithmetic in Java. I use arbitrary precision floating point numbers in key places of the update cycle in Gaia Sky, so it made sense to explore this. My initial approach was a naive benchmark: a simple main() method running arithmetic operations in a loop and measuring the time taken. The results were strongly in favor of BigDecimal, even for large precision values. This was unexpected, as the general consensus I found online suggested that Apfloat is more performant, especially for higher precision operations (hundreds of digits).

To get more accurate and reliable measurements, I decided to implement a proper JMH benchmark. The benchmark project source is available in this repository. The benchmarks test addition, subtraction, multiplication, division, power, natural logarithm, and sine for both Apfloat and BigDecimal at different precision levels.

Why JMH?

JMH is a benchmarking framework specifically designed for measuring performance in Java applications. It is developed by the OpenJDK team and provides a robust methodology for generating reliable and reproducible benchmark results by accounting for JVM warm-up, runtime optimizations, and other factors that can skew measurements. Given the surprising results in the naive implementation, using JMH allowed me to get more accurate measurements and mitigate potential inaccuracies caused by JVM behavior.

The Benchmark Implementation

The JMH benchmark project is structured to measure the average time taken for each arithmetic operation over several iterations and precision levels. Here’s the structure:

Separate benchmarks for addition, subtraction, multiplication, division, natural logarithm, power, and sine, additionally to an allocation test.
Each benchmark tests Apfloat and BigDecimal.
Create the actual objects at benchmark level to factor out allocation costs. Specific benchmark to test allocation overhead.
Settled on four precision levels, on a scale ranging from low and high precision settings, represented as the number of digits. They are 25, 50, 500, and 1000 digits.
Average time mode.
Every benchmark function only runs one operation once. The allocation test creates a couple of objects and consumes them.
One warm-up iterations of one second each to minimize JVM effects (@Warmup(iterations = 1, time = 1)).
Three main iterations of five seconds each for the measurement (@Measurement(iterations = 3, time = 5)).
Send results into Blackhole to prevent JIT optimizations.

Here is an example for the Sin benchmark:

Code: benchmark implementation

The Results

Below are the specs of the system I used to run the tests and the specific software versions used. Only the CPU and the memory should play a significant role.

# JMH version: 1.37
# VM version: JDK 21.0.7, OpenJDK 64-Bit Server VM, 21.0.7+6
CPU: Intel(R) Core(TM) i7-7700 (8) @ 4.20 GHz
GPU 1: NVIDIA GeForce GTX 1070 [Discrete]
GPU 2: Intel HD Graphics 630 [Integrated]
Memory: 32.00 GiB
Swap: 8.00 GiB

And here are the benchmark results.

Addition

Addition results – Interactive view

We already see that BigDecimal is much faster in all precisions. It is not even close.

Subtraction

Subtraction results – Interactive view

In the subtraction benchmark BigDecimal comes out on top as well.

Multiplication

Multiplication results – Interactive view

The same story repeats for multiplication.

Division

Division results – Interactive view

Again. Division is a notoriously costly operation, but BigDecimal still comes out comfortably on top.

Now, let’s test some more involved arithmetic operations, like the natural logarithm, the sine, and the power function. In Apfloat, those are directly implemented in the library. For BigDecimal, we use the big-math project.

Log

Log results – Interactive view

The logarithm is faster with Apfloat at the higher precision settings, but it BigDecimal still wins in the lower precisions.

Sin

Sin results – Interactive view

The sine is much faster in BigDecimal in all precision settings.

Pow

Pow results – Interactive view

And finally, the power repeats the same story, with BigDecimal sitting comfortably on the throne again.

Allocation

For science, I thought it would be cool to test the allocation overhead, so I prepared the Allocation test, which allocates two instances of either Apfloat or BigDecimal and consumes them.

Allocation results – Interactive view

We see that allocation is very costly in both libraries. However, while Apfloat seems to be roughly constant with the precision, BigDecimal shows a higher cost with 25 digits, the lowest precision setting. I though this was very sus, so I re-ran the test a bunch of times and with more iterations and longer times, and got back the same result. I’m not sure what’s the root cause for this, but it is surprising and intriguing.

Since both Apfloat and BigDecimal are immutable, allocation costs need to be factored in. New objects need to be allocated every time new operands are needed.

Analysis

Contrary to expectations, BigDecimal consistently outperformed Apfloat across all operations and precision levels, including the higher precisions (500 and 1000 digits) where Apfloat was expected to excel. There is a single case when Apfloat is faster, and that is in the high precision natural logarithm benchmark. I think it’s safe to say that this is due to the particular implementation or algorithm being used. Otherwise, the disparity is particularly noticeable in division and sine operations, where Apfloat is significantly slower than BigDecimal. Specifically, BigDecimal was several times faster than Apfloat in most operations and precisions. Those are, in my opinion, significant results.

Finally, allocation seems to be faster with Apfloat, and there’s a weird dependency on the precision for BigDecimal which I found strange.

Questions and Next Steps

I was genuinely surprised by the outcome of these benchmarks, as it contradicts the general consensus regarding Apfloat’s supposed performance advantage in high-precision arithmetic. I am reaching out to the community to validate my methodology and results. Are these findings trustworthy, or did I overlook something crucial in my benchmarking approach? Feedback and insights are very much welcome.

Oh Garmin, not you!

Toni Sagrista Selles — Sat, 29 Mar 2025 00:00:00 +0000

I’ve been a Garmin user for many years, shelling out non-trivial amounts of monies for their sports watches. My first Garmin watch was a Forerunner 10 (black/red). Battery life was abysmal, but back then this was the norm. Today, I’m sporting a Forerunner 255, which I love. It’s not top-of-the-line, but it is more than enough for my modest purposes. These devices have been my trusty companions on countless runs, football matches, and hikes, providing invaluable data without any hidden costs. But now, Garmin has decided to introduce Garmin Connect+, a subscription service priced at €8.99 per month or €89.99 annually. Really, Garmin?

My Garmin Forerunner 255.

This past Thursday, March 27th, Garmin announced a premium plan called Garmin Connect+ in a press release titled “Elevate your health and fitness goals with Garmin Connect+”. This new service promises AI-powered insights through their “Active Intelligence” feature, offering personalized suggestions based on health and activity data. Additionally, it includes a performance dashboard with custom charts, enhanced LiveTrack features, and exclusive app badges. I don’t care for any of that, but these additions may sound appealing to some. I can’t help but feel a sense of déjà vu. Initially, companies introduce new features behind a paywall, assuring users that existing functionalities remain free. But as revenue targets loom, there’s a creeping tendency to lock previously free features behind that same paywall, degrading the user experience. This gradual decline, often referred to as enshittification, has plagued many platforms.

Garmin’s move mirrors trends seen with other fitness platforms like Strava, which have also introduced subscription models for premium features. While it’s understandable that publicly traded companies seek additional revenue streams, it’s disheartening when it comes at the expense of loyal users who have already invested heavily in their products. The general feeling of their customers is clear. You just need to look around the Garmin subreddit, or the Garmin Subscription Model megathread specifically, to know what I’m talking about.

Of course, as these things usually go, Garmin assures us that all existing features will remain free and that Connect+ merely adds new functionalities. I don’t buy it. Forgive me for being skeptical. We’ve seen this play out before, and it often doesn’t end well for the consumer.

Garmin watches are already a significant investment. Introducing a subscription model feels like a cash grab, especially when the features offered seem like they could be standard inclusions. It’s a slippery slope, and I fear we’re at the top, ready to slide down. I hope Garmin proves me wrong and maintains the integrity of its free offerings. But history suggests otherwise, and I can’t help but brace for the inevitable enshittification of a platform I once held in high regard.

One thing is clear to me. My next sports watch will not be a Garmin watch. This move has annihilated my trust in the company. I’ve started researching other options, and I have found Polar and Suunto, both based in Europe, to be excellent alternatives.

Langur Monkey - Toni Sagristà Sellés

Local agentic workflows are getting crazy good

Local TTS is getting very capable and accessible

Fine-tuning Qwen3.5 for Gaia Sky

Hardware

Training dataset creation

Documentation dataset

Raw distilled entry

Sanitized “gold” entry

API dataset

Identity

Fine-tuning

Testing

Knowledge & Capabilities:

Behavioral Guidelines:

Option 1: Using the Official AUR (Recommended)

Option 2: Building from Source

Post-Installation Notes for Arch

Additional Notes

Performance

Conclusions

7Artisans EF-FX adapter review

The 7Artisans EF-FX lens adapter. It is a good and cheap solution to use your old EF/EF-S lenses on your Fuji X-mount camera.

Lenses and body

Build quality

The Viltrox EF-FX (left) and the 7Artisans EF-FX (right). They look and feel very similar from the outside.

Auto focus performance

The Viltrox EF-FX (left) and the 7Artisans EF-FX attached to the Canon 50mm f/1.8 II (right). The lens snaps into the adapter in an oddly satisfying way.

No firmware archaeology required

Aperture control and EXIF

Wrap-up

GGUF quantization guide

Naming conventions

Unquantized formats

Legacy quantization formats (Q*_0, Q*_1)

K-Quant formats (modern default)

I-Quant formats (aggressive compression)

Special formats

Decision guide

Conclusions

LM Studio on systemd linger

Yet another architectural update for Play Kid

The debug panel, showing the machine state and a code disassembly.

Play Kid with the top menu bar and the ‘Open ROM’ menu entry.

Game Boy emulator tech stack update

Debug panel

The new integrated debugger features a real-time disassembly view and breakpoint management.

Playing around with the new Play Kid UI based on egui.

Dependency hell

Conclusion

Play Kid

Play Kid running different games with different color palettes.

Downloads

Build

Run

Operation

Debug panel

The debug panel, showing the machine state and a code disassembly.

Playing around with the Play Kid debug UI.

CLI args

SDL2 version

The debug mode.

Useful links

Implementing a Game Boy emulator

Me playing Super Mario Land, levels 2 to 4, with my own emulator.

Foreword

Game Boy essentials

The CPU

Memory

The PPU

The APU

Cartridges

UI and debug mode

Future work

Conclusions

Google *unkills* JPEG XL?

Let’s recap

Chromium’s new stance

About JPEG XL

Conclusion

Legacy quantization formats (`Q_0`, `Q_1`)

Google unkills JPEG XL?