Log In  

demo cart

This demo shows off the interface. To use bigmap in your game, see "setup" below.

Cart #bigmap_demo-1 | 2022-01-18 | Code ▽ | Embed ▽ | No License


The recent 0.2.4 release added support for larger maps:

> Similar to gfx memory mapping, the map can now be placed at address 0x8000 and above (in increments of 0x100). This gives 4 times as much runtime space as the default map, and an additional POKE is provided to allow customisable map sizes.

Larger maps are now possible, but it's difficult to get them into memory -- the built-in map editor only works with vanilla-sized maps.

This cart is a full map editor that makes it easy to make these larger maps!


  • tight iteration loop - play a level in your game, jump into the map editor to make a small tweak, and return to the game with minimal friction
  • change map size at any time
    • max width: 256 tiles
    • max height: none
    • max total size: 32K tiles (e.g. 128*256, or 32*1024)
  • easy copy-paste (right mouse + drag to copy, left mouse to paste)
  • zooming in/out
  • large brushes - place multiple tiles at a time
  • show 16x16 "room" outlines (useful for carts like celeste that are made of many 16x16 rooms)
  • "transparency" - optionally treat sprite 0 in large brushes as "transparent"
  • compressed maps using PX9
  • autosaving
  • the map editor uses 0 of your tokens -- it's a completely separate cart that you only use during development
    (well, it costs ~300 tokens to load the map string and run the decompressor)
  • your game will still be splore-compatible
  • your game can call map(), mget(), tline() etc without any extra work


The editor currently has no undo/redo functionality. That's not ideal! I'm hoping to get it working soon.

To undo all changes since your last save (probably the end of your last session using bigmap), use the "discard changes" button in the top-right.

If you make a large mistake, replace map.p8l with your an autosaved version (inside mygame/autosave/) and reload bigmap.


Setting the bigmap editor up takes a bit of work. This is mainly necessary to enable a tight map iteration loop, and also to work around the restrictions of pico-8 (for example, it's impossible to read a file from disk without user interaction, and asking the user to drag-and-drop their map file every time they wanted to edit is way too much friction for my tastes)

To start, make sure you have a folder (e.g. mygame/) with your game cart inside (e.g. mygame/mygame.p8)

  1. cd mygame (navigate into the folder containing your game)
  2. mkdir autosave (create a folder to store backups/autosaves)
  3. printh("","map.p8l") (this creates an empty map.p8l file)
  4. Save this file (https://gist.github.com/pancelor/f933286f244c6b85b7720dbe6f809143) as px9_decomp.lua (inside the mygame/ directory)
  5. load #bigmap (note: this is different from the bigmap_demo cart)
  6. Uncomment the two #include lines in the second tab (tab 1)
  7. save bigmap.p8
  8. Paste this snippet into mygame.p8: (inside _init(), or at top-level; either works)

    menuitem(1,"▒ edit map",function()
      -- pass spritesheet through upper memory,
      -- avoiding an extra second of load time
      local focusx,focusy=0,0
      poke(0x5500,1,focusx,focusy) --signal
      load("bigmap.p8","discard changes","mygame.p8")

    (make sure you change "mygame.p8" to the actual filename of your game)

    This snippet adds the menu option to enter bigmap while playing your game. If you set focusx and focusy, bigmap will start focused on that map coordinate.

  9. Paste this snippet into mygame.p8 at top-level:
    #include map.p8l
    #include px9_decomp.lua
    if map_import then map_import() end
  10. Save mygame.p8

You should now be good to go!

test+edit iteration loop

  1. Save mygame.p8. any unsaved changes will be lost every time you launch bigmap. (I wish this was avoidable but I couldn't find a way around it that preserved the quick test+edit loop I wanted)
  2. Run mygame.p8
  3. Pause the game (with P or Enter)
  4. Choose "edit map"
  5. Edit your map!
    If you accidentally press escape and exit the map editor, type r or resume into the console to resume the map editor.
  6. Return to your game with P, Enter, or the clickable "Play" button in the top-right

I advise setting up mygame.p8 to jump you to the room you were editing when it starts - this can be done by reading the focusx and focusy global variables that are set inside the map_import() function (inside map.p8l)

See my celeste mod or the getting started video for an example of how to do this.

technical details

When you press the save or play button, bigmap uses printh to write a text file called map.p8l into the current directory. This text file happens to be valid lua code that defines a function called map_import(), so when mygame.p8 executes #include map.p8l and map_import(), it runs the code generated by bigmap.

Here's an example of what map.p8l looks like:

-- this file was auto-generated by bigmap.p8
function map_import()
 local function vget(x,y) return @(0x8000+x+y*mapw) end
 local function vset(x,y,v) return poke(0x8000+x+y*mapw,v) end
 px9_sdecomp(0,0,vget,vset,"◝◝◝ユ◝7な◝◝✽,ゃf\0★)&るちP;](♥KねF ... many many more chars here ... X▤ミヘラ⬇️⬇️Bれん")

This has 3 main parts:

  1. Set up some helpful global vars - mapw and maph are the width and height of the map, in tiles. focusx and focusy are the tile coordinate of the tile that was in the center of the screen when map.p8l was saved -- you can use this info to jump directly to that room to let you make small tweaks and test them very quickly
  2. poke(0x5f56,0x80,mapw) -- this tells pico-8 to use mapdata stored at 0x8000, with map width mapw
  3. The rest of the function uses PX9 to decompress the binary data stored in that long string. The decompressed data gets stored starting at 0x8000 and takes up mapw*maph bytes.

That compressed data string is created using PX9 and this snippet for encoding binary data in strings.


stuff I used:

alternative map editors you might consider using instead:


happy map editing!

I'd like to see what you make -- let me know if you use this in your projects! And if you want to credit me I'd appreciate it :)

Is bigmap helpful? Is it too confusing to set up? Find any bugs? Let me know what you think!

P#105301 2022-01-19 00:12 ( Edited 2023-10-06 06:03)


wait- how do I play it????
this is sick
EDIT: I mean- play the levels I made? how do I?

P#105364 2022-01-19 14:18 ( Edited 2022-01-19 14:46)

Yeah how do you play your levels?

P#105374 2022-01-19 17:40

@SandwichBlam @GeKStudios I tried to explain it under the "usage guide" section -- is there a specific part about it that's confusing?

(note that you have to download the bigmap cart with load #bigmap; the web demo playable here is just a demo to get an idea of what it's like to use the editor)

P#105377 2022-01-19 18:19 ( Edited 2022-01-19 18:20)

ahhhhh! thanks- i was playing the web demo haha

P#105390 2022-01-19 22:19

changelog for v1.2:

  • clarified some things (e.g. map size limits)
  • added a video guide on how to set up your project with bigmap
    • the base cart I start from in the video is available to download (load #bigmap_example)
  • thanks to @Peteksi for helping me fix two bugs!
  • thanks to @freds72 for pointing out some issues with the compression! (now fixed)

If you've already started using bigmap, you'll want to download the latest version (load #bigmap) and also download the updated px9_decomp.lua script

P#105459 2022-01-21 06:12

Hallo pancelor!
after a little bit, I got bigmap up and running on my pico-8! this is a really cool tool, and now we can make huge celeste carts like the works of taco360 due to the nonexistent map hight size! very nice!
(one note: when I had to set up the .lua file, I had to copy the code into notepad and save it as a .lua. that was confusing, as I first tried to save it as a .lua from my pico-8 and it became a .lua.p8.)
edit: I do NOT know how to use github. XD

P#109508 2022-04-01 11:56 ( Edited 2022-04-01 12:05)

glad to hear it -- lmk if you run into any issues!

P#109701 2022-04-04 19:49

can this be used with an Evercore celeste file? as in, setting the level width, height, x, and y, and it would work?

P#113625 2022-06-25 14:58

I don't know what evercore is @SandwichBlam, but bigmap should be able to work with it -- all bigmap does is edit the map data of a cart.

you might have to do extra work to make them work nicely together, but I would think it should be the same as any other cart. follow the "setup guide" video and let me know if you have questions!

P#113809 2022-06-29 20:58

Evercore is like a sort of bigger map addition to celeste classic.

If you've played Fault, those scrolling levels are what evercore adds you have to specify the level height, width, x, and y. so, I'm not sure if that would work with an external map editor...

P#113835 2022-06-30 13:15

Awesome tool! Useful and easy to install. Good job

P#135404 2023-10-04 14:00

[Please log in to post a comment]

Follow Lexaloffle:          
Generated 2024-02-28 23:13:33 | 0.069s | Q:33