tiny blog

Reading JourneyMap's chunk cache

Casey — Tue, 22 Sep 2026 00:00:00 +0000

Unfinished article

Why even..

I've been mapping out one Minecraft server hosted by some YTber that primarily plays on beta-like modpacks.

That server was obviously themed like one as well, with some restrictions on what mods clients are allowed to use. Most notably, no "meta-gaming", even though ruleset doesn't necessarily explain that:

------------------[ 1 / 2 ]------------------
No cheating!
No major/consistent griefing! (lava casts, base destruction, etc.)
No consistent stealing! (stealing from players chests regularly)
Beefing is allowed if the third side is not included
                      Next >>
---------------------------------------------
------------------[ 2 / 2 ]------------------
Occasional theft is allowed
Occasional/light griefing is allowed (breaking torches, doors, paintings, armor stands)
Red nickname - controlled griefer group, yellow - controlled cheater group
<< Back
---------------------------------------------

I guess "No cheating!" kinda counts as meta-gaming, even though it's pretty vague.

What it means is that you're really not supposed to use minimaps or any other external tools to assist your gameplay. Yes, even JEI/EMI/etc fall under that.

Anyways, after installing mod hider and adding JourneyMap (as well as some other definitely allowed mods) to the hidden list and mapping a huge area, we get this:

Screenshot of the web map I wrote a bit after

You could probably notice a suspiciously circular area except it's not mapped out fully. That was my attempt at stream-sniping the admin and mapping out his area. The reason it's not fully mapped is that after this, he decided to inflict withering and slowness to everyone inside that circle. Lame!

I basically gave up playing on it after that, but there are some people that still use my minimap and send me updated region screenshots!

With latest update I also noticed new files alongside regular PNGs: chunk_cache.

`*.jmc`

chunk_cache is per-dimension folder that contains chunk cache in JMs proprietary file format. Chunk cache files are grouped into regions, the same way it works in regular Minecraft.

Unlike regular regions, .jmc files don't store NBT data and seem to only care about block data (with variants), as well as light levels. Basically, most of things you'd need to render a map from scratch.

.jmc files (from now on I'm gonna call them by their header magic: JMCA) are even structured the same way as regular region files: header contains offsets and sizes of each chunks' data. JMCA header also includes region position (which is absent in McRegion files), as well as a couple unused fields which might see a light in the future (I sure hope not, I don't want to make any changes to my reader, especially with backwards compatibility). Unlike McRegion, chunks in JMCA are not "page"¹-aligned, which saves a bit on space. JMCA also only supports zLib compression^{[citation needed]}

In short, JMCA header can be represented as this C struct:

struct __attribute__((__packed__)) JMCA_Header {
    char magic[4]; // 'J', 'M', 'C', 'A'
    uint8_t unused1[2];
    int16_t region_x;
    int16_t region_z;
    uint8_t unused2[6];
    int32_t offsets[32 * 32];
    int32_t lengths[32 * 32];
};

All numbers are network(big)-endian.

Chunks' data can be accessed by seek()ing to its offsets[cx + cz * 32] and read()ing lengths[cx + cz * 32] bytes, and then inflating it with zLib.

Each chunk could be thought as a separate file with a separate magic and stuff.

`JMCS`

Each chunks' data starts with JMCS magic value, format and sections information, followed by sections data. Again, structured similarly to McRegion chunks, except chunks are not stored as NBT this time. In fact, I don't think there's any NBT in .jmc files at all!

struct __attribute__((__packed__)) JMCS_Header {
    char magic[4]; // 'J', 'M', 'C', 'S'
    uint8_t version; // Only 3 and 4 are present at the moment of writing this
    int32_t min_section;
    int32_t min_build_height;
    int32_t max_build_height;
    uint8_t section_count; // No. of sections actually stored in the file
};

Number of sections is derived from *_build_height: (max_build_height - min_build_height) >> 4. Note that this is not "how many sections are stored in the file", but how many sections there could be in each chunk. You should only read section_count sections. This value is used to reject sections that are outside of buildable range.

Header is followed by sections data that can't be represented by a C struct, but I'll try anyways!

struct JMCS_Section {
    uint8_t section; // Actual value is min_section + section
    int32_t palette_size;
    struct JMCS_Palette_Entry {
        UTF_String name;
        uint8_t n_properties;
        struct JMCS_Palette_Property {
            UTF_String key;
            UTF_String value;
        } properties[n_properties];
    } palette[palette_size];
    uint16_t indices[16 * 16 * 16 * 2];
};

UTF_String is that weird aah format that Java uses: unt16_t length followed by "modified UTF-8" string.

Reader MUST read section data even if section value is outside of buildable range.

// TODO: finish this

Footnotes

Chunk data in McRegion .mca files is aligned to 4kiB pages for some reason. Each chunk can also only have 255 pages, so compressed chunk size is limited to just under 1MiB², which is REALLY not a lot for Minecraft (especially modded one). I've personally ran into that problem on my modded Minecraft server that had a bunch of items in SophisticatedStorage chests, which caused light data to not save. I had to move everything to SophisticatedBackpacks, since they only store storage UUIDs and not items themselves.

APPARENTLY it's not supposed to do that! It should instead write chunk data to .mcc files instead of storing them in the region itself. Source: Minecraft Wiki: Region file format

Playing with the CYD

Casey — Thu, 17 Sep 2026 12:56:00 +0000

A couple weeks ago I bought myself a tiny little yellow ESP32 board with a touchscreen on it, commonly known as "Cheap Yellow Display" (aka CYD). It's a pretty capable board with ESP32-D0WD-V3 MCU on it as well as some useful peripherals (such as microSD card slot, DAC with an amplifier and afformentioned touchscreen).

At the moment of writing this post I've done way too many things without taking many photos, so this post is gonna look pretty lame 😔

Short board info

thang	description
RAM	520KB
Flash	4MB QSPI
Display	`ILI9341` ¹
Touchscreen	resistive with `XPT2046` controller
UART driver	`CH340` as always
Price	~$12

Unfortunately it only works at 40MHz or lower, 80MHz makes it freak out too much (image below)

Screen at 80MHz

It also has on-board RGB LED on pins 4, 16 and 17 (not addressable one, unfortunately) but I ended up using those pins for a different purpose :3

A ton of helpful information I got from this page, including some mentioned here

i can see now

First thing I did with it is flashed MicroPython and tried to get display running

After ~~very long sesh~~ looking into how others have done it in Arduino land, i just ended up sending minimal init sequence to that display:

_INIT_SEQUENCE = micropython.const((
    (0x01, None),
    (0xcf, b"\x00\xc1\x30"), # PWCTRB
    (0xed, b"\x64\x03\x12\x81"), # POSC
    (0xe8, b"\x85\x00\x78"), # DTCA
    (0xcb, b"\x39\x2c\x00\x34\x02"), # PWCTRA
    (0xf7, b"\x20"), # PUMPRC
    (0xea, b"\x00\x00"), # DTCB
    (0xc0, b"\x23"), # PWCTR1
    (0xc1, b"\x10"), # PWCTR2
    (0xc5, b"\x3e\x28"), # VMCTR1
    (0xc7, b"\xB3"), # VMCTR2
    #        ^^^^
    # EVIL FUCKING THING THAT
    # WAS 0x86 BEFORE AND LOOKED
    # LIKE ABSOLUTE GARBAGE
    (0x36, b"\x20"), # MADCTL: Rotation
    (0x37, b"\x00"), # VSCRSADD
    (0x3a, b"\x55"), # PIXFMT
    (0xb1, b"\x00\x18"), # FRMCTR1
    (0xb6, b"\x08\x82\x27"), # DFUNCTR
    (0xf2, b"\x00"), # ENABLE3G
    (0x26, b"\x01"), # GAMMASET
    (0xe0, b"\x0f\x31\x2b\x0c\x0e\x08\x4e\xf1\x37\x07\x10\x03\x0e\x09\x00"), # GMCTRP1
    (0xe1, b"\x00\x0e\x14\x03\x11\x07\x31\xc1\x48\x08\x0f\x0c\x31\x36\x0f"), # GMCTRN1
    # Imma be honest, I have no idea what those values mean ^
    (0x11, None), # SLPOUT
    (0x29, None), # DISPLAY_ON
))

after which sending frames was as easy as setting window for changes:

cmd_with_data(0x2A, struct.pack(">HH", x, x + w - 1))
cmd_with_data(0x2B, struct.pack(">HH", y, y + h - 1))
cmd(0x2C) # RAMWR

and just writing image buffer as is-

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
MemoryError: memory allocation failed, allocating 153600 bytes

...rrrright....

Luckily for me I have spent enough time on making ComputerCraft Term API-compatible renderer for MicroPython which lets me update lines at a time (just 5724 bytes of pixels) instead of whole screen at once

After some refactoring and cleanup, all we have to do to get a working terminal is:

from ccterm import CCTerm
from machine import Pin, SPI
from lcd import LCD

spi_lcd = SPI(1, 40000000, mosi=13, miso=12, sck=14)
lcd = LCD(spi_lcd, Pin(2, Pin.OUT), Pin(15, Pin.OUT))
backlight = Pin(21, Pin.OUT, value=1)

term_buf = bytearray(53 * 26 * 2)
line_buf = bytearray(53 * 6 * 9 * 2)
term = CCTerm(term_buf, 53, 26)

def refresh_screen():
    lcd.set_window(1, 3, 318, 234) # centers it out
    for y in range(26):
        term.get_line_pixel_data(y, line_buf)
        lcd.data(line_buf)

term.set_background_color(1 << 15) # black
term.set_text_color(1) # white
term.clear()
term.puts("Hello, ")
term.set_text_color(1 << 3)
term.puts("MicroPython!\n")

refresh_screen()

Source of everything can be found here

Which gives us this:

Excuse poor image quality, I was taking those photos at work

Now it would be nice to have a..

way to input stuff

A bit before getting this board I also bought CardKB from M5Stack. It's a tiny keyboard with 50 keys, I²C interface and a status LED, powered by ATMega8A chip. Annoyingly, it costed more than CYD, but not by much

Using it is was so much easier than poking that display: just read a byte from 0x5F and that's it, the key! Keycodes pretty much follow ASCII for alphanumeric symbols, ESC is sent as familiar 0x1B and Return key is CR and not LF for some reason. fn+[K] keycodes are a bit weird, but nothing too difficult to work with. I ended up using them as an alternative to Ctrl+[K] presses in the end.

A couple really annoying things with that keyboard: it tends to reset if you touch second pin of ISP section and using those keys for prolonged periods of time hurts my fingers a ton. I might end up printing keycaps for those to make my life a bit easier

As previously mentioned, Fn-keycodes are slightly weird, so I made a mapping of some of them to more common sequences (that MicroPython also understands):

char_mapping = {
    0x08: b"\x08", # BS
    0x09: b"\x09", # HT,
    0x0D: b"\x0D", # CR
    0x9A: b"\x01", # Fn+A -> Ctrl+A (goto beginning)
    0xA8: b"\x03", # Fn+C -> Ctrl+C (keyboard interrupt)
    0x9C: b"\x04", # Fn+D -> Ctrl+D (eof)
    0x8F: b"\x05", # Fn+E -> Ctrl+E (goto end)
    0xB5: b"\x1b[A", # Up
    0xB6: b"\x1b[B", # Down
    0xB4: b"\x1b[D", # Left
    0xB7: b"\x1b[C", # Right
    0x98: b"\x1b[H", # Home
    0xa5: b"\x1b[4~", # End
    0x8b: [0x0B], # Fn+BS -> Del
}

Oh also! Since we need I²C bus, I ended up using conveniently-shaped-4-pin-header-that-also-happens-to-have-power-wired-into-it. I cut off half the cable keyboard came with, soldered it to the one that CYD had and added 4 connectors in case I'd want to connect something else to the same bus. It looks ugly and I don't wanna show it

Now if we just...

from machine import I2C
iic = I2C(scl=Pin(22), sda=Pin(27))

# ...

# NOTE: for the time being I'm using only this
# as it's too early to use full ESC/CSI sequences here
char_mapping = {
    0x0D: 0x0A
}

while True:
    try:
        kc = iic.readfrom(0x5F, 1)[0]
        if kc != 0x00:
            term.putc(char_mapping.get(kc, kc))
    except Exception:
        pass

    refresh_screen()
    time.sleep_ms(50)

And now we can type stuff on the screen, yay!

Sometime later I'm gonna talk about how I made this monsterosity work as self-contained MicroPython REPL, made it feel touches and scream on boot

That's it for now, I wanna piss and don't feel like writing anymore, baiii

First page

Casey — Thu, 17 Sep 2026 10:50:00 +0000

Hello, world!

More coming soon hopefully