Log In  

if there's something I forgot, let me know

No, you probably won't know what I forgot, but if something messes up, or something's really weird and confusing, let me know.


Cart #wvm_mapc_tool-0 | 2023-03-04 | Code ▽ | Embed ▽ | No License

Code licensed under CC BY 4.0. Yeah, that's right, steal the freaking code!!!!!

About - MCT, Map Command Tool

This is a cartridge that can help fit large maps in an extremely small space via the use of two byte commands that fill in or remove large sections at a time.
It doesn't do so automatically, but you are given a little interface to do the work.
You can also edit the maker code itself to create extra commands (there's five dedicated 2 byte commands available, and you can probably go crazy with the alternate commands).

It's not a compression system like PX9, but it still puts large amounts of data in a smaller space.
Still, it might not be what you're looking for, as it requires you to simplify quite a lot of the data and (as of right now) costs about 500 tokens to implement (which is kind of a lot).
In return, theoretically, you get a significant savings in map space. The above gif's map is in 10% of the usual space. I have not tested this against any other compression system.

Just think really hard about what kind of maps you have before you pick a compression system.

I really want to work towards making it super editable & good for whatever, so if you have any suggestions, let me know!! Please!

Data to command table costs ~229 tokens
Unmodified commands to map costs ~263 tokens
Make sure you have a screens = {} declaration.

You can see an example implementation down below in the OTHER section!

Some limitations

  • There are only 14 main commands, 15 usable alternate commands.
  • Currently it only supports nibbles for each main command value. Thus it can really only support 16x16 maps.
  • It can only use 63 tile values without adding an extra byte (though you can use commands A-E to add extra tiles).
  • Fills only use one tile at a time.
  • If two maps use the same screen space, that's on you, dingus.
  • Binary export messes with commands if they have too much zero
  • The cart doesn't use devkit keyboard.


D>T 229t, T>M 263t

How to Use

Download the cart and place tiles in the spritesheet representing tiles from your game. Run the cart. Start editing!
Use arrow keys to move.
O and X are modifiers, and holding them will change what your arrow keys do - X will change what part of the screen you work with, and O will let you change a specific value.
O is also used as the "accept" button.

You can export it at any time by going to the bottom bar, hitting EXPORT, and then selecting either binary or hex.
Hexadecimal prints something like hf037, and is safe to put in any text editor. Binary instead gives you one-byte characters, along the lines of bユs that are meant to be put in a PICO-8 string, can contain weird characters that could possibly mess with other text editors, and will break if you have a command with "zero parameters" (see Commands documentation).
After hitting O on an export type, hit CTRL-C up to 12 times (just in case) and paste it somewhere safe.

To import, copy the entirety of a map string, paste into the app up to 12 times (just in case), then hit IMPORT 3 or 4 times.



Top Bar
Use left and right to change the screen.
O opens up the banner, where you can add and delete screens, or go to the map preview (which uses the bigmap space).
On the banner, hit O to perform the action selected and use arrows to change selection.
Deletion is an irreversible action. Be careful.
The bar also shows how many bytes the current screen uses.

Arrows change the selection. Holding O makes them change a value instead.
To add a new command, go to NEW, hold O, and use up/down to choose where to place the new command.
All commands are put in the map in order, starting with "G" (which can't be changed as that marks where a new map is).
On a null command, you can press left and then O to delete it.

Bottom Bar
When unselected, the bar shows the total bytes this set of screens is using, compared to how many bytes it would take up uncompressed. It also shows the compression rate.
When selected, a banner opens up allowing you to import and export the map. To use import, you have to paste while the cart is in focus.
Importing is an irreversible action. Make sure your data is backed up well.
Exporting opens up the export menu and lets you export to hex or binary. You have to press CTRL-C to copy once you hit O on an export option.


Normal command parameters are sorted COMMAND, X, Y, V

Binary Conditions
If a command does not follow these conditions, it will be changed or removed on binary export. If you wanna use a lot of zeroes, you need to use hex export.
For normal commands, Y or V must be non-zero.
For F0, you must have one non-zero value. THIS COMMAND WILL DEFAULT TO X=F and Y=F OTHERWISE
For F1, you must have one non-zero value.
For F2, X or Y must be non-zero, and V must be non-zero.


0 - null, ignored on export

**Normal Commands**
two bytes, all 4 bits per parameter

1   - erase one line
  x,v - start, end
  y   - y position

2   - fill from bottom
  x,v - start, end
  y   - y position

3   - fill one line
  x,v - start, end
  y   - y position

4-7 - place one tile
  x,y - position
  v   - tile:
  4 is 0-15
  5 is 16-31
  6 is 32-47
  7 is 48-63

8   - fill from top
  x,v - start, end
  y   - y position

9   - erase from bottom
  x,v - start, end
  y   - y position

a-e - unused

f   - ALT MODE

**Alternate Commands**
alternate commands use a different parameter format

f0  - new screen (2 bytes, always one per screen)
  x,y - screen position on bigmap
  however, you don't have to use this as screen position
  idk what else you'd use it for though

f1  - change fill brush (2b - f1, 8v)
  v   - tile to use as brush

f2  - place one tile (3b - f2, 4x 4y, 8v)
  x,y - position
  v   - tile to use


I created this so that I could compress my map data without having to put BY-NC-SA, a license I didn't want on a game I'm making. So I'm making all of this cartridge under a CC-BY license. That includes the map loading code, but all you have to do is put a -- by wish volo comment right before it and you'll be good.

I completely encourage you to do whatever the heck you want. That's what this is meant for.


Yes, it works:

Cart #wvm_mct_test-0 | 2023-03-04 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

I think a good way to use the "tiles" in the cart is as representations - it doesn't have to look exactly as it does in the editor. You can make it look different during import, like changing a tile based on possible variations or whatever.
example: Tile 1, no matter what it is in the normal cart, represents all and any ground tiles of type X. When loading to map data, if it detects value 1, then it will pick a random tile from group X and draw it!
easy peasy.

You can put a PAL() call at the bottom of DRAW(), cause that's where the map preview code is, if you want to see a different palette to match what your tiles will actually look like.

If you don't use a specific command, feel free to comment it out.
If you stick to using only hex or binary, then you can cut a few extra tokens out of the functions.

at some point i need to add base 64
the only issue with base 64 is that it might actually cost more tokens to do so, but it'd save more space than hex

Dev ramble

okay so i made this thing based on Super Mario Bros' maps, or at least what i heard about them.

i didn't want to bother with finding a compression system on PICO-8, and i didn't want to use PX9 because it's under a fairly restrictive license
(nothing wrong with it, i just don't want to worry about what i can and can't do. like, uh. make money.)

at first i was just going to make something that tallied up all the tiles in byte order, then shove it to two bytes
it'd say the tile, then the amount of times that tile appeared, counting horizontally. does that make sense?

and i made it, and it did okay.

then i thought about "how big are SMB maps?" so i tried to look it up but then i found "hey, this game uses a bunch of commands that say to draw a fill pattern here or whatever"

so i decided to do something based on that! and that's the story.

oh also one time i forgot about 0x8000's existence, and there was a bunch of other stupid stuff i did because i didn't think 100% of the way, but i don't remember much beyond "oh crap, big maps exist"
that doesn't really have anything to do with the editor, that was just me worrying about how many tokens i'd have to spend to have a dynamically loading map

also yes, the ui is (coincidentally) like LSDJ's if you noticed

If this sucks, then it's perfectly fine cause it was fun to put it together, write the documentation, interestingly enough. I finally made a relatively smart thing! that has a purpose! woo!
and i'm still gonna use this cart anyways lol

do whatever you want with it lol

P#126521 2023-03-04 01:43

just remembered that i forgot a “export to file” completely
(which would let you shove data to the bytes of a cartridge rather than a string)
so i’ll get around to that probably

P#126578 2023-03-04 02:34

[Please log in to post a comment]

Follow Lexaloffle:          
Generated 2023-12-05 02:49:45 | 0.012s | Q:14