picogame — rychlá reference

Tahák

Všechny signatury na jednom místě. Vysvětlení najdeš v kompletním API enginu; engine se nauč přes tutoriály.

Jednostránkový tahák všeho, co engine nabízí: nativní C modul picogame a pomocné knihovny picogame_* v čistém Pythonu ve složce lib/. Signatury ukazují názvy parametrů a výchozí hodnoty; * označuje keyword-only argumenty. Barvy jsou wire-order RGB565 inty (vytvářejte je pomocí rgb565). Delší vysvětlení viz PICOGAME.md.

---

Nativní modul: picogame (import picogame as pg)

Konstanty a barva

• RGB565, PAL8 — pixelové formáty bitmapy.
• rgb565(r, g, b) -> int — wire-order barva z 8bitových kanálů.
• collide(x1, y1, x2, y2, ax1, ay1, ax2, ay2) -> bool — AABB překryv (8 argumentů = box vs box) nebo bod-v-boxu (6 argumentů: collide(x1, y1, x2, y2, px, py)). Inkluzivní AABB — boxy kolidují při doteku (boxy spritu předávej jako (x, y, x+w, y+h); spustí se při kontaktu). Pozn.: collide je inkluzivní, na rozdíl od půlotevřených pixelových rozsahů u render — jiné domény (hitboxy vs pixely).

Bitmap(data, width, height, *, format=RGB565, palette=None, frames=1, stride=0, transparent=None)

Obrazový atlas stejně velkých frame (libovolná velikost). data je buffer; palette (pole wire barev) je vyžadováno pro PAL8. transparent = index/barva přeskočená při blittingu.

• Read-only props: width, height, frames, format, stride, palette (PAL8 paleta buffer nebo None), transparent (transparentní hodnota nebo None).

Sprite(bitmap, x=0, y=0, *, frame=0, visible=True, flip_x=False, flip_y=False)

Umístěná, animovatelná instance Bitmap.

• Props pozice/animace: x, y (int px) · fx, fy (float sub-pixel) · frame · visible · flip_x, flip_y · bitmap (výměna) · data (váš payload).
• Transform props (nearest-neighbour, kolem anchoru):
  • scale — float měřítko vykreslení; 1.0 = nativní (rychlá cesta), 2.0 = dvojnásobná velikost, zlomky povoleny (např. pulz).
  • angle — rotace ve stupních; 0 = žádná (rychlá cesta). Kombinuje se se scale.
  • transpose — bool; prohodí osy X/Y → levná rotace o 90° (s flip_x/flip_y = všech 8 orientací), ostrá, bez šumu. Jen rychlá cesta (scale 1, angle 0); footprint prohodí w/h.
  • anchor = (fx, fy) — pivot jako zlomky bitmapy (0..1): (0.5, 0.5) = střed, (0.5, 1.0) = dole uprostřed. x/y a rotace jsou kolem tohoto bodu.
• Blit-effect props (po jednom; nastavení jednoho zruší ostatní; levné, bez bitmap navíc):
  • shadow — bool; neprůhledné pixely ztmaví cíl (drop-shadow / ztmavující overlay).
  • flash — wire-RGB565 barva (nebo 0/None = vypnuto); neprůhledné pixely vykreslené jako tato plochá barva (hit-flash). Pulz 1–3 frame.
  • tint — wire-RGB565 barva (nebo 0 = vypnuto); neprůhledné pixely vynásobené jí — obarví sprite a přitom zachová jeho stínování (damage-red, freeze-blue, glow).
  • dither — 0 (neprůhledné) .. 16 (neviditelné); Bayer-stipple průsvitnost, bez alfy (duchové, mlha, fade-in/out).
• move(x, y) — nastaví pozici. · touch() — označí dirty po in-place úpravě bitmapy/palette.

Display(busdisplay)

Rychlý DMA backend obalující busdisplay boardu (FourWire SPI). Předejte do Scene.

Scene(display, buffer_a, buffer_b, *, background=0, top=0, bottom=0, left=0, right=0)

Scéna v retained-mode s vykreslováním pomocí dirty-rectangle; buffer_a/b jsou strip buffery.

• add(item, *, fixed=False) -> item — přidá Sprite/Tilemap/Particles/Canvas/StripDraw (pořadí vkládání = zdola→nahoru) a vrátí ho (takže spr = scene.add(Sprite(...)) funguje). fixed=True (jen keyword) ho připne k obrazovce (ignoruje kameru) pro HUD/dialog.
• add_all(items) — přidá několik (zdola→nahoru).
• set_view(ox, oy) — offset kamery (pozice počátku scény na obrazovce); jeho změna překreslí vše.
• view — read-only (ox, oy) aktuální offset kamery.
• invalidate() — vynutí překreslení celé obrazovky při dalším refresh.
• refresh() -> list | None — porovná a překreslí změněné oblasti; vrací dirty rect [x1,y1,x2,y2] (znovupoužitý) nebo None.

Tilemap(tileset, cols, rows)

Mřížka tile indexů do tileset Bitmap (každý frame = jeden tile); vrstva Scene.

• tile(tx, ty, value=None, *, flip_x=False, flip_y=False, transpose=False) -> int — získá tile, nebo ho nastaví (s volitelnou per-cell orientací: flip_x/flip_y/transpose dají všech 8 orientací tile — příznaky orientace jsou jen keyword; kombinujte s deduplikovaným tilesetem, viz png2picogame.py --dedup). Mimo rozsah ignorováno. Rovina orientace se alokuje líně (RAM jen pokud ji mapa používá).
• fill(value) — nastaví každý tile (vymaže orientaci).
• move(x, y) — umístí mapu.
• Read-only props: x, y, cols, rows.

Particles(capacity, size=1, gravity=0.0, fade=False)

Sdružená částicová vrstva (malé pohyblivé tečky) vykreslená jako jedna vrstva Scene.

• emit(x, y, count, speed=1, life=30, color=0xFFFF) — výbuch count teček, náhodná rychlost ≤ speed px/tick, žijících life ticků.
• tick() — posune o jeden krok (pohyb, gravitace, stárnutí). Volejte každý frame.
• clear() — odstraní vše.

Canvas(width, height, transparent=None, buffer=None)

RAM RGB565 kreslicí plocha skládaná jako vrstva Scene (width*height*2 bajtů). transparent z ní udělá tvarovaný overlay; buffer ji podloží externí pamětí (např. řezem arény). Pro animované plochy přes celý frame dejte přednost StripDraw (bez bufferu).

• clear(color) · pixel(x, y, color) · fill_rect(x, y, w, h, color) · rect(x, y, w, h, color)
• line(x0, y0, x1, y1, color) · circle(cx, cy, r, color) · fill_circle(cx, cy, r, color) · ring(cx, cy, r, thickness, color)
• triangle(x0,y0, x1,y1, x2,y2, color) · fill_triangle(...) · ellipse(cx, cy, rx, ry, color) · fill_ellipse(...)
• fill_round_rect(x, y, w, h, r, color) · frame3d(x, y, w, h, light, dark) (zkosený box) · move(x, y)
• Read-only props: x, y, width, height.

StripDraw(callback, x=0, y=0, width=0, height=0)

Vrstva v immediate-mode bez pixelového bufferu: při každém refresh volá callback(view, vx, vy, vw, vh) jednou pro každý render strip uvnitř svého obdélníku. view je Canvas mířící na živý strip (použijte Canvas primitiva); view-lokální (0,0) = obrazovkové (vx, vy). Překresluje se každý frame → pro animovaný/scanline obsah (pseudo-3D, gradienty). V posouvané scéně ho přidejte jako fixed.

• Read/write props: x, y, width, height — přesun/změna velikosti vrstvy (po zmenšení zavolejte scene.invalidate()).

Procedurální noise (koherentní value noise, 0..1)

• value2d(x, y, *, seed=0) -> float · value1d(x, *, seed=0) -> float
• fbm2d(x, y, *, octaves=4, seed=0, lacunarity=2.0, gain=0.5) -> float · fbm1d(x, *, octaves=4, seed=0, lacunarity=2.0, gain=0.5) -> float — fraktální (součet oktáv).

---

Pomocné knihovny (lib/picogame_*.py, čistý Python)

picogame_game — boot jedním voláním

• setup(display=None, strip_h=24, background=0, fast=True) -> (scene, buffer_a, buffer_b) — převezme displej, postaví Scene + dva strip buffery.

picogame_clock — pacing frame

• Clock(fps=30, max_dt=0.1) · .set_fps(fps) · .tick() -> dt (uspí do frame, vrátí sekundy) · .tick_async().
• FixedStep(step_fps=60, max_steps=5) · .steps() — generátor vracející konstantní dt na fixní krok.

picogame_input — tlačítka

• Masky: UP DOWN LEFT RIGHT A B X Y ALL; profil PICOPAD.
• Buttons(profile=None, pull=None) · .poll() -> mask · .is_pressed(mask=ALL) · .just_pressed(mask=ALL) · .just_released(mask=ALL) · .repeat(button, delay=15, interval=4) — PICO-8 btnp auto-repeat (menu / pohyb v mřížce).
• Timer(frames) — okno vstupní tolerance (coyote time / jump buffering): .feed(cond) (dobíjí, dokud je true, jinak slábne) · .charge() · .is_active · .consume() (true jednou, pak se vymaže).

picogame_font — textové bitmapy

• render_text(pg, font, text, fg, bg=None) -> (bitmap, w, h) — vykreslí řetězec do PAL8 Bitmap (bg=None → průhledné).
• render_text_pal(pg, font, text, fg, bg=None) -> (bitmap, w, h, palette) — totéž, plus pole palette; změňte palette[1] pro přebarvení textu na místě (bez přestavby).
• Label(pg, font, x, y, fg, bg) · .move(x, y) · .set(text) -> changed · .draw(display, buffer).

picogame_ui — HUD widgety (LINE_H = 12)

• SceneLabel(scene, pg, font, x, y, fg, bg) · .set(text) — textový popisek nezávislý na kameře (fixed vrstva Scene).
• TextBox(pg, font, x, y, w, h, fg, bg, maxlines=6) · .draw(display, buffer, lines).
• Menu(pg, font, x, y, items, fg, bg, title=None) · .tick(btn) -> index | -1 · .draw(display, buffer).

picogame_shapes — generátory jednobarevných bitmap

• rect(w, h, color) · circle(d, color) · ring(d, color, thickness=2)
• from_mask(mask, color) — Bitmap z řetězcové masky ('#' = nastaveno).
• atlas(frames_data, w, h, color) — zabalí w×h buffery do víceframe Bitmap.
• color_frames(w, h, colors) — frame i = plné colors[i].
• tileset_colors(w, h, colors) — tileset: frame 0 prázdný, frame 1..N obarvené.
• poly_frames(size, points, nframes, color, fill=True) — předpeče nframes rotací polygonu.

picogame_pool — znovupoužitelný pool sprite

• Pool(scene, bitmap, capacity, anchor=None, fixed=False) · .spawn() -> sprite | None · .free(s) · .free_all() · .count() -> int. (.items = všechny sprite.)

picogame_collide — kolize bez alokace

• hit(a, b, hw=None, hh=None) — AABB překryv dvou sprite.
• hit_point(a, px, py, hw=None, hh=None) — bod ve sprite.
• is_within(a, b, r) — test kruhové vzdálenosti (bez sqrt).

picogame_math — vektorová matematika (v picogame_math)

• length(dx, dy) · distance(x1, y1, x2, y2) · normalize(dx, dy) · angle_rad(dx, dy) (radiány) · from_angle_rad(a, mag=1.0) · clamp(v, lo, hi).

picogame_math — numerické helpery + tahová trigonometrie

• clamp(v, lo, hi) · mid(a, b, c) · lerp(a, b, t) · inv_lerp(a, b, v) · remap(v, a, b, c, d) · sgn(x) · approach(v, target, step) · wrap(v, lo, hi).
• sin_t(turns) · cos_t(turns) · atan2_t(dy, dx) -> turns — úhly jako 0..1 otáčky (standardní, ne PICO-8 invertovaný sin).

picogame_tiles — per-tile metadatové flagy (PICO-8 fget/fset)

• Bity/masky: B_SOLID B_HAZARD B_LADDER … (indexy) a SOLID HAZARD LADDER … (masky).
• TileFlags(flags=None, tile_px=8) — flags = {tile_index: bitfield} nebo seznam. .get(tile, bit=None) · .set(tile, bit, value=True) · .at(tilemap, cx, cy, bit) · .at_px(tilemap, px, py, bit) (kolize jedním řádkem). Klíčováno tile indexem (sdíleno všemi buňkami, které ho používají).

picogame_seq — sekvence řízené generátory (coroutine vzor)

• wait(frames) · over(frames, fn) (fn(t), t 0..1) · move_over(sprite, x, y, frames) — vše jsou generátory; skládejte přes yield from.
• Seq(gen=None) · .start(gen) · .tick() -> done · .done — posune o jeden krok za frame (cutscény, „udělej X za N frame“).

picogame_anim — frame animace v čase

• FrameAnim(sprite, frames, fps=8, loop=True) · .reset() · .tick(dt).
• AnimatedSprite(sprite, anims) · .play(name) · .tick(dt).

picogame_fx — šťáva a rastrové efekty

• Shake(scene, max_offset=6, decay=0.03) · .add(amount) (0.6 zásah, 0.15 náraz) · .tick(cam_x=0, cam_y=0) — trauma screen shake složený nad kamerou.
• Fade(scene, w, h, x=0, y=0, color=0, cell=8) · .out()/.into()/.set(level)/.dim(level)/.pulse() · .tick() -> done — dither fade / dim / blesk, přes celou obrazovku nebo oblast. 0bajtový StripDraw overlay.
• Tween(value=0.0, speed=0.2) · .to(target) · .set(v) · .tick() -> value · .is_done — vyhladí skalár (UI/pop-upy).
• Camera(scene, w, h, lerp=0.18, world_w=0, world_h=0) · .follow(tx, ty, snap=False) · .offset() -> (ox,oy) · .apply() — vyhlazené sledování + omezení na svět (skládejte se Shake přes shake.tick(*cam.offset())).
• Sky(scene, x, y, w, h, top, bottom) — vertikální gradient (per-scanline, 0 RAM). · Scanlines(scene, x, y, w, h, step=2, dark=0) — CRT overlay.

picogame_palette — triky s Game-Boy palette na PAL8 grafice (poté volejte sprite.touch())

• cycle(palette, lo, hi, step=1) — rotuje položky (animovaná voda/láva/portály; ~0 grafiky navíc).
• swap(dst_palette, src_palette) — přebarví sdílenou bitmapu (GBC styl; levnější než 2. bitmapa).
• fade(palette, base, t, target=0, skip=None) — lerp k barvě (hladké stmívání jasu; base = snapshot() originálu).
• snapshot(palette) / restore(palette, base).

picogame_rand — seedovatelný RNG

• Rand(seed=None) (deterministický xorshift; None = seed z času) · .below(n) · .randint(a, b) · .random() · .chance(p) · .choice(seq) · .shuffle(lst) · .weighted(weights) -> index · .seed(s).
• Bag(items, rng) · .next() — shuffle-bag (7-bag) anti-streak randomizér.

Noise — nativní funkce picogame (pg.*)

• value2d, value1d, fbm2d, fbm1d jsou funkce přímo na nativním modulu picogame (volejte jako pg.value2d, pg.value1d, pg.fbm2d, pg.fbm1d); samostatný modul picogame_noise neexistuje.

picogame_save — NVM perzistence

• Save(key, schema, *, offset=0) · .defaults() · .load() -> dict · .save(values) · .reset(). Přežije restart/smazání souborového systému.

picogame_audio — PWM audio

• Audio(pin=None, voices=4, sample_rate=22050, channels=1, bits=16, signed=True) · .load(path) · .play(sample, *, voice=None, loop=False, volume=1.0) · .sfx(sample, volume=1.0) · .music(sample, loop=True, volume=1.0) · .stop(voice=None) · .stop_music() · .is_playing.
• tone(frequency=440, ms=120, sample_rate=22050, volume=0.6) — sample pípnutí obdélníkovou vlnou.

picogame_arena — buffer proti fragmentaci

• Arena(pixels) · .alloc(nbytes) -> memoryview · .canvas(w, h, transparent=None) -> Canvas · .reset() · .free() -> int. Vezměte jeden velký buffer předem, rozdávejte řezy. Viz MEMORY.md.

picogame_scene — deklarativní loader levelů

• load(pg, scene, display=None, strip_h=24, font=None, bank=None) -> View — postaví scénu z předpečeného SCENE dictu.
• load_bank(pg, bank) — postaví sdílenou asset banku jednou (znovupoužitelnou napříč levely).
• View: .tile_xy(px, py) · .group(tag) · .point(name) · .in_zone(x, y, tag=None) · .is_solid(tx, ty) · .tile_has(tx, ty, prop) · .play(sound_id) · .tick(dt). Viz SCENE_FORMAT.md.