picopilot 0.0.0 → 0.1.1

package/src/skills/picopilot-code/reference/platformer.md

@@ -0,0 +1,119 @@
+# Platformer reference (side-view, gravity + tile collision)
+
+Structure for a side-scrolling platformer: the player has velocity, gravity
+pulls it down, and collision is resolved AXIS BY AXIS against solid map tiles.
+This is the shape that gets platformers wrong most often, so follow the axis
+order and the corner checks exactly.
+
+## The load-bearing rules (get these wrong and it feels broken)
+
+1. Gravity and input change VELOCITY (`dx`,`dy`), never position directly. A
+   fall must ACCELERATE, so `dy += gravity` each frame, not `y += gravity`.
+2. Move and resolve X FIRST, then Y SEPARATELY. Moving both then testing once
+   sticks the player in corners and forbids wall-sliding.
+3. An 8px sprite occupies pixels `x .. x+7` (NOT `x+8`). Check tile collision at
+   all four corners; `x+8` reads the NEXT tile and gives phantom collisions.
+4. Reset `grounded` to false every frame BEFORE the Y resolve, then set it true
+   only when a downward move hits a floor. Otherwise jump never re-arms (or
+   arms forever = infinite mid-air jumps).
+5. `_update` is 30fps. Tune `gravity`/jump for 30 steps/sec, or switch the whole
+   cart to `_update60()` and tune for 60. Do not mix.
+
+## Solid-tile test (map flag 0 = solid, by convention)
+
+```lua
+-- pixel (x,y) -> is its map tile solid? flag 0 set = solid.
+function solid(x,y) return fget(mget(x\8,y\8),0) end
+
+-- 8x8 actor a: any of its four corners on a solid tile?
+function hits(a)
+ return solid(a.x,a.y)   or solid(a.x+7,a.y)
+     or solid(a.x,a.y+7) or solid(a.x+7,a.y+7)
+end
+```
+
+## Player update (input -> velocity -> per-axis move+resolve)
+
+```lua
+gravity=0.3
+accel=0.5
+friction=0.85
+jump=-4
+
+function make_player(x,y)
+ return {x=x,y=y,dx=0,dy=0,grounded=false}
+end
+
+function update_player(p)
+ -- input into horizontal velocity
+ if btn(0) then p.dx-=accel end
+ if btn(1) then p.dx+=accel end
+ -- jump only when standing
+ if btnp(4) and p.grounded then p.dy=jump end
+
+ -- physics on velocity
+ p.dy+=gravity
+ p.dx*=friction
+
+ -- resolve X
+ p.x+=p.dx
+ if hits(p) then
+  -- back out and stop horizontal motion (simple, non-swept)
+  p.x-=p.dx p.dx=0
+ end
+
+ -- resolve Y (reset grounded first)
+ p.y+=p.dy
+ p.grounded=false
+ if hits(p) then
+  p.y-=p.dy
+  if p.dy>0 then p.grounded=true end  -- landed on a floor
+  p.dy=0
+ end
+end
+```
+
+## Camera follow with level-edge clamp
+
+```lua
+-- level_w = level width in PIXELS. mid() clamps so you never scroll past the map.
+function update_camera(p)
+ local cx=mid(0, p.x-64+4, level_w-128)  -- +4 centers the 8px sprite
+ camera(cx,0)
+end
+
+function _draw()
+ cls()
+ update_camera(player)
+ map()              -- draw the tilemap in world space
+ draw_player(player)
+ camera()           -- RESET before HUD or the score scrolls off with the world
+ print("score "..score,2,2,7)
+end
+```
+
+## Animation (walk cycle from a timer, flip when facing left)
+
+```lua
+function draw_player(p)
+ -- 4-frame walk (sprites 1..4), advancing ~every 8 update frames; flip when moving left
+ local s=1+flr(t()*4%4)
+ spr(s, flr(p.x), flr(p.y), 1,1, p.dx<0)   -- 6th arg = flip_x (boolean)
+end
+```
+
+## Genre pitfalls checklist
+
+- [ ] Gravity accumulates into `dy`, not into `y`.
+- [ ] X resolved, THEN Y resolved (two separate move+test blocks).
+- [ ] Corner checks use `x+7`/`y+7`, not `x+8`/`y+8`.
+- [ ] `grounded` reset to false each frame before the Y resolve.
+- [ ] Constants tuned for the actual framerate (`_update` = 30, `_update60` = 60).
+- [ ] `camera()` reset before drawing the HUD.
+
+## Level fast (high speed) tunneling
+
+Backing out the whole move (`p.x-=p.dx`) is fine at low speeds. If an actor can
+move more than ~4-6 px/frame it can tunnel THROUGH a 1-tile wall. When you need
+that, step the move in 1px increments (or sub-steps) and test each step, instead
+of one big move + one test.

package/src/skills/picopilot-code/reference/puzzle-grid.md

@@ -0,0 +1,106 @@
+# Puzzle / grid reference (discrete cells, tile-step movement, rules)
+
+Structure for a grid puzzle (block-pushing, rule-based, or match games). The
+world is a 2D array of CELLS, the player moves ONE cell per input (not by
+velocity), and a
+turn is: read intent, test the move against rules, commit if legal. There is no
+gravity and no sub-pixel motion here; do NOT reach for the platformer shape.
+
+## The load-bearing rules
+
+1. State is a GRID, not a pixel position. Store `col,row` (integers), render by
+   multiplying by 8 (`x=col*8`). Movement changes `col,row` by exactly +/-1.
+2. Input is DISCRETE: use `btnp` (fires once per press), never `btn` (fires every
+   frame = the player rockets across the board).
+3. A move is a TRANSACTION: compute the target cell, check every rule (in bounds?
+   wall? pushable block that itself can move?), and only then mutate the grid.
+   Never move first and undo, it corrupts multi-object pushes.
+4. Grids are 1-based in Lua. Guard bounds explicitly (`c>=1 and c<=cols`).
+
+## Grid setup (rows as split strings = cheap + readable levels)
+
+```lua
+cols,rows=16,16
+-- a level as one string per row: .=floor #=wall @=player $=box
+level=split("################, #@.....#......#, #..$..........#, ...(more rows)...", ",")
+
+grid={}          -- grid[r][c] = tile char
+player={c=2,r=2}
+
+function load_level()
+ grid={}
+ for r=1,rows do
+  grid[r]={}
+  local row=level[r]
+  for c=1,cols do
+   local ch=sub(row,c,c)
+   grid[r][c]=ch
+   if ch=="@" then player.c,player.r=c,r grid[r][c]="." end
+  end
+ end
+end
+```
+
+## Discrete move as a transaction (with box-push)
+
+```lua
+-- dir -> delta. split pairs are the idiomatic lookup.
+dc=split"0,0,-1,1"   -- up,down,left,right dx (matches btnp 2,3,0,1 order below)
+dr=split"-1,1,0,0"
+
+function cell(c,r) -- safe read; out of bounds reads as wall
+ if c<1 or c>cols or r<1 or r>rows then return "#" end
+ return grid[r][c]
+end
+
+function try_move(dx,dy)
+ local nc,nr=player.c+dx,player.r+dy
+ local t=cell(nc,nr)
+ if t=="#" then return end          -- wall: no move
+ if t=="$" then                     -- box: can it be pushed one further?
+  local bc,br=nc+dx,nr+dy
+  if cell(bc,br)~="." then return end  -- blocked behind: whole move illegal
+  grid[br][bc]="$" grid[nr][nc]="."    -- commit the push
+ end
+ player.c,player.r=nc,nr            -- commit the player move
+end
+
+function _update()
+ -- btnp order: 0 left,1 right,2 up,3 down
+ if btnp(0) then try_move(-1,0) end
+ if btnp(1) then try_move(1,0) end
+ if btnp(2) then try_move(0,-1) end
+ if btnp(3) then try_move(0,1) end
+end
+```
+
+## Render (grid -> screen, cell*8)
+
+```lua
+function _draw()
+ cls(1)
+ for r=1,rows do for c=1,cols do
+  local t=grid[r][c]
+  if t=="#" then rectfill((c-1)*8,(r-1)*8,(c-1)*8+7,(r-1)*8+7,5)
+  elseif t=="$" then spr(2,(c-1)*8,(r-1)*8) end
+ end end
+ spr(1,(player.c-1)*8,(player.r-1)*8)   -- player
+end
+```
+
+## Win / rule evaluation
+
+Evaluate win AFTER a committed move, by scanning the grid (e.g. every box on a
+target). For a game where the RULES are themselves objects on the grid, the rule
+set is DATA you re-parse each turn (scan the grid for rule triples, rebuild a
+properties table), then movement/legality queries that table. Keep the rule pass
+separate from the move pass; do not interleave them.
+
+## Genre pitfalls checklist
+
+- [ ] Position is integer `col,row`, rendered as `*8`, not a pixel velocity.
+- [ ] Input uses `btnp`, not `btn`.
+- [ ] Moves are validated fully BEFORE any grid mutation (transaction).
+- [ ] Multi-object pushes check the space behind the pushed object.
+- [ ] Bounds guarded (1-based); out-of-bounds reads treated as wall.
+- [ ] Win/rule evaluation is a separate pass after the move commits.

package/src/skills/picopilot-code/reference/rpg-menus-dialog.md

@@ -0,0 +1,122 @@
+# RPG menus + dialog reference (UI state machines, text reveal)
+
+Structure for the menu/dialog side of an RPG or any UI-driven game (title menus,
+inventory, shop, dialog boxes, turn-based battle menus). The defining problem is
+NOT movement, it is a STACK of UI STATES, a cursor over a list of options, and
+text that reveals over time. Get the state stack and the cursor-wrap right; the
+"game feel" here is menu responsiveness and readable text pacing.
+
+## The load-bearing rules
+
+1. UI is a STACK of modes (`{"map"}` -> push `"menu"` -> push `"item"`). Input and
+   draw dispatch on the TOP of the stack. Opening a submenu PUSHES; canceling
+   (btnp 5 / X) POPS. This is cleaner than a flat `mode` string once menus nest.
+2. Menu input is DISCRETE: `btnp` only. A cursor is an index into an options list;
+   moving wraps with `%`. Confirm = btnp(4), cancel = btnp(5).
+3. Dialog text REVEALS over time (one char every few frames), not all at once.
+   Track a reveal counter; a confirm press either fast-forwards to full text or,
+   if already full, advances to the next line.
+4. Draw menus in SCREEN space. If the field behind is camera-offset, `camera()`
+   (reset) before drawing the box, or it slides with the world.
+
+## Mode stack + dispatch
+
+```lua
+stack={"field"}
+function top() return stack[#stack] end
+function push(m) add(stack,m) end
+function pop() if #stack>1 then deli(stack) end end   -- never pop the base mode
+
+function _update()
+ local m=top()
+ if m=="field" then
+  update_field()
+  if btnp(4) then push("menu") menu_cur=1 end
+ elseif m=="menu" then
+  update_menu()
+ elseif m=="dialog" then
+  update_dialog()
+ end
+end
+```
+
+## Cursor over a list, with wrap
+
+```lua
+menu_items=split"items,magic,status,save"   -- data as a split string
+menu_cur=1
+
+function update_menu()
+ -- up/down move the cursor, wrapping (1-based, so the %+1 dance)
+ if btnp(2) then menu_cur=(menu_cur-2)%#menu_items+1 end
+ if btnp(3) then menu_cur=menu_cur%#menu_items+1 end
+ if btnp(4) then choose(menu_items[menu_cur]) end   -- confirm
+ if btnp(5) then pop() end                          -- cancel closes the menu
+end
+
+function draw_menu()
+ camera()                       -- SCREEN space
+ rectfill(80,8,120,40,0) rect(80,8,120,40,7)
+ for i,it in ipairs(menu_items) do
+  local y=12+(i-1)*7
+  print(it,88,y, i==menu_cur and 7 or 5)
+  if i==menu_cur then print(">",83,y,7) end
+ end
+end
+```
+
+## Dialog with timed text reveal
+
+```lua
+dlg={text="",shown=0}
+function say(s) dlg.text=s dlg.shown=0 push("dialog") end
+
+function update_dialog()
+ if dlg.shown < #dlg.text then
+  dlg.shown+=0.5                       -- ~2 chars/frame; tune for pacing
+  if btnp(4) then dlg.shown=#dlg.text end  -- confirm fast-forwards to full
+ else
+  if btnp(4) then pop() end            -- fully shown: confirm closes/advances
+ end
+end
+
+function draw_dialog()
+ camera()
+ rectfill(4,100,123,123,1) rect(4,100,123,123,7)
+ print(sub(dlg.text,1,flr(dlg.shown)), 8,104, 7)  -- sub reveals up to `shown`
+end
+```
+
+(For multi-line/word-wrapped dialog, pre-split the text into lines that fit the box
+width and reveal line by line. `print` glyphs are ~4px wide, so ~28 chars per line
+in a full-width box.)
+
+## Turn-based battle menu (same primitives)
+
+A battle is the SAME machinery: a mode on the stack (`"battle"`), a cursor over
+actions (`Fight/Item/Run`), pushing a target-select submenu, then running the
+action and popping back. Keep the battle STATE (hp, turn order) separate from the
+MENU state (which option is highlighted); do not entangle them.
+
+## Coroutine for scripted sequences (optional)
+
+For a scripted intro / cutscene (text, then move a sprite, then more text), a
+coroutine reads far cleaner than a hand-rolled step counter:
+
+```lua
+function intro()
+ say("long ago...") yield_until_closed()
+ -- move the king sprite, wait, etc.
+ say("...a hero was needed.") yield_until_closed()
+end
+-- drive it: seq=cocreate(intro); each frame if costatus(seq)~="dead" then coresume(seq) end
+```
+
+## Genre pitfalls checklist
+
+- [ ] UI is a STACK (push submenu / pop on cancel), dispatched on the top mode.
+- [ ] Menu input is `btnp` only; cursor index WRAPS with `%` (mind 1-based).
+- [ ] Dialog text reveals over time; confirm fast-forwards, then advances.
+- [ ] Menus/boxes drawn in SCREEN space (`camera()` reset first).
+- [ ] Battle/menu STATE kept separate from which option is highlighted.
+- [ ] Word-wrap pre-computed to the box width (~28 chars full-width).

package/src/skills/picopilot-code/reference/top-down-adventure.md

@@ -0,0 +1,117 @@
+# Top-down adventure reference (tiled world, 4-dir movement, interaction)
+
+Structure for a top-down explorer (action-adventure, RPG overworld). The player walks a
+tiled world in 4 (or 8) directions, collides with solid tiles, the camera follows
+across a map larger than the screen, and the player interacts with specific tiles
+(doors, chests, NPCs). Unlike the platformer there is no gravity; unlike the
+puzzle grid, movement is smooth pixel motion, not cell-stepping.
+
+## The load-bearing rules
+
+1. The player has a pixel position and a FACING direction. Movement is smooth
+   (pixels/frame), but collision is still tested against map tiles via
+   `mget`/`fget`.
+2. Resolve X and Y separately (same axis-by-axis idea as the platformer) so the
+   player slides along walls instead of sticking on corners.
+3. Facing is state you keep for animation AND for "what am I interacting with"
+   (the tile in front of the player).
+4. The map is bigger than 128x128: `camera` follows the player and CLAMPs to the
+   map's pixel bounds. `map()` draws the whole tilemap in world space.
+
+## Movement + per-axis wall collision
+
+```lua
+speed=1.5
+player={x=64,y=64,face=3}   -- face: 0 left,1 right,2 up,3 down (btn order)
+
+function solid(x,y) return fget(mget(x\8,y\8),0) end   -- flag 0 = solid
+function blocked(x,y)  -- 8x8 body, four corners
+ return solid(x,y) or solid(x+7,y) or solid(x,y+7) or solid(x+7,y+7)
+end
+
+function update_player(p)
+ local dx,dy=0,0
+ if btn(0) then dx=-speed p.face=0 end
+ if btn(1) then dx=speed  p.face=1 end
+ if btn(2) then dy=-speed p.face=2 end
+ if btn(3) then dy=speed  p.face=3 end
+
+ -- resolve X then Y separately (slide along walls)
+ if not blocked(p.x+dx,p.y) then p.x+=dx end
+ if not blocked(p.x,p.y+dy) then p.y+=dy end
+end
+```
+
+## The tile in front (interaction target)
+
+```lua
+fdx=split"-1,1,0,0"   -- indexed by face+1: left,right,up,down
+fdy=split"0,0,-1,1"
+
+function front_tile(p)
+ -- the map cell one step ahead in the facing direction
+ local fx=p.x+4 + fdx[p.face+1]*8   -- +4 = center of the 8px body
+ local fy=p.y+4 + fdy[p.face+1]*8
+ return fx\8, fy\8
+end
+
+function _update()
+ update_player(player)
+ if btnp(4) then           -- action button: interact with the tile ahead
+  local tx,ty=front_tile(player)
+  local s=mget(tx,ty)
+  if s==CHEST then mset(tx,ty,CHEST_OPEN) got_item() end
+  -- doors, signs, NPCs: branch on the sprite id at (tx,ty)
+ end
+end
+```
+
+## Camera follow with map-edge clamp
+
+```lua
+-- map_w,map_h = map size in PIXELS (tiles*8).
+function update_camera(p)
+ local cx=mid(0, p.x-64, map_w-128)
+ local cy=mid(0, p.y-64, map_h-128)
+ camera(cx,cy)
+end
+
+function _draw()
+ cls()
+ update_camera(player)
+ map()                       -- whole tilemap, world space
+ spr(walk_frame(player), flr(player.x), flr(player.y), 1,1, player.face==0)
+ camera()                    -- RESET before the HUD
+ draw_hud()
+end
+```
+
+## Rooms / streaming (optional, for large worlds)
+
+Two common approaches:
+- One big shared map, camera just moves over it (simplest; limited by the 128x32
+  map size, extendable with the shared bank).
+- Room-based: each screen is a fixed 16x16 tile region; when the player crosses
+  an edge, snap the camera to the next room and reposition the player. Store room
+  coords, draw `map(room_c*16, room_r*16, 0,0, 16,16)`.
+
+## Animation (frame per facing + walk cycle)
+
+```lua
+-- 2-frame walk per direction; base sprite per facing in a split lookup.
+face_base=split"16,16,32,48"   -- left/right share sprites, flipped
+function walk_frame(p)
+ local moving = btn(0) or btn(1) or btn(2) or btn(3)
+ local step = moving and flr(t()*4%2) or 0
+ return face_base[p.face+1]+step
+end
+```
+
+## Genre pitfalls checklist
+
+- [ ] Movement is smooth pixel motion, but collision still tests map tiles.
+- [ ] X and Y resolved separately (wall-slide, no corner-stick).
+- [ ] Facing is kept as state and drives BOTH animation and interaction target.
+- [ ] Interaction reads the tile ONE step ahead in the facing direction.
+- [ ] Camera follows and clamps to the map's PIXEL bounds; reset before HUD.
+- [ ] `btnp` for the discrete action button; `btn` for continuous walking.

package/src/skills/picopilot-code/reference/twin-stick-arcade.md

@@ -0,0 +1,128 @@
+# Twin-stick / arcade reference (many entities, spawn/despawn, juice)
+
+Structure for an action arcade cart (shooter, bullet-hell, wave survival). The
+defining problem is MANY short-lived entities at once (bullets, enemies,
+particles) that spawn and despawn every frame. Get the entity-list lifecycle and
+the despawn-while-iterating right, then layer on the "juice" that makes arcade
+carts feel good. Shipped arcade carts are `rnd`-heavy for exactly that juice.
+
+## The load-bearing rules
+
+1. One flat list per KIND (`bullets`, `enemies`, `particles`), each entity a
+   table. `add` to spawn, `del`/`deli` to despawn.
+2. Despawn safely. Deleting the CURRENT item inside `foreach` is safe. Deleting
+   inside an ASCENDING `for i=1,#list` is NOT (it errors once the list shrinks).
+   Use `foreach`, or iterate DESCENDING when you delete by index.
+3. Off-screen or dead entities must be removed, or the list grows unbounded and
+   the cart slows/crashes. Cull every frame.
+4. Movement is velocity-based and free (no grid, no gravity unless you want it).
+   `sin`/`cos` take TURNS (0..1) for aiming/spread.
+
+## Entity lists + safe cull
+
+```lua
+bullets={}
+enemies={}
+parts={}
+
+function fire(x,y,ang,spd)
+ -- ang in TURNS (0..1). sin is screen-inverted, so this aims correctly on screen.
+ add(bullets,{x=x,y=y,dx=cos(ang)*spd,dy=sin(ang)*spd,life=90})
+end
+
+function update_bullets()
+ foreach(bullets,function(b)
+  b.x+=b.dx b.y+=b.dy b.life-=1
+  -- cull off-screen OR expired; del of the CURRENT item under foreach is safe
+  if b.life<=0 or b.x<-4 or b.x>131 or b.y<-4 or b.y>131 then
+   del(bullets,b)
+  end
+ end)
+end
+```
+
+## Spawning waves + aiming at the player
+
+```lua
+function spawn_enemy()
+ -- rnd picks a random screen edge; flr for an integer choice
+ add(enemies,{x=flr(rnd(128)),y=-8,hp=3})
+end
+
+function enemy_shoot(e)
+ -- atan2 gives the turn-angle from e to the player; feed it straight to fire()
+ fire(e.x,e.y, atan2(player.x-e.x, player.y-e.y), 1.5)
+end
+```
+
+## Particles / juice (why arcade carts call rnd a lot)
+
+```lua
+function burst(x,y,col,n)
+ for i=1,n do
+  local a=rnd()               -- random turn 0..1
+  local s=0.5+rnd(1.5)        -- random speed
+  add(parts,{x=x,y=y,dx=cos(a)*s,dy=sin(a)*s,life=10+rnd(10),col=col})
+ end
+end
+
+function update_parts()
+ foreach(parts,function(p)
+  p.x+=p.dx p.y+=p.dy p.dx*=0.9 p.dy*=0.9 p.life-=1
+  if p.life<=0 then del(parts,p) end
+ end)
+end
+
+function draw_parts()
+ foreach(parts,function(p) pset(p.x,p.y,p.col) end)
+end
+```
+
+Screen shake is a cheap, high-impact juice: offset the camera by a decaying
+random amount, then RESET it.
+
+```lua
+shake=0
+function add_shake(n) shake=max(shake,n) end
+function apply_shake()
+ if shake>0 then
+  camera(rnd(shake)-shake/2, rnd(shake)-shake/2)  -- random offset
+  shake*=0.8
+  if shake<0.5 then shake=0 end
+ else
+  camera()   -- no shake: ensure camera is reset (draw state persists!)
+ end
+end
+```
+
+## Collision (cheap circle test for round-ish sprites)
+
+```lua
+-- squared-distance test avoids sqrt. r = sum of radii.
+function hit(a,b,r)
+ local dx,dy=a.x-b.x,a.y-b.y
+ return dx*dx+dy*dy < r*r
+end
+```
+
+## Draw + reset discipline
+
+```lua
+function _draw()
+ cls()
+ apply_shake()
+ map() ; foreach(enemies,draw_enemy) ; foreach(bullets,draw_bullet) ; draw_parts()
+ camera()          -- RESET before HUD (shake/camera persist otherwise)
+ print("score "..score,2,2,7)
+end
+```
+
+## Genre pitfalls checklist
+
+- [ ] Each entity KIND is its own list; entities are tables.
+- [ ] Despawn uses `foreach`+`del` (safe) or a descending index loop, never an
+      ascending `for i=1,#list` with in-loop `del`.
+- [ ] Off-screen/dead entities are culled EVERY frame (no unbounded growth).
+- [ ] Angles are TURNS (0..1); `atan2`/`sin`/`cos` used consistently.
+- [ ] `rnd(x)` wrapped with `flr` when an integer is needed.
+- [ ] `camera()` reset after any shake, before the HUD.