wibi's picture


every day imgur is not dead is another little miracle.

so those in that game would be gems. but what's up with that?

firstly this is all about an upcoming (not anymore, it has already released) version of jumper 4 real.
secondly i should talk about how saves work.

for the most part everything about a save slot is stored in a file named slotN.txt where N is the slot number. it is a pretty human-readable format. here's an example:
https://pastebin.com/raw/HWbdkX6f

gems, however, are stored in a different file, slotN.j4g, in a condensed format. (j4g is a format i came up with short for "jumper 4 gems".) this is partly so collecting a bunch of gems doesn't take up a bunch of disk space, and partly so that it's much quicker for the menu to just read off how many gems each slot has. in future i may put other info the menu wants to read quickly here as well, like how many different rooms the user has triggered the "you win" screen from.
here's the j4g specifications. you'll note there's no header.

big-endian

2 BYTES UINT16 {BLUE GEM COUNT}
2 BYTES UINT16 {RED GEM COUNT}
12 BYTES {RESERVED}
2 BYTES INT16 [THE X POSITION OF THE 1ST BLUE GEM; SIGNED]
2 BYTES INT16 [THE Y POSITION OF THE 1ST BLUE GEM; SIGNED]
2 BYTES INT16 [THE X POSITION OF THE 2ND BLUE GEM; SIGNED]
2 BYTES INT16 [THE Y POSITION OF THE 2ND BLUE GEM; SIGNED]
... {AMOUNT OF BYTES TO READ IS DETERMINED BY BLUE GEM COUNT}
2 BYTES INT16 [THE X POSITION OF THE 1ST RED GEM; SIGNED]
2 BYTES INT16 [THE Y POSITION OF THE 1ST RED GEM; SIGNED]
2 BYTES INT16 [THE X POSITION OF THE 2ND RED GEM; SIGNED]
2 BYTES INT16 [THE Y POSITION OF THE 2ND RED GEM; SIGNED]
... {AMOUNT OF BYTES TO READ IS DETERMINED BY RED GEM COUNT}

up to four versions of this file exist per levelset: slot 1, slot 2, slot 3, and combined (union)

"the x position" and "the y position" refer to the x and y position of the room the gem is in.
(what you would call "levels", jumper 4 real would call "rooms", and every room is somewhere on a grid spanning from -32768 to 32767.)
(if there's multiple gems of the same type in the same room, there is a mechanic where all of them turn out to be holograms except the last one you try to collect.)

"combined (union)" is this:

named "union" because it is the "union" of all gems you have across all savefiles (as well as deleted savefiles). it's like a permanent progress indicator.
whenever you collect some new gems and go back to the menu, when the game writes what new gems you've collected in save slot N, it also tries to update the "union" file. it cross references with all the gems you have in slot N and ticks off whatever gems are already present in the union file, and the remainder gets appended.
well not actually "appended" since the structure of j4g files means new blue gems have to be inserted into the middle of the file, and also i implemented it really weirdly such that the "union" table of gems effectively gets replaced with the "slot N" table of gems and then has the gems that aren't in slot N appended to it, but that part doesn't really matter since lua's pairs function has no defined order and that's how i iterate through all the gem tables anyway (the key is a room position and the value is true).

but now you may be wondering about that number to the right of the /. you may be wondering how the menu knows what the total amount of each type of gem is, without manually scanning every single level for gems.

the answer is... it doesn't! it just checks two variables you set from the editor. (if either of them are 0 or left empty, then it doesn't show the gem total at all. also, there is nothing stopping you from lying about the total amount of gems your levelset contains.)

however, the editor does have a "recount gems" button that automatically totals up the amount of gems every room has.
how are rooms stored? well hey i have another freaking pastebin link woah.
https://pastebin.com/raw/625G65ES

OK THIS PART OF THE POST IS ABOUT HOW ROOMS WORK.

map data itself is two bytes per tile - the first byte being a "bank" (though this, like many other decisions, is entirely arbitrary and not really enforced) - with the additional restraint (for the time being) that every byte has to be printable ASCII. also there's some hacky compression for rows that are all the same tile or adjacent rows that are identical.
you'll notice there's no separator between each tile. this might lead you to believe "oh, ok, so you used some string buffer thing, and you check an initial byte to see if it's | and if so you know it's map data, and from there on you consume 2 bytes at a time" but no!!! i wrote a stupid custom string split function that specifically only splits across multiples of n (2 in this case). that was back when i didn't even know string buffers existed. where were we? oh, right.
so right away there's a problem: we can't just use string.find for the 2 bytes that comprise a blue or red gem, because what if i got really pressed for space for some reason (95 tlies/objects per bank isn't infinite!!) and started using using { or | as a bank? then if it were right next to a tile that ended in O, it falsely finds O{ or O| and thinks it's got a gem. but it don't! and it's not possible to tell what parity a tile is on except relative to the last newline (not to the start of file).
so i COULD just write another hacky mess that's like string.find but only for specific parities and also considers the last line break to be parity 0. but i had a better idea that was way faster.
up to this point i had three agreed-upon "starting characters" for this pseudo-format i saved as .txt:

  1. ===. indicates a header, kinda like puzzlescript. and yes it has to be exactly three =s because uhh it looks nice. also there has to be a === at the end too. the main bulk of the header is expected to be ONLY UPPERCASE LETTERS, but it can have a : to denote a "phase", which can be UPPERCASE LETTERS INCLUDING NUMB3RS.
  2. |. indicates data of any sort. can rarely have lowercase letters before it, usually to indicate what type the following data is (number, string, bool).
  3. >. indicates a "command", like duplicating rows of map data, or switching how data is interpreted (like a sub-header). i think a long time ago i had an internal rule that commands should all be 3 letters long but that doesn't matter anymore, and anything that can follow a | can follow a >.

is there some central parser that knows what to do with all these characters? no! no there isn't. in fact, i've probably written roughly the same parsing code about 4-5 times, with the difference mainly being where data goes and what commands do.
so to store what gems are in a level at the very start of the file more easily, i introduced a fourth character:
  1. !. indicates arbitrary-ish bytes follow. all bytes must have the top bit set so none of them will be ascii, and the byte sequence is terminated with a zero-byte. (and then a line break.)

so now every room has a header starting with !, 0x80 (np++ assigns this to €), and a zero-byte..
whenever a room is saved, the process that jots down each tile also checks if that tile corresponds to a blue gem or a red gem. if it's a blue gem, it flips the last of the 2nd byte of the header. if it's a red gem, it flips the penultimate bit of the 2nd byte of the header. i.e. blue gem only is 1, red gem only is 2, blue gem and red gem is 3.
and the "recount gems" button just nips the first 2 bytes of every room in the levelset.
it checks the first byte. if the first byte isn't !, then it notes that the room is using an old version of the level format with no header, and it will print how many such rooms it encountered once it's done counting.
then it checks the second byte. if the last bit is set, it knows the room contains a blue gem. if the penultimate bit is set, it knows the room contains a red gem. so it just sums all that up and then fills the textboxes above it with the results it got.

in retrospect, having introduced a header into my level format, i probably should have had the first byte (well, last 7 bits of the first byte) be a version number instead of gem information, so if i make any more silly changes then i can know definitively what version of the room "format" each room was saved with.
indeed i should. but so far, i haven't.
yay!