Build your own NES Emulator... with Kotlin

Artur Skowroński
Build your own NES Emulator... with Kotlin
Let Fools Dream

Artur Skowronski
Head of Java / Kotlin Development

We will focus mostly on SMB today

I always loved video game mechanics

JDK 1.8
No build system
Applets
Tangled code…

Why still to do that
NES Architecture
Why writing emulator is interesting (and hard as hell)
What are the interesting aspects of doing that in Kotlin

Intel 8080
A popular CPU featured in
the Altair, the
fi
rst “personal’”
computer.
It has an 8-bit data bus
and a 16-bit address bus.
Motorola 6800
Another 8-bit CPU designed by
Motorola, it contains a
completely different instruction
set.
Many do-it-yourself computer
kits, synthesisers and all-in-one
computers included the 6800.
MOS 6502
A redesigned version of 6800.
While incompatible,
the new chip was much
less expensive to produce and
iconic computer makers
(Commodore, Apple, Atari)
chose the 6502.
Ricoh 6502
Nintendo needed something
inexpensive but familiar to
develop for, so they selected the
6502.
Ricoh, their CPU supplier,
successfully produced a 6502-
compatible CPU
1974 1974 1975 1983

In 1985, NES CPU was ~10
YO Design

What 8-bit means?
• “Bitness” historically refers to word width — that is, how many bits the
processor fetches from RAM and processes in a single instruction. If
registers are 8-bit (as in the 6502 / Ricoh 2A03), we call it an 8-bit
machine — regardless of other specs.
• Beyond the technical meaning, “8-bit” today also refers to the video
game era of the 1980s — NES, Commodore 64, Atari 800, and the like.
• The visual style from that era is often called “8-bit art.
• It has 8-bit registers, which means that the numbers it operates on
range from 0 to 255 (2⁸ = 256 values).
• It uses a 16-bit address bus, which allows it to address up to 65,536
bytes of memory (64 KB).
00 77 10

Pulse Pulse
Sample
Triangle Noise

WRAM (CPU work RAM) – the
processor’s notepad: it stores life
counts, player position, scores, and so
on.

VRAM is the PPU’s on-the-
fl
y drawing sheet:
32 × 30 grid of 960 tile indices and its 64-
byte attribute table together constitute data
the PPU reads to determine which tile and
palette appear in every screen cell.

Picture Processing Unit
PRG-ROM (Program Rom) CHR-ROM (Character Rom)
WRAM
Through PPU I/O

Now it’s time for true black magic - Cartidges

Most modern Cartidges are just memory cards

NES cartidge is a minicomputer

Cartidge
PRG-ROM
CHR-ROM
Mappers

Mappers
Mapper
Transparent
Address Space
Mapper
WRAM
PRG-ROM (Program Rom)
Bank Switching
Bank 1 Bank 2 Bank 3
Through PPU I/O

Cartidge
PRG-ROM
CHR-ROM
Mappers
• Rather than the cartridge containing only the
game program, it has a separate set of address and
data lines that connect directly to the PPU,
containing its graphics and tiles.
• Game cartridges can provide the RAM, if that’s
needed.
• They were really expensive to make
• There were also special Mappers for Sound

Why writing emulator is interesting (and hard as hell)

Fun Fact #1 - There is no color palette in NES

“Super Mario Bros”
fi
rst level Google Search
5990F5
9DA8F8 6888F8
8E8CF8
5990F4
949FCF

There is no color palette in NES 🤷

RGBA
Digital

RGBA
Digital
Radio Frequency!
Analog

Frames per second NTSC/PAL
One cable (yellow RCA), where the
luminance (Y) and color (C) signals
were mixed together.

The NES didn’t have a true combined RGB palette like modern
devices. Its PPU generated colors from 16 brightness levels ×
12 hues, giving a theoretical total of 192 combinations.
However, NES features a
fi
xed palette of 64 colors, each
assigned a unique index ranging from 0x00 to 0x3F. These
indices are stored in the PPU palette memory and are used by
games to reference speci
fi
c colors when rendering
backgrounds and sprites.

There are particular set of pallets “agreed”
https://www.nesdev.org/wiki/PPU_palettes

fun loadPalette(file: String): Boolean {
try {
if (file.lowercase().endsWith("pal")) {
val fStr = javaClass.classLoader.getResourceAsStream(file)
val tmp = ByteArray(64 * 3)
var n = 0
while (n < 64) {
n += fStr!!.read(tmp, n, tmp.size - n)
}
val tmpi = IntArray(64 * 3)
for (i in tmp.indices) {
tmpi[i] = tmp[i].toInt() and 0xFF
}
for (i in 0 until 64) {
val r = tmpi[i * 3 + 0]
val g = tmpi[i * 3 + 1]
val b = tmpi[i * 3 + 2]
origTable[i] = r or (g shl 8) or (b shl 16)
}
} else {

val hsl = RGBtoHSL(emphTable[currentEmph][i])
var h = getHue(hsl) + hueAdd
var s = (getSaturation(hsl) * (1.0 + saturationAdd / 256f)).toInt()
var l = getLightness(hsl)
r = 128 + lightnessAdd + ((r - 128) * (1.0 + contrastAddValue / 256f)).toInt()
g = 128 + lightnessAdd + ((g - 128) * (1.0 + contrastAddValue / 256f)).toInt()
b = 128 + lightnessAdd + ((b - 128) * (1.0 + contrastAddValue / 256f)).toInt()
colorTable[0] = getRgb(124, 124, 124)
(…) /// All 64 (or 52…) needs to be mapped.

Fun Fact #2 - Emulating “mappers” is the worst

May you live in interesting times

Remember when we talk about mappers
Mapper
Transparent
Address Space
Mapper
WRAM
PRG-ROM (Program Rom)
Bank Switching
Bank 1 Bank 2 Bank 3
Through PPU I/O

Cartidge
PRG-ROM
CHR-ROM
Mappers
There was A LOT OF different
mappers 🥶

Each need to be emulated… separately

Mappers are tightly coupled with everything
sealed class MapperDefault(nes: NES) : MemoryMapper {
var cpuMem: Memory
var ppuMem: Memory
var cpuMemArray: ShortArray
var rom: ROMData? = null
var cpu: CPU?
var ppu: PPU
var papu: PAPU
var cpuMemSize: Int
var joy1StrobeState: Int = 0
var joypadLastWrite: Int
var mousePressed: Boolean = false
init {
this.cpuMem = nes.cpuMemory
this.cpuMemArray = cpuMem.mem
this.ppuMem = nes.ppuMemory
this.cpu = nes.cpu
this.ppu = nes.ppu
this.papu = nes.papu
this.inputHandler = nes.gui!!.getJoy1()
this.inputHandler2 = nes.gui!!.getJoy2()
cpuMemSize = cpuMem.memSize
joypadLastWrite = -1
}
Mapper Class needs to have access
to the whole NES, it is coupled with
every potential hardware

sealed class MapperDefault(nes: NES) : MemoryMapper {
var cpuMem: Memory
var ppuMem: Memory
var cpuMemArray: ShortArray
var rom: ROMData? = null
var cpu: CPU?
var ppu: PPU
var papu: PAPU
var cpuMemSize: Int
var joypadLastWrite: Int
var mousePressed: Boolean = false
init {
this.cpuMem = nes.cpuMemory
this.cpuMemArray = cpuMem.mem
this.ppuMem = nes.ppuMemory
this.cpu = nes.cpu
this.ppu = nes.ppu
this.papu = nes.papu
this.inputHandler = nes.gui!!.getJoy1()
this.inputHandler2 = nes.gui!!.getJoy2()
cpuMemSize = cpuMem.memSize
joypadLastWrite = -1
}
Sealed Classes are lifesaver - a lot of
when operations involved

iNES standard
val mapperType: Int = ((header[6].toInt() and 0xF0) shr 4) or (header[7].toInt() and 0xF0)
• It's short for "interleaved NES" or simply "NES emulator standard" — a format invented by
Marat Fayzullin in the 1990s when he developed the early emulator iNES.
• Every .nes
fi
le in iNES format starts with a 16-byte header, followed by the actual game
data
• It tells the emulator:
• how much code (PRG-ROM) and graphics (CHR-ROM) is in the
fi
le
• which mapper to use
• what mirroring and battery-save features are expected

class MapperTable {
companion object {
/** Human-readable names for iNES/NES 2.0 mapper numbers 0-254. */
val mapperName: Array<String>
/** Whether a given mapper is implemented by this emulator. */
val mapperSupported: BooleanArray
init {
mapperName = Array(255) { "Unknown Mapper" }
mapperSupported = BooleanArray(255)
mapperName[ 0] = "NROM"
mapperName[ 1] = "Nintendo MMC1"
mapperName[ 2] = "UxROM"
mapperName[ 3] = "CNROM"
mapperName[ 4] = "Nintendo MMC3"
// …and so on
mapperSupported[0] = true // NROM
mapperSupported[1] = true // MMC1
mapperSupported[2] = true // UxROM
mapperSupported[3] = true // CNROM
mapperSupported[4] = true // MMC3
// …and so on
}
}
}
Compatibility grows with amount of
mappers implemented

fun regLoad(address: Int): Short {
when (address shr 12) {
0 -> {}
1 -> {}
2 -> {
run {}
run {
when (address and 0x7) {
0x0 -> {
// 0x2000:
// PPU Control Register 1.
// (the value is stored both
// in main memory and in the
// PPU as flags)
return cpuMem.mem[0x2000]
}
0x1 -> {
// 0x2001:
// PPU Control Register 2.
// (the value is stored both
// in main memory and in the
// PPU as flags)
return cpuMem.mem[0x2001]
}
0x2 -> {
// 0x2002:
// PPU Status Register.
// The value is stored in
// main memory in addition
// to as flags in the PPU.
// (not in the real NES)
return ppu!!.readStatusRegister()
}
You need to manually map particular
registers, deciding what will be
returned to emulator

Just the basic mapper
SMB is using basic mapper 😮💨

Fun Fact #3 - Emulation of Sound is the the worst

Kanał Co go wyróżnia? „Haczyki” dla emulatora
Pulse1 /
Pulse2
4
‑
pozycyjna tabela wypełnienia (duty) + sprzętowe
obwiednie i sweep
Glitch z „zawinięciem” sweep
‑
a, z którego korzysta np.
Mega Man 2
Triangle Generuje tylko 32
‑
krokową falę schodkową
Brak głośności ≠ cisza (kanał ciągle „gra”, co wpływa na
miks)
Noise LFSR 15bit i tryb krótszy 7bit
Losowy bit jest generowany co 2CPU
‑
cykle – trzeba to
dokładnie tra
fi
ć
DMC Odtwarza 1
‑
bitowe próbki z RAM
‑
u przez DMA
DMA „kradnie” cykle CPU— wrażliwe na kolejność
instrukcji w grach
Frame Counter (240 Hz NTSC) zamyka jedną „ramkę audio” na każde cztery ramki obrazu (60 Hz)
„odpala” wszystkie obwiednie i sweep
‑
y. Gdy emulator nie liczy takt w takt, narastania/zaniki grają
o ułamek sekundy za wcześnie lub za późno.

fun writeReg(address: Int, value: Short) {
if (address in 0x4000..0x4013) {
val channel = registry!!.getChannel(address)
channel?.writeReg(address, value)
} else if (address == 0x4015) {
// Enable/disable APU channels
updateChannelEnable(value.toInt())
dmc!!.writeReg(address, value) // updating DMC
}
}
APU registers are mapped to the
memory address space $4000–$4017,
which the 6502 CPU normally uses to
communicate with other devices and
RAM.
As a result, every game can write to
the APU as if it were regular memory
- the emulator must replicate this
behavior 1:1, even if some interactions
are undocumented.

if (dmc!!.isEnabled) {
dmc!!.shiftCounter -= (nCycles shl 3)
while (dmc!!.shiftCounter <= 0 && dmc!!.dmaFrequency > 0) {
dmc!!.shiftCounter += dmc!!.dmaFrequency
cpu.stallCycle(CPU.IRQ_NORMAL)
}
}
class CPU() {
private var stallCycles = 0
fun tick() {
if (stallCycles > 0) {
stallCycles--
return // CPU wait
}
val opcode = bus.read(PC++)
executeOpcode(opcode)
}
fun stallCycle() {
stallCycles++
}
}
DMC is a special APU channel that
autonomously loads samples from
memory - but at the cost of CPU
cycles!
This fragment simulates the
moments when DMC "steals" the bus
on a real NES, the CPU simply has to
wait.
In an emulator, delays in code
execution must be faithfully
reproduced to ensure the sound
behaves like it did on the original
hardware.

In NES, everything is coupled with everything

Writing everything from scratch due
to “speci
fi
cation”
kNES is a reimplementation and
extension of the vNES emulator
(originally developed by Brian F. R.) in
Kotlin

Fun Fact #4 - Save States are super easy to implement

val cpuMemory: Memory = Memory(0x10000) // WRAM Main memory (internal to CPU)
Memory is simply an object to be serialized.
Save state implementation is essentially an elegant
System.arraycopy()and ByteBuffer copy wrapped in
some I/O - just stream the emulator’s memory into a
buffer.

ByteBuffer base, passing through all the components
fun stateLoad(buf: ByteBuffer): Boolean {
var continueEmulation = false
val success: Boolean
if (cpu.isRunning) {
continueEmulation = true
stopEmulation()
}
if (buf.readByte().toInt() == 1) {
cpuMemory.stateLoad(buf)
ppuMemory.stateLoad(buf)
sprMemory.stateLoad(buf)
cpu.stateLoad(buf)
memoryMapper?.stateLoad(buf)
ppu.stateLoad(buf)
success = true
} else {
success = false
}
if (continueEmulation) {
startEmulation()
}
return success
}
fun stateSave(buf: ByteBuffer) {
val continueEmulation = this.isRunning
stopEmulation()
// A marker for the beginning of state data
buf.putByte(1.toShort())
cpuMemory.stateSave(buf)
ppuMemory.stateSave(buf)
sprMemory.stateSave(buf)
cpu.stateSave(buf)
memoryMapper?.stateSave(buf)
ppu.stateSave(buf)
// Continue emulation:
if (continueEmulation) {
startEmulation()
}
}

fun startEmulation() {
if (Globals.enableSound && !papu.isRunning) {
papu.start()
}
if (isRomLoaded && !cpu.isRunning) {
cpu.beginExecution()
isRunning = true
}
}
fun stopEmulation() {
if (cpu.isRunning) {
cpu.endExecution()
isRunning = false
}
if (Globals.enableSound && papu.isRunning) {
papu.stop()
}
}
• Stopping emulation before saving ensures
coherent, atomic, and restorable state without
corruption or inconsistency like.
• Capturing part of the state before a CPU
instruction executes
• Capturing another part after a PPU change
• Saving values mid-update (e.g. halfway through
a frame render or sound buffer push)
• This leads to an inconsistent snapshot - and when
you restore it later, the emulator might crash, hang,
or behave incorrectly.

Task Challenge Dif
fi
culty
Savestate
Serialization of a few
dozen kilobytes on demand.
🟢 Trivial
Audio
‑
APU
Calculating waves
1755k × 60 = 100 million samples
per second
+ analog mixing
+ errors
🔴 Hard

Fun Fact #5 - There are particular test ROMs you can use

https://www.nesdev.org/wiki/Emulator_tests
Fun Fact #5 - There are particular test ROMs you can use

Kotlin Compose - Picking the proper UI Stack

Picking the UI technology
@Composable
fun NESScreenRenderer(screenView: ComposeScreenView) {
var frameCount by remember { mutableStateOf(0) }
var currentBitmap by remember { mutableStateOf(screenView.getFrameBitmap()) }
val baseScale = screenView.getScale()
val isMacOS = System.getProperty("os.name").toLowerCase().contains("mac")
val scale = if (isMacOS) baseScale * 2 else baseScale
val scaledWidth = 256 * baseScale
val scaledHeight = 240 * baseScale
DisposableEffect(Unit) {
screenView.onFrameReady = {
currentBitmap = screenView.getFrameBitmap()
frameCount++
}
onDispose {
screenView.onFrameReady = null
}
}
Canvas(
modifier = Modifier
.width(scaledWidth.dp)
.height(scaledHeight.dp)
) {
drawImage(
image = currentBitmap,
dstSize = IntSize(scaledWidth, scaledHeight)
)
}
}
•Original version I forked
from was apples based
•Compose was good solution
for Kotlin, albeit rendering
images every frame was
slow

Picking the UI technology
fun getFrameBitmap(): Bitmap {
frameCounter++
// Log some color information for debugging
if (frameCounter % 60L == 0L) { // Log once per second at 60fps
println("[DEBUG] First few pixels in buffer: " +
"${Integer.toHexString(buffer[0])}, " +
"${Integer.toHexString(buffer[1])}, " +
"${Integer.toHexString(buffer[2])}")
}
// Create a Skiko Bitmap
val bitmap = Bitmap()
val imageInfo = ImageInfo(width, height, ColorType.RGBA_8888, ColorAlphaType.UNPREMUL)
bitmap.allocPixels(imageInfo)
// Set the pixel data directly from the buffer
// We need to ensure alpha channel is set for each pixel
val pixelsWithAlpha = IntArray(buffer.size)
for (i in buffer.indices) {
pixelsWithAlpha[i] = buffer[i] or 0xFF000000.toInt()
}
// Convert IntArray to ByteArray for installPixels
val byteBuffer = ByteBuffer.allocate(pixelsWithAlpha.size * 4)
.order(ByteOrder.nativeOrder())
val intBuffer = byteBuffer.asIntBuffer()
intBuffer.put(pixelsWithAlpha)
bitmap.installPixels(imageInfo, byteBuffer.array(), width * 4)
return bitmap
}
•That’s why I decided to
create Skiko version
•Skiko is a Kotlin
Multiplatform graphics
library developed by
JetBrains.
•It provides a cross-platform
wrapper around Skia, the
same powerful 2D graphics
engine used in Google
Chrome, Flutter, and
Android.

Is it Kotlin Multiplatform…? Not yet

How useful was AI in the process?

For Code Migration - Junie is really great, apart being quite slow

For Solving Bugs? Effectively useless

For Solving Bugs? Effectively useless
He was doing a lot of stupid, brute force stuff
* Synchronizing everything with everything
* Adding indirections
* Changing UI Logic
* Adding manual ticking
* Drawing sample images to check if we can render anything
And trying same solution… multiple times

Build your own NES Emulator... with Kotlin

Build your own NES Emulator... with Kotlin

More Related Content

Similar to Build your own NES Emulator... with Kotlin

More from Artur Skowroński

Recently uploaded

Build your own NES Emulator... with Kotlin