## Instructions - Target PICO-8 v0.2.6; respect hard limits: 8192 tokens, 65536 chars code, 128x128 px, 16 colors, 256 sprites. - Structure code as _init() setup + _update() or _update60() logic + _draw() render; never block _draw with logic. - Keep tables small; reuse locals, avoid string concat per frame, prefer integer math and fixed-point where hot. - Build sprites in 8x8 grid (0-255); use flags for solid/collectible and map tiles 0-127 for levels. - Use mget/mset for tile collision: check corners with solid flag, resolve X then Y separately to avoid sticking. - Design SFX in tracker (channels 0-3), music patterns 0-63; reserve channel 3 for engine jingles vs gameplay. - Compress with picotool count; refactor long if-chains to lookup tables when tokens exceed 7000. - Test at 30fps (_update) for logic-heavy games, 60fps (_update60) for twitch platformers; lock with vsync. - Save persistent data with cartdata(id) + dset/dget (256 slots); namespace cartdata id uniquely. - Export via .p8.png for BBS + HTML zip; include label art 128x128, title, controls in forum post. - Document controls on label/boot screen: arrows/Z/X + P pause; support mobile touch mapping in web export. - Playtest on real hardware (PocketCHIP/Anbernic) or splore queue to catch palette/contrast issues. ## Examples - Example 1: "player move" -> btn(0-3) velocity, spr() flip, mget collision, sfx(0) on jump. - Example 2: "token save" -> replace `if a==1 then b=2 elseif a==2 then b=3 end` with `b=({[1]=2,[2]=3})[a] or b`. - Example 3: "music loop" -> music(0,0,7) pattern chain with SFX speed 12, stop with music(-1) on game over. ## Workflows - New cart workflow: Sprites 0-15 player -> map sketch 0,0 -> SFX jump/coin -> code _init/_update/_draw -> label art. - Collision workflow: Flag sprites red solid -> write solid_at(x,y) using mget+fget -> move X test -> move Y test. - Audio workflow: Draft SFX 0-7 -> chain into music pattern -> test memory with info overlay -> adjust speed. - Export workflow: cstore thumbnail -> save .p8 -> export .p8.png + .html -> post to BBS with gif via GifBooth. ## Templates - Core loop: ```lua function _init() p={x=64,y=64,dx=0,dy=0} gravity=0.2 end function _update() p.dy+=gravity p.x+=p.dx p.y+=p.dy if btnp(4) then p.dy=-3 sfx(0) end end function _draw() cls(1) map(0,0,0,0,16,16) spr(1,p.x,p.y) end ``` - Collision helper: ```lua function solid(x,y) return fget(mget(x\8,y\8),0) end ``` - Token checklist: [ ] tokens<7500 [ ] no per-frame alloc [ ] cartdata id set [ ] label done [ ] controls listed. - BBS post template: Title | GIF | Controls | Token count | Update log | .p8.png attach. ## Tools - Editor: Built-in sprite/map/sfx/music editors, PICO-8 Education, Picotool CLI for counts. - External: Aseprite 128px import, P8Tool minifier, GifBooth recorder, Splore browser. - Libs: pico8lib tween, Jelpi platformer base, PICO-8 forum carts for patterns. - Export: lexaloffle BBS, itch.io PICO-8 template, PICO-8 mobile wrapper. ## Advanced - Use poke(0x5f5c,255) mouse + stat() for dev tools overlay without extra tokens in release (strip). - Implement screen shake with camera(rnd) decay; particle pools as fixed arrays of 32 structs. - Do palette swap via pal({[13]=8},0) for hit flash; reset each frame to avoid bleed. - Stream levels with reload(0x2000,0x2000,0x1000) bank switching for >128 tile maps. - Optimize with _update60 + fixed timestep accumulator for deterministic replays. - Pack sfx with speed 8-12 + slide/vibrato to save patterns; reuse one noise SFX pitched via speed param. - Tweetcart discipline: 560-char carts teach table-driven design transferable to full 8k-token games. ## Documentation - PICO-8 manual: https://www.lexaloffle.com/dl/docs/pico-8_manual.html - API wiki: https://pico-8.fandom.com/wiki/Category:API - BBS carts: https://www.lexaloffle.com/bbs/?cat=7&carts_tab=1 - Token tips: https://github.com/seleb/PICO-8-Token-Optimizations - Nerdy teachers: https://nerdyteachers.com/PICO-8/ - Tweetjam guide: https://github.com/seaweedq12/pico8-tweetjam